How-to: run the audits¶

The framework has 5 layered audits + a pre-commit gate.

Quick reference¶

make audit            # run all 5 audits in sequence
make audit-quick      # structural + semantic only (fast)
make test             # pytest with coverage
make all              # lint + typecheck + test + audit (full local gate)

What each audit catches¶

Audit	What it validates
`scripts/audit.py`	YAML/JSON parse errors; SKILL.md frontmatter; curated registry cross-refs; `registry-full.yaml` consistency; agent/orchestrator/routing references
`scripts/audit_semantic.py`	`preferred_skills` exist; `governs_areas` exist; `sub_areas` declared in CAPABILITY-GRAPH; routing intent classes match handlers
`scripts/audit_paranoid.py`	README drift; spec cross-refs; JSON schema well-formedness; curated tier fields; stray scripts
`scripts/audit_deep.py`	Inventory partials; template TBD markers; template cross-refs; README skill count drift
`scripts/verify_all.py`	ARTIFACTS-INVENTORY summary counts; markdown link resolution; cross-refs in YAML examples

Exit codes (pre-commit)¶

Code	Meaning
0	All checks passed
1	Structural or semantic issue (commit aborted)
2	`_meta` drift detected — run `python scripts/sync_registry.py` and re-stage

Bypass (not recommended)¶

git commit --no-verify

CI will still catch you — see .github/workflows/audit.yml.