@opengsd/gsd-core 1.14.0 → 1.15.0

package/gsd-core/bin/lib/roadmap.cjs

@@ -28,7 +28,7 @@ const planningScopeMod = require("./planning-scope.cjs");
 const { SCOPE } = planningScopeMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserModule = require("./roadmap-parser.cjs");
-const { stripShippedMilestones, extractCurrentMilestone, extractCurrentMilestoneScoped, replaceInCurrentMilestone, listMilestoneHeadings, scanMilestonePhaseIds, collectTablePhaseRows } = roadmapParserModule;
+const { stripShippedMilestones, extractCurrentMilestone, extractCurrentMilestoneScoped, replaceInCurrentMilestone, listMilestoneHeadings, scanMilestonePhaseIds, collectTablePhaseRows, hasPhaseListingTableHeader } = roadmapParserModule;
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 const markdown_table_cjs_1 = require("./markdown-table.cjs");
 const phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
@@ -52,6 +52,9 @@ const { extractFrontmatter, parseMustHavesBlock } = frontmatter;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const verificationMod = require("./verification.cjs");
 const { isPhaseComplete } = verificationMod;
+// #4906 Phase 2 (#4917/ADR-4910): the PlanningDoc parse -> mutate -> serialize
+// seam, mirroring phase.cts's already-migrated `writePlansField` site.
+const planning_document_cjs_1 = require("./planning-document.cjs");
 // ─── coerceTruthToString ──────────────────────────────────────────────────────
 /**
  * Coerce an arbitrary YAML scalar/object into a string for cross-cutting
@@ -170,9 +173,9 @@ function searchPhaseInContent(content, escapedPhase, phaseNum, convention) {
         .find((candidate) => candidate.level <= currentHeading.level);
     const sectionEnd = nextHeading ? nextHeading.offset : content.length;
     const section = content.slice(headerIndex, sectionEnd).trim();
-    // Extract goal if present (supports both **Goal:** and **Goal**: formats)
-    const goalMatch = section.match(/\*\*Goal(?::\*\*|\*\*:)\s*([^\n]+)/i);
-    const goal = goalMatch ? goalMatch[1].trim() : null;
+    // Extract goal if present (supports both **Goal:** and **Goal**: formats).
+    // #4731: multiline-aware — hard-wrapped Goals read past the line break.
+    const goal = roadmapParserModule.extractPhaseFieldMultiline(section, 'Goal');
     // Mode: vertical-MVP slice mode flag. Lowercased + trimmed for canonical
     // comparison; unrecognized values are preserved verbatim for forward-compat.
     const modeMatch = section.match(/\*\*Mode(?::\*\*|\*\*:)\s*([^\n]+)/i);
@@ -392,8 +395,7 @@ function collectAnalyzePhases(content, phasesDir, phaseDirNames, convention) {
         const nextHeader = restOfContent.match(new RegExp(`\\n {0,3}#{2,4}\\s+${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.ANY_BRACKET, convention)}[A-Za-z]?\\d[\\d.-]*`, 'i'));
         const sectionEnd = nextHeader ? sectionStart + nextHeader.index : content.length;
         const section = content.slice(sectionStart, sectionEnd);
-        const goalMatch = section.match(/\*\*Goal(?::\*\*|\*\*:)\s*([^\n]+)/i);
-        const goal = goalMatch ? goalMatch[1].trim() : null;
+        const goal = roadmapParserModule.extractPhaseFieldMultiline(section, 'Goal');
         const modeMatch = section.match(/\*\*Mode(?::\*\*|\*\*:)\s*([^\n]+)/i);
         const mode = modeMatch ? modeMatch[1].trim().toLowerCase() : null;
         const dependsMatch = section.match(/\*\*Depends on(?::\*\*|\*\*:)\s*([^\n]+)/i);
@@ -658,7 +660,94 @@ function cmdRoadmapAnalyze(cwd, raw) {
         if (seenChecklistKeys.has(key))
             continue;
         seenChecklistKeys.add(key);
-        checklistOccurrences.push({ token, bracketId });
+        // #4899: the checkbox state (`[x]` vs `[ ]`) isn't a capturing group in
+        // `checklistPattern` — adding one would shift every downstream `1 + G` /
+        // `G` index this loop and `missingDetails` below already depend on.
+        // Reading it off the full match text instead is index-safe.
+        checklistOccurrences.push({ token, bracketId, checked: /\[x\]/i.test(checklistMatch[0]) });
+    }
+    // #4899: `collectAnalyzePhases` only recognises `### Phase N:` headings and
+    // progress-table rows — the shape `templates/roadmap.md` itself emits
+    // (checklist entries only, no detail sections yet) produces `phases: []`
+    // even though `checklistOccurrences` above just proved real phases exist.
+    // That evidence was computed and then discarded on the way to the final
+    // `phases: []` output (ADR-4910 §5/Phase 4). When the heading/table scan
+    // found nothing but the checklist did, synthesize a minimal `AnalyzePhase`
+    // per non-sentinel checklist occurrence — same enrichment calls
+    // (`matchPhaseDirs`, `countPhasePlansAndSummaries`, `isPhaseComplete`) the
+    // heading branch of `collectAnalyzePhases` already uses, so a synthesized
+    // phase's on-disk status is derived identically, not approximated.
+    //
+    // `missing_phase_details` is intentionally left untouched by this branch:
+    // its contract is "this checklist token has no `### Phase N:` heading or
+    // progress-table row", and that remains true for every synthesized token —
+    // synthesis fills in `phases[]` from the checklist itself, it does not
+    // manufacture a detail section. Removing these tokens from
+    // `missing_phase_details` would hide the very malformed-ROADMAP signal
+    // ADR-4910 (#4899) treats as evidence to surface, not evidence to launder.
+    //
+    // Gated on `!hasPhaseListingTableHeader(effectiveContent)` (found by the
+    // pre-existing #4480 regression "a status table cannot hide missing phase
+    // details"): a `| Phase | Status |`-shaped table with no Name column
+    // correctly declares no phases via `collectAnalyzePhases`, but its mere
+    // presence signals this roadmap has already moved to table-based tracking —
+    // synthesizing phantom phases from checklist entries alongside a
+    // deliberately thin tracking table would manufacture phase_count where the
+    // roadmap's own structure says "not yet detailed", the same laundering this
+    // branch exists to avoid for `missing_phase_details`. #4899's actual target
+    // shape (`templates/roadmap.md`: checklist only, no Progress section at
+    // all) has no such table and is unaffected.
+    if (phases.length === 0 && checklistOccurrences.length > 0 && !hasPhaseListingTableHeader(effectiveContent)) {
+        for (const occ of checklistOccurrences) {
+            if (isSentinelPhase(occ.token, occ.bracketId))
+                continue;
+            const normalized = normalizePhaseName(occ.token);
+            const dirMatch = matchPhaseDirs(_phaseDirNames, normalized, convention).matches[0];
+            let diskStatus = 'no_directory';
+            let planCount = 0;
+            let summaryCount = 0;
+            let hasContext = false;
+            let hasResearch = false;
+            let contextReadError = null;
+            let contextScope = SCOPE.COMPLETE;
+            if (dirMatch) {
+                const counts = countPhasePlansAndSummaries(node_path_1.default.join(phasesDir, dirMatch), convention);
+                planCount = counts.planCount;
+                summaryCount = counts.summaryCount;
+                hasContext = counts.hasContext;
+                hasResearch = counts.hasResearch;
+                contextReadError = counts.contextReadError;
+                contextScope = counts.scope;
+                const completionResult = isPhaseComplete(node_path_1.default.join(phasesDir, dirMatch), { convention });
+                if (completionResult.value.complete)
+                    diskStatus = 'complete';
+                else if (summaryCount > 0)
+                    diskStatus = 'partial';
+                else if (planCount > 0)
+                    diskStatus = 'planned';
+                else if (hasResearch)
+                    diskStatus = 'researched';
+                else if (hasContext)
+                    diskStatus = 'discussed';
+                else
+                    diskStatus = 'empty';
+            }
+            phases.push({
+                number: occ.token,
+                name: `Phase ${occ.token}`,
+                goal: null,
+                mode: null,
+                depends_on: null,
+                plan_count: planCount,
+                summary_count: summaryCount,
+                has_context: hasContext,
+                has_research: hasResearch,
+                disk_status: diskStatus,
+                roadmap_complete: occ.checked,
+                context_read_error: contextReadError,
+                context_scope: contextScope,
+            });
+        }
     }
     // The EMITTED value stays the bare token, unchanged: `phases[].number` is a
     // token under every convention, and `missing_phase_details` is read against
@@ -923,10 +1012,19 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         let roadmapContent = originalContent;
         const phasePattern = phaseMarkdownRegexSource(phaseNum);
         // #4247: ONE local source for the ATX phase-heading anchor that every
-        // section-scoped writer below (`planCountPattern`,
+        // section-scoped writer below (`planSectionPattern`,
         // `insertRowsPatternA|B`) starts with — extracted so the target-detection
         // gate below reads the SAME grammar the writers anchor on, and a future
         // edit to one cannot drift from the other three copies.
+        // #4906 Phase 5 (#4984): NOT migrated onto the heading-baseline selector —
+        // this write-path anchor was never one of the five ADR-4910 §8 call sites
+        // this phase owns (init.cts/milestone.cts's buildPhaseHeadingScanRegex
+        // sites); a direct any-bracket selector call here would have added a
+        // fourth uncounted ANY_BRACKET consumer to roadmap.cts's pinned
+        // tests/adr-612-bracket-heading-selection.test.cjs census. Left
+        // bracket-blind deliberately, matching this call's pre-#4984 behavior;
+        // folding it into the census is Phase 6 work.
+        // phase-id-owner: deliberately unmigrated (#4984 revert) — see comment above.
         const phaseHeadingAnchor = `#{2,4}\\s*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}(?=[:\\s])`;
         // #4247: target detection runs against the ORIGINAL content's active
         // (post-</details>) region — the same milestone scoping every writer
@@ -936,7 +1034,7 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         const gateActiveRegion = gateDetailsClose === -1
             ? originalContent
             : originalContent.slice(gateDetailsClose + '</details>'.length);
-        // Heading target: the exact grammar `planCountPattern` /
+        // Heading target: the exact grammar `planSectionPattern` /
         // `insertRowsPatternA|B` anchor on (an ATX phase heading for this phase).
         const headingTargetFound = new RegExp(phaseHeadingAnchor, 'i').test(gateActiveRegion);
         // Checklist target: when the phase is complete, its own checklist bullet
@@ -1033,7 +1131,14 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         //      `_match` unchanged. An untouched first line cannot orphan its own
         //      continuation on the next line, since the pattern never spans past
         //      `\n` in the first place.
-        const planCountPattern = new RegExp(`(${phaseHeadingAnchor}(?:(?!\\n#{1,4}\\s)[\\s\\S])*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*|(?:^|\\n)Plans:)\\s*)(\\d+\\s*\\/\\s*\\d+\\s+plans(?:\\s+(?:complete|executed))?|\\d+\\s+plans?)?([^\\r\\n]*)`, 'i');
+        // #4906 Phase 2 (#4917/ADR-4910): migrated off the one-capture-group
+        // regex that replaced to end of line onto the PlanningDoc `boldField`
+        // write seam. `planSectionPattern` scopes the match to phase N's OWN
+        // detail section (heading + body up to the next heading) — the same
+        // window `phaseHeadingAnchor`'s siblings anchor on — and the callback
+        // below runs parse -> classify -> (maybe) mutate -> serialize entirely
+        // within that section text, mirroring phase.cts's `writePlansField`.
+        const planSectionPattern = new RegExp(`${phaseHeadingAnchor}(?:(?!\\n#{1,4}\\s)[\\s\\S])*`, 'i');
         const planCountText = isComplete
             ? `${summaryCount}/${planCount} plans complete`
             : `${summaryCount}/${planCount} plans executed`;
@@ -1042,24 +1147,107 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         // gsd-core/templates/roadmap.md actually ships, not to "anything in
         // brackets" — a bracketed human annotation like `[Deferred pending
         // re-scope]` is structurally bracketed too but carries none of this
-        // wording, so it correctly falls through to arm 3 untouched.
+        // wording, so it correctly falls through to arm 3 untouched. Kept as a
+        // caller-side classifier (NOT seam grammar) reused below against the
+        // `boldField` node's own parsed `value`.
         const isTemplatePlaceholder = (value) => {
             const trimmed = value.trim();
             return /^\[\s*Number of plans\b[\s\S]*\]$/i.test(trimmed);
         };
-        roadmapContent = replaceInCurrentMilestone(roadmapContent, planCountPattern, (_match, label, existingCount, trailing) => {
-            if (existingCount) {
-                // Arm 1: real count token — rewrite it, preserve the trailing annotation.
-                return `${label}${planCountText}${trailing}`;
+        // Positive detectors for the two "real count token" shapes (#2853 /
+        // #3584 Finding B): a fraction count (`N/M plans complete|executed`) or a
+        // bare singular/plural count (`N plan`/`N plans`, the fresh single-plan
+        // template shape at gsd-core/templates/roadmap.md:62). Either one is an
+        // existing count token to overwrite (arm 1), never template placeholder
+        // (arm 2) or freeform prose (arm 3).
+        // #4906 regression fix: PREFIX match (not full-string) — a real count
+        // token may have a glued-on annotation with no ` — ` separator (e.g.
+        // `0/1 plans executed (11-16 are gap closure from VERIFICATION)`), which
+        // `parseBoldFieldLine`'s em-dash-only trailing-content split leaves
+        // entirely inside `value` (TRAILING_SEPARATOR_RE in planning-document.cts
+        // is unchanged and correct — this is a caller-side classification fix,
+        // not a seam fix). Returns the matched prefix length, or -1 if no match.
+        const fractionCountPrefixLength = (value) => {
+            const m = value.match(/^\d+\s*\/\s*\d+\s+plans(?:\s+(?:complete|executed))?/i);
+            return m ? m[0].length : -1;
+        };
+        const bareCountPrefixLength = (value) => {
+            const m = value.match(/^\d+\s+plans?/i);
+            return m ? m[0].length : -1;
+        };
+        roadmapContent = replaceInCurrentMilestone(roadmapContent, planSectionPattern, (sectionText) => {
+            const parsed = (0, planning_document_cjs_1.parsePlanningDoc)(sectionText, 'ROADMAP.md');
+            if (!parsed.ok) {
+                // Unreadable section (e.g. an unterminated frontmatter fence) —
+                // leave it byte-identical rather than throwing.
+                return sectionText;
             }
-            if (isTemplatePlaceholder(trailing)) {
-                // Arm 2: fresh-template placeholder — replace with the count.
-                return `${label}${planCountText}`;
+            const fieldId = (0, planning_document_cjs_1.findField)(parsed.value, 'Plans');
+            if (!fieldId) {
+                // #4906 regression (#1163, caught by gsd-test): a hand-edited or
+                // pre-template ROADMAP.md may carry a PLAIN (non-bold) `Plans:` line
+                // rather than the canonical `**Plans**:`/`**Plans:**` bold field.
+                // BOLD_FIELD_RE is deliberately bold-only (widening it to any bare
+                // `Label:` would register ordinary prose like "Note: see below" as a
+                // spurious field seam-wide) — this is domain knowledge about ONE
+                // field's legacy tolerated shape, the same class of thing
+                // `isTemplatePlaceholder` above already keeps caller-side rather
+                // than seam grammar, so the fallback lives here, not in
+                // planning-document.cts.
+                const plainMatch = sectionText.match(/^([ \t]*)Plans:([ \t]*)([^\r\n]*)$/m);
+                if (!plainMatch) {
+                    // No `**Plans:**`/`**Plans**:`/plain `Plans:` line in this phase's
+                    // own section — nothing to write; not a failure (mirrors the old
+                    // regex's silent no-match no-op).
+                    return sectionText;
+                }
+                const [whole, indent, spacing, plainValue] = plainMatch;
+                const plainFractionLen = fractionCountPrefixLength(plainValue);
+                const plainBareLen = bareCountPrefixLength(plainValue);
+                const plainCountPrefixLen = plainFractionLen >= 0 ? plainFractionLen : plainBareLen;
+                if (plainCountPrefixLen < 0 && !isTemplatePlaceholder(plainValue)) {
+                    // Arm 3: freeform prose, TBD, a bracketed human annotation, or an
+                    // empty value — leave the section exactly as it was.
+                    return sectionText;
+                }
+                const plainSuffix = plainCountPrefixLen >= 0 ? plainValue.slice(plainCountPrefixLen) : '';
+                const newPlainLine = `${indent}Plans:${spacing}${planCountText}${plainSuffix}`;
+                const start = plainMatch.index ?? sectionText.indexOf(whole);
+                return sectionText.slice(0, start) + newPlainLine + sectionText.slice(start + whole.length);
+            }
+            const current = (0, planning_document_cjs_1.readNode)(parsed.value, fieldId);
+            if (!current.ok) {
+                return sectionText;
+            }
+            const currentValue = current.value;
+            const fractionPrefixLen = fractionCountPrefixLength(currentValue);
+            const barePrefixLen = bareCountPrefixLength(currentValue);
+            const countPrefixLen = fractionPrefixLen >= 0 ? fractionPrefixLen : barePrefixLen;
+            if (countPrefixLen < 0 && !isTemplatePlaceholder(currentValue)) {
+                // Arm 3: freeform prose, TBD, a bracketed human annotation, or an
+                // empty value — leave the section exactly as it was.
+                return sectionText;
             }
-            // Arm 3: freeform prose, TBD, a bracketed human annotation, a wrapped
-            // sentence's first line, or an empty value — leave the line exactly as
-            // it was.
-            return _match;
+            // Arm 1 (real count token, possibly with a glued-on no-separator
+            // annotation re-attached verbatim as `suffix`) or arm 2 (fresh-template
+            // placeholder, whole value replaced): write the computed count.
+            // `setFieldValue`'s valueSpan/trailingSpan split additionally preserves
+            // any EM-DASH-separated trailing annotation (#2853) automatically — no
+            // separate "preserve trailing" branch needed for that shape.
+            const suffix = countPrefixLen >= 0 ? currentValue.slice(countPrefixLen) : '';
+            const newValueToWrite = planCountText + suffix;
+            const staged = (0, planning_document_cjs_1.setFieldValue)(parsed.value, fieldId, newValueToWrite);
+            if (!staged.ok) {
+                return sectionText;
+            }
+            const out = (0, planning_document_cjs_1.serialize)(staged.value);
+            if (!out.ok) {
+                // `hasUnreadableNodes` refusal (ADR-4910 amendment) — a ragged
+                // SIBLING node elsewhere in this same section refuses the whole
+                // splice. Never throw; leave the section unchanged.
+                return sectionText;
+            }
+            return out.value;
         });
         // If complete: check checkbox
         if (isComplete) {
@@ -1067,10 +1255,17 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
             roadmapContent = replaceInCurrentMilestone(roadmapContent, checkboxPattern, `$1x$2 (completed ${today})`);
         }
         // Mark completed plan checkboxes (e.g. "- [ ] 50-01-PLAN.md", "- [ ] 50-01:", or "- [ ] **50-01**")
-        for (const summaryFile of phaseInfo.summaries) {
-            const planId = summaryFile.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
-            if (!planId)
-                continue;
+        // #4741: tick only plans the phase's own COUNT still counts. `plans` is the
+        // superseded-filtered set (#2349 via scanPhasePlans) while `summaries` is
+        // the raw *-SUMMARY.md listing — a superseded plan can carry a SUMMARY
+        // (e.g. `status: halted`), and ticking it read as "executed" right under a
+        // count line that excludes it. The prefix match mirrors the checkbox regex
+        // below (rows match by planId prefix, which the PLAN-01.md naming shape
+        // relies on), so non-superseded plans tick exactly as before.
+        const tickableSummaries = phaseInfo.summaries
+            .map((summaryFile) => ({ summaryFile, planId: summaryFile.replace('-SUMMARY.md', '').replace('SUMMARY.md', '') }))
+            .filter(({ planId }) => planId !== '' && phaseInfo.plans.some((planFile) => planFile.startsWith(planId)));
+        for (const { planId } of tickableSummaries) {
             const planEscaped = (0, pattern_cjs_1.escapeRegex)(planId);
             const planCheckboxPattern = new RegExp(`(-\\s*\\[) (\\]\\s*(?:\\*\\*)?${planEscaped}(?:\\*\\*)?)`, 'i');
             roadmapContent = roadmapContent.replace(planCheckboxPattern, '$1x$2');
@@ -1094,9 +1289,26 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         // Detection is scoped to the active region so a plan that appears in an
         // archived <details> block is still correctly detected as missing from the
         // active milestone section.
+        //
+        // #4786: a plan row may be written WITH the `-PLAN.md` suffix (canonical
+        // template form) or WITHOUT it (hand-written form: `- [x] 659-01 — desc`).
+        // The tick loop above keys on the bare planId stem with a PREFIX match
+        // (pre-existing, out of scope here), while detection required the full
+        // `-PLAN.md` filename — so every suffix-less row was counted missing and
+        // the insertion fired BESIDE the recognized list — 32 checkbox lines for
+        // 16 plans, exit 0. The stem arm below accepts the bare id only up to a
+        // boundary (whitespace / `:` / dashes / `-PLAN.md` / `.md` / `**` / `)`),
+        // so `5-011` never satisfies `5-01`. Deliberately NOT in the boundary set:
+        // `.` — a dotted sub-id (`5-01.5`) is a real distinct plan, and counting
+        // its row as 5-01's presence would suppress a genuine insertion.
         const missingPlans = phaseInfo.plans.filter((planFile) => {
             const planEscaped = (0, pattern_cjs_1.escapeRegex)(planFile);
-            return !new RegExp(`-\\s*\\[[x ]\\]\\s*(?:\\*\\*)?${planEscaped}`, 'i').test(activeRegion);
+            if (new RegExp(`-\\s*\\[[x ]\\]\\s*(?:\\*\\*)?${planEscaped}`, 'i').test(activeRegion))
+                return false;
+            const stem = planFile.replace(/-PLAN\.md$/i, '');
+            const stemEscaped = (0, pattern_cjs_1.escapeRegex)(stem);
+            const stemPresent = new RegExp(`-\\s*\\[[x ]\\]\\s*(?:\\*\\*)?${stemEscaped}(?=$|\\s|:|—|–|-PLAN\\.md|\\.md|\\*\\*|\\))`, 'i').test(activeRegion);
+            return !stemPresent;
         });
         if (missingPlans.length > 0) {
             // Insert missing plan checklist rows (#1163).  We prefer to anchor to the
@@ -1139,10 +1351,9 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
             if (withRows !== roadmapContent) {
                 roadmapContent = withRows;
                 // Mark any newly-inserted rows that already have summaries as complete
-                for (const summaryFile of phaseInfo.summaries) {
-                    const planId = summaryFile.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
-                    if (!planId)
-                        continue;
+                // (#4741: same superseded-filtered tick list as the loop above — a
+                // pre-existing superseded row must stay unchecked on this path too).
+                for (const { planId } of tickableSummaries) {
                     const planEscaped = (0, pattern_cjs_1.escapeRegex)(planId);
                     const planCheckboxPattern = new RegExp(`(-\\s*\\[) (\\]\\s*(?:\\*\\*)?${planEscaped}(?:\\*\\*)?)`, 'i');
                     roadmapContent = roadmapContent.replace(planCheckboxPattern, '$1x$2');
@@ -1299,6 +1510,15 @@ function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
         // #3537: padding-tolerant fragment so the caller's resolved padded id
         // matches un-padded ROADMAP headings.
         const phaseEscaped = phaseMarkdownRegexSource(phaseNum);
+        // #4906 Phase 5 (#4984): NOT migrated onto the heading-baseline selector —
+        // this site was never one of the five ADR-4910 §8 call sites this phase
+        // owns (init.cts/milestone.cts's buildPhaseHeadingScanRegex sites); a
+        // direct any-bracket selector call here would have added a fifth
+        // uncounted ANY_BRACKET consumer to roadmap.cts's pinned
+        // tests/adr-612-bracket-heading-selection.test.cjs census. Left
+        // bracket-blind deliberately, matching this call's pre-#4984 behavior;
+        // folding it into the census is Phase 6 work.
+        // phase-id-owner: deliberately unmigrated (#4984 revert) — see comment above.
         const phaseHeaderPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEscaped}${OPTIONAL_PHASE_TAG_SOURCE}:[^\\n]*)`, 'i');
         const phaseMatch = content.match(phaseHeaderPattern);
         if (!phaseMatch)