.cursorrules · diff

git:20260710.b0b7baf to git:20260710.57b0cf5

1 added, 1 removed. Audit A to A.

# 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_autopoiesis`, `template_autoresearch_project`, `template_autoscientists`, `template_code_project`, `template_data_descriptor`, `template_eda_notebook`, `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`.

+ - **Canonical exemplars** (always tracked, per `infrastructure.project.public_scope.PUBLIC_PROJECT_NAMES`): `template_active_inference`, `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`.

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.