Address trek-e's adversarial review on PR #3046. Two critical merge-blockers
plus four hardening items, all now covered with tests.
CRITICAL #1 — substring-version trap:
`[^<]*${escapedVersion}[^<]*` did substring containment, so
`milestone: v0.1` matched <summary>v0.10 …</summary> and returned the
v0.10 block's body as the active milestone — confidently-wrong content
worse than the pre-PR fall-through. Add `(?![\d.])` non-version-character
lookahead, mirroring the same boundary protection used by the existing
`currentVersionStr` logic on the heading path. Test asserts v0.1 active
with v0.10 sibling block returns v0.1's phases, not v0.10's.
CRITICAL #2 — nested <details> silent truncation:
The lazy `[\s\S]*?</details>` terminates on the FIRST </details>, which
is the inner closer when nesting is present. Prior comment claimed
"would mis-anchor (acceptable; falls through)" — factually wrong: the
match succeeds with truncated body and is returned with a confident
`## ${summary}` heading. Future maintainer investigating a "missing
phase" report would be misled. Add `!detailsMatch[2].includes('<details')`
guard so nesting falls through to stripShippedMilestones (loud failure)
instead of returning truncated content (silent failure). Test locks
the contract: no synthesized v0.9 heading anchored to truncated body.
HARDENING:
- Empty-body guard: `<details><summary>v0.9</summary></details>` would
synthesize `## v0.9\n` (phantom milestone, zero phases, no error
signal). Treat as no-match.
- Inline-HTML in <summary>: rejected by `[^<]*` capture. Widen to
`(?:(?!</summary>).)*?` (non-greedy until close tag) and strip tags
+ leading `#` from the captured summary before promoting to a `##`
heading. Covers GitHub-rendered <em>(active)</em>, <code>v0.9</code>,
<strong>...</strong> patterns.
- JSDoc: rewrote to describe both anchoring strategies and the
synthesized-heading contract; demoted stale "Port of core.cjs lines
1102-1170" to historical context with the divergence list.
- Comment block: rewrote in contract style ("any consumer scanning
/##\s*.*vX.Y/ sees the active milestone") instead of coupling to
specific call sites (roadmapAnalyze, "later in this file"). Adds
explicit regex anatomy + hardening-guards section so future readers
can audit each guard.
OUT OF SCOPE (per trek-e's "Recommended action" tier):
- Debug logging on fall-through paths (Suggestion #10) — adds tracing
surface to a function that doesn't currently use logger; appropriate
for a follow-up if/when other extraction bugs surface.
- Uppercase <DETAILS>/<SUMMARY> + extended attribute coverage
(Test gap #7 last two rows) — already covered by the documented `i`
flag and the existing <details open> test; adding redundant cases
inflates the test set without locking new contracts.
Verification: 45/45 roadmap.test.ts tests pass (was 41/41; added 4
hardening tests). FAMP end-to-end smoke unchanged: roadmap.get-phase 3
returns "Claude Code integration polish", roadmap.analyze surfaces
v0.9 Local-First Bus in data.milestones with phase_count: 4.
4b66ca5800