git:20260922.fb3a8f8 to git:20261019.6b254e1

- # Cursor and IDE agents — repository guidance

-

- Use this file together with **[README.md](README.md)** (onboarding),

- **[CLAUDE.md](CLAUDE.md)** (commands and patterns for Claude Code), and

- **[AGENTS.md](AGENTS.md)** (full system reference, troubleshooting, configuration).

-

- ## What to read first

-

- | Goal | Primary doc |

- | --- | --- |

- | Clone → run pipeline | [README.md](README.md) Quickstart, [docs/RUN_GUIDE.md](docs/RUN_GUIDE.md) |

- | Exact shell commands, CI mirror, examples | [CLAUDE.md](CLAUDE.md) |

- | Pipeline stages, validation, multi-project rules, deep TOC | [AGENTS.md](AGENTS.md) |

- | Directory-specific APIs and conventions | `AGENTS.md` / `README.md` within that subdirectory (each `projects/<name>/manuscript/` has its own `AGENTS.md`) |

- | Public project names (`infrastructure.project.public_scope`) | [docs/_generated/active_projects.md](docs/_generated/active_projects.md) |

- | Live counts and coverage claims | [docs/_generated/COUNTS.md](docs/_generated/COUNTS.md) (refresh via measured `pytest` + [`scripts/docgen/active_projects.py`](scripts/docgen/active_projects.py); see [`docs/_generated/README.md`](docs/_generated/README.md)) |

-

- ## Architecture (non-negotiable)

-

- - **Thin orchestrators:** Business logic belongs only in `infrastructure/` (generic)

- or `projects/{name}/src/` (domain). Root `scripts/` and `projects/{name}/scripts/`

- coordinate I/O, subprocesses, and plotting — they call tested functions; they do

- not own algorithms.

- - **Layer 1:** `infrastructure/`, repo `scripts/`, `tests/infra_tests/`.

- - **Layer 2:** Each active project under `projects/<name>/` with `src/`, `tests/`,

- `manuscript/`, `scripts/`, `output/`. Final deliverables are copied to `output/<name>/`.

- - **Canonical exemplars** (always tracked, per `infrastructure.project.public_scope.PUBLIC_PROJECT_NAMES`): `template_active_inference`, `template_advanced_literature_review`, `template_autopoiesis`, `template_autoresearch_project`, `template_autoscientists`, `template_code_project`, `template_data_descriptor`, `template_eda_notebook`, `template_formal`, `template_gold_refinement`, `template_literature_meta_analysis`, `template_madlib`, `template_methods_paper`, `template_newspaper`, `template_pitch_deck`, `template_pools_rules_tools`, `template_prose_project`, `template_redacted_report`, `template_registered_report`, `template_search_project`, `template_sia`, `template_storybook`, `template_template`, `template_textbook`, `template_experiment_tree`.

- Authoritative roster: `docs/_generated/active_projects.md`.

- Do not assume other folder names under `projects/` exist in every checkout; use discovery output above.

- - **`output/` is disposable:** Both `projects/<name>/output/` and root `output/<name>/`

- are regenerated by the pipeline — do not commit their contents.

-

- ## Tooling

-

- - **Python / deps:** `uv sync` at repo root. Prefer `uv run …` for every tool.

- - **Pre-commit (matches CI lint for Python):** `ruff` + `mypy` on `infrastructure/`

- and `projects/*/src/`; **pre-push** adds no-mocks check, fast pytest smoke, Bandit

- (`bandit.yaml`), skills manifest check (all hooks are blocking — a failure prevents the push).

- See [.pre-commit-config.yaml](.pre-commit-config.yaml).

- - **Adding dependencies:** `uv add <pkg>` at repo root for shared deps; use

- `uv add <pkg> --project projects/<name>` for project-local deps. Always run `uv sync` after.

- - **Tests:** No mocks (`unittest.mock`, `MagicMock`, `mocker.patch`, etc.). Use real data,

- temp files, `pytest-httpserver` for HTTP, subprocess for CLIs. Infra coverage floor 60%,

- project src floor 90% (unless CI documents an exception for a rotating project — see

- `.github/AGENTS.md` and `.github/workflows/ci.yml` for current exceptions).

-

- ## Editing discipline

-

- - Prefer **registry-backed** manuscript figures, equations, and variables over hard-coded

- numbers in prose when the project defines injectors.

- - After adding, removing, or moving any folder under `projects/`, regenerate

- `docs/_generated/active_projects.md`: `uv run python scripts/docgen/active_projects.py`.

- - Keep stage numbering and pipeline phrasing aligned across README, CLAUDE, AGENTS, and

- `infrastructure/core/pipeline/pipeline.yaml`.

- - Touch only files and behaviour the user requested; avoid drive-by refactors.

-

- ## Agent memory (local only)

-

- - Continual-learning writes to `.cursor/hooks/state/continual-learning-memory.json` only; never add Learned sections to root `AGENTS.md` (public-repo contract).

- ## Security and secrets

- - Follow [docs/rules/security.md](docs/rules/security.md) and [bandit.yaml](bandit.yaml).

- - Do not commit secrets, API keys, or machine-local paths into shared docs.