docs_lint rule 5: MANIFEST.md coverage, both directions

[WilfordGrimley]

The gap

docs/MANIFEST.md is the by-surface routing table — path | purpose | governs-what-surface | authority — so a task can be routed to its governing docs without anyone remembering which file covers what.

Its own Maintenance section said:

A soft orphan check now exists ... but a row here is not yet hard-enforced (deliberately deferred — see the lessons→gates triage note in lessons.md: measure whether a doc actually goes stale unnoticed before promoting this to a gate).

That measurement came back. Eight real docs had no row and no covering directory row:

doc	authority now assigned
features/stage-e-operations.md	BINDING — the operational runbook for Stage E streaming runs, envelope-trip clearing, the dispatch loop
features/theming.md	BINDING
features/display-left-rail.md	BINDING
features/foreign-order-resilience.md	BINDING
features/consent-toast.md	BINDING
features/bleed-measurement.md	BINDING
identification-pipeline.md	reference
reference/funnel-spec.md	historical

Six of the eight are BINDING-grade. Nothing said so, because nothing was looking.

Why not extend the orphan rule

The existing orphan rule targets this class and passed on every one of them — correctly. They are all reachable by some link from some sibling.

Reachable and routable are different properties. A doc reachable only through a see-also link buried in a sibling is reachable and unroutable at the same time, and this table exists to provide the second. Folding the check into the orphan rule would conflate the two and produce a message that names the wrong fix, so this is a fifth interconnection rule with its own message.

Both directions

The second half is a gap nobody had noticed at all: a row whose path does not resolve. The generic backtick-path rule requires a / in the candidate, so a top-level row like `theory.md` was never verified to exist. A rename would have left the routing table silently pointing at nothing.

An unparseable MANIFEST table is a finding, not a pass — deriving an empty covered-set would check nothing and go green.

The nine rows

Drafted from each doc's own self-description, not assigned by guesswork. Two examples of the judgment:

• reference/funnel-spec.md → historical, because it says so itself: "Reference only; not re-derived or updated after ratification — it is a point-in-time record of the ruling, not a living spec", and points at features/grid-selector.md as the living authority. Same shape as the already-historical reference/vote-weight-matrix.md.
• identification-pipeline.md → reference, the one genuinely arguable case. It describes current behaviour accurately and is actively maintained, but consistently positions itself downstream of theory.md, pipeline-fidelity-gate.md, features/printing-tags.md and features/catalog-completion-plan.md — all already BINDING for those surfaces. Marking it BINDING would create four overlapping authorities for one surface. Flagging this as the row most worth a second opinion.

Plus one upstreaming/drafts/ directory row (both files there self-declare a prep/branch-cut status; the binding checklist for such a branch is upstreaming/conventions.md, not the drafts).

Allowlist: the two index roots only, per-entry-justified. A row for the routing table inside the routing table routes nobody anywhere.

Two stale doc claims fixed — same defect class

• MANIFEST.md's Maintenance section still said the row convention was unenforced. It now records what changed and why, including that its own deferral's precondition was met.
• documentation-process.md said docs_lint enforces the model with "four rules". It is five.

Can it fail? Four demonstrations, restored to clean after each

1. A new doc with no row (docs/features/_demo-new.md):

   ::error file=docs/features/_demo-new.md::MANIFEST.md coverage gap: features/_demo-new.md has no row in docs/MANIFEST.md and is not covered by a directory row. MANIFEST.md is the by-surface ROUTING table — a doc missing from it is unroutable even when it is reachable by a link, which is why the orphan rule passes on it...
   

2. A row pointing at a renamed file — the direction nothing checked before:

   ::error file=docs/MANIFEST.md,line=23::MANIFEST.md row `theory-renamed.md` does not resolve to a real file under docs/. A routing table pointing at something deleted routes readers nowhere — update or remove the row.
   

3. The eight, as found — all nine new rows removed: 10 findings, exit=10 (the eight plus the two upstreaming/drafts/ files the directory row covers).
4. No false positive — a new doc under an existing directory row (docs/reports/_demo.md): docs-lint: clean. exit=0.

Verification

• python3 .github/scripts/docs_lint.py --strict — clean.
• python3 .github/scripts/tests/test_docs_lint.py — 50 tests, OK (was 39 on master). New TestManifestCoverage covers: missing row (top-level and nested), directory-row coverage including nested depth, a sibling prefix not being satisfied by a similar directory row (reports/ must not cover reports-archive/), unresolvable file row, unresolvable directory row, index-root allowlisting, allowlist exemption, header-separator rows ignored, a table row inside a fenced block not counted as a row, unparseable manifest, and a missing manifest not exploding.
• pre-commit run (ruff/isort/black/mypy/prettier) — passed.

Nothing under MPCAutofill/ changed, so the backend suite was not re-run.

Note on ordering

This branch is cut from master independently of #587/#588/#590. #588 also edits docs-lint.yml's path filters; this PR does not touch that file, so there is no conflict between them.

🤖 Generated with Claude Code

https://claude.ai/code/session_013NhYmT1PxCcyemA16dFDxN