/stdd:review — Audit spec coverage or docs/ freshness

/stdd:review — Audit spec coverage or docs/ freshness

Feature: $ARGUMENTS

Mode

Pick the mode by argument shape:

• Per-feature coverage ($ARGUMENTS is set) — map this spec's acceptance criteria to its tests. Use before merging, when picking up a stale branch, or after a spec edit that may have outpaced the tests.
• Tree-wide freshness (no $ARGUMENTS) — sweep docs/ for prose and ticks that have drifted away from the current code. Use periodically — for example, before cutting a release or after a refactor that touched vocabulary across multiple modules. The per-feature /stdd:tdd finish step catches drift around the feature it just shipped; this catches drift anywhere else.

Both modes are read-only. Never edit, never run tests.

Per-feature coverage ($ARGUMENTS is set)

1. Read docs/specs/$ARGUMENTS.md. The guard's flexible feature mapping applies — docs/specs/auth/login.md, docs/specs/auth-login.md, and docs/specs/auth_login.md all match $ARGUMENTS=auth/login. If no spec is found, stop:

   No spec found. Run /stdd:spec $ARGUMENTS first.

2. Locate the test file(s):

   • Co-located: src/$ARGUMENTS.test.<ext> (or matching nested path)
   • Separated: tests/test_$ARGUMENTS.<ext> (or matching nested path)

   If none are found, report it as a single gap covering every criterion and stop after step 4 with Coverage: 0/M criteria.

3. For each acceptance criterion in the spec, scan the test file(s) for its AC-N ID — match either AC-N (in strings or docstrings) or AC_N (in identifiers). Note the test category (happy path, edge, error, security). Tests with no matching criterion are themselves a gap.

4. Print the audit — table plus Gaps section plus the final Coverage: N/M criteria line. Follow the format in "Coverage audit format" in the stdd rules.

5. If gaps exist, point the user to /stdd:tdd $ARGUMENTS to close them.

Tree-wide freshness (no $ARGUMENTS)

Run three lightweight sweeps over the whole repo and print one consolidated report. Each sweep is greppable in seconds; none parse code semantically.

1. Stale-phrase scan

Grep docs/ (excluding docs/specs/'s own scope notes, which legitimately describe what that spec is not yet doing) for phrases that promise unfinished behaviour:

"not yet implemented", "documented gap", "is a no-op", "will be added", "coming soon", "to be done", "TODO", "FIXME", "deferred", "follow-up".

For each hit, decide still accurate (leave) or shipped (suggest update). Prefer reading 5 lines of context before deciding.

2. AC-tick consistency

For every spec in docs/specs/:

• Each - [x] AC must have at least one test carrying its AC-N (or AC_N) tag anywhere under src/ or tests/ — not just the per-spec test file. Specs may share an umbrella integration file (e.g. cli/doctor.test.ts covering cli/doctor, cli/doctor-network, and cli/doctor-app-probes); the tag's presence is what counts, not the file it lives in. Cross-spec AC-N collisions are tolerated — if pipeline/attachments AC-15 and sources/group-discovery AC-15 both exist, one tagged test satisfies both, and the reviewer disambiguates from the test's content. Flag any [x] AC with no matching test anywhere — the tick is wrong or the test was deleted.
• Each - [ ] AC whose tag is present in a test is mis-marked — flag.
• Tests carrying an AC-N tag that does not match any criterion in any spec are orphans — flag with the test file and tag.

Implementation hint: build one set of AC-N tags present anywhere in src/ + tests/ (the union), then for each spec's ACs check membership in that set. Per-spec-file scoping is the wrong semantics and produces false positives.

3. Spec-vs-code drift

For every spec in docs/specs/, extract the identifiers it names in its Public interface section (exported function names, type names, constants). For each identifier, grep src/. If not found, the spec references a removed or renamed symbol — flag.

Report

One section per sweep. Within each, one finding per line:

<file>:<line> — <finding> — <suggested action>

End with a single summary line: X stale phrases, Y AC-tick discrepancies, Z drift findings.

If everything is clean, print docs/ is fresh — no findings. and stop.

Do not write to files. The output is an action list — close AC-tick or drift findings via /stdd:tdd <name>; hand-edit stale phrases in their containing file.