@pareto4/pp-core 1.11.1 → 1.12.0

package/pp-core/bin/lib/roadmap-parser.cjs

@@ -12,8 +12,9 @@
  * Dependencies (leaf modules only — no loadConfig):
  *   - node:fs / node:path (stdlib)
  *   - ./phase-id.cjs        (escapeRegex, phaseMarkdownRegexSource)
- *   - ./planning-workspace.cjs (planningDir)
+ *   - ./planning-workspace.cjs (planningDir, milestonePathsFor)
  *   - ./shell-command-projection.cjs (platformReadSync)
+ *   - ./core-utils.cjs      (generateSlugInternal — the phase-dir slug owner)
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -25,7 +26,10 @@ const phaseIdModule = require("./phase-id.cjs");
 const { escapeRegex, phaseMarkdownRegexSource } = phaseIdModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
-const { planningDir } = planningWorkspace;
+const { planningDir, milestonePathsFor } = planningWorkspace;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const coreUtilsModule = require("./core-utils.cjs");
+const { generateSlugInternal } = coreUtilsModule;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // ─── Roadmap milestone scoping ───────────────────────────────────────────────
 /**
@@ -37,6 +41,25 @@ function stripShippedMilestones(content) {
 /**
  * Extract the current milestone section from ROADMAP.md by positive lookup.
  */
+/**
+ * The `<details>` block whose `<summary>` names `version` — the collapsed shape
+ * templates/roadmap.md gives a shipped milestone — as [start, end) offsets, or null.
+ * One owner for both extractCurrentMilestone (version from STATE.md) and milestoneScope
+ * (version asked for), 261007-mmz follow-up 4.
+ */
+function summaryDetailsBlock(content, version) {
+    const summaryPattern = new RegExp(`<summary[^>]*>([^<]*${escapeRegex(version)}[^<]*)<\\/summary>`, 'i');
+    const summaryMatch = content.match(summaryPattern);
+    if (!summaryMatch)
+        return null;
+    const summaryIdx = content.indexOf(summaryMatch[0]);
+    const detailsOpenIdx = content.slice(0, summaryIdx).lastIndexOf('<details');
+    if (detailsOpenIdx === -1)
+        return null;
+    const closingMatch = content.slice(detailsOpenIdx).match(/<\/details>/i);
+    const end = closingMatch ? detailsOpenIdx + (closingMatch.index ?? 0) + '</details>'.length : content.length;
+    return { start: detailsOpenIdx, end };
+}
 function extractCurrentMilestone(content, cwd) {
     if (!cwd)
         return stripShippedMilestones(content);
@@ -62,29 +85,18 @@ function extractCurrentMilestone(content, cwd) {
         return stripShippedMilestones(content);
     const escapedVersion = escapeRegex(version);
     const sectionPattern = new RegExp(`(^#{1,3}\\s+(?!Phase\\s+\\S).*${escapedVersion}\\b[^\\n]*)`, 'gmi');
-    const summaryPattern = new RegExp(`<summary[^>]*>([^<]*${escapedVersion}[^<]*)<\\/summary>`, 'i');
     const headingMatches = [...content.matchAll(sectionPattern)];
     if (headingMatches.length === 0) {
-        const summaryMatch = content.match(summaryPattern);
-        if (summaryMatch) {
-            const summaryIdx = content.indexOf(summaryMatch[0]);
-            const beforeSummary = content.slice(0, summaryIdx);
-            const detailsOpenIdx = beforeSummary.lastIndexOf('<details');
-            if (detailsOpenIdx !== -1) {
-                const afterDetails = content.slice(detailsOpenIdx);
-                const closingMatch = afterDetails.match(/<\/details>/i);
-                const detailsEnd = closingMatch
-                    ? detailsOpenIdx + (closingMatch.index ?? 0) + '</details>'.length
-                    : content.length;
-                const anyMilestoneOrDetails = /^#{1,3}\s+(?!Phase\s+\S)(?:.*v\d+\.\d+|✅|📋|🚧|🔄)|<details/im;
-                const firstMilestoneMatch = content.match(anyMilestoneOrDetails);
-                const preambleCutoff = firstMilestoneMatch ? firstMilestoneMatch.index : detailsOpenIdx;
-                const preamble = content.slice(0, preambleCutoff)
-                    .replace(/<details>[\s\S]*?<\/details>/gi, '')
-                    .replace(/^#{2,4}\s*Phase\s+[\w][\w.-]*\s*:[^\n]*(?:\n(?!#{1,6}\s)[^\n]*)*\n?/gim, '')
-                    .replace(/^#{1,4}\s*Phase Details\b[^\n]*\n?/gim, '');
-                return preamble + content.slice(detailsOpenIdx, detailsEnd);
-            }
+        const block = summaryDetailsBlock(content, version);
+        if (block) {
+            const anyMilestoneOrDetails = /^#{1,3}\s+(?!Phase\s+\S)(?:.*v\d+\.\d+|✅|📋|🚧|🔄)|<details/im;
+            const firstMilestoneMatch = content.match(anyMilestoneOrDetails);
+            const preambleCutoff = firstMilestoneMatch ? firstMilestoneMatch.index : block.start;
+            const preamble = content.slice(0, preambleCutoff)
+                .replace(/<details>[\s\S]*?<\/details>/gi, '')
+                .replace(/^#{2,4}\s*Phase\s+[\w][\w.-]*\s*:[^\n]*(?:\n(?!#{1,6}\s)[^\n]*)*\n?/gim, '')
+                .replace(/^#{1,4}\s*Phase Details\b[^\n]*\n?/gim, '');
+            return preamble + content.slice(block.start, block.end);
         }
         return stripShippedMilestones(content);
     }
@@ -178,6 +190,71 @@ function replaceInCurrentMilestone(content, pattern, replacement) {
     const after = content.slice(offset);
     return before + after.replace(pattern, replacement);
 }
+// ─── The phase-section-bounded Plans line (D-08-33) ───────────────────────────
+/**
+ * A lazy scan that CANNOT leave the phase section it started in.
+ *
+ * Each step is tempered by a negative lookahead for the next phase heading, so
+ * a pattern anchored on `### Phase N` reaches only text that still belongs to
+ * phase N. `[\s\S]*?` on its own does not stop at a heading, and both roadmap
+ * writers used exactly that: given a phase section with no Plans line, the scan
+ * walked into the NEXT phase and wrote there.
+ *
+ * Owned here, in one place, because that bound is the property both the summary
+ * line pattern and `cmdRoadmapUpdatePlanProgress`'s row-insertion anchors need,
+ * and three copies of it would be three chances to lose it again (D-08-33).
+ *
+ * ReDoS shape (T-08-52): one lazy loop over a single character class, guarded
+ * by a lookahead with no quantifier of its own beyond the bounded `#{2,4}\s*`.
+ * There is no nested quantifier for a hostile roadmap to exploit; the
+ * `bug-663-redos-roadmap-phase-parsing` and `feat-3594-parser-adversarial-roadmap`
+ * suites are the standing regression net (an elapsed-time assertion is banned by
+ * `local/no-elapsed-assertion`).
+ */
+const PHASE_SECTION_SCAN = '(?:(?!\\n#{2,4}\\s*Phase\\s)[\\s\\S])*?';
+/**
+ * The three Plans-summary-line spellings a ROADMAP.md may use. All are
+ * tolerated; the canonical template (`pp-core/templates/roadmap.md`) writes the
+ * first:
+ *   `**Plans**: N plans`  — bold word, colon OUTSIDE the bold markers
+ *   `**Plans:** N plans`  — colon INSIDE the bold markers
+ *   `Plans: N plans`      — plain-text header at start of a line
+ */
+const PLANS_SUMMARY_SPELLINGS = '(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*|(?:^|\\n)Plans:)';
+/**
+ * Build the pattern that locates ONE phase's Plans summary line and captures
+ * everything up to (and including) its `Plans:` marker, leaving the line's value
+ * as the unmatched tail for the caller to replace.
+ *
+ * `pattern.replace(p, '$1<new value>')` therefore rewrites the value and nothing
+ * else. Group 1 spans from the phase heading to the marker.
+ *
+ * FOUR properties, each of which one of the two call sites was missing before
+ * plan 08-10 (D-08-33):
+ *
+ *   1. All three spellings. `cmdPhaseComplete` knew only `**Plans:**`, so on a
+ *      CANONICAL roadmap — `**Plans**:`, colon outside — it did not find its own
+ *      phase's line and kept scanning.
+ *   2. The `(?=[:\s])` phase-number boundary. Without it `Phase 1` matches the
+ *      heading `Phase 10`; `cmdRoadmapUpdatePlanProgress` had this guard and
+ *      `cmdPhaseComplete` did not.
+ *   3. The phase-section bound (`PHASE_SECTION_SCAN`). This is the F2 defect
+ *      measured on the live UAT fixture: `phase complete 1` rewrote line 90 of
+ *      ROADMAP.md — inside `### Phase 2` — to `2/2 plans complete`, asserting a
+ *      build that had never happened for a phase with nothing executed. The
+ *      same latent bug sat in `cmdRoadmapUpdatePlanProgress`.
+ *   4. A same-line tail (`[^\S\n]*`, horizontal whitespace only). Both sites
+ *      used `\s*`, which crosses newlines: a bare `Plans:` checklist HEADER on
+ *      its own line would have had the first checklist row below it consumed and
+ *      rewritten into a count.
+ *
+ * Consumers: `cmdRoadmapUpdatePlanProgress` (src/roadmap.cts) and
+ * `cmdPhaseComplete` (src/phase.cts). Neither carries its own copy.
+ */
+function buildPlansSummaryLinePattern(phaseNum) {
+    const phaseSource = phaseMarkdownRegexSource(phaseNum);
+    return new RegExp(`(#{2,4}\\s*Phase\\s+${phaseSource}(?=[:\\s])${PHASE_SECTION_SCAN}${PLANS_SUMMARY_SPELLINGS}[^\\S\\n]*)[^\\n]+`, 'i');
+}
 function findRoadmapPhaseInContent(content, phaseNum) {
     const phasePattern = new RegExp(`#{2,4}\\s*(?:\\[[^\\]]+\\]\\s*)?Phase\\s+${phaseMarkdownRegexSource(phaseNum)}:\\s*([^\\n]+)`, 'i');
     const headerMatch = content.match(phasePattern);
@@ -219,7 +296,7 @@ function getRoadmapPhaseInternal(cwd, phaseNum) {
         return null;
     }
 }
-function getMilestoneInfo(cwd) {
+function resolveMilestoneInfo(cwd) {
     try {
         const roadmap = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md'));
         if (roadmap === null)
@@ -239,45 +316,83 @@ function getMilestoneInfo(cwd) {
         }
         if (stateVersion) {
             const escapedVer = escapeRegex(stateVersion);
-            const headingMatch = roadmap.match(new RegExp(`##[^\\n]*${escapedVer}[:\\s]+([^\\n(]+)`, 'i'));
+            // 261007-ixt W3c: a `### Phase N: vX.Y …` heading names a version without
+            // declaring it, so it must not supply the milestone's name.
+            const headingMatch = roadmap.match(new RegExp(`^#{2,}\\s+(?!Phase\\s+\\S)[^\\n]*${escapedVer}[:\\s]+([^\\n(]+)`, 'im'));
             if (headingMatch) {
                 if (!headingMatch[0].includes('✅')) {
-                    return { version: stateVersion, name: headingMatch[1].trim() };
+                    return { info: { version: stateVersion, name: headingMatch[1].trim() }, declared: true };
                 }
             }
             else {
                 const listMatch = roadmap.match(new RegExp(`🚧\\s*\\*?\\*?${escapedVer}\\s+([^*\\n]+)`, 'i'));
                 if (listMatch) {
-                    return { version: stateVersion, name: listMatch[1].trim() };
+                    return { info: { version: stateVersion, name: listMatch[1].trim() }, declared: true };
+                }
+                const bodyMatch = roadmap.match(new RegExp(`^\\*\\*\\s*Milestone\\s+${escapedVer}\\s*[—–:-]+\\s*([^*\\n]+?)\\s*\\*\\*`, 'im'));
+                if (bodyMatch) {
+                    return { info: { version: stateVersion, name: bodyMatch[1].trim() }, declared: true };
                 }
-                return { version: stateVersion, name: 'milestone' };
+                return { info: { version: stateVersion, name: 'milestone' }, declared: true };
             }
         }
         const inProgressMatch = roadmap.match(/🚧\s*\*\*v(\d+(?:\.\d+)+)\s+([^*]+)\*\*/);
         if (inProgressMatch) {
-            return {
-                version: 'v' + inProgressMatch[1],
-                name: inProgressMatch[2].trim(),
-            };
+            return { info: {
+                    version: 'v' + inProgressMatch[1],
+                    name: inProgressMatch[2].trim(),
+                }, declared: true };
         }
         const cleaned = stripShippedMilestones(roadmap);
-        const headingMatch = cleaned.match(/## (?!.*✅).*v(\d+(?:\.\d+)+)[:\s]+([^\n(]+)/);
+        // 261007-ixt W3c: a PHASE heading that names a version (`### Phase 12: v1.0
+        // Carry-Forward Closure`) does not declare that milestone — the same rule
+        // getMilestonePhaseFilter's `(?!Phase\s+\S)` lookahead applies (CARRY-04). With no
+        // STATE.md to read (health --repair regenerating it), this branch used to name
+        // the regenerated v1.1 record `v1.0 Carry-Forward Closure`.
+        const headingMatch = cleaned.match(/^#{2,}\s+(?!Phase\s+\S)(?!.*✅).*v(\d+(?:\.\d+)+)[:\s]+([^\n(]+)/m);
         if (headingMatch) {
-            return {
-                version: 'v' + headingMatch[1],
-                name: headingMatch[2].trim(),
-            };
+            return { info: {
+                    version: 'v' + headingMatch[1],
+                    name: headingMatch[2].trim(),
+                }, declared: true };
+        }
+        // A milestone declared in bold body text — `**Milestone v1.1 — Vault Hardening**`,
+        // the form CARRY-04 taught getMilestonePhaseFilter to recognise.
+        const bodyDeclared = cleaned.match(/^\*\*\s*Milestone\s+v(\d+(?:\.\d+)+)\s*[—–:-]+\s*([^*\n]+?)\s*\*\*/m);
+        if (bodyDeclared) {
+            return { info: {
+                    version: 'v' + bodyDeclared[1],
+                    name: bodyDeclared[2].trim(),
+                }, declared: true };
         }
+        // Last resort: nothing DECLARES a current milestone (no STATE.md version, no
+        // in-progress marker, no milestone heading, no bold-body declaration). The first
+        // version the text mentions is a guess — between milestones it is whichever closed
+        // milestone the completed list happens to name first (261007-ixt W4).
         const versionMatch = cleaned.match(/v(\d+(?:\.\d+)+)/);
         return {
-            version: versionMatch ? versionMatch[0] : 'v1.0',
-            name: 'milestone',
+            info: { version: versionMatch ? versionMatch[0] : 'v1.0', name: 'milestone' },
+            declared: false,
         };
     }
     catch {
-        return { version: 'v1.0', name: 'milestone' };
+        return { info: { version: 'v1.0', name: 'milestone' }, declared: false };
     }
 }
+/**
+ * The milestone the planning documents DECLARE as current, or null when nothing
+ * declares one (261007-ixt W4). getMilestoneInfo keeps its long-standing last-resort
+ * guess for display callers; a writer that stores the milestone in a record must not
+ * store a guess — between milestones the guess was whichever closed milestone the
+ * ROADMAP's completed list named first.
+ */
+function getDeclaredMilestoneInfo(cwd) {
+    const resolved = resolveMilestoneInfo(cwd);
+    return resolved.declared ? resolved.info : null;
+}
+function getMilestoneInfo(cwd) {
+    return resolveMilestoneInfo(cwd).info;
+}
 // ─── Fence-aware text helper ──────────────────────────────────────────────────
 /**
  * Return a copy of `text` with every line that lies inside a fenced code block
@@ -319,6 +434,90 @@ function stripFencedLines(text) {
     }
     return result.join('\n');
 }
+/**
+ * 261007-mmz follow-up 3: the ONE owner of "which part of a ROADMAP text belongs to
+ * milestone <version>". Extracted verbatim from getMilestonePhaseFilter (which now
+ * calls it), so `milestone complete` and the closed-milestone snapshot reader scope a
+ * text the same way. With no versionOverride the scope is the current milestone
+ * (STATE.md-keyed when cwd is given, otherwise the document minus shipped blocks).
+ */
+function milestoneScope(roadmapContent, versionOverride, cwd) {
+    // 261007-mmz follow-up 4: when a version is asked for, STATE.md is never consulted —
+    // the answer depends on the text and the version only, so `milestone complete vX`
+    // (cwd) and the archived-snapshot reader (no cwd) scope the same text the same way.
+    // STATE.md keys only the no-version "current milestone" question.
+    let roadmap = versionOverride ? extractCurrentMilestone(roadmapContent) : extractCurrentMilestone(roadmapContent, cwd);
+    let missingExplicitVersion = false;
+    if (versionOverride) {
+        const escapedVersion = escapeRegex(versionOverride);
+        const sectionPattern = new RegExp(`(^#{1,3}\\s+(?!Phase\\s+\\S).*${escapedVersion}[^\\n]*)`, 'mi');
+        const sectionMatch = roadmapContent.match(sectionPattern);
+        // A milestone declared only in a <summary> (the collapsed templates/roadmap.md shape)
+        // is scoped to ITS <details> block. This used to fall through to the current-milestone
+        // read: with cwd, STATE.md's milestone (v1.0 → 1-4, but v1.1 → v1.1's phases); without
+        // cwd, the document minus shipped blocks — i.e. everything EXCEPT the requested
+        // milestone (measured: v1.0's snapshot owned {5}, not {1..4}).
+        const summaryBlock = sectionMatch ? null : summaryDetailsBlock(roadmapContent, versionOverride);
+        if (summaryBlock) {
+            roadmap = roadmapContent.slice(summaryBlock.start, summaryBlock.end);
+        }
+        else if (!sectionMatch) {
+            const hasVersionedMilestones = /^#{1,3}\s+(?!Phase\s+\S).*v\d+\.\d+/mi.test(roadmapContent);
+            // A milestone is not always declared in a HEADING. The vault-assurance
+            // workstream declares its milestone on line 3 of its ROADMAP in bold
+            // body text — `**Milestone v1.1 — Vault Hardening** · started …` — while
+            // its only version-bearing heading is `### Phase 12: v1.0 …`, which the
+            // `(?!Phase\s+\S)` lookahead excludes ON PURPOSE: a phase heading that
+            // merely NAMES a version does not declare that milestone. Before phase
+            // 12 that combination left hasVersionedMilestones false for every
+            // requested version, so the guard could never fire, `roadmap` stayed
+            // scoped to the CURRENT milestone, and `milestone complete v1.0`
+            // archived the current milestone's phases under a v1.0 label and
+            // exited 0. Recognising the bold-body form is what closes CARRY-04.
+            const declaresBodyMilestone = /^\*\*\s*Milestone\s+v\d+\.\d+/mi.test(roadmapContent);
+            const bodyDeclaresRequested = new RegExp(`^\\*\\*\\s*Milestone\\s+${escapedVersion}\\b`, 'mi').test(roadmapContent);
+            const versionInSummary = new RegExp(`<summary[^>]*>[^<]*${escapedVersion}[^<]*<\\/summary>`, 'i').test(roadmapContent);
+            if ((hasVersionedMilestones || declaresBodyMilestone) && !versionInSummary && !bodyDeclaresRequested) {
+                roadmap = '';
+                missingExplicitVersion = true;
+            }
+        }
+        else {
+            const sectionStart = sectionMatch.index;
+            const headingLevel = (sectionMatch[1].match(/^(#{1,3})\s/) ?? ['', '#'])[1].length;
+            const restContent = roadmapContent.slice(sectionStart + sectionMatch[0].length);
+            const nextMilestonePattern = new RegExp(`^#{1,${headingLevel}}\\s+(?!Phase\\s+\\S)(?:.*v\\d+\\.\\d+|✅|📋|🚧)`, 'i');
+            let sectionEnd = roadmapContent.length;
+            let fenceChar = null;
+            let fenceLen = 0;
+            let charOffset = 0;
+            for (const line of restContent.split('\n')) {
+                const fenceMatch = line.match(/^\s{0,3}((?:`{3,}|~{3,}))(.*)/);
+                if (fenceMatch) {
+                    const char = fenceMatch[1][0];
+                    const len = fenceMatch[1].length;
+                    const trailing = fenceMatch[2] || '';
+                    if (!fenceChar) {
+                        fenceChar = char;
+                        fenceLen = len;
+                    }
+                    else if (char === fenceChar && len >= fenceLen && /^\s*$/.test(trailing)) {
+                        fenceChar = null;
+                        fenceLen = 0;
+                    }
+                }
+                else if (!fenceChar && nextMilestonePattern.test(line)) {
+                    sectionEnd = sectionStart + sectionMatch[0].length + charOffset;
+                    break;
+                }
+                charOffset += line.length + 1;
+            }
+            const currentSection = roadmapContent.slice(sectionStart, sectionEnd);
+            roadmap = currentSection;
+        }
+    }
+    return { scope: roadmap, missingExplicitVersion };
+}
 /**
  * Returns a filter function that checks whether a phase directory belongs
  * to the current milestone based on ROADMAP.md phase headings.
@@ -335,12 +534,18 @@ function stripFencedLines(text) {
 function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention) {
     const milestonePhaseNums = new Set();
     let missingExplicitVersion = false;
+    let roadmapMissing = false;
     try {
         const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
         const roadmapContent = (0, shell_command_projection_cjs_1.platformReadSync)(roadmapPath);
-        if (roadmapContent === null)
+        if (roadmapContent === null) {
+            // The catch at the end of this block swallows the throw and the tail
+            // returns a pass-all filter. That stays as it is — the FLAG, not the
+            // catch, is what now carries the information out, so every caller's
+            // control flow is byte-identical (phase 12, CARRY-04).
+            roadmapMissing = true;
             throw new Error('missing');
-        let roadmap = extractCurrentMilestone(roadmapContent, cwd);
+        }
         const hasVersionedMilestonesGlobal = /^#{1,3}\s+.*v\d+\.\d+/mi.test(roadmapContent);
         const hasPhaseHeadings = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+[\w]/i.test(roadmapContent);
         if (!hasVersionedMilestonesGlobal && hasPhaseHeadings && phaseIdConvention === 'milestone-prefixed') {
@@ -348,63 +553,9 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention) {
                 'The project has phase_id_convention set to "milestone-prefixed" in config.json but the ' +
                 'ROADMAP does not use versioned milestone headings. Run `pp-tools roadmap upgrade --convention milestone-prefixed` to migrate (dry-run by default).');
         }
-        if (versionOverride) {
-            const escapedVersion = escapeRegex(versionOverride);
-            const sectionPattern = new RegExp(`(^#{1,3}\\s+(?!Phase\\s+\\S).*${escapedVersion}[^\\n]*)`, 'mi');
-            let sectionMatch = roadmapContent.match(sectionPattern);
-            if (!sectionMatch) {
-                const summaryPat = new RegExp(`<summary[^>]*>[^<]*${escapedVersion}[^<]*<\\/summary>`, 'i');
-                const summaryHit = roadmapContent.match(summaryPat);
-                if (summaryHit) {
-                    const beforeSummary = roadmapContent.slice(0, summaryHit.index);
-                    const detailsIdx = beforeSummary.lastIndexOf('<details');
-                    if (detailsIdx !== -1) {
-                        sectionMatch = null;
-                    }
-                }
-            }
-            if (!sectionMatch) {
-                const hasVersionedMilestones = /^#{1,3}\s+(?!Phase\s+\S).*v\d+\.\d+/mi.test(roadmapContent);
-                const versionInSummary = new RegExp(`<summary[^>]*>[^<]*${escapedVersion}[^<]*<\\/summary>`, 'i').test(roadmapContent);
-                if (hasVersionedMilestones && !versionInSummary) {
-                    roadmap = '';
-                    missingExplicitVersion = true;
-                }
-            }
-            else {
-                const sectionStart = sectionMatch.index;
-                const headingLevel = (sectionMatch[1].match(/^(#{1,3})\s/) ?? ['', '#'])[1].length;
-                const restContent = roadmapContent.slice(sectionStart + sectionMatch[0].length);
-                const nextMilestonePattern = new RegExp(`^#{1,${headingLevel}}\\s+(?!Phase\\s+\\S)(?:.*v\\d+\\.\\d+|✅|📋|🚧)`, 'i');
-                let sectionEnd = roadmapContent.length;
-                let fenceChar = null;
-                let fenceLen = 0;
-                let charOffset = 0;
-                for (const line of restContent.split('\n')) {
-                    const fenceMatch = line.match(/^\s{0,3}((?:`{3,}|~{3,}))(.*)/);
-                    if (fenceMatch) {
-                        const char = fenceMatch[1][0];
-                        const len = fenceMatch[1].length;
-                        const trailing = fenceMatch[2] || '';
-                        if (!fenceChar) {
-                            fenceChar = char;
-                            fenceLen = len;
-                        }
-                        else if (char === fenceChar && len >= fenceLen && /^\s*$/.test(trailing)) {
-                            fenceChar = null;
-                            fenceLen = 0;
-                        }
-                    }
-                    else if (!fenceChar && nextMilestonePattern.test(line)) {
-                        sectionEnd = sectionStart + sectionMatch[0].length + charOffset;
-                        break;
-                    }
-                    charOffset += line.length + 1;
-                }
-                const currentSection = roadmapContent.slice(sectionStart, sectionEnd);
-                roadmap = currentSection;
-            }
-        }
+        const scoped = milestoneScope(roadmapContent, versionOverride, cwd);
+        const roadmap = scoped.scope;
+        missingExplicitVersion = scoped.missingExplicitVersion;
         const phasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)\s*:/gi;
         const roadmapUnfenced = stripFencedLines(roadmap);
         let m;
@@ -417,6 +568,7 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention) {
         const passAll = (() => true);
         passAll.phaseCount = 0;
         passAll.missingExplicitVersion = missingExplicitVersion;
+        passAll.roadmapMissing = roadmapMissing;
         return passAll;
     }
     const normalized = new Set([...milestonePhaseNums].map(n => n.split('-').map(seg => (seg.replace(/^0+(?=\d)/, '') || '0')).join('-').toLowerCase()));
@@ -444,13 +596,128 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention) {
     }
     isDirInMilestone.phaseCount = milestonePhaseNums.size;
     isDirInMilestone.missingExplicitVersion = missingExplicitVersion;
+    isDirInMilestone.roadmapMissing = roadmapMissing;
     return isDirInMilestone;
 }
+/**
+ * `<number>:<slug>` keys for every `Phase N: Name` heading in `text` — the identity a
+ * phase directory carries in its own name (`01-release-pipeline`), number normalised
+ * (leading zeros dropped) and name slugged by the same owner that names directories.
+ */
+function phaseHeadingKeys(text) {
+    const keys = new Set();
+    const pattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+(\d+[A-Za-z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi;
+    let m;
+    const unfenced = stripFencedLines(text);
+    while ((m = pattern.exec(unfenced)) !== null) {
+        const slug = generateSlugInternal(m[2]);
+        if (slug)
+            keys.add(`${m[1].replace(/^0+(?=\d)/, '').toLowerCase()}:${slug}`);
+    }
+    return keys;
+}
+function phaseDirKey(dirName) {
+    const m = dirName.match(/^0*(\d+[A-Za-z]?(?:\.\d+)*)-(.+)$/);
+    return m ? `${(m[1] || '0').toLowerCase()}:${m[2].toLowerCase()}` : null;
+}
+/**
+ * 261007-ixt D-9: which directories under `phases/` belong to a CLOSED milestone.
+ *
+ * A directory is closed when an archived `milestones/vX-ROADMAP.md` (the snapshot
+ * `milestone complete` writes) lists a phase with the same number AND the same name,
+ * and the current milestone's ROADMAP scope does not list it. Number alone is not
+ * enough — a later milestone may reuse numbers under new names — and a phase the
+ * current scope still names is still the record's milestone (milestone complete
+ * without --archive-phases leaves both the snapshot and the directories in place).
+ *
+ * The milestone filter cannot see this: when the current milestone names no phase
+ * (between milestones), it passes every directory, and the progress scan counted a
+ * closed milestone's leftover directories as the current milestone's (measured on the
+ * live vault-assurance tree: v1.0's 01–07 rewrote the v1.1 block 5/5/39/39 to
+ * 7/7/119/120). No archive on disk → nothing is closed, so a single-milestone
+ * project's checklist-only ROADMAP keeps counting every directory.
+ */
+function getClosedMilestonePhaseDirFilter(cwd) {
+    const owners = getClosedMilestonePhaseDirOwners(cwd);
+    return (dirName) => owners(dirName).length > 0;
+}
+/**
+ * 261007-mmz: the same predicate as getClosedMilestonePhaseDirFilter, answering WHICH
+ * closed milestones name a directory — the versions whose archived snapshot lists the
+ * directory's number AND name, sorted, minus any phase the current milestone's scope
+ * still lists. The filter above is `owners(dir).length > 0`, so the two can never
+ * disagree; `phases archive-closed` reads the versions to move a leftover directory
+ * into the one milestone archive that names it, and leaves it when none or several do.
+ */
+/**
+ * 261007-mmz follow-up 3: the phases an archived `<version>-ROADMAP.md` snapshot names
+ * for ITS OWN milestone. A snapshot is a copy of the whole ROADMAP at close time, so it
+ * also lists the next milestone's phases; reading every heading made v1.0's snapshot
+ * claim v1.1's phase 5 (measured on the step-walked fixture: `phases archive-closed`
+ * moved 05-security-audit into v1.0-phases while `milestone complete v1.0` had scoped
+ * 1-4). The scope comes from milestoneScope — the same owner `milestone complete`
+ * uses — read without cwd, because STATE.md no longer describes a closed milestone.
+ *
+ * A snapshot in which that scope names no phase for its own version is one the fixed
+ * verb would have refused to write (D-1/D-3), so only a close made before 261007-mmz
+ * produces it — the live vault-assurance v1.0 snapshot is one: a `### … whole of v1.0`
+ * heading in its Open Work section captures the section match. For those the reading
+ * stays the pre-existing whole-snapshot one, which is what 261007-ixt D-9 measured on
+ * the live tree; number AND name must still match.
+ */
+function snapshotPhaseKeys(text, version) {
+    const scoped = phaseHeadingKeys(milestoneScope(text, version).scope);
+    return scoped.size > 0 ? scoped : phaseHeadingKeys(text);
+}
+function getClosedMilestonePhaseDirOwners(cwd) {
+    const byKey = new Map();
+    try {
+        const archiveDir = milestonePathsFor(planningDir(cwd)).milestonesArchive;
+        for (const file of node_fs_1.default.readdirSync(archiveDir).sort()) {
+            const vm = file.match(/^(v\d+(?:\.\d+)*)-ROADMAP\.md$/i);
+            if (!vm)
+                continue;
+            const text = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(archiveDir, file));
+            if (text === null)
+                continue;
+            for (const key of snapshotPhaseKeys(text, vm[1])) {
+                const versions = byKey.get(key) ?? [];
+                if (!versions.includes(vm[1]))
+                    versions.push(vm[1]);
+                byKey.set(key, versions);
+            }
+        }
+    }
+    catch { /* no archive directory: nothing is closed */ }
+    if (byKey.size === 0)
+        return () => [];
+    try {
+        const roadmapRaw = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md'));
+        if (roadmapRaw !== null) {
+            for (const key of phaseHeadingKeys(extractCurrentMilestone(roadmapRaw, cwd)))
+                byKey.delete(key);
+        }
+    }
+    catch { /* unreadable ROADMAP: the archive alone decides */ }
+    return (dirName) => {
+        const key = phaseDirKey(dirName);
+        return key !== null ? [...(byKey.get(key) ?? [])] : [];
+    };
+}
 module.exports = {
+    getClosedMilestonePhaseDirFilter,
+    getClosedMilestonePhaseDirOwners,
     stripShippedMilestones,
     extractCurrentMilestone,
     replaceInCurrentMilestone,
+    buildPlansSummaryLinePattern,
+    // Exported for `cmdRoadmapUpdatePlanProgress`'s row-INSERTION anchors, which
+    // need the same "cannot cross a phase heading" bound but a different tail and
+    // a different alternation. One owner for the bound, two shapes built from it.
+    PHASE_SECTION_SCAN,
     getRoadmapPhaseInternal,
     getMilestoneInfo,
+    getDeclaredMilestoneInfo,
     getMilestonePhaseFilter,
+    milestoneScope,
 };