Agents write archeological, deliberation-narrating javadoc; the conventions and guards only cover roadmap citations

Split comment style out of the citation-focused "Javadoc conventions" section into its own named section, so it cannot be skimmed away as citation hygiene. The rules, stated testably rather than as adjectives:

Extend "Documentation names only live tests/code" so archeology and rejected-implementation narration join line-by-line narration and caller censuses as named smells, scoped explicitly to the comment/javadoc habitat, and draw the line the principle currently misses: why is the constraint that makes the code correct; deliberation is the process that found the constraint. Document the first, discard the second. The smell must be stated by subject so it cannot swallow the two why-not forms the repo’s own method requires: disclosed coverage gaps and measured counter-results (fact-model.adoc prices its rejected rewrites in seconds precisely so the next agent does not re-attempt them). The doc is size-budgeted by DocSizeBudgetTest and sits 14 words under the budget (3,486 against 3,500), so the addition will displace existing words: hold it to clauses on the existing smell sentence, and choose the displaced words deliberately at implementation time, which is the policy the document’s own Constraints entry already states. The smell’s Enforced by line names a pair: the phrase guard below for the named subclass, review for the rest. The Spec → Ready and In Review → Done reviewer gates already cite this principle, so this gives them something concrete to point at.

A sibling of RoadmapReferenceGuardTest (same comment-region lexing as RoadmapReferenceScanner, whose scanSource(Path, String) shape is already unit-testable over in-memory strings) that fails the build on unambiguous archeological tells in comment and javadoc regions across main and test sources. Seed phrase list: "learned the hard way", "historically", "in an earlier version", "in a previous version". Admission criterion: a phrase qualifies only if every plausible comment use narrates repository history rather than program behavior. That keeps "previously", "no longer", "used to", and "rather than" off the list; each has legitimate present-tense or dataflow readings ("a module the pom no longer declares", "used to resolve the trace glob"), and "rather than" is sometimes legitimate why. This is deliberately a lower admission bar than `RetiredVocabularyGuardTest’s demonstrated-recurrence rule: the seeds enter on the convention’s launch evidence; later additions follow the recurrence bar. The guard’s failure message teaches the day-one rule, mirroring how the citation guard’s message teaches its rewrite rule.

Three honesty requirements, each following an in-tree guard precedent:

The tree currently has three hits (InlineMultiplicityCheck, RewriteSchemaLoaderTest, TestFilmDetailsDto); rewriting them ships with the guard, each restating any real constraint in present tense per the day-one rule (in InlineMultiplicityCheck, the report-versus-gate declaration stays; only its defense goes). BuildOutputReportPipelineTest is deliberately not on the list: its only archeological wording is a "no longer" comment, which the admission criterion above keeps off the seed list, so it sits in the guard’s disclosed residue, review-enforced like the rest of the style.

Add a comment-style entry to the reviewer-prompt skill’s "What to look for" list, beside "Stale references", so that review shape reads the diff’s comments against the convention. The srp templates get nothing: their design-intent section forbids re-accreting checklists and names phrasing as out of the gate’s scope, and the workflow gates are covered anyway, since they cite the principles doc this item extends and the build guard runs regardless.

Verdict: withhold. One blocking finding on question two, one factual finding on question one. The goal comes across without reconstruction from the phase list, the diagnosis is well evidenced, and nearly every claim the spec makes about the tree checks out. The blocker is a single phase whose scope argument is built on a picture of GuardScope that is one guard out of date.

Finding 1 (question two: architecture fit). Phase 3’s "Scope by axis split, not roster fork" breaks StoreFixtureGuardTest, and the spec does not say what to do about it.

Three guards walk GuardScope.IN_SCOPE_MODULES today, not two. Besides RoadmapReferenceGuardTest and RetiredVocabularyGuardTest, which the phase names, StoreFixtureGuardTest.noTestStandsAStoreUpOutsideAHarness iterates the same roster. `GuardScope’s own class javadoc still calls it the "Shared walk scope for the prose guards", which is where the two-guard picture comes from, and `roadmap-tool-store-site-and-guard-scope’s third bullet already records that sentence as stale.

Under a single roster, subtraction can only remove, so "the phrase guard scans roadmap-tool" means the roster gains roadmap-tool. StoreFixtureGuardTest then walks roadmap-tool/src/test/java, where SchemaReferencePagesTest.rendersEveryRelationOfTheLiveCatalogExactlyOnce calls GraphitronModelStore.open() in a code region. StoreFixtureScanner recognises that type as a whole identifier token in code regions, the file is in neither HOMES nor EXEMPT, so the build goes red on a file this item never touches.

The acceptance criterion "`GuardScope` still has one module roster; per-guard subject subtractions carry their reasons" is therefore not satisfiable as written. StoreFixtureGuardTest’s subject argues against a subtraction rather than for one: `roadmap-tool-store-site-and-guard-scope names covering that site as the wanted outcome, and StoreFixtureGuardTest.Why carries exactly two permanent reasons, the store’s own lifetime being the subject and the class being a capture oracle, neither of which fits. A subtraction written anyway would state "there is an unfixed violation here", which converts a declared scope gap into a suppression.

What would satisfy this: pick an arm and write it into the phase. Adopt FactStores at the one roadmap-tool site inside this item, which is small and closes that Backlog item’s first question; or give the phrase guard an additive scope of its own and say what becomes of the one-definition invariant the phase currently protects; or write the StoreFixtureGuardTest subtraction with its real reason and record in that Backlog item that the gap became declared rather than closed. Whichever arm, say what happens to RetiredVocabularyGuardTest, which also widens. Its Java, SDL and SQL scans over roadmap-tool find nothing today, so the widening is benign, but that is a fact the spec should state rather than one the implementer discovers. The phase’s claim to settle the fork "for prose guards" is the framing that hides the third guard, so it needs revisiting too.

Finding 2 (question one: a checkable claim that does not hold). The tree has three seed-phrase hits, not four.

Scanning comment regions for the four seed phrases, with javadoc continuation lines rejoined, finds InlineMultiplicityCheck, RewriteSchemaLoaderTest and TestFilmDetailsDto. `BuildOutputReportPipelineTest’s only archeological wording is "no longer" at line 43, and the admission criterion in the same paragraph deliberately keeps "no longer" off the seed list. So either the file list is wrong or the seed list is, and I cannot tell which from the spec. Left as-is, the acceptance criterion "the current hits are rewritten" disagrees with what the guard will actually report.

Non-blocking.

DocSizeBudgetTest’s headroom is 14 words: `development-principles.adoc is 3,486 words against the 3,500-word budget. Phase 2’s "if it cannot fit" reads as a contingency when displacement is certain. The document’s own Constraints entry already makes displacement the policy, so this is phrasing rather than a design gap, but the implementer should not read the conditional as an option.

Everything else checked. RoadmapReferenceScanner.scanSource(Path, String) exists with that shape and is unit-testable over in-memory strings; RetiredVocabularyGuardTest carries the demonstrated-recurrence bar, the scanned-file floors, and a both-directions synthetic phrase test whose matchPhrases already rejoins the projected habitat so a phrase broken across a javadoc continuation line matches, which is the exact mechanism phase 3 asks for; CollectionValuedColumnGateTest carries the disclosed-gap javadoc the phase cites, and fact-model.adoc names CaptureCorpusIsolationTest in its "Not mechanically enforced" list and does price its rejected rewrites in seconds; GraphitronSchemaBuilder’s class javadoc is one sentence of what plus a boundary paragraph plus a call-order paragraph, so it calibrates the paragraph-admission rule exactly as the phase claims; `InlineMultiplicityCheck’s javadoc is the specimen described, with the report-versus-gate declaration separable from its defense; "rather than" and "instead of" appear 54 times in roadmap-tool main-source comments, so "40+" holds; `development-principles.adoc’s "Documentation names only live tests/code" names exactly the two smells the spec says it names and carries the Enforced by line; the `reviewer-prompt skill’s "What to look for" list has the "Stale references" entry to sit beside; and the srp skill’s template design intent does forbid re-accreting checklists and does name phrasing as out of the gate’s scope.

Verdict: sign off. Both round-1 findings are answered, and the adoption arm the rework picked is the one that leaves no suppression behind.

Phase 3 now names all three roster readers and says what the widening does to each. FactStores.inMemory() is GraphitronModelStore.open() plus a boot count, so SchemaReferencePagesTest’s swap is behaviour-preserving, and holding the handle in a `var leaves no GraphitronModelStore identifier token in a code region for StoreFixtureScanner to find. The test-jar dependency is a trodden path rather than a new one: graphitron-model’s pom already republishes its tests for exactly this harness, and `graphitron, graphitron-lsp, graphitron-mcp and graphitron-maven-plugin all consume it with the shape the phase describes, so roadmap-tool adds a <type>test-jar</type> entry beside a compile dependency it already declares. StoreFixtureGuardTest.Why does carry exactly LIFETIME and ORACLE, which is what rules out the subtraction and the EXEMPT entry. The anti-vacuity floors are lower bounds and the widening only adds files, so "they hold as-is" is right. RetiredVocabularyGuardTest’s widening is benign as stated: neither registry finds anything in roadmap-tool’s Java sources, its one `.graphqls fixture, or the reverse-enforcer’s main-source identifier scan.

The hit-list correction went further than either arm round 1 named, and better: three files listed, with BuildOutputReportPipelineTest placed explicitly in the guard’s disclosed residue rather than dropped in silence, which is the same honesty the phase asks of the guard’s own javadoc.

One convention note, not a finding: the round-1 findings carry no per-finding response notes beneath them. The commit message records the responses in full, so nothing is lost here; the adjacency convention exists so the Done-gate reviewer audits a delta instead of re-reading, and it is worth keeping to on the next round.