@opengsd/gsd-core 1.10.0 → 1.12.0

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

@@ -12,35 +12,46 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const clock_cjs_1 = require("./clock.cjs");
+const pattern_cjs_1 = require("./pattern.cjs");
+const text_lines_cjs_1 = require("./text-lines.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
-const { output, error } = ioMod;
+const { output, error, formatDiagnosticToken } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { escapeRegex, normalizePhaseName, phaseMarkdownRegexSource, phaseTokenMatches, stripProjectCodePrefix, OPTIONAL_PHASE_TAG_SOURCE, roadmapPhaseLookupSources } = phaseIdMod;
+const { normalizePhaseName, phaseMarkdownRegexSource, matchPhaseDirs, stripProjectCodePrefix, OPTIONAL_PHASE_TAG_SOURCE, roadmapPhaseLookupSources, isSentinelPhaseId, scopeToPhase } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { findPhaseInternal } = phaseLocatorMod;
+const { findPhaseInternal, listMilestonePhaseDirs, listAllPhaseDirs } = phaseLocatorMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+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, replaceInCurrentMilestone } = roadmapParserModule;
+const { stripShippedMilestones, extractCurrentMilestone, extractCurrentMilestoneScoped, replaceInCurrentMilestone, listMilestoneHeadings, scanMilestonePhaseIds, collectTablePhaseRows } = 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");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
 const { planningPaths, withPlanningLock, findContextMdIn } = planningWorkspace;
+// #3641: milestone-scope's convention resolution reads the project config
+// (no cycle — config-loader does not import this module).
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const configLoaderForScope = require("./config-loader.cjs");
+const { loadConfig: loadConfigForScope } = configLoaderForScope;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const scanPhasePlans = require("./plan-scan.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const coreUtils = require("./core-utils.cjs");
-const { countMatchedSummaries } = coreUtils;
+const { countMatchedSummaries, findUnsummarizedPlans } = coreUtils;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatter = require("./frontmatter.cjs");
 const { extractFrontmatter, parseMustHavesBlock } = frontmatter;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const verificationMod = require("./verification.cjs");
-const { readVerificationStatus } = verificationMod;
+const { isPhaseComplete } = verificationMod;
 // ─── coerceTruthToString ──────────────────────────────────────────────────────
 /**
  * Coerce an arbitrary YAML scalar/object into a string for cross-cutting
@@ -83,27 +94,53 @@ function countPhasePlansAndSummaries(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.
     let phaseFiles = [];
+    // #3885 (ADR-3473 §8.5): distinguish "genuinely absent" (ENOENT) from
+    // "could not read" (EACCES/EIO/...) — the collapse of both to an empty
+    // listing is exactly the defect class this item closes. Mirrors
+    // core-utils.cts's getPhaseFileStats / phase-locator.cts's
+    // listMilestonePhaseDirs SCOPE.UNREADABLE discriminator.
+    let contextReadError = null;
     try {
         phaseFiles = node_fs_1.default.readdirSync(phaseDir);
     }
-    catch { /* empty */ }
+    catch (err) {
+        const code = err?.code;
+        if (code !== 'ENOENT') {
+            contextReadError = `Could not read phase directory ${formatDiagnosticToken(phaseDir)}: ${formatDiagnosticToken(err?.message ?? String(err))}`;
+        }
+    }
+    // #3511: scope the raw listing to this phase dir before the
+    // phase-numbered-artifact predicates (hasContext/hasResearch) — planCount/
+    // 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));
     return {
         planCount,
         summaryCount,
-        hasContext: findContextMdIn(phaseFiles) !== null,
-        hasResearch: phaseFiles.some(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md'),
+        hasContext: findContextMdIn(scopedFiles) !== null,
+        hasResearch: scopedFiles.some(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md'),
+        contextReadError,
     };
 }
 // `phaseMarkdownRegexSource` lives in phase-id.cjs (#3537) and is imported above.
 // ─── searchPhaseInContent ─────────────────────────────────────────────────────
+/**
+ * Build the phase-heading regex used by `searchPhaseInContent` for a given
+ * pre-escaped phase source. Extracted (#3412) so tests can assert against the
+ * exact production pattern instead of hand-duplicating it.
+ * #1729: OPTIONAL_PHASE_TAG_SOURCE after the number tolerates a pre-colon ( ) tag.
+ */
+function buildPhaseHeadingRegex(escapedPhase) {
+    return new RegExp(`^(?:\\[[^\\]]{1,200}\\]\\s*)?Phase\\s+${escapedPhase}${OPTIONAL_PHASE_TAG_SOURCE}:\\s*(.+)$`, 'i');
+}
 /**
  * Search for a phase header (and its section) within the given content string.
  * Returns a result object if found (either a full match or a malformed_roadmap
  * checklist-only match), or null if the phase is not present at all.
  */
 function searchPhaseInContent(content, escapedPhase, phaseNum) {
-    // #1729: OPTIONAL_PHASE_TAG_SOURCE after the number tolerates a pre-colon ( ) tag.
-    const headingPattern = new RegExp(`^(?:\\[[^\\]]{1,200}\\]\\s*)?Phase\\s+${escapedPhase}${OPTIONAL_PHASE_TAG_SOURCE}:\\s*(.+)$`, 'i');
+    const headingPattern = buildPhaseHeadingRegex(escapedPhase);
     const headings = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(content);
     const headingIndex = headings.findIndex((heading) => headingPattern.test(heading.text));
     const headerMatch = headingIndex === -1 ? null : headings[headingIndex].text.match(headingPattern);
@@ -173,7 +210,8 @@ function searchPhaseInContent(content, escapedPhase, phaseNum) {
  * phase resolution as `roadmap.get-phase` — not a milestone-only subset.
  */
 function getRoadmapPhaseWithFallback(cwd, phaseNum) {
-    if (/^999(?:\.|$)/.test(stripProjectCodePrefix(phaseNum)))
+    // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
+    if (isSentinelPhaseId(stripProjectCodePrefix(phaseNum)))
         return null;
     const roadmapPath = planningPaths(cwd).roadmap;
     // Read directly rather than gating on fs.existsSync: existsSync returns false
@@ -206,7 +244,8 @@ function getRoadmapPhaseWithFallback(cwd, phaseNum) {
 }
 // ─── cmdRoadmapGetPhase ───────────────────────────────────────────────────────
 function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
-    if (/^999(?:\.|$)/.test(stripProjectCodePrefix(phaseNum))) {
+    // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
+    if (isSentinelPhaseId(stripProjectCodePrefix(phaseNum))) {
         output({ found: false, phase_number: phaseNum }, raw, '');
         return;
     }
@@ -242,6 +281,17 @@ function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
             if (!malformed)
                 malformed = (milestoneResult?.error ? milestoneResult : (fullResult?.error ? fullResult : null));
         }
+        // #3577: no heading or checklist entry matched — fall back to a
+        // markdown-table row declaration (the same last-resort tier
+        // getRoadmapPhaseInternal gained). Zero-pad-tolerant id compare (#3572
+        // lesson: the declared form may be padded).
+        const stripPad = (s) => s.replace(/^0+(?=.)/, '');
+        const tableHit = collectTablePhaseRows(milestoneContent).find((tr) => stripPad(tr.id) === stripPad(phaseNum))
+            ?? collectTablePhaseRows(fullContent).find((tr) => stripPad(tr.id) === stripPad(phaseNum));
+        if (tableHit) {
+            output({ found: true, phase_number: phaseNum, phase_name: tableHit.name ?? `Phase ${tableHit.id}`, goal: null, section: tableHit.row.trim() }, raw, tableHit.row.trim());
+            return;
+        }
         if (malformed) {
             output(malformed, raw, '');
             return;
@@ -252,16 +302,16 @@ function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
         error('Failed to read ROADMAP.md: ' + e.message);
     }
 }
-// ─── cmdRoadmapAnalyze ────────────────────────────────────────────────────────
-function cmdRoadmapAnalyze(cwd, raw) {
-    const roadmapPath = planningPaths(cwd).roadmap;
-    if (!node_fs_1.default.existsSync(roadmapPath)) {
-        output({ error: 'ROADMAP.md not found', milestones: [], phases: [], current_phase: null }, raw, undefined);
-        return;
-    }
-    const rawContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
-    const content = extractCurrentMilestone(rawContent, cwd);
-    const phasesDir = planningPaths(cwd).phases;
+/**
+ * #3165: scan `content` for phase-detail headings (`##/###/#### Phase N: Name`)
+ * and enrich each with its on-disk plan/summary/completion status and ROADMAP
+ * checkbox. Pure extraction over `content` + the pre-built `phaseDirNames`
+ * lookup index — no milestone windowing of its own; the caller chooses the
+ * content (scoped window or fallback). Extracted verbatim from
+ * `cmdRoadmapAnalyze`'s former inline loop so the fallback re-runs the EXACT
+ * same enrichment, not a second derivation.
+ */
+function collectAnalyzePhases(content, phasesDir, phaseDirNames) {
     // Extract all phase headings: ## Phase N: Name or ### Phase N: Name
     // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
     // 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.
@@ -272,29 +322,9 @@ function cmdRoadmapAnalyze(cwd, raw) {
     const phasePattern = /#{2,4}\s*(?:\[[^\]]{1,200}\]\s*)?Phase\s+([A-Za-z]?\d+[A-Z]?(?:[.-]\d+)*)(?:\s*\([^)\n]{0,200}\))?\s*:\s*([^\n]+)/gi;
     const phases = [];
     let match;
-    // Phase 0 (pre-milestone) and Phase 999 (backlog) are sentinels, not real
-    // phases. They legitimately have no directory and must never be surfaced as
-    // current/next phase or counted in phase_count. Mirrors the engine-wide
-    // sentinel convention (phase-id getMilestoneFromPhaseId, roadmap-command-router
-    // SENTINELS, the #1445 /^999/ progress filters). (#1580)
-    const isSentinelPhase = (num) => {
-        const major = parseInt(num, 10);
-        return major === 0 || major === 999;
-    };
-    // Build phase directory lookup once (O(1) readdir instead of O(N) per phase)
-    const _phaseDirNames = (() => {
-        try {
-            return node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true })
-                .filter(e => e.isDirectory())
-                .map(e => e.name);
-        }
-        catch {
-            return [];
-        }
-    })();
     while ((match = phasePattern.exec(content)) !== null) {
         const phaseNum = match[1];
-        if (isSentinelPhase(phaseNum))
+        if (isSentinelPhaseId(phaseNum))
             continue;
         const phaseName = match[2].replace(/\(INSERTED\)/i, '').trim();
         // Extract goal from the section
@@ -319,20 +349,32 @@ function cmdRoadmapAnalyze(cwd, raw) {
         let summaryCount = 0;
         let hasContext = false;
         let hasResearch = false;
-        // DEAD catch removed (#2245 audit): _phaseDirNames.find(...) is a pure
+        // #3885 (ADR-3473 §8.5): null unless dirMatch resolves and its readdirSync
+        // hit a non-ENOENT error — no directory at all is `disk_status:
+        // 'no_directory'`, a real (if uninteresting) answer, not a read error.
+        let contextReadError = null;
+        // DEAD catch removed (#2245 audit): matchPhaseDirs(...) is a pure
         // array lookup on an already-resolved string array, and
         // countPhasePlansAndSummaries is itself fully defensive (its own
         // readdirSync is self-guarded, and it delegates to scanPhasePlans, which
         // never throws) — nothing in this block can throw, so the try/catch could
         // never be triggered.
-        const dirMatch = _phaseDirNames.find(d => phaseTokenMatches(d, normalized));
+        const dirMatch = matchPhaseDirs(phaseDirNames, normalized).matches[0];
         if (dirMatch) {
             const counts = countPhasePlansAndSummaries(node_path_1.default.join(phasesDir, dirMatch));
             planCount = counts.planCount;
             summaryCount = counts.summaryCount;
             hasContext = counts.hasContext;
             hasResearch = counts.hasResearch;
-            if (summaryCount >= planCount && planCount > 0)
+            contextReadError = counts.contextReadError;
+            // ADR-3180 §7.4 (issue #3186, disk-strict, #3168 fix): route "is this
+            // phase complete" through the canonical owner (`isPhaseComplete`),
+            // which calls readVerificationStatus UNCONDITIONALLY — plan count is
+            // 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));
+            if (completionResult.value.complete)
                 diskStatus = 'complete';
             else if (summaryCount > 0)
                 diskStatus = 'partial';
@@ -345,19 +387,23 @@ function cmdRoadmapAnalyze(cwd, raw) {
             else
                 diskStatus = 'empty';
         }
-        // Check ROADMAP checkbox status.
-        // #3537: padding-tolerant fragment — the heading discovered above may use
-        // a different padding than the summary-bullet checkbox below it (mixed
-        // padding inside one ROADMAP is legal and seen in real projects).
+        // Check ROADMAP checkbox status. #3537: padding-tolerant fragment — the
+        // heading discovered above may use a different padding than the
+        // summary-bullet checkbox below it (mixed padding inside one ROADMAP is
+        // legal and seen in real projects).
+        //
+        // ADR-3180 §7.4 (disk-strict, #2957, maintainer decision 2026-08-08):
+        // `roadmapComplete` is reported below as metadata ONLY — it carries NO
+        // machine authority over `diskStatus`. The override that used to trust a
+        // ticked checkbox over disk file structure is DELETED, not generalized
+        // (#2957: "a ticked ROADMAP checkbox is a human annotation with no
+        // machine authority"). A phase marked complete solely by a ticked
+        // checkbox — no passing `*-VERIFICATION.md`, plans outstanding — now
+        // reports incomplete; this is the deliberate Tier-2 break (ADR-3180 §7.4
+        // Decision 3).
         const checkboxPattern = new RegExp(`-\\s*\\[(x| )\\]\\s*.*Phase\\s+${phaseMarkdownRegexSource(phaseNum)}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'i');
         const checkboxMatch = content.match(checkboxPattern);
         const roadmapComplete = checkboxMatch ? checkboxMatch[1] === 'x' : false;
-        // If roadmap marks phase complete, trust that over disk file structure.
-        // Phases completed before GSD tracking (or via external tools) may lack
-        // the standard PLAN/SUMMARY pairs but are still done.
-        if (roadmapComplete && diskStatus !== 'complete') {
-            diskStatus = 'complete';
-        }
         phases.push({
             number: phaseNum,
             name: phaseName,
@@ -370,18 +416,116 @@ function cmdRoadmapAnalyze(cwd, raw) {
             has_research: hasResearch,
             disk_status: diskStatus,
             roadmap_complete: roadmapComplete,
+            context_read_error: contextReadError,
         });
     }
-    // Extract milestone info
-    const milestones = [];
-    const milestonePattern = /##\s*(.*v(\d+(?:\.\d+)+)[^(\n]*)/gi;
-    let mMatch;
-    while ((mMatch = milestonePattern.exec(content)) !== null) {
-        milestones.push({
-            heading: mMatch[1].trim(),
-            version: 'v' + mMatch[2],
+    // #3577: markdown-table row declarations join the enumeration — same
+    // enrichment contract as headings (disk counts when the directory exists),
+    // zero-pad-tolerant duplicate guard so an id declared in BOTH a heading and
+    // a table counts once.
+    const stripPadA = (s) => s.replace(/^0+(?=.)/, '');
+    const seen = new Set(phases.map((ph) => stripPadA(ph.number)));
+    for (const tr of collectTablePhaseRows(content)) {
+        if (seen.has(stripPadA(tr.id)))
+            continue;
+        const dirMatchA = matchPhaseDirs(phaseDirNames, normalizePhaseName(tr.id)).matches[0];
+        let tPlanCount = 0;
+        let tSummaryCount = 0;
+        let tHasContext = false;
+        let tHasResearch = false;
+        let tContextReadError = null;
+        if (dirMatchA) {
+            const counts = countPhasePlansAndSummaries(node_path_1.default.join(phasesDir, dirMatchA));
+            tPlanCount = counts.planCount;
+            tSummaryCount = counts.summaryCount;
+            tHasContext = node_fs_1.default.existsSync(node_path_1.default.join(phasesDir, dirMatchA, 'CONTEXT.md'));
+            tHasResearch = node_fs_1.default.existsSync(node_path_1.default.join(phasesDir, dirMatchA, 'RESEARCH.md'));
+            // #3885 (ADR-3473 §8.5): reuse the SAME countPhasePlansAndSummaries call's
+            // discriminator — this row's hasContext/hasResearch are read via a direct
+            // existsSync (which cannot itself distinguish EACCES from absent), but
+            // an unreadable phase directory is still surfaced via the sibling call.
+            tContextReadError = counts.contextReadError;
+        }
+        phases.push({
+            number: tr.id,
+            name: tr.name ?? `Phase ${tr.id}`,
+            goal: null,
+            mode: null,
+            depends_on: null,
+            plan_count: tPlanCount,
+            summary_count: tSummaryCount,
+            has_context: tHasContext,
+            has_research: tHasResearch,
+            disk_status: dirMatchA ? 'ok' : 'no_directory',
+            roadmap_complete: false,
+            context_read_error: tContextReadError,
         });
     }
+    return phases;
+}
+function cmdRoadmapAnalyze(cwd, raw) {
+    const roadmapPath = planningPaths(cwd).roadmap;
+    if (!node_fs_1.default.existsSync(roadmapPath)) {
+        output({ error: 'ROADMAP.md not found', milestones: [], phases: [], current_phase: null }, raw, undefined);
+        return;
+    }
+    const rawContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+    // #3184/#3165: use the scoped variant so a truncated window is a
+    // distinguishable signal in the output instead of a silent `phase_count: 0`
+    // indistinguishable from a genuinely empty milestone.
+    const { value: content, scope } = extractCurrentMilestoneScoped(rawContent, cwd);
+    const phasesDir = planningPaths(cwd).phases;
+    // Build phase directory lookup once (O(1) readdir instead of O(N) per phase)
+    // #3185 exemption reason (ADR-3180 Decision 4a): this is a heading->directory
+    // LOOKUP INDEX, not a milestone enumeration. It must see the PHYSICAL set so
+    // a heading already scoped by extractCurrentMilestoneScoped above can find
+    // its directory; filtering it through listMilestonePhaseDirs would scope
+    // the same set twice. #3882 (ADR-3473 §8.2): routed through the named
+    // "physical set, sentinels included" axis instead of a hand-rolled
+    // readdirSync — every heading matched below already excludes sentinel
+    // phase numbers via isSentinelPhaseId before it ever consults this list
+    // (collectAnalyzePhases), so a sentinel directory's presence here is
+    // output-invariant; this only removes the re-derivation, not the reason.
+    const _phaseDirNames = listAllPhaseDirs(phasesDir, { includeSentinels: true }).value;
+    // Scan the scoped milestone window for phase-detail headings and enrich each
+    // with its on-disk status. Extracted into `collectAnalyzePhases` (#3165) so
+    // the SAME enrichment re-runs on the fallback below — not a second copy.
+    let phases = collectAnalyzePhases(content, phasesDir, _phaseDirNames);
+    // `effectiveContent` is what the downstream checklist scan (missing_details)
+    // iterates. Defaults to the scoped window; switched to the fallback document
+    // when the recovery path below fires, so a phase found via fallback is not
+    // falsely reported as "in checklist but missing a detail section."
+    let effectiveContent = content;
+    // #3165: recover phase_count when the scoped window came back empty. A
+    // CLOSED milestone heading sitting between the active milestone heading and
+    // its own phase-detail sections closes `extractCurrentMilestoneScoped`'s
+    // window over prose only — `phases` is empty, and the consuming resume gate
+    // (`workflows/next.md` Route 0) iterates `.phases[]` so a safety invariant
+    // silently never runs. When the window is suspect (non-COMPLETE scope), the
+    // scoped scan found nothing, AND phase directories exist on disk (real
+    // evidence phases exist), re-scan the shipped-milestone-stripped document so
+    // the phase list reflects the real phases instead of a silent zero. The
+    // `scope` field retains its non-COMPLETE value downstream so consumers can
+    // still tell this is a best-effort count, not a cleanly scoped one. Position
+    // alone cannot attribute phases to the active vs the intervening closed
+    // milestone, so this never claims COMPLETE — it converts silence into a
+    // populated, flagged result.
+    if (phases.length === 0 && scope !== SCOPE.COMPLETE && _phaseDirNames.length > 0) {
+        const fallbackContent = stripShippedMilestones(rawContent);
+        const fallbackPhases = collectAnalyzePhases(fallbackContent, phasesDir, _phaseDirNames);
+        if (fallbackPhases.length > 0) {
+            phases = fallbackPhases;
+            effectiveContent = fallbackContent;
+        }
+    }
+    // Extract milestone info. #3216: routed through the canonical
+    // `listMilestoneHeadings` owner (deleted the inline `##…` regex, which
+    // truncated names at a parenthetical and had no phase-heading exclusion)
+    // rather than re-deriving the enumeration here.
+    const milestones = listMilestoneHeadings(content).map((m) => ({
+        heading: m.heading,
+        version: m.version,
+    }));
     // Find current and next phase
     const currentPhase = phases.find(p => p.disk_status === 'planned' || p.disk_status === 'partial') || null;
     const nextPhase = phases.find(p => p.disk_status === 'empty' || p.disk_status === 'no_directory' || p.disk_status === 'discussed' || p.disk_status === 'researched') || null;
@@ -399,11 +543,43 @@ function cmdRoadmapAnalyze(cwd, raw) {
     const checklistPattern = /-\s*\[[ x]\]\s*\*\*Phase\s+([A-Za-z]?\d+[A-Z]?(?:[.-]\d+)*)/gi;
     const checklistPhases = new Set();
     let checklistMatch;
-    while ((checklistMatch = checklistPattern.exec(content)) !== null) {
+    while ((checklistMatch = checklistPattern.exec(effectiveContent)) !== null) {
         checklistPhases.add(checklistMatch[1]);
     }
     const detailPhases = new Set(phases.map(p => p.number));
-    const missingDetails = [...checklistPhases].filter(p => !detailPhases.has(p) && !isSentinelPhase(p));
+    const missingDetails = [...checklistPhases].filter(p => !detailPhases.has(p) && !isSentinelPhaseId(p));
+    // #3217 (ADR-3180 §7.6 rules 3-4): `progress_percent` used to accumulate
+    // `totalPlans`/`totalSummaries` above — a heading-matched enumeration
+    // (`phasePattern` over the milestone-windowed `content`) paired against
+    // `_phaseDirNames`, a DELIBERATELY unscoped physical directory listing
+    // (see its own comment above: it is a heading->directory lookup index,
+    // not a milestone enumeration). That set is not the same set
+    // `listMilestonePhaseDirs` scopes for `query progress` / `stats` (#3185
+    // Phase 3), so `progress_percent` could silently diverge from both siblings
+    // on the same project (rule 3). Route `progress_percent`'s own
+    // numerator/denominator through the single scoped owner instead — mirrors
+    // cmdProgressRender/cmdStats's own aggregation — and withhold the
+    // percentage entirely when THAT scope is not COMPLETE (rule 4), never
+    // returning `0` for "could not compute". This does not touch `total_plans`
+    // / `total_summaries` / `phases` / `completed_phases` above — those stay
+    // the heading-matched detail view; only `progress_percent`'s own inputs
+    // move onto the scoped owner.
+    let scopedTotalPlans = 0;
+    let scopedTotalSummaries = 0;
+    let progressScope = SCOPE.UNREADABLE;
+    try {
+        const { value: progressDirs, scope: scopedResult } = listMilestonePhaseDirs(phasesDir, { cwd });
+        progressScope = scopedResult;
+        for (const dir of progressDirs) {
+            const scan = scanPhasePlans(node_path_1.default.join(phasesDir, dir));
+            scopedTotalPlans += scan.planCount;
+            scopedTotalSummaries += scan.summaryCount;
+        }
+    }
+    catch { /* progressScope stays the pessimistic SCOPE.UNREADABLE default */ }
+    const progressPercent = progressScope === SCOPE.COMPLETE
+        ? (0, phase_lifecycle_cjs_1.clampPercent)(scopedTotalSummaries, scopedTotalPlans)
+        : null;
     const result = {
         milestones,
         phases,
@@ -411,13 +587,94 @@ function cmdRoadmapAnalyze(cwd, raw) {
         completed_phases: completedPhases,
         total_plans: totalPlans,
         total_summaries: totalSummaries,
-        progress_percent: totalPlans > 0 ? Math.min(100, Math.round((totalSummaries / totalPlans) * 100)) : 0,
+        progress_percent: progressPercent,
+        // #3217 finding 2: `progress_percent` is gated by a SECOND, independently
+        // computed `listMilestonePhaseDirs` scope (`progressScope` above) — not
+        // by the top-level `scope` field, which describes the heading-windowing
+        // identity `phases`/`total_plans`/`total_summaries`/`completed_phases`
+        // were built from. Those two scopes can legitimately disagree (e.g.
+        // `scope: "complete"` alongside a genuinely unreadable phases directory),
+        // and per the documented contract "scope tells you whether the counts
+        // are trustworthy", a consumer seeing `progress_percent: null` needs a
+        // field to tell WHY without reading source. Exposing `progress_scope`
+        // (rather than reconciling the two scopes into one, or re-deriving
+        // `total_plans`/`phases`/etc. from the scoped set) preserves the
+        // deliberate, already-documented choice a few lines up: `phases`/
+        // `total_plans`/`total_summaries`/`completed_phases` stay the
+        // heading-matched detail view (`_phaseDirNames` is a lookup index, not a
+        // milestone enumeration — see its comment); only `progress_percent`'s own
+        // inputs move onto the scoped owner.
+        progress_scope: progressScope,
         current_phase: currentPhase ? currentPhase.number : null,
         next_phase: nextPhase ? nextPhase.number : null,
         missing_phase_details: missingDetails.length > 0 ? missingDetails : null,
+        // #3184/#3165: distinguishes a genuinely empty milestone (`scope:
+        // "complete"`, `phase_count: 0`) from a window that could not be fully
+        // resolved (`"truncated"` / `"unscoped"` / `"unreadable"`) — those cases
+        // were previously output-identical.
+        scope,
     };
     output(result, raw, undefined);
 }
+// ─── cmdRoadmapMilestoneScope ────────────────────────────────────────────────
+/**
+ * #3262 (write-time milestone-scope guard): read-only probe emitting the
+ * current milestone window's IDENTITY — its scope classification and the
+ * phase ids it declares — so the edit-phase workflow can capture it before
+ * its in-place section write, re-derive it after, and roll back on any
+ * change. This is the milestone-scope sibling of the workflow's existing
+ * `depends_on` gate, expressed as a command because the workflow's write is
+ * assistant-driven free-text surgery, not a code path.
+ *
+ * Deliberately NOT `cmdRoadmapAnalyze`: analyze's #3165 recovery re-populates
+ * `phases` from the shipped-milestone-stripped document when the scoped
+ * window is suspect, which is right for a human-facing progress report and
+ * wrong for a before/after equality probe — the refill would mask exactly
+ * the narrowing this guard exists to detect. This probe reports the RAW
+ * window (`extractCurrentMilestoneScoped` + `scanMilestonePhaseIds`), no
+ * fallback, so a narrowed window is always visible as a changed phase set.
+ */
+function cmdRoadmapMilestoneScope(cwd, raw) {
+    const roadmapPath = planningPaths(cwd).roadmap;
+    if (!node_fs_1.default.existsSync(roadmapPath)) {
+        output({ error: 'ROADMAP.md not found', scope: SCOPE.UNREADABLE, phases: [], phase_count: 0 }, raw, undefined);
+        return;
+    }
+    const rawContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+    // #3641: resolve phase_id_convention and thread it into the scope axis, so
+    // this probe and `roadmap validate`'s V005 answer the SAME question the
+    // SAME way for a bracket-convention project — a window the classifier
+    // calls TRUNCATED in validate must never read COMPLETE here (the #3262
+    // capture/compare guard consumes this scope). Resolution mirrors the
+    // validate router's: .planning/config.json first, ROADMAP.md frontmatter
+    // as fallback.
+    let phaseIdConvention;
+    try {
+        const cfg = loadConfigForScope(cwd);
+        phaseIdConvention = cfg['phase_id_convention'];
+    }
+    catch {
+        phaseIdConvention = undefined;
+    }
+    if (phaseIdConvention === undefined || phaseIdConvention === null) {
+        // Bounded per local/no-unbounded-quantifier (#2128): frontmatter is a
+        // short header block — 4KB is orders of magnitude beyond any real one.
+        const fmMatch = rawContent.match(/^---\r?\n([\s\S]{0,4000}?)\r?\n---/);
+        if (fmMatch) {
+            const kvMatch = fmMatch[1].match(/^phase_id_convention:\s*(.*)$/m);
+            if (kvMatch) {
+                const val = kvMatch[1].trim();
+                if (val !== 'null' && val !== '') {
+                    phaseIdConvention = val.replace(/^["']|["']$/g, '');
+                }
+            }
+        }
+    }
+    const { value: window, scope } = extractCurrentMilestoneScoped(rawContent, cwd, undefined, phaseIdConvention);
+    // Document order (Set insertion order) — deterministic for a given document.
+    const phases = [...scanMilestonePhaseIds(window)];
+    output({ scope, phases, phase_count: phases.length }, raw, undefined);
+}
 // ─── cmdRoadmapUpdatePlanProgress ─────────────────────────────────────────────
 /**
  * Scope a ROADMAP.md content string down to its "Progress table" writable
@@ -474,10 +731,34 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     // completion date until the phase's verification status is 'passed', matching
     // cmdPhaseComplete's gate (phase.cts:1436). Previously the checkbox fired the
     // moment the last plan summary landed — before gsd-verifier had verified.
+    //
+    // ADR-3180 §7.4 (issue #3186, disk-strict): routed through the canonical
+    // owner (`isPhaseComplete`) instead of hand-rolling `summaryCount >=
+    // planCount && verificationPassed` locally — the owner calls
+    // readVerificationStatus UNCONDITIONALLY, so `isComplete` here always
+    // agrees with `roadmap analyze` / `init manager` / `phase complete` for
+    // 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 verificationResult = readVerificationStatus(phaseDir);
-    const verificationPassed = verificationResult.status === 'passed';
-    const isComplete = summaryCount >= planCount && verificationPassed;
+    const completionResult = isPhaseComplete(phaseDir);
+    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
+    // owner's `complete` is exactly `verification.status === 'passed'`, and
+    // that must stay true (disk-strict: a zero-plan phase with a passing
+    // `*-VERIFICATION.md` IS complete, #3168). But `readVerificationStatus`'s
+    // staleness check only compares SUMMARY mtimes against the verification
+    // file — it has no idea a NEW plan was added after the file was written,
+    // so a still-fresh `passed` verification says nothing about a plan added
+    // afterward. This command WRITES a checkbox and a completion date into
+    // ROADMAP.md, a materially stronger claim than "verification passed" —
+    // mirroring cmdPhaseComplete's own fail-closed plan-coverage gate
+    // (phase.cts:~1995, #2648: "a coverage gate that passes when it cannot
+    // read the plans is no gate at all"), composed explicitly here rather than
+    // folded into the predicate: complete AND all plans executed.
+    const coverageScan = scanPhasePlans(phaseDir);
+    const unsummarizedPlans = findUnsummarizedPlans(coverageScan.planFiles, coverageScan.summaryFiles);
+    const isComplete = completionResult.value.complete && unsummarizedPlans.length === 0;
     // #3057 B3: routing above is unchanged (an indeterminate staleness check
     // still routes as if nothing were stale) — this only makes the fact visible
     // to whatever reads this command's JSON output.
@@ -539,26 +820,65 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         //   `**Plans:** N plans`  — bold "Plans:" (colon inside bold)
         //   `Plans: N plans`      — plain text header
         //
-        // #2853: the verb owns the count token ONLY — it must not destroy hand-written
-        // prose a human placed after the count (e.g. "(11-16 are gap closure ...)").
-        // Group $1 = phase header → `Plans:` label + trailing whitespace (unchanged).
-        // Group $2 = the existing count token to replace: matches `N/N plans complete`,
-        // `N/N plans executed`, or the bare template `N plans` form. Group $3 = whatever
-        // else is on the line (`[^\r\n]*`, so CRLF `\r` is preserved).
+        // #2853 / #3584: the verb owns the count token ONLY — it must not destroy
+        // hand-written prose a human placed on the line. Group $1 = phase header →
+        // `Plans:` label + trailing whitespace (unchanged). Group $2 = the existing
+        // count token to replace: matches `N/N plans complete`, `N/N plans executed`,
+        // or the bare template `N plan(s)` form — singular is part of the tool's OWN
+        // grammar (gsd-core/templates/roadmap.md:62 ships `**Plans**: 1 plan` as the
+        // documented one-plan-phase shape), so the `s` is optional there (bug #3584
+        // Finding B; pre-fix a bare `1 plan` fell into the drop-everything path and
+        // was accidentally overwritten with the correct count — post-fix it must be
+        // recognised as a token in its own right or it freezes stale forever). Group
+        // $3 = whatever else is on the line (`[^\r\n]*`, so a CRLF `\r` is never part
+        // of the match and rides along untouched in the unmatched remainder of the
+        // string — never stranded, never duplicated).
         //
-        // Trailing text is preserved ONLY when a real count token ($2) was present —
-        // i.e. an annotation a human wrote after a real count. When $2 is absent the
-        // line is the fresh-template bracketed placeholder (`[Number of plans…]`) or
-        // other freeform guidance, not user prose: the count replaces the whole token,
-        // preserving the pre-#2853 clean-output behaviour on the template path.
-        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');
+        // Three arms, in order:
+        //   1. $2 present (a real count token) → rewrite the token, preserve $3
+        //      verbatim (an annotation a human wrote after a real count; #2853).
+        //   2. $2 absent AND $3, trimmed, is the fresh-template PLACEHOLDER shipped
+        //      by gsd-core/templates/roadmap.md — either
+        //      `[Number of plans, e.g., "3 plans" or "TBD"]` (line 37) or
+        //      `[Number of plans]` (lines 51/75/88) → replace it with the computed
+        //      count. Detected POSITIVELY on the distinctive `Number of plans`
+        //      wording (anchored, case-insensitive), NEVER on "wholly bracketed" —
+        //      a bracketed HUMAN annotation such as `[Deferred pending re-scope]`
+        //      is structurally identical but must be arm-3 preserved (bug #3584
+        //      Finding A).
+        //   3. Anything else (freeform prose, `TBD` / `TBD — annotation`, a
+        //      bracketed human note, the first line of a wrapped sentence, an
+        //      empty value) → leave the whole matched line untouched by returning
+        //      `_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');
         const planCountText = isComplete
             ? `${summaryCount}/${planCount} plans complete`
             : `${summaryCount}/${planCount} plans executed`;
+        // Positive detector for the fresh-template placeholder ONLY (bug #3584
+        // Finding A). Anchored to the distinctive `Number of plans` wording that
+        // 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.
+        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) => {
-            // Preserve trailing text only when a real count preceded it.
-            const suffix = existingCount ? trailing : '';
-            return `${label}${planCountText}${suffix}`;
+            if (existingCount) {
+                // Arm 1: real count token — rewrite it, preserve the trailing annotation.
+                return `${label}${planCountText}${trailing}`;
+            }
+            if (isTemplatePlaceholder(trailing)) {
+                // Arm 2: fresh-template placeholder — replace with the count.
+                return `${label}${planCountText}`;
+            }
+            // 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;
         });
         // If complete: check checkbox
         if (isComplete) {
@@ -570,7 +890,7 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
             const planId = summaryFile.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
             if (!planId)
                 continue;
-            const planEscaped = escapeRegex(planId);
+            const planEscaped = (0, pattern_cjs_1.escapeRegex)(planId);
             const planCheckboxPattern = new RegExp(`(-\\s*\\[) (\\]\\s*(?:\\*\\*)?${planEscaped}(?:\\*\\*)?)`, 'i');
             roadmapContent = roadmapContent.replace(planCheckboxPattern, '$1x$2');
         }
@@ -594,7 +914,7 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         // archived <details> block is still correctly detected as missing from the
         // active milestone section.
         const missingPlans = phaseInfo.plans.filter((planFile) => {
-            const planEscaped = escapeRegex(planFile);
+            const planEscaped = (0, pattern_cjs_1.escapeRegex)(planFile);
             return !new RegExp(`-\\s*\\[[x ]\\]\\s*(?:\\*\\*)?${planEscaped}`, 'i').test(activeRegion);
         });
         if (missingPlans.length > 0) {
@@ -642,7 +962,7 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
                     const planId = summaryFile.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
                     if (!planId)
                         continue;
-                    const planEscaped = escapeRegex(planId);
+                    const planEscaped = (0, pattern_cjs_1.escapeRegex)(planId);
                     const planCheckboxPattern = new RegExp(`(-\\s*\\[) (\\]\\s*(?:\\*\\*)?${planEscaped}(?:\\*\\*)?)`, 'i');
                     roadmapContent = roadmapContent.replace(planCheckboxPattern, '$1x$2');
                 }
@@ -747,6 +1067,11 @@ function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
     let updated = false;
     withPlanningLock(cwd, () => {
         const content = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+        // #3413: preserve the file's own EOL style when the checklist block below
+        // is rebuilt and spliced back in — splitLines() cleans each captured line
+        // of any dangling \r, so rejoining with a bare '\n' would silently
+        // downgrade a CRLF ROADMAP.md's rewritten block to LF only.
+        const eol = (0, text_lines_cjs_1.detectEol)(content);
         // Find the phase section.
         // #3537: padding-tolerant fragment so the caller's resolved padded id
         // matches un-padded ROADMAP headings.
@@ -776,12 +1101,20 @@ function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
         // Review fix (F2): `(?:^|\n)` anchors the match to start-of-line so mid-line
         // occurrences like `***Plans:***` embedded in a sentence or `OpenPlans: foo`
         // do not trigger a false match. Groups 1 and 2 retain the same semantics.
-        const plansBlockMatch = phaseSection.match(/(?:^|\n)(\*{0,2}Plans\*{0,2}:[^\n]*\n)((?:\s*-\s*\[[ x]\][^\n]*\n?)+)/i);
+        // #3415: empirically verified linear-time to 10.9MB / 320,000 lines of adversarial
+        // checklist input (0.31ms@1000 lines -> 8.4ms@320,000 lines). The outer `+` group has
+        // no trailing constraint after it in the pattern, so a successful greedy pass never
+        // needs to explore alternate `\r?\n?` boundary partitions to satisfy something later —
+        // it accepts the first complete parse and stops, which rules out the #2128-class
+        // ambiguous-boundary blowup despite the nested-quantifier shape. Non-global match on
+        // already phase-sliced content, not the whole file.
+        // eslint-disable-next-line local/no-unbounded-quantifier -- outer `+` has no trailing constraint to force re-partitioning; measured linear to 10.9MB
+        const plansBlockMatch = phaseSection.match(/(?:^|\r?\n)(\*{0,2}Plans\*{0,2}:[^\r\n]*\r?\n)((?:\s*-\s*\[[ x]\][^\r\n]*\r?\n?)+)/i);
         if (!plansBlockMatch)
             return;
         const plansHeader = plansBlockMatch[1];
         const existingList = plansBlockMatch[2];
-        const listLines = existingList.split('\n').filter(l => /^\s*-\s*\[/.test(l));
+        const listLines = (0, text_lines_cjs_1.splitLines)(existingList).filter(l => /^\s*-\s*\[/.test(l));
         if (listLines.length === 0)
             return;
         // #314 perf: build a first-wins Map so per-line lookup is O(1) instead of O(plans).
@@ -834,11 +1167,22 @@ function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
                 annotatedLines.push(`- ${t}`);
             }
         }
-        const newListBlock = annotatedLines.join('\n') + '\n';
-        // #1103: when `(?:^|\n)` consumed a leading `\n` (mid-string match), re-emit it
-        // so the line preceding the Plans: header is not fused onto it.
-        const leadingNewline = plansBlockMatch[0].startsWith('\n') ? '\n' : '';
-        const newPhaseSection = phaseSection.replace(plansBlockMatch[0], leadingNewline + plansHeader + newListBlock);
+        const newListBlock = (0, text_lines_cjs_1.joinLines)(annotatedLines, eol) + eol;
+        // #1103: when `(?:^|\r?\n)` consumed a leading terminator (mid-string
+        // match), re-emit it verbatim so the line preceding the Plans: header is
+        // not fused onto it. #3413: the widened `(?:^|\r?\n)` can now consume a
+        // 2-char `\r\n` — re-emit whatever was actually captured (`''`, `'\n'`,
+        // or `'\r\n'`), not a hardcoded `'\n'`, or a CRLF file loses its `\r`.
+        const leadingMatch = /^\r?\n/.exec(plansBlockMatch[0]);
+        const leadingNewline = leadingMatch ? leadingMatch[0] : '';
+        // Review fix (#3413 security): use the FUNCTION-replacement form. The
+        // string-replacement form expands String#replace's special patterns
+        // (`$&`, `` $` ``, `$'`, `$$`, `$1`-`$9`) inside the replacement — and
+        // newListBlock is built from author-controlled truths/plan-file content,
+        // so a line containing a literal `` $` `` (etc.) would splice unrelated
+        // surrounding phaseSection text into the result. A function replacer is
+        // never pattern-interpreted.
+        const newPhaseSection = phaseSection.replace(plansBlockMatch[0], () => leadingNewline + plansHeader + newListBlock);
         const nextContent = content.slice(0, phaseStart) + newPhaseSection + content.slice(phaseEnd);
         if (nextContent === content)
             return;
@@ -856,6 +1200,8 @@ module.exports = {
     cmdRoadmapGetPhase,
     getRoadmapPhaseWithFallback,
     cmdRoadmapAnalyze,
+    cmdRoadmapMilestoneScope,
     cmdRoadmapUpdatePlanProgress,
     cmdRoadmapAnnotateDependencies,
+    buildPhaseHeadingRegex,
 };