@opengsd/gsd-core 1.11.0 → 1.12.0

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

@@ -29,7 +29,7 @@ const cliExitMod = require("./cli-exit.cjs");
 const { ExitError } = cliExitMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserMod = require("./roadmap-parser.cjs");
-const { extractCurrentMilestoneScoped } = roadmapParserMod;
+const { extractCurrentMilestoneScoped, hasPhaseEntries } = roadmapParserMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningScopeMod = require("./planning-scope.cjs");
 const { SCOPE } = planningScopeMod;
@@ -151,11 +151,45 @@ function routeRoadmapCommand({ roadmap, args, cwd, raw, error }) {
                         warnings.push({ code: 'V003', message: 'ROADMAP.md frontmatter is malformed (unterminated --- fence)' });
                     }
                 }
-                // No recognizable phase structure — at least one `### Phase N:` heading.
-                // Mirrors the phase-heading pattern used across roadmap-parser.cts.
-                const hasPhaseEntry = /^#{2,4}\s*Phase\s+\S/im.test(roadmapContent);
+                // #3641: resolve phase_id_convention ONCE, ahead of every consumer in
+                // this validate pass — V004's entry check and V005's scope classifier
+                // below, and the W021 milestone-prefix check after them.
+                // Authoritative source: .planning/config.json (set by the upgrade
+                // command). Fallback: ROADMAP.md frontmatter (for projects that set
+                // the field there directly).
+                let convention;
+                try {
+                    const cfg = loadConfig(cwd);
+                    convention = cfg['phase_id_convention'];
+                }
+                catch {
+                    convention = undefined;
+                }
+                if (convention === undefined || convention === null) {
+                    // Fallback: read from ROADMAP.md frontmatter. Bounded to match
+                    // cmdRoadmapMilestoneScope's copy exactly (#3641 review NEW-1: an
+                    // unbounded capture here read past 4KB frontmatters the probe's
+                    // bounded copy could not, diverging validate from the probe).
+                    const fmMatch = roadmapContent.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 !== '') {
+                                convention = val.replace(/^["']|["']$/g, '');
+                            }
+                        }
+                    }
+                }
+                // No recognizable phase structure. #3641: routed through the
+                // roadmap-parser owner (`hasPhaseEntries` — headings, #2199 bullets,
+                // #3577 table rows) instead of a private inline heading regex, so the
+                // document-level check and the V005 scope axis below can never
+                // disagree about what a phase entry is — and so a bracket-convention
+                // project's `### [GSD.04] 01:` entries are entries here too.
+                const hasPhaseEntry = hasPhaseEntries(roadmapContent, convention);
                 if (!hasPhaseEntry && !warnings.some((w) => w.code === 'V002')) {
-                    warnings.push({ code: 'V004', message: 'ROADMAP.md contains no recognizable phase entries (no "### Phase N:" headings)' });
+                    warnings.push({ code: 'V004', message: 'ROADMAP.md contains no recognizable phase entries (no phase headings, bullet entries, or table rows)' });
                 }
                 // #3263: a whole-document phase check (V004 above) is satisfied by a
                 // document whose phase entries live OUTSIDE the active milestone's
@@ -169,12 +203,14 @@ function routeRoadmapCommand({ roadmap, args, cwd, raw, error }) {
                 // an unscoped/unreadable window is a different failure mode with a
                 // different remediation, deliberately not warned here.
                 try {
-                    const scoped = extractCurrentMilestoneScoped(contentAfterBom, cwd);
+                    // #3641: thread the resolved convention so the scope axis's
+                    // hasPhaseEntries comparison recognizes bracket phase entries.
+                    const scoped = extractCurrentMilestoneScoped(contentAfterBom, cwd, undefined, convention);
                     if (scoped.scope === SCOPE.TRUNCATED) {
                         warnings.push({
                             code: 'V005',
                             message: 'Active milestone window is truncated: phase entries exist in ROADMAP.md but are excluded from the ' +
-                                'active milestone\'s resolved window (check for a heading between the milestone heading and its "### Phase N:" sections)',
+                                'active milestone\'s resolved window (check for a heading between the milestone heading and its phase-entry sections)',
                         });
                     }
                 }
@@ -182,30 +218,8 @@ function routeRoadmapCommand({ roadmap, args, cwd, raw, error }) {
                     // The classifier is best-effort here — a throw must not mask the
                     // structural warnings already collected above.
                 }
-                // W021 only fires when phase_id_convention is explicitly 'milestone-prefixed'.
-                // Authoritative source: .planning/config.json (set by the upgrade command).
-                // Fallback: ROADMAP.md frontmatter (for projects that set the field there directly).
-                let convention;
-                try {
-                    const cfg = loadConfig(cwd);
-                    convention = cfg['phase_id_convention'];
-                }
-                catch {
-                    convention = undefined;
-                }
-                if (convention === undefined || convention === null) {
-                    // Fallback: read from ROADMAP.md frontmatter
-                    const fmMatch = roadmapContent.match(/^---\r?\n([\s\S]+?)\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 !== '') {
-                                convention = val.replace(/^["']|["']$/g, '');
-                            }
-                        }
-                    }
-                }
+                // W021 only fires when phase_id_convention is explicitly
+                // 'milestone-prefixed' — the same hoisted resolution above (#3641).
                 if (convention === 'milestone-prefixed') {
                     warnings.push(...checkW021(roadmapContent));
                 }

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

@@ -29,7 +29,10 @@ const phaseIdModule = require("./phase-id.cjs");
 const { phaseMarkdownRegexSource, stripProjectCodePrefix, OPTIONAL_PHASE_TAG_SOURCE, 
 // #2121: roadmapPhaseLookupSources now lives in phase-id.cjs (single owner of
 // the lookup-source ordering); imported here rather than defined locally.
-roadmapPhaseLookupSources, extractPhaseToken, isSentinelPhaseId, } = phaseIdModule;
+roadmapPhaseLookupSources, extractPhaseToken, isSentinelPhaseId, 
+// #3641: the single-owner heading-intro and digit-token grammar sources —
+// see BRACKET_PHASE_ENTRY_HEADING_RE below.
+PHASE_HEADING_PREFIX_SRC, PHASE_NUMBER_TOKEN_SOURCE, } = phaseIdModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
 const { planningDir } = planningWorkspace;
@@ -340,7 +343,7 @@ const MILESTONE_HEADING_SIGNAL_PATTERN = /v\d+\.\d+|✅|📋|🚧|\bMilestone\b/
  * template or the #3204/#1761/#3185 reports exercises that shape; it is
  * recorded here rather than hidden.
  */
-function hasMilestoneSectioning(content) {
+function countMilestoneHeadings(content) {
     const isPhaseHeading = (text) => /^Phase\s+\S/i.test(text);
     let milestoneHeadingCount = 0;
     for (const heading of (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(content)) {
@@ -351,10 +354,29 @@ function hasMilestoneSectioning(content) {
         if (!MILESTONE_HEADING_SIGNAL_PATTERN.test(heading.text))
             continue;
         milestoneHeadingCount++;
-        if (milestoneHeadingCount >= 2)
-            return true;
     }
-    return false;
+    return milestoneHeadingCount;
+}
+function hasMilestoneSectioning(content) {
+    // The >=2 short-circuit the inline walk used to have is gone — a ROADMAP's
+    // heading count is small and tokenizeHeadings materializes the full token
+    // array regardless, so the shared walk pays nothing for it.
+    return countMilestoneHeadings(content) >= 2;
+}
+/**
+ * #3642: the >=1 sibling of `hasMilestoneSectioning`. The >=2 predicate
+ * answers SIBLING-conflation ("could two sections' phases mix") and is
+ * unchanged; but `buildStateFrontmatter`'s unbounded branch asks a question
+ * >=2 under-answers: "is there ANY milestone section whose phases a
+ * whole-document count would attribute to a milestone that matches no
+ * heading?" With exactly ONE section and an asserted milestone absent from
+ * the ROADMAP, >=2 said "flat" and the single section's phases leaked into
+ * the asserted milestone's total_phases (silent clobber of the stored
+ * value). Same walk, same vocabulary, threshold 1 — exported for that
+ * consumer only; every other consumer keeps the >=2 semantics.
+ */
+function hasAnyMilestoneSection(content) {
+    return countMilestoneHeadings(content) >= 1;
 }
 /**
  * #3184: the sole "which heading is this milestone's" rule — locate the version's
@@ -405,14 +427,39 @@ function sliceMilestoneWindow(content, version) {
  * exist" — a window containing only sentinel phases still reached the
  * region and must read COMPLETE, not TRUNCATED.
  */
-function hasPhaseEntries(markdown) {
+// #3641: the bracket-convention phase-ENTRY heading shape — ADR-612 Decision
+// 1's own discriminator: a phase heading is a bracket followed by a
+// DIGIT-then-colon (`### [GSD.04] 01: Name`); a bracket followed by a NAME
+// is a milestone heading and must never count. Every fragment interpolates a
+// single-owner export from phase-id.cts — the heading intro
+// (PHASE_HEADING_PREFIX_SRC: a `[...]` bracket optionally followed by a
+// `Phase ` label, or a bare `Phase ` label), the digit-bearing token
+// (PHASE_NUMBER_TOKEN_SOURCE, which also covers the dotted sub-phase form
+// `[GSD.02] 05.03:`), and the optional pre-colon tag
+// (OPTIONAL_PHASE_TAG_SOURCE) — never a re-typed grammar. Tested IN
+// ADDITION to the legacy pattern below, so bracket mode is a strict
+// superset: mid-migration legacy-labeled headings (`Phase AUTH-101:`-style
+// custom ids included) keep their existing recognition. Review finding: an
+// earlier single-alternative form with a `[\\w]` token admitted
+// `[bracket] Word:` shapes — a colon-bearing MILESTONE heading inside the
+// window read as an entry (defeating V005 outright for that spelling) and a
+// decoy `### [GSD.04] Notes:` outside the window manufactured a false V005
+// while suppressing the correct V004. The digit anchor forecloses both.
+const BRACKET_PHASE_ENTRY_HEADING_RE = new RegExp(`^${PHASE_HEADING_PREFIX_SRC}${PHASE_NUMBER_TOKEN_SOURCE}${OPTIONAL_PHASE_TAG_SOURCE}\\s*:`, 'i');
+function hasPhaseEntries(markdown, phaseIdConvention) {
     // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+    // #3641: the widened grammar engages ONLY when the resolved convention is
+    // 'bracket' — a project that has not opted in runs the legacy pattern
+    // alone, byte-identically.
     const phaseHeadingPattern = /^(?:\[[^\]]{1,200}\]\s*)?Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]{0,200}\))?\s*:/i;
+    const bracketMode = phaseIdConvention === 'bracket';
     for (const h of (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(markdown)) {
         if (h.level < 2 || h.level > 4)
             continue;
         if (phaseHeadingPattern.test(h.text))
             return true;
+        if (bracketMode && BRACKET_PHASE_ENTRY_HEADING_RE.test(h.text))
+            return true;
     }
     // #3184 review finding: the bullet fallback must be fence-aware too, or a
     // FENCED markdown EXAMPLE of the `- [ ] **Phase N — Name**` syntax (e.g. a
@@ -592,8 +639,18 @@ function classifyMilestoneWindow(input) {
  * symbols, 20 direct callers) means its signature and return type do not
  * change. This is the real owner; `extractCurrentMilestone` becomes a
  * one-line wrapper returning `.value` so every existing caller is untouched.
+ *
+ * @param phaseIdConvention - #3641: the RESOLVED `phase_id_convention`
+ *   config value, threaded to `hasPhaseEntries` so the scope axis's row-8
+ *   comparison recognizes bracket-convention phase entries
+ *   (`### [GSD.04] 01: Name`). Optional: absent, or any value other than
+ *   `'bracket'`, compiles the legacy entry grammar byte-identically — the
+ *   widening engages only for a project that resolved the convention
+ *   explicitly. `extractCurrentMilestone`'s wrapper deliberately does NOT
+ *   expose it (its 20 callers are not the scope-axis consumers; V005's
+ *   router site and `getMilestonePhaseFilter` resolve and thread it).
  */
-function extractCurrentMilestoneScoped(content, cwd, ws) {
+function extractCurrentMilestoneScoped(content, cwd, ws, phaseIdConvention) {
     if (!cwd) {
         // Row 1: a deliberate unscoped read (no cwd supplied) is a real answer —
         // the caller asked for no scoping, so whole-document is COMPLETE.
@@ -631,12 +688,12 @@ function extractCurrentMilestoneScoped(content, cwd, ws) {
                 versionResolved,
                 hasVersionedMilestones: versionedMilestonesPresent,
                 headingFound: false,
-                windowHasPhaseEntries: hasPhaseEntries(value),
-                documentHasPhaseEntries: hasPhaseEntries(value),
+                windowHasPhaseEntries: hasPhaseEntries(value, phaseIdConvention),
+                documentHasPhaseEntries: hasPhaseEntries(value, phaseIdConvention),
             }),
         };
     }
-    const documentHasPhaseEntries = hasPhaseEntries(stripShippedMilestones(content));
+    const documentHasPhaseEntries = hasPhaseEntries(stripShippedMilestones(content), phaseIdConvention);
     const summaryPattern = new RegExp(`<summary[^>]*>([^<]*${(0, pattern_cjs_1.escapeRegex)(version)}[^<]*)<\\/summary>`, 'i');
     const headingMatches = locateMilestoneHeadings(content, version);
     if (headingMatches.length === 0) {
@@ -666,7 +723,7 @@ function extractCurrentMilestoneScoped(content, cwd, ws) {
                         versionResolved,
                         hasVersionedMilestones: versionedMilestonesPresent,
                         headingFound: true,
-                        windowHasPhaseEntries: hasPhaseEntries(value),
+                        windowHasPhaseEntries: hasPhaseEntries(value, phaseIdConvention),
                         documentHasPhaseEntries,
                     }),
                 };
@@ -680,7 +737,7 @@ function extractCurrentMilestoneScoped(content, cwd, ws) {
                 versionResolved,
                 hasVersionedMilestones: versionedMilestonesPresent,
                 headingFound: false,
-                windowHasPhaseEntries: hasPhaseEntries(value),
+                windowHasPhaseEntries: hasPhaseEntries(value, phaseIdConvention),
                 documentHasPhaseEntries,
             }),
         };
@@ -756,7 +813,7 @@ function extractCurrentMilestoneScoped(content, cwd, ws) {
             versionResolved,
             hasVersionedMilestones: versionedMilestonesPresent,
             headingFound: true,
-            windowHasPhaseEntries: hasPhaseEntries(value),
+            windowHasPhaseEntries: hasPhaseEntries(value, phaseIdConvention),
             documentHasPhaseEntries,
         }),
     };
@@ -1257,7 +1314,7 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention, ws) {
         const roadmapContent = (0, shell_command_projection_cjs_1.platformReadSync)(roadmapPath);
         if (roadmapContent === null)
             throw new Error('missing');
-        const scopedResult = extractCurrentMilestoneScoped(roadmapContent, cwd, ws);
+        const scopedResult = extractCurrentMilestoneScoped(roadmapContent, cwd, ws, phaseIdConvention);
         let roadmap = scopedResult.value;
         // Default: the filter's window IS extractCurrentMilestoneScoped's own
         // window (reused verbatim, not re-derived — ADR-3180 Decision 4c).
@@ -1289,7 +1346,7 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention, ws) {
             // via `currentVersion`), and `buildStateFrontmatter` (state.cts:1700,
             // via `storedMilestone`).
             const sliced = sliceMilestoneWindow(roadmapContent, versionOverride);
-            const documentHasPhaseEntries = hasPhaseEntries(stripShippedMilestones(roadmapContent));
+            const documentHasPhaseEntries = hasPhaseEntries(stripShippedMilestones(roadmapContent), phaseIdConvention);
             if (sliced !== null) {
                 versionScoped = true;
                 versionSectionFound = true;
@@ -1312,7 +1369,7 @@ function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention, ws) {
                 versionResolved: true,
                 hasVersionedMilestones: hasVersionedMilestonesGlobal,
                 headingFound: sliced !== null,
-                windowHasPhaseEntries: hasPhaseEntries(roadmap),
+                windowHasPhaseEntries: hasPhaseEntries(roadmap, phaseIdConvention),
                 documentHasPhaseEntries,
             });
         }
@@ -1508,6 +1565,8 @@ module.exports = {
     sliceMilestoneWindow,
     hasVersionedMilestones,
     hasMilestoneSectioning,
+    // #3642: the >=1 sibling buildStateFrontmatter's unbounded branch consumes.
+    hasAnyMilestoneSection,
     // #1956: sole owner of the #2012 decoy-avoidance scope for the
     // `drift-guard phase-status` CLI seam.
     findRoadmapProgressTable,
@@ -1518,4 +1577,8 @@ module.exports = {
     scanMilestonePhaseIds,
     collectTablePhaseRows,
     findMilestoneScopeHeadingLines,
+    // #3641: the scope axis's phase-ENTRY predicate, exported so roadmap
+    // validate's V004 document-level check routes through the same single
+    // owner (and its convention gate) instead of a private inline copy.
+    hasPhaseEntries,
 };

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

@@ -16,13 +16,13 @@ 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 { 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, listMilestonePhaseDirs } = phaseLocatorMod;
+const { findPhaseInternal, listMilestonePhaseDirs, listAllPhaseDirs } = phaseLocatorMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningScopeMod = require("./planning-scope.cjs");
 const { SCOPE } = planningScopeMod;
@@ -36,6 +36,11 @@ 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
@@ -89,10 +94,21 @@ 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
@@ -104,6 +120,7 @@ function countPhasePlansAndSummaries(phaseDir) {
         summaryCount,
         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.
@@ -332,6 +349,10 @@ function collectAnalyzePhases(content, phasesDir, phaseDirNames) {
         let summaryCount = 0;
         let hasContext = false;
         let hasResearch = false;
+        // #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
@@ -345,6 +366,7 @@ function collectAnalyzePhases(content, phasesDir, phaseDirNames) {
             summaryCount = counts.summaryCount;
             hasContext = counts.hasContext;
             hasResearch = counts.hasResearch;
+            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
@@ -394,6 +416,7 @@ function collectAnalyzePhases(content, phasesDir, phaseDirNames) {
             has_research: hasResearch,
             disk_status: diskStatus,
             roadmap_complete: roadmapComplete,
+            context_read_error: contextReadError,
         });
     }
     // #3577: markdown-table row declarations join the enumeration — same
@@ -410,12 +433,18 @@ function collectAnalyzePhases(content, phasesDir, phaseDirNames) {
         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,
@@ -429,6 +458,7 @@ function collectAnalyzePhases(content, phasesDir, phaseDirNames) {
             has_research: tHasResearch,
             disk_status: dirMatchA ? 'ok' : 'no_directory',
             roadmap_complete: false,
+            context_read_error: tContextReadError,
         });
     }
     return phases;
@@ -446,21 +476,17 @@ function cmdRoadmapAnalyze(cwd, raw) {
     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 (documented reason, not a file allowlist — 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.
-    const _phaseDirNames = (() => {
-        try {
-            return node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true })
-                .filter(e => e.isDirectory())
-                .map(e => e.name);
-        }
-        catch {
-            return [];
-        }
-    })();
+    // #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.
@@ -615,7 +641,36 @@ function cmdRoadmapMilestoneScope(cwd, raw) {
         return;
     }
     const rawContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
-    const { value: window, scope } = extractCurrentMilestoneScoped(rawContent, cwd);
+    // #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);