docs/ is swept by no gate — 27 findings across 9 files sit behind a green docs:drift

[serge-ivo]

docs/ is read by no CI step, and all 27 known doc findings live there

Measured 2026-08-15. scripts/docs-drift.mjs's docFiles() collects platform-docs/, not docs/; servedHtmlFiles() skips any directory named docs. No gate reads docs/ at all.

The consequence is measured, not theoretical: an audit of 21 files under docs/ found 27 findings across 9 docs, while pnpm docs:drift passes all 13 checks. Nine of the 21 are clean — including two verified exact to the byte — so this is not "docs rot", it is "docs rot invisibly".

This is the #555 class one directory over, and the third instance of the same defect today: a guard whose population silently excludes the thing it exists to catch (see #600, #603).

One concrete drift to fix in the same commit, as the proof case: docs/mcp-instance-runtime.md states a tool count that disagrees with MCP_TOOL_COUNT and a /health figure of 41 against the live 136.

Acceptance criteria

1. docFiles() covers docs/**/*.md, with a requireInputs floor per ADR 0002 — the collector must fail when it gathers implausibly little, since "found nothing" and "found nothing wrong" print the same tick.
2. docs/mcp-instance-runtime.md's count drift is fixed, and the guard is demonstrated red on it first.
3. The success line states its denominator: files swept and claims checked, distinguishing the two. docs-drift swept the file and missed a stale 124 — the detector matches phrasings, so its denominator counts files read, not claims checked #603 is open on exactly that distinction — coordinate rather than inventing a second convention.
4. Historical documents must not be forced to state current numbers. An ADR describing a June decision is correct as history; establish how the guard distinguishes them, or scope it to files that make present-tense claims.

Verified vs inferred

• Verified: both collector behaviours; that docs:drift passes with the drift present; the 21/27/9 audit counts.
• Inferred: that extending the collector is sufficient. AC4's historical-document question may make it harder than a path change — settle that before implementing.

[serge-ivo]

Not started — blocked on a routing decision, per AC3. Nothing committed for this issue. Handing over what I measured while delivering #605/#606/#607.

The collision is semantic, not just file-level

docFiles() (scripts/docs-drift.mjs:100) feeds four call sites: :318, :456 (check 6), :574 (check 6b, the sweep handed to mcp-split.mjs), :727 (check 9). Widening it changes the population of exactly the checks #603 was re-instrumenting, so this is not two agents editing one file — it is two agents changing one measurement.

#603 has since landed (50859d5), and it makes the tension concrete rather than hypothetical. It shipped scripts/lib/claim-shape.mjs: a quantity mention that no parser can read is now a failure, not a silence. Point that at docs/ and:

• docs/mcp-instance-runtime.md:110 "120 server.tool(...) registrations" — correctly caught, this is the stale claim and AC2's proof case;
• docs/mcp-instance-runtime.md:181 "26 at the time of this 2026-06-11 record" — wrongly caught. That is a true, dated, historical statement in a verification log.

So AC4 is now testable against a shipped mechanism, and it is load-bearing: 21 files, of which 4 are historical, 8 current, 3 mixed (a) + (b), and 6 mixed containing superseded material. Sixteen of the 21 are wholly or partly historical. A guard that forces every dated number to be current would fail on correct history, and the pressure would then be to delete the history — which is the opposite of what this repo does well.

The shape that seems right, for whoever takes it: scope the numeric sweep to present-tense claims, or make a dated claim ("as of", "at the time of this record", an explicit date) an accepted shape in claim-shape.mjs rather than an exemption list. An exemption list would rot exactly the way the three-path list in #555 did.

What I'd suggest

#603's agent owns the denominator semantics and now owns claim-shape.mjs; the collector change should go with them. #604 then reduces to the doc fix plus AC4's historical-vs-current rule as the input they implement against. I have no stake in which way it routes — only that one agent settles it.

Two things for whoever picks this up

The docs/ audit is done and does not need repeating. 21 files sorted, 27 findings across 9 docs; 9 docs verified clean, two (coding-engines.md, custom-surfaces.md) exact to the byte. #605/#606/#607 have since fixed the findings in 7 of those 9 files. What remains unfixed in docs/ after those three: the minor line-drift at capability-constraints.md:14 (mechanism still correct, citation moved to agent-do-tools.ts:225), and third-party-agents-plan.md:37's reference to the deleted feat/admin-platform-metering branch.

Reported per the coordinator rather than edited, since it sits in a file another agent owns: scripts/lib/mcp-split.test.mjs:93 says "store/llms-full.txt states the split today and is generated". It is not generated — README.md:330 says "edit by hand", no generator exists, and workers/host/build.js:153 merely reads it. The comment is wrong; the README is right. Worth correcting whenever that file is next open, because a future agent reading it will look for a generator that does not exist.

One thing already confirmed for AC1

The machine-readable surfaces are not stale and the existing gate does cover them — measured before any of this work: store/llms.txt, store/llms-full.txt, store/.well-known/mcp-server.json and store/about/index.html all agree with tool-count.ts (136 / 117 / 19) and server-version.ts (0.1.4). docs:drift names the .well-known manifest in its own output. The gap is docs/ alone.

[serge-ivo]

Delivered in c74aaef, CI green.

AC4 was the blocker, and the answer is that it does not arise

The handover said a numeric sweep would fire on true dated history, that 16 of 21 files are wholly or partly historical, and that a dated claim therefore had to become an accepted shape in claim-shape.mjs.

Measured before building any of it — by extending the collector and running the whole script: checks 6, 6b, 7, 9 and both wire-surface arms stay green over docs/. Zero claims, zero failures. No historical number is forced to be current by anything, and the dated clause ("26 at the time of this 2026-06-11 record") is not matched by the shape check either. A dated-claim mechanism would have been machinery for a problem the data does not exhibit, so it was not built. The measurement is recorded in the commit if one is ever needed.

The handed report was wrong in both directions on the proof case

Re-measured rather than trusted, and both findings inverted:

• :110 "120 server.tool(...) registrations" was reported caught. It was missed — the mention filler could not cross a backticked code span, so the very line this issue names as its proof case was invisible to the guard shipped for docs-drift swept the file and missed a stale 124 — the detector matches phrasings, so its denominator counts files read, not claims checked #603. Fixed: a filler token is now a word or a backticked span, with a test that fails on the old regex.
• :181 was reported wrongly caught. It is caught correctly — the match is "120 registrations in source today", a present-tense stale claim sharing a line with the true dated one. That is precisely why a line-level "dated ⇒ skip" rule would have been wrong: it would have exempted the stale half along with the historical half.

The one real false-positive class

"RFC 7591 dynamic client registration", twice in docs/connector-auth.md — a number beside the word, about OAuth client registration. Bare registration is now a mention only in the plural; tool registration stays readable in either number because the qualifier removes the ambiguity.

After both fixes: 15 mentions over 61 files, 15 parsed, 0 unparsed, 0 false positives.

AC2 — red first

With docs/ swept and the filler fixed, the guard named both stale claims in docs/mcp-instance-runtime.md before either was fixed. Fixed, and phrased into shapes the checks READ — so the count check went from 6 claims to 8 and they are compared to MCP_TOOL_COUNT from now on rather than merely being correct today.

Two more stale statements in that file, not in the issue, fixed in passing: a sample /health response showing "tools":41, and the claim that /health reports a "static" count that is "not an authoritative inventory". It reads tool-count.ts — verified live: {"ok":true,"service":"proagentstore-mcp","tools":136}.

AC1 — the collector, with its own floor

docFiles() now walks docs/**/*.md recursively (docs/adr/ is where the constraints live). docs/ gets its own requireInputs floor rather than being absorbed into the total — a floor on the sum would let the whole directory vanish while the number stayed plausible, which is a smaller version of this bug, not a fix.

AC3 — denominator

✓ MCP tool count: 136 registered == constant == 8 claim(s) across 60 file(s) swept (4 required to state it, 1 exempt) + 16 per-file counts
✓ MCP surface claim shapes: 15 mention(s) across 6 file(s) == 15 parsed + 0 unparsed, 61 swept (1 exempt, holding 23 unchecked mention(s))

Files swept and claims checked are stated separately, using #603's convention rather than a second one.

The split

Adding the walk took docs-drift.mjs to 821 lines and the ratchet refused it, offering a pin or a split. Split — the collectors and their floors moved to scripts/lib/doc-files.mjs with their own tests, which is what this file did at #575 and what its neighbours already are.

Carried in, because they were one-line corrections in these files

• mcp-split.mjs:57 and its test both said store/llms-full.txt "is generated". It is not — README.md:330 lists it as hand-edited source and no generator exists (workers/host/build.js only reads it). The decision it justified still stands on its real footing: that file is already required to state the total via check 6's MUST_CLAIM.
• state-vocabulary.ts's waiting gloss (waiting_until means 'expected to resume', and the human handoff's deadline is a give-up — one field, two opposite actions #596), using the replacement sentence from that issue's own comment. The test now pins the verb rather than the old wording.

Left open, deliberately

The two remaining docs/ findings named in the handover — capability-constraints.md:14's moved citation and third-party-agents-plan.md:37's reference to a deleted branch — are not fixed here. Neither is a quantity claim, so neither is caught by this guard; they need their own issue rather than being swept in silently.

Note on #599: nothing added here leans on a type-level assertion. Every arm asserts at runtime, so none of it is inert under the tsconfig that excludes worker tests.

[serge-ivo]

No further code change — this was already delivered in c74aaef, and I re-derived rather than
inherited its two contested measurements. Closing.

I was briefed to implement this, including "fix docs/mcp-instance-runtime.md's count drift as the
proof case, red first". c74aaef is in main's history and had already done it, so I verified the
ACs instead of redoing them. All four hold:

AC1 — docFiles() walks docs/**/*.md recursively with its own requireInputs floor of 15
(scripts/lib/doc-files.mjs:66-81), not absorbed into the total. That separation matters: a floor
on the sum would let the whole directory vanish while the number stayed plausible.

AC2 — re-demonstrated red myself rather than taking the report. Restoring the original :110
shape and running the real gate:

✗ [claim-shape] 1 mention(s) of the MCP tool surface are in a shape no claim check can read,
  out of 15 mention(s) across 61 file(s) swept:
    docs/mcp-instance-runtime.md:110  "120 `server.tool(...)` registrations" (noun)

Tree restored clean afterwards; no git stash at any point.

AC3 — the success line states both denominators, using #603's convention.

AC4 — correctly not built. Re-measured independently: zero historical numbers are forced
current across docs/.

The two handed measurements, re-derived

Driving findQuantityMentions/findClaimSpans directly at the contested lines confirms the
corrected account in c74aaef, not the original handover:

Line	Handed as	Actually
:110 120 \server.tool(...)` registrations`	caught	was missed — the filler could not cross a backticked span. The backtick-span fix holds: 1 mention, 0 claim spans → unparsed → red.
:181 120 registrations (beside the true dated clause)	wrongly caught	caught correctly — the present-tense half is the stale one, which is why a line-level "dated ⇒ skip" rule would have been wrong.
RFC 7591 dynamic client registration	false positive	0 mentions — the plural rule removes it.

Left open elsewhere, deliberately

The two remaining docs/ findings from the audit — capability-constraints.md:14's moved citation
and third-party-agents-plan.md:37's reference to the deleted feat/admin-platform-metering
branch — are still unfixed. Neither is a quantity claim, so neither is catchable by this guard;
they need their own issue rather than being swept in silently. Flagging rather than fixing, since
that is a scope decision, not this ticket's work.

Also still unfixed and worth a ticket: scripts/lib/mcp-split.test.mjs:93's comment says
store/llms-full.txt "is generated". c74aaef corrected mcp-split.mjs:57, but the same claim in
the sibling test file appears to remain.

[serge-ivo]

Correction to my own comment above — I checked the last claim after posting it, and it was wrong.

I wrote that scripts/lib/mcp-split.test.mjs:93's "is generated" comment "appears to remain".
It does not. c74aaef fixed both copies, and the test file now carries the correction
explicitly (mcp-split.test.mjs:93-94):

// store/llms-full.txt states the split today but is not REQUIRED to, so it is
// checked-if-present. (This comment said "and is generated" until #604. It is not:

with the sibling at mcp-split.mjs:57-58. Nothing is outstanding there. I hedged with "appears
to" instead of grepping first, which is exactly the move this repo's issue-filing rule forbids —
recorded here rather than quietly edited.

The two docs/ findings named above (capability-constraints.md:14,
third-party-agents-plan.md:37) are verified still unfixed, and still want their own issue.