Closes the second clause of soc-w6vh.5 acceptance: "A validation check
catches docs references to absent .agents/learnings files."
Walks docs/plans/ and docs/learnings/ for specific-dated
`.agents/learnings/YYYY-MM-DD-<slug>.md` references. For each, requires
EITHER a matching docs/learnings/<basename>.md mirror OR an explicit
annotation tag on the same line: `(local-only)`, `(documentary)`,
`(template)`, or `# documentary` comment.
Scope (v1): two surfaces only (docs/plans/, docs/learnings/) — the
high-claim-density paths where rationale-from-local-learnings has
historically drifted. Other surfaces (docs/levels/, docs/standards/,
docs/rfcs/) are intentionally exempt because they carry template /
example references rather than claim-grade rationale citations.
Sibling pattern: matches scripts/check-contracts-structural-floor.sh —
walk surface, assert structural property, emit clear FAIL message with
fix hint (export rationale to docs/learnings/ OR add annotation).
Bats coverage: 9 tests covering all paths — mirror present, missing
no annotation (FAIL), missing with three annotation flavors
(local-only/documentary/template), truncated path (skipped), outside
walked surfaces (silent), --warn-only flag downgrade, multiple
references mixed.
Code-driven fitness: docs-learning-reference validation gates
0 → 1 (warn-only-capable, blocking by default).
Cycle 62 / bd-driven mode. Closes soc-w6vh.5 acceptance second clause;
parent soc-w6vh.5 can now close once .5.1 closes.
Boden Fuller