The specs/ directory retains design decisions and the plans/ directory
retains implementation plans. These files
explain why a change was made and how it was intended to proceed. They are not
shell configuration, agent instructions, or executable skills, and merely
being tracked here does not load them into a session.
readme-policy.json is different: it is active policy data consumed by
bin/docs-audit. It declares which top-level directories require a README,
which ones have an explicit exemption, the root directory-map contract, and
the source/generated pairs and skill inventory owned by the audit.
Keep a specification when it records a decision that remains useful for interpreting the repository. Keep a plan as an implementation record even after its checkboxes have been completed; it is evidence, not a live task queue. Current behavior belongs in the README or source file owned by the subsystem, not only in a dated plan.
When adding a tracked top-level directory, update readme-policy.json with
either a required README or an explicit exemption, then add exactly one row to
the root directory map. Verify the complete documentation graph with:
bin/docs-audit auditThe audit is read-only. bin/docs-audit generate is the separate command that
rewrites the tracked skill inventory.