Skip to content

AGENTS.md

Latest commit

 

History

History
56 lines (48 loc) · 3.92 KB

AGENTS.md

File metadata and controls

56 lines (48 loc) · 3.92 KB
Raw

AGENTS.md — docs/reference/

Generated and reference-style documentation. Anything in this directory is either auto-generated by a script or is a stable reference index that does not walk a contributor through a workflow (those go in docs/guides/).

Latest generated audit: live theorem/status counts come from the generated theorem map and manuscript/refs/labels.yaml; live pytest, PDF, figure, and artifact counts come from output/reports/release_readiness.json, output/reports/test_results.json, and output/MANIFEST.md. Historical round deltas live in docs/CHANGELOG.md and docs/reference/veridical_status.md.

Files

File Source Update cadence
_theorem_map.md Auto-generated by scripts/generate_theorem_map.py Every run_all.py
architecture.md Hand-authored When the layer split or major module boundaries move
four_track_coherence.md Hand-authored When a track (Lean / Python / Manuscript / Tests) gains or loses a theorem family
lean_reference.md Hand-authored When the Mathlib refinement roadmap advances (the witness-payload-discharge plan in MathlibRefinementRoadmap.md); on each lean/ boundary change
methods_audit.md Hand-authored When Lean status categories, pymdp adapter semantics, or simulation verification gates change
methods_orchestration.md Hand-authored When scripts/run_all.py ordering, parallelization, manifest writing, manuscript-variable timing, or figure-provenance metadata changes
invariants_reference.md Hand-authored When a new invariant family is added to src/lean/invariants.py or scripts/build_dashboard.py; cross-checked against output/reports/dashboard_invariants.txt
manuscript_map.md Hand-authored When a manuscript chapter is added / split / merged
math_reference.md Hand-authored When the load-bearing identities (Theorem 5.1, the closed form, the coupling tax) change
python_api.md Hand-authored index over python_api_*.md + gates/ / orchestration/ sections When src/ exposes a new public symbol outside the four domain subpackages
python_api_lean.md Hand-authored When src/lean/ exposes a new public symbol
python_api_manuscript.md Hand-authored When src/manuscript/ exposes a new public symbol
python_api_simulation.md Hand-authored When src/simulation/ exposes a new public symbol
python_api_visualizations.md Hand-authored When src/visualizations/ exposes a new public symbol
statistics_reference.md Hand-authored When src/simulation/statistics.py adds or changes an aggregate
veridical_status.md Hand-authored When a theorem's status: in manuscript/refs/labels.yaml changes

Rules

  1. Generated files are read-only. _theorem_map.md is regenerated by scripts/generate_theorem_map.py. Edit the generator, not the file. The leading underscore signals that it is generated.
  2. Hand-authored references must mirror reality. Every API table cell here must match the actual src/<module>/<file>.py symbol. Verified by the auto-generated test in tests/test_python_api_coverage.py.
  3. Do not walk a contributor through a task. Workflow guides live in docs/guides/. References are catalogs, indexes, and lookup tables.
  4. Use stable anchors. When a section is referenced from a manuscript chapter, the anchor must persist across rewrites; prefer ## My Heading {#stable_anchor} style rather than implicit slug targeting.

See also