# Canonical Factsheet

> Auto-generated by `scripts/docgen/counts.py` from live repo state. Do not edit
> manually — run `uv run python scripts/docgen/counts.py --write` to refresh.

**Generated from live repo state on 2026-07-22 (UTC).** Volatile literals are re-derived on every run: tracked `infrastructure/` Python-file count via `git ls-files infrastructure | grep .py` (**722**), project-scope + publishing test collection via `pytest --collect-only` (**588** / **740**), the public exemplar roster, and the importable module list. The per-exemplar test/coverage snapshot table is a measured snapshot with source-commit and source-hash provenance in
[`coverage_snapshot.json`](coverage_snapshot.json) (see Test Status).

This file aggregates verifiable facts from discovery scripts, CI configuration, and test execution. Human-written documentation should link here rather than duplicate lists or numbers.

## Project Roster

Private lifecycle projects live outside this public repo in a separate external repository (location set via `TEMPLATE_PRIVATE_PROJECTS_ROOT` or `.private_projects_root`). The simplified sidecar defaults to `working/` and `archive/`; optional `ongoing/` (long-lived projects with no publication target) plus legacy `active/`, `published/`, and `other/` folders are still recognized when present. `run.sh`/`infrastructure.orchestration` symlinks existing private lifecycle folders into same-named typed subfolders under `template/projects/` (`working/*` → `projects/working/*`, `ongoing/*` → `projects/ongoing/*`, `archive/*` → `projects/archive/*`, optional `active/*` → `projects/active/*`, …) before discovery/rendering; only `projects/templates/` and optional `projects/active/` are default-rendered, while `working/`, `ongoing/`, and `archive/` are non-rendered mirrors for explicit targeted work. Override with `TEMPLATE_PRIVATE_PROJECTS_ROOT` or `.private_projects_root`; disable auto-sync with `TEMPLATE_SKIP_LINK_SYNC=1`; inspect with `uv run python -m infrastructure.orchestration link-projects --dry-run`.

**Public CI/documentation project scope** (`projects/`, filtered through `infrastructure.project.public_scope`; authoritative snapshot → [`active_projects.md`](active_projects.md)):

- `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`

`projects/_test_project/` is a stub layout used by validation tests only — omitted from `discover_projects()` (path may be absent in sparse checkouts; not a tracked exemplar tree).

**Work-in-progress projects** (`projects/working/`, not discovered/rendered): local-only symlinks to the private repo's `working/` projects — roster omitted from public docs; list with `ls projects/working/`.

**Ongoing projects** (`projects/ongoing/`, not discovered/rendered): local-only symlinks to the private repo's `ongoing/` projects — long-lived work with no publication target, roster omitted from public docs; render explicitly via the qualified name `ongoing/<name>`; list with `ls projects/ongoing/`.

**Archived projects** (`projects/archive/`, preserved but not executed): local-only symlinks to the private repo's `archive/` projects (roster omitted from public docs) — list with `ls projects/archive/`. `projects/published/` and `projects/other/` are optional legacy non-rendered lifecycle mirrors.

Regenerate [`active_projects.md`](active_projects.md) with:

```bash
uv run python scripts/docgen/active_projects.py
```

Default exemplar for paths: `projects/templates/template_code_project/`.

## Infrastructure Modules

Current importable Python subpackages under `infrastructure/` (25):

- autoresearch
- benchmark
- core
- doctor
- documentation
- fonds
- llm
- methods
- orchestration
- project
- prose
- provenance
- publishing
- reference
- rendering
- reporting
- research
- rules
- scientific
- search
- sia
- skills
- steganography
- tools
- validation

Plus `infrastructure/config/`, `infrastructure/docker/`, and `infrastructure/logrotate.d/` (configuration/documentation directories, not Python packages). Recount with:

```bash
find infrastructure -mindepth 1 -maxdepth 1 -type d -name '[!.]*' \
  -exec sh -c 'test -f "$1/__init__.py" && basename "$1"' sh {} \; | wc -l
```

Tracked Python modules (matches the drift gate):

```bash
git ls-files infrastructure | grep -c '\.py$'
```

(Last refreshed count: **722** on 2026-07-22 UTC — point-in-time; re-derive with the command above, the literal drifts as the tree changes.)

See `infrastructure/AGENTS.md` for module-specific function signatures and entry points.

## Test Status

```bash
uv run pytest tests/infra_tests/project/test_discovery.py -q
```

Current collection commands:

```bash
uv run pytest tests/infra_tests/project/ --collect-only -q --no-cov
uv run pytest tests/infra_tests/publishing/ --collect-only -q --no-cov
```

Result: **588** project-scope infrastructure tests collected and **740** publishing tests collected. Full behavioral gates still live in CI and in the verification commands listed by the relevant `AGENTS.md` files.

**Exemplar `pytest --collect-only` totals** (derived live in each project's declared environment; coverage snapshot last updated 2026-07-22; `template_active_inference` coverage was re-derived in its project-local environment — see note below):

| Project | Tests collected | `src/` line+branch coverage |
|---------|-----------------|----------------------------|
| `template_active_inference` | 786 | 93.23 % |
| `template_advanced_literature_review` | 77 | 93.07 % |
| `template_autopoiesis` | 512 | 97.84 % |
| `template_autoresearch_project` | 370 | 96.46 % |
| `template_autoscientists` | 115 | 99.28 % |
| `template_code_project` | 242 | 96.98 % |
| `template_data_descriptor` | 54 | 98.75 % |
| `template_eda_notebook` | 77 | 98.97 % |
| `template_formal` | 279 | 95.28 % |
| `template_gold_refinement` | 328 | 92.64 % |
| `template_literature_meta_analysis` | 1162 | 94.10 % |
| `template_madlib` | 181 | 99.67 % |
| `template_methods_paper` | 90 | 98.98 % |
| `template_newspaper` | 150 | 99.70 % |
| `template_pitch_deck` | 125 | 97.73 % |
| `template_pools_rules_tools` | 261 | 94.88 % |
| `template_prose_project` | 134 | 99.57 % |
| `template_redacted_report` | 143 | 97.53 % |
| `template_registered_report` | 37 | 96.42 % |
| `template_search_project` | 315 | 97.69 % |
| `template_sia` | 67 | 99.69 % |
| `template_storybook` | 21 | 94.40 % |
| `template_template` | 143 | 99.14 % |
| `template_textbook` | 192 | 96.19 % |

Collection counts come from per-project `uv run pytest tests/ --collect-only -q --no-cov` runs; coverage values come from the latest per-project coverage gates (`uv run pytest projects/templates/<name>/tests/ --cov=projects/templates/<name>/src`). After changing project `src/` or tests, rerun that project's coverage gate and then explicitly refresh provenance with `uv run python scripts/docgen/counts.py --refresh-coverage-provenance --write`; ordinary `--write` fails when source hashes no longer match. `template_active_inference` pins its own `.venv`/toolchain, so its coverage is re-derived in that environment, not from the repo-root interpreter. Orchestration modules (`analysis.py`, `figures.py`, `dashboard.py`, `manuscript_variables.py`) are in the coverage denominator for the code exemplar; `experiment_config.py` is the shared loader for `manuscript/config.yaml` → `experiment:`.

Drift-checker coverage: `uv run python scripts/audit/check_template_drift.py --strict`. Repo `scripts/` fat files emit **WARNING**; project `scripts/` fat files emit **ERROR** through the thin-orchestrator detectors. Per-exemplar detectors include function name drift, test class drift, `__all__` doc drift, coverage floor drift, dead links, oversize `src/*.py`, blanket `except Exception`, mocks in tests, and canonical-file presence.

**Thin-orchestrator gates:**

| Gate | Command | Threshold |
| --- | --- | --- |
| Exemplar drift | `uv run python scripts/audit/check_template_drift.py --strict` | 22+4 detectors |
| Module line count | `uv run python scripts/gates/module_line_count_check.py` | warn ≥800 / fail ≥950 (`infrastructure/`, `scripts/`); warn ≥150 / fail ≥250 (`projects/{exemplar}/scripts/` via `PUBLIC_PROJECT_NAMES`) |
| Unified health | `uv run python -m infrastructure.core.health` | optional `--gates=module-line-count` |
| Tracked public scope | `uv run python scripts/audit/check_tracked_all.py` | non-template paths under `projects/`, `fonds/`, `rules/`, and `tools/` |
| Generated artifacts | `uv run python scripts/audit/check_tracked_generated_artifacts.py` | prohibited generated state outside the canonical public-output allowlist |

Coverage gates (enforced in CI):

- infrastructure/ : >= 60% (measured baseline → [`docs/development/coverage-gaps.md`](../development/coverage-gaps.md))
- public template project `src/` trees : >= 90% (matrix project tests; Ruff uses `public_scope lint-paths`, while mypy uses the import-safe `source-paths`)

Run full suite with:

```bash
uv run python scripts/pipeline/stage_01_test.py --project template_code_project
```

## Command Conventions

Use `uv run` for reproducibility:

- Tests: `uv run python scripts/pipeline/stage_01_test.py --project <name>`
- Pipeline: `uv run python scripts/runner/execute_pipeline.py --project <name> --core-only`
- Interactive: `./run.sh`
- Specific test: `uv run pytest path/to/test.py::test_name -q`

Avoid raw `python3` or `pytest` in documentation.

## Output Layout

- Working outputs: `projects/{name}/output/`
- Final deliverables: `output/{name}/` (subdirectories per project: pdf/, figures/, data/, reports/)
- No root-level `output/pdf/` or `output/project_combined.md`

## Core Patterns

**Thin orchestrator**:

Scripts in `scripts/` and `projects/{name}/scripts/` import computation from `infrastructure.*` or `projects.{name}.src.*`. They handle only I/O, orchestration, and reporting.

**`template_code_project/src/` layout:**
- `optimizer.py`, `invariants.py` — math primitives, infrastructure-free
- `experiment_config.py` — `load_experiment_config()`; single parser for `manuscript/config.yaml` → `experiment:`
- `analysis.py` — experiment orchestration, stability/benchmark, validation, publishing, `main()`
- `figures.py` — matplotlib figure generators (uses `load_experiment_config`)
- `dashboard.py` — Plotly dashboard payload + HTML (`load_experiment_config`)
- `manuscript_variables.py` — `{{TOKEN}}` substitution (`load_experiment_config`, `quadratic_optimum`)

**No-mocks policy**: Tests use real computation, temp files (`tmp_path`), `pytest-httpserver` for HTTP, and `reportlab` for PDF tests.

**Reproducibility**: Fixed seeds, deterministic outputs, idempotent analysis scripts that skip if outputs exist.

## Pipeline Entry Points (from scripts/AGENTS.md)

See `scripts/AGENTS.md` for the pipeline entry-point inventory. The interactive menu's single source of truth is `infrastructure.orchestration.menu.MENU_OPTIONS`.

Key signatures:

- `execute_test_pipeline(...)` in `infrastructure.reporting.pipeline_test_runner`
- `discover_projects(root: Path) -> list[Project]`

## Validation Commands

```bash
uv run python -m infrastructure.validation.cli markdown projects/{name}/manuscript/
uv run python -m infrastructure.validation.cli pdf output/{name}/pdf/
```

## Structure

```mermaid
flowchart TD
    Root[Root] --> Infra[infrastructure/ <br/>25 importable packages]
    Root --> Projects[projects/ <br/>see active_projects.md]
    Root --> Tests[tests/infra_tests/]
    Infra --> Core[core/ <br/>pipeline, logging, files, config]
    Projects --> Src[src/ <br/>project logic]
    Tests --> ProjectTests[project/test_*.py <br/>90% cov]
```

Link to this file from other documentation instead of repeating facts.

**Regeneration note:** Refresh [`active_projects.md`](active_projects.md) with `scripts/docgen/active_projects.py`. Re-derive this file with `uv run python scripts/docgen/counts.py --write` after meaningful CI or test-scale changes. Re-run `uv run python scripts/audit/check_template_drift.py --strict` and `uv run python scripts/gates/module_line_count_check.py` when drift or line-count gates change.