---
name: legibility-check
description: Validate maintainer docs structure, standards freshness, manifest paths, and plan state. Run this after modifying any file under .agents/docs/standards/, .agents/docs/plans/, .agents/docs/architecture/, or AGENTS.md — it catches stale metadata, broken manifest paths, and plan state drift before CI does.
user_invocable: true
---

# 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

1. **Standards freshness** — every `.agents/docs/standards/*.md` must have frontmatter with `owner`, `last_reviewed` (ISO date), and `source_of_truth`. Files reviewed more than 60 days ago produce a warning.
2. **Architecture manifest** — every path listed in `.agents/docs/architecture/manifest.yaml` under `expected_paths:` must exist in the repo.
3. **Plan state drift** — every `.agents/docs/plans/**/*.md` must have a `status` frontmatter field (`active`, `completed`, or `cancelled`). Completed plans must not contain unchecked `- [ ]` checkboxes (outside fenced code blocks).

## Run

```bash
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:

```bash
uv run python scripts/check_legibility.py && echo "All clear"
```