ID |
|
|---|---|
Status |
Backlog |
Bucket |
cleanup |
Priority |
4 |
Created |
2026-07-26 |
Updated |
2026-07-26 |
Retire transient roadmap-ID citations from pom.xml comments
The transient-citation rule in CLAUDE.md ("Javadoc conventions") is enforced by
RoadmapReferenceGuardTest, which scans Java comment and string-literal regions. Build
configuration is a third habitat that no scan reaches: nine pom.xml files carry roadmap-ID
citations in XML comments, spanning 22 distinct IDs, and the rot has already happened. The
Java-17 floor comment in graphitron-jakarta-rest/pom.xml explains why the module carries no
@Test classes by citing an item whose file no longer exists under roadmap/, so a contributor
reading that comment has no way to recover the reason.
These comments are load-bearing in the same way javadoc is: they explain why a plugin execution,
a <release> override, or a deploy-skip flag is shaped the way it is, and a reader with no
roadmap/ directory (a consumer inspecting a published pom, or any contributor after the item
ships) gets a dangling reference instead of a rationale. The fix has the same shape the rule
already prescribes for javadoc: state the fact, or point at the durable doc page that carries the
rationale, and drop the citation. Whether the sweep earns a mechanical guard is a Spec-stage
question; the citation-recurrence check being scoped to prose documents leaves this habitat open
either way.
The published docs/architecture/ pages are a fourth habitat with the same exposure and a wider
audience: the module reference page cites two items in a single table row, one of them the same dead
id as the pom comment. Whether the two habitats are one sweep or two items is a Spec-stage question;
the argument for one is that the fix and the judgment call ("is this citation load-bearing enough to
replace, or does the fact stand alone?") are identical in both.
Surfaced by the Spec review of the agent-onboarding surface item, which corrects the same drift in
CLAUDE.md and .claude/web-environment.md, adds the prose-document guard, and scopes both of
these habitats out.