liaohch3 Legibility Check
Run deterministic checks for maintainer docs that mirror what CI enforces via .github/workflows/legibility.yml. Catching these locally saves a round-trip to CI.
What it checks
- Standards freshness — every
.agents/docs/standards/*.mdmust have frontmatter withowner,last_reviewed(ISO date), andsource_of_truth. Files reviewed more than 60 days ago produce a warning. - Architecture manifest — every path listed in
.agents/docs/architecture/manifest.yamlunderexpected_paths:must exist in the repo. - Plan state drift — every
.agents/docs/plans/**/*.mdmust have astatusfrontmatter field (active,completed, orcancelled). Completed plans must not contain unchecked- [ ]checkboxes (outside fenced code blocks).
Run
uv run python scripts/check_legibility.py
Options:
--freshness-days N— change the staleness threshold (default: 60)--strict-freshness— promote stale warnings to failures--repo-root PATH— override repo root (default: cwd)
Fixing common failures
| Failure | Fix |
|---|---|
missing frontmatter key 'X' |
Add the missing key to the YAML frontmatter block at the top of the file |
last_reviewed must be ISO date |
Use YYYY-MM-DD format |
last_reviewed ... is stale |
Update last_reviewed to today's date after reviewing the content |
expected path missing: X |
Either create the file or remove the stale entry from manifest.yaml |
status must be one of [...] |
Add status: active (or completed/cancelled) to plan frontmatter |
completed plan still contains unchecked TODO |
Check off remaining items or change status back to active |
After fixing
Re-run the check to confirm all issues are resolved before committing:
uv run python scripts/check_legibility.py && echo "All clear"