The checking scripts
Three scripts that answer questions nobody can answer by reading — documentation consistency, requirement coverage, and an independent panel.
They are scripts rather than lists of greps for the same reason rules are identifiers rather than paragraphs: a check every agent reimplements is a check that means something different each time.
They live in tools/ in this repository.
check-docs.py
Validates the complete documentation set. Run it from the repository root after installing the artefact structure, and after any authority, link or requirement change.
tools/check-docs.py [project-root] # defaults to .It discovers Markdown, MDX and published HTML below every docs/ directory, so
the root product reference and module-local references are checked together.
| Check | Catches |
|---|---|
| links | a relative link that resolves to nothing — worse in an authority map than no map at all |
| authority | a missing root docs/index.* authority table, or a second authority table |
| ids | a requirement identifier referenced but never defined, or defined twice across modules |
| closure | a governed document unreachable from the root product reference |
Closure is the one prose checking misses. A module reference that the product reference never reaches can be valid and well-formed while remaining invisible.
Exit code 1 if anything fails. Directories whose contents are historical or generated are ignored.
check-coverage.py
Validates the traceability join and the table-based module work registers.
tools/check-coverage.py [project-root] # defaults to .| Output | Means |
|---|---|
| definitions | Duplicate requirement IDs across module references |
| coverage | Requirements no story cites, and story citations with no definition |
| registers | Missing sibling registers, malformed WBS epics, missing gates, invalid statuses and stories with no requirement |
| ready frontier | Planned stories under an epic whose gate begins with Ready |
Module references are discovered as <module>/docs/index.{html,md,mdx}. Each
must have a sibling work-register.md using the standard four-column story
table. The checker treats a delivery gate as an epic annotation and refuses
blocked or ready as story statuses.
See the work register.
run-panel.py
Fans a panel out through codex and collects the answers.
tools/run-panel.py <prompts-dir> <output-dir> [--jobs 5] [--timeout 900]Each *.md file in the prompt directory is one panellist, and each runs as its
own process with no knowledge of the others. That independence is the point: a
panel whose members see each other's answers converges, and a converged panel
tells you nothing.
Every panellist gets its own output file, named after its prompt. A panellist that fails does not take the others down; the summary says who answered and who did not, and the exit code is non-zero if anyone failed — a partial panel silently reported as complete is the failure this guards against.
Two invocation details are load-bearing and are already handled inside the script — see codex for why.
See panels.