@opengsd/gsd-core 1.13.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
@@ -89,7 +92,7 @@ function coerceTruthToString(t) {
     return '';
 }
 // ─── countPhasePlansAndSummaries ──────────────────────────────────────────────
-function countPhasePlansAndSummaries(phaseDir) {
+function countPhasePlansAndSummaries(phaseDir, convention) {
     const { planCount, summaryCount } = scanPhasePlans(phaseDir);
     // hasContext and hasResearch are not plan-scan concerns — read the directory
     // once and share the listing for all non-plan metadata that cmdRoadmapAnalyze needs.
@@ -112,7 +115,9 @@ function countPhasePlansAndSummaries(phaseDir) {
     // summaryCount above stay on scanPhasePlans's own unscoped listing since a
     // PLAN/SUMMARY leading number is a plan sequence number, not a phase
     // number. Mirrors core-utils.cts's getPhaseFileStats.
-    const scopedFiles = scopeToPhase(phaseFiles, node_path_1.default.basename(phaseDir));
+    // #612: `convention` threaded from the one caller (which already threads it
+    // into matchPhaseDirs) so a bracket dir scopes by its real token.
+    const scopedFiles = scopeToPhase(phaseFiles, node_path_1.default.basename(phaseDir), convention);
     return {
         planCount,
         summaryCount,
@@ -168,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);
@@ -349,8 +354,17 @@ function collectAnalyzePhases(content, phasesDir, phaseDirNames, convention) {
     // #3036: widen the id capture to accept non-numeric-leading ids (e.g. B7, P0.3-2)
     // that get-phase/execute-phase already resolve. An optional leading letter prefix
     // ([A-Za-z]?) covers letter-prefixed ids without breaking numeric-leading ones.
+    // #4478: line-anchored (`^ {0,3}`, `/m`) — unanchored, `#{2,4}` matched a
+    // `### Phase N:`-shaped mention ANYWHERE `exec()`'s scan reached: mid-sentence
+    // prose, inside a blockquote, inside an inline code span (backtick-quoted on
+    // the same line, not a fenced block `tokenizeHeadings` would exclude). Any
+    // such line minted a phantom phase entry, inflating phase_count and able to
+    // collide on a phase NUMBER with a real heading nearby. `{0,3}` leading
+    // spaces mirrors `tokenizeHeadings`'s own CommonMark ATX-heading tolerance
+    // (src/markdown-sectionizer.cts:453) so a legitimately-indented heading that
+    // matched before this fix still matches after it.
     // phase-id-owner: uses the [.-] (dot-or-dash) separator variant, not the canonical dot-only token; a swap to PHASE_NUMBER_TOKEN_SOURCE would drop hyphenated phase-id matches.
-    const phasePattern = new RegExp(`#{2,4}\\s*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.ANY_BRACKET, convention, true)}([A-Za-z]?\\d+[A-Z]?(?:[.-]\\d+)*)(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gi');
+    const phasePattern = new RegExp(`^ {0,3}#{2,4}\\s*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.ANY_BRACKET, convention, true)}([A-Za-z]?\\d+[A-Z]?(?:[.-]\\d+)*)(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gim');
     // The capturing intro inserts the bracket id at group 1 only under the
     // bracket convention; the token and name shift by the same offset.
     const G = convention === 'bracket' ? 1 : 0;
@@ -372,11 +386,16 @@ function collectAnalyzePhases(content, phasesDir, phaseDirNames, convention) {
         // #3691: `\d` → `\d[\d.]*` so decimal phase headings (e.g. `### Phase 02.3:`) are
         // recognised as section boundaries. #3036: `[A-Za-z]?\d` so non-numeric-leading ids
         // (e.g. B7) are also recognised.
-        const nextHeader = restOfContent.match(new RegExp(`\\n#{2,4}\\s+${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.ANY_BRACKET, convention)}[A-Za-z]?\\d[\\d.-]*`, 'i'));
+        // #4478 follow-up (independent code review on this same fix): ` {0,3}` after
+        // the literal `\n` mirrors phasePattern's own new leading-space tolerance
+        // above -- without it, a legitimately-indented (1-3 space) NEXT phase
+        // heading was invisible to this boundary lookup, letting the PRIOR phase's
+        // goal/mode/depends_on extraction bleed across the section boundary into
+        // the next phase's own body.
+        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);
@@ -420,7 +439,7 @@ function collectAnalyzePhases(content, phasesDir, phaseDirNames, convention) {
         // convention into that owner rather than reviving the primitive `.find()`.
         const dirMatch = matchPhaseDirs(phaseDirNames, normalized, convention).matches[0];
         if (dirMatch) {
-            const counts = countPhasePlansAndSummaries(node_path_1.default.join(phasesDir, dirMatch));
+            const counts = countPhasePlansAndSummaries(node_path_1.default.join(phasesDir, dirMatch), convention);
             planCount = counts.planCount;
             summaryCount = counts.summaryCount;
             hasContext = counts.hasContext;
@@ -433,7 +452,10 @@ function collectAnalyzePhases(content, phasesDir, phaseDirNames, convention) {
             // NOT a precondition, so a zero-plan phase with a passing
             // `*-VERIFICATION.md` reports complete here too, not just via
             // `phase.complete`.
-            const completionResult = isPhaseComplete(node_path_1.default.join(phasesDir, dirMatch));
+            // #612: `convention` (a parameter of this function, same thread as
+            // matchPhaseDirs above) rides into completion so a bracket phase dir
+            // resolves and scopes its verification report like its legacy twin.
+            const completionResult = isPhaseComplete(node_path_1.default.join(phasesDir, dirMatch), { convention });
             if (completionResult.value.complete)
                 diskStatus = 'complete';
             else if (summaryCount > 0)
@@ -638,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
@@ -841,7 +950,11 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     // the same phase (ADR-3180 §7.4's headline: one predicate for the read
     // path and the write path).
     const phaseDir = node_path_1.default.join(cwd, phaseInfo.directory);
-    const completionResult = isPhaseComplete(phaseDir);
+    // ADR-3180 §7.4 read/write-path symmetry with the threaded site at ~583:
+    // thread convention here too, so this write path's completion reading
+    // agrees with the read path's under the bracket convention.
+    const convention = resolvePhaseIdConvention(cwd);
+    const completionResult = isPhaseComplete(phaseDir, { convention });
     const verificationResult = completionResult.value.verification;
     // #2648 precedent, applied at this write site (ADR-3180 §7.4 / #3186):
     // `isPhaseComplete` deliberately carries NO plan-count precondition — the
@@ -872,6 +985,23 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     }
     // Wrap entire read-modify-write in lock to prevent concurrent corruption
     let updated = false;
+    // #4247: the refusal flag. The write/report decision below must be keyed to
+    // "a writable roadmap representation of THIS phase was found", never to "any
+    // byte moved". On a checklist-form ROADMAP (`- [ ] **Phase N: …**`, the
+    // roadmapper's own summary-checklist form) every phase-targeted grammar
+    // below requires an ATX `#{2,4} Phase N` heading and therefore finds
+    // nothing; the Progress-table row is the only other writable target, and
+    // when its Phase cell does not match `phaseCellRe` (e.g. a word-prefixed
+    // `Phase 68` cell — deliberately unrecognized on the read side too,
+    // `deriveProgressFromRoadmap`'s `/^\d/` data-row filter) the command used
+    // to fall through to unrelated byte deltas (an UN-scoped plan-checkbox mark
+    // anywhere in the document) and report `updated: true` while the phase's
+    // own row stayed untouched — with the file-global write then letting the
+    // platform write seam's markdown normalization inject blank lines around
+    // other phases' bullets, splitting hand-wrapped sentences mid-entry. The
+    // refusal below declines with the analyzer's own `missing_phase_details`
+    // vocabulary and leaves ROADMAP.md byte-identical.
+    let missingPhaseDetails = false;
     withPlanningLock(cwd, () => {
         // #3957 (B9.4): captured BEFORE any transform runs, so the write/report
         // decision below reflects whether the transforms actually changed
@@ -881,6 +1011,41 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         const originalContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
         let roadmapContent = originalContent;
         const phasePattern = phaseMarkdownRegexSource(phaseNum);
+        // #4247: ONE local source for the ATX phase-heading anchor that every
+        // 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
+        // below applies — so the gate asks "does the file carry a writable phase
+        // representation" rather than "did some regex fire mid-transform".
+        const gateDetailsClose = originalContent.lastIndexOf('</details>');
+        const gateActiveRegion = gateDetailsClose === -1
+            ? originalContent
+            : originalContent.slice(gateDetailsClose + '</details>'.length);
+        // 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
+        // (`- [ ] **Phase N: …**`) IS a writable phase row — the completion
+        // checkbox stamp below updates it. Same grammar as that writer, widened
+        // one notch to `[ x]` so an ALREADY-checked bullet still counts as a
+        // found target: an idempotent re-run then takes the honest
+        // "no changes were needed" decline instead of this refusal.
+        const checklistTargetFound = isComplete && new RegExp(`-\\s*\\[[ x]\\]\\s*.*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'i').test(gateActiveRegion);
+        // Table-row target: set by the row-scoped cell updates below.
+        let tableRowFound = false;
         // Progress table row: update Plans Complete/Status/Completed columns BY
         // COLUMN NAME (handles 4- or 5-column RoadmapProgress tables regardless of
         // Milestone-column presence) via the markdown-table seam (ADR-2143 §7) —
@@ -899,11 +1064,15 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         roadmapContent = editProgressTableSlice(roadmapContent, (scoped) => {
             let text = scoped;
             const plansResult = (0, markdown_table_cjs_1.updateTableCell)(text, rowMatch, 'Plans Complete', ` ${summaryCount}/${planCount} `);
-            if (plansResult.ok)
+            if (plansResult.ok) {
                 text = plansResult.value;
+                tableRowFound = true;
+            }
             const statusResult = (0, markdown_table_cjs_1.updateTableCell)(text, rowMatch, 'Status', ` ${status.padEnd(11)}`);
-            if (statusResult.ok)
+            if (statusResult.ok) {
                 text = statusResult.value;
+                tableRowFound = true;
+            }
             // Preserve only a valid ISO date (#1161: idempotent; self-heal garbage).
             // Ragged-tolerant (#2245 Blocker 2): probe the CURRENT Completed cell via
             // a no-op updateTableCell write (its own tolerant row scan) rather than
@@ -918,8 +1087,10 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
                 }
                 return '  ';
             });
-            if (completedResult.ok)
+            if (completedResult.ok) {
                 text = completedResult.value;
+                tableRowFound = true;
+            }
             return text;
         });
         // Update plan count in phase detail section.
@@ -960,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(`(#{2,4}\\s*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}(?=[:\\s])(?:(?!\\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`;
@@ -969,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;
+            }
+            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;
             }
-            if (isTemplatePlaceholder(trailing)) {
-                // Arm 2: fresh-template placeholder — replace with the count.
-                return `${label}${planCountText}`;
+            // 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;
             }
-            // 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;
+            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) {
@@ -994,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');
@@ -1021,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
@@ -1040,8 +1325,8 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
             //
             // Pattern A: anchor to bare `Plans:` header (preferred).
             // Pattern B: fallback to bold summary when no bare header exists.
-            const insertRowsPatternA = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}(?=[:\\s])(?:(?!\\n#{1,4}\\s)[\\s\\S])*?(?:^|\\n)(?:Plans:)[^\\n]*)`, 'i');
-            const insertRowsPatternB = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}${OPTIONAL_PHASE_TAG_SOURCE}(?=[:\\s])(?:(?!\\n#{1,4}\\s)[\\s\\S])*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*)[^\\n]*)`, 'i');
+            const insertRowsPatternA = new RegExp(`(${phaseHeadingAnchor}(?:(?!\\n#{1,4}\\s)[\\s\\S])*?(?:^|\\n)(?:Plans:)[^\\n]*)`, 'i');
+            const insertRowsPatternB = new RegExp(`(${phaseHeadingAnchor}(?:(?!\\n#{1,4}\\s)[\\s\\S])*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*)[^\\n]*)`, 'i');
             const sortedMissing = [...missingPlans].sort();
             const newRows = sortedMissing.map(p => `- [ ] ${p}`).join('\n');
             const inserter = (match) => `${match}\n${newRows}`;
@@ -1066,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');
@@ -1081,10 +1365,24 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         // `cmdRoadmapAnnotateDependencies`'s existing `nextContent !== content`
         // gate. Previously this wrote and reported `updated: true`
         // unconditionally, even on an idempotent re-run that changed nothing.
-        if (roadmapContent !== originalContent) {
+        //
+        // #4247: ...but ONLY when a writable representation of THIS phase was
+        // found. Without the target gate, a byte delta from an unrelated
+        // transform (the un-scoped plan-checkbox mark) satisfied the #3957 gate
+        // and produced a success-shaped `updated: true` while the phase's own
+        // row stayed untouched — and the file-global write let the platform
+        // write seam's markdown normalization reflow unrelated entries. When no
+        // target exists the command refuses: no write at all, so ROADMAP.md is
+        // left byte-identical, and the caller gets a typed
+        // `missing_phase_details` decline instead of a false green.
+        const phaseRepresentationFound = tableRowFound || headingTargetFound || checklistTargetFound;
+        if (phaseRepresentationFound && roadmapContent !== originalContent) {
             (0, shell_command_projection_cjs_1.platformWriteSync)(roadmapPath, roadmapContent);
             updated = true;
         }
+        if (!phaseRepresentationFound) {
+            missingPhaseDetails = true;
+        }
     });
     const computed = {
         phase: phaseNum,
@@ -1097,6 +1395,13 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     if (updated) {
         output({ updated: true, ...computed }, raw, `${summaryCount}/${planCount} ${status}`);
     }
+    else if (missingPhaseDetails) {
+        // #4247: honest refusal — the reason names the real condition (the
+        // analyzer's `missing_phase_details` vocabulary), never "already
+        // reflects", which was false: the ROADMAP was never able to record this
+        // phase's progress in the first place.
+        declineNoOp(raw, 'updated', 'missing_phase_details', `roadmap update-plan-progress skipped — ROADMAP.md has no writable entry for phase ${formatDiagnosticToken(String(phaseNum))} (no matching Progress-table row, no phase detail section, and no checklist entry this command can update). ROADMAP.md was left unchanged.`, computed);
+    }
     else {
         declineNoOp(raw, 'updated', "no changes were needed — ROADMAP.md already reflects this phase's plan/summary counts and status", "roadmap update-plan-progress skipped — no changes were needed; ROADMAP.md already reflects this phase's plan/summary counts and status.", computed);
     }
@@ -1205,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)