Validation Requirements¶
Before declaring any nontrivial task complete, an agent runs the following checks.
1. Run the validator/test suite¶
python scripts/check.py
This is expected to run all repository validators and tests (link/format/metadata checks, and any
applicable automated tests). See the scripts/ directory for the concrete validators as they are
added.
2. Review relative links¶
Confirm every relative link added or touched actually resolves to an existing file/anchor. Broken links are a common byproduct of moving or renaming files.
3. Review front matter¶
Confirm every substantive document touched has front matter conforming to
docs/governance/document-metadata-standard.md:
required fields present, document_type and status valid, owner a valid role.
4. Search for unresolved placeholders¶
Search for stray TBD, TODO, FIXME, XXX, or similar markers left in committed content. Per
document-metadata-standard.md, unresolved matters
belong in docs/governance/assumptions-register.md or docs/governance/open-questions.md, not
scattered inline without a trace.
5. Confirm no duplicate document IDs¶
Check that no document_id value is reused across two different documents (see
document-metadata-standard.md — IDs are stable and
never reused).
6. Confirm no secrets¶
Check that no Restricted-classification information (passwords, API keys, tokens, private customer data, etc. — see docs/governance/information-classification.md) has been introduced.
When validation fails¶
If scripts/check.py or any manual check surfaces a problem, fix it before declaring the task
done — do not report completion with known-failing validation. If a failure is out of scope for
the current task, note it explicitly in the handoff (see
change-and-handoff-protocol.md) rather than silently ignoring it.