fix(spec-drift): close nine defects an adversarial review found in the freshness gate, two of them P1

[jeremylongshore]

What

Closes nine defects an adversarial review found in the freshness gate #237 shipped — two P1 — plus a provenance gap the review surfaced in its own evidence. Every finding reproduced first, fixed, then locked by a test that was mutation-verified by reverting the fix.

Why this review happened

Per the repo's own posture note, no AI reviewer runs here — Gemini is sunset, Greptile is dark. #237 merged green with a mutation-tested lock and exactly one pair of eyes. That was the real gap, and it cost two P1s.

The two P1s are the same bug this gate exists to end, re-entering by a door the lock didn't watch

F1 — the registry can name a checker in the wrong MODE

--surface is a top-level parser arg, so the wrong mode accepts and silently ignores it:

$ python3 scripts/extract-agent-definition-projection.py --check --surface totally-bogus
extract-agent-definition-projection --check: OK — committed projection is fresh.   exit=0

Swap --check-fresh → --check in any semantic_coverage.checker and the driver prints an authoritative all-green board — including plugin-marketplaces, which has real outstanding findings:

  CLEAN  plugin-marketplaces  enforced     ← this surface has 3 real findings
projection-freshness: CLEAN (exit 0) over 5 field-level surface(s).

check-surface-registry.py returned exit 0 on that registry. So did the test suite. Both validated only that checker[0] is an existing file — never what the argv means.

That lands here specifically because the registry is the file humans are told to edit ("flipping a surface to failing is a one-line registry edit"). The next person who flips a surface, sees red, and "fixes" the flag gets a green board and no gate objects.

Fixed in two layers — the registry gate pins each checker's freshness-mode flag and rejects any other mode flag (--write included, which would have the gate mutate the baseline it guards), and the extractors now reject --surface outside --check-fresh instead of ignoring it.

Chose an explicit in-script allowlist over letting the registry declare its own mode, because a config that attests to its own correctness is the thing being defended against.

F2 — plugin-manifest asserted a silently truncated closed enum

No closedness guard at all:

input	old output
One of `command` (Claude Code v2.1.200+), `http`, or `mcp_tool`.	['command']
One of `command`, `http`, or {/* min-version: … */}`mcp_tool`.	['command', 'http']

Same clause-truncation that broke permissionMode — but the three siblings behave oppositely: agent-definition and hook-config decline (residue guard); only this one produced confident nonsense.

A short enum is worse than an absence: the projection is the field-diff baseline, so the next report reads as a legitimate value removal and sends a human to reconcile a phantom. Not hypothetical — the captured plugins-reference page already carries MDX comments in table cells; it just hasn't landed on a One of row yet.

Root cause fixed, not papered over: a period followed by a digit is a version number, not a sentence end. One shared rule (captured_source.clause_end) makes all three cases correct:

One of `string`, `number`, `boolean`, `directory`, or `file`.   -> enum ['string','number','boolean','directory','file']
One of `command` (Claude Code v2.1.200+), `http`, or `mcp_tool`. -> candidates ['command','http','mcp_tool']
One of `command`, `http`, or {/* min-version… */}`mcp_tool`.     -> enum ['command','http','mcp_tool']

The other seven

#	Defect	Fix
F3/F9	driver exited CLEAN (exit 0) over 0 field-level surface(s) — contradicting its own docstring	INOPERABLE on empty; declared semantic_coverage_floor so shrinking coverage is a reviewed edit, not a quietly smaller green board
F4	bare next()/json.loads on a malformed capture → exit 1 → driver read DRIFT, so the watcher would open a reconciliation issue for a parser breakage	INOPERABLE; the 0/1/2 distinction preserved
F5	a 30-entry enum gaining one member rendered two sides byte-identical for all 400 visible chars — reader saw a differing byte count. Most likely real drift on claude-hooks, an enforced surface	scalar lists diff element-wise → LIST_CHANGED: events.enum: +["WorktreeRemove"]
F6	True == 1, 1 == 1.0 — a bool becoming an int diffed to nothing	type changes are always findings
F7	registry gate died with TypeError: unhashable type instead of naming the problem	reported, not crashed
F8	re.DOTALL on the MDX stripper — inert today, and an unbalanced {/* opening a 16-line block exists in the captured mcp-config doc	line-bounded, reason recorded

Plus a gap the review surfaced in its own evidence

Nothing verified that vendor-meta.json describes the bytes on disk. --check proves the projection derives from the files and never reads sha256 at all — so a hand re-vendor recording a wrong hash passed every gate while the provenance quietly described a file that wasn't there. Three reference docs were re-vendored by hand during this work, each editing sha256 and bytes in a text editor. That's the concrete shape of the risk.

New scripts/check-vendor-meta-integrity.py: every declared file exists, sha256 + bytes match, and no undeclared file sits in a capture dir (an input with no provenance is one vendor-meta edit from being parsed as authority). Wired into ci.yml + the scripts-tests job.

Demonstrated — corrupting a recorded sha fails the new gate while the gate people believe covers it still says OK:

vendor-meta integrity: sha256 MISMATCH — records deadbeef…, file is 504eb9c3…
extract-agent-definition-projection --check: OK — committed projection is fresh.

Verification

Check	Result
all five extractors --check + --self-test	OK — and no projection changed: the parser fixes are provably behaviour-preserving on today's pages
pytest scripts/tests/ -q	226 passed (33 new)
check-surface-registry / check-vendor-meta-integrity	OK — 5 captures, 23 files
projection-freshness	exit 0
detector-health / sak-dashboard --check	OK
audit-harness verify	OK after init

Mutation-tested by reverting each fix in turn — every one turns the suite red:

F1a mode not validated        4 failed
F1b --surface silently ignored 2 failed
F2  no closedness guard        2 failed
F3  empty map = clean          1 failed
F5  whole-value list render    1 failed
F6  no type guard              4 failed
F8  DOTALL restored            2 failed

The sweep also caught a real stale expectation in #237's own suite (test_each_diff_class_is_detected expected CHANGED_VALUE where element-wise diffing now correctly emits LIST_CHANGED). Updated the expectation, not the behaviour.

Risk

• The two parser changes are the only behaviour changes to shipped output paths, and both are verified no-ops on today's pages (no projection byte changed). They alter output only on inputs that previously produced a wrong or silent answer.
• semantic_coverage_floor is new registry state; check-surface-registry.py requires it, so a registry missing it fails loudly rather than silently disabling the floor.
• Rollback is per-commit: every fix is independent and none share a file with another's core edit except captured_source.py (F5+F6, both in _walk).

Follow-up

• The reviewer's suggested lessons entry — "a config-driven gate that validates the checker's EXISTENCE has not validated its MODE" — generalises past this repo and is worth landing in the estate lessons file.
• hook-config's _enum_from_description still renders an added value as a vanishing enum (it declines rather than recording candidates). Deliberately not changed here: its clause selection falls back to the whole description, so open-candidates there produced 14 keys of pure noise when measured. Fixing it needs its clause selection anchored first.

Refs

Refs #237