@opengsd/gsd-core 1.14.0 → 1.15.0

package/gsd-core/bin/lib/capability-validator.cjs

@@ -1947,7 +1947,6 @@ const KNOWN_HOST_BEHAVIORS = new Set([
   'skillPriorityFrontmatter',
   'skillsGlobalOnboarding',
   'skillsManifestPrefix',
-  'skipCodexSkillsManifest',
   'skipHomePrefixSubstitution',
   'skipSettingsUi',
   'skipSharedHooksInstall',

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

@@ -281,6 +281,7 @@ function loadDecisionExtraction(contextPath) {
     return {
         trackable: extraction.decisions.filter((d) => d.trackable),
         outcome: extraction.outcome,
+        unreadableIds: extraction.unreadableIds ?? [],
     };
 }
 /**
@@ -329,21 +330,48 @@ function cmdDecisionCoveragePlan(projectDir, args, raw) {
         output({ passed: true, skipped: true, reason: 'CONTEXT.md missing', total: 0, covered: 0, uncovered: [], message: 'No CONTEXT.md - nothing to check.' }, raw, undefined);
         return;
     }
-    const { trackable: decisions, outcome } = loadDecisionExtraction(contextPath);
+    // #4794: a NON-FILE path (a directory — the adjacent same-looking positional
+    // swapped, the issue's repro 2) is a caller error like #2770's empty argument:
+    // fs.existsSync is true, the read yields nothing, and the gate used to
+    // certify passed:true on a phase full of decisions. Fail closed, naming it.
+    // The stat is wrapped: a path that vanishes between existsSync and statSync
+    // (or any stat failure) must answer the SAME fail-closed JSON, never a throw.
+    let contextIsFile = false;
+    let contextKind = 'non-file entry';
+    try {
+        const st = node_fs_1.default.statSync(contextPath);
+        contextIsFile = st.isFile();
+        if (st.isDirectory())
+            contextKind = 'directory';
+    }
+    catch {
+        contextIsFile = false;
+        contextKind = 'unreadable path';
+    }
+    if (!contextIsFile) {
+        output({ passed: false, skipped: false, reason: 'context path is not a file', total: null, covered: null, message: `Decision coverage gate: the context path "${contextArg}" is not a readable file (${contextKind}). Swap the adjacent positionals or pass --context <path-to-CONTEXT.md>.` }, raw, undefined);
+        return;
+    }
+    const { trackable: decisions, outcome, unreadableIds } = loadDecisionExtraction(contextPath);
     // #1365 fail-loud gate: any could-not-parse outcome must NOT silently pass —
     // even when some decisions were extracted (e.g. D-01 valid but D-02 malformed).
     // A parse-miss on ANY bullet means the gate cannot certify full coverage.
     // Fire independent of decisions.length so a partial-parse still blocks.
     if (outcome === 'could-not-parse') {
+        // #4794: nothing was measured — the answer must not carry the fields of a
+        // gate that did. total/covered are null (a type change is the point:
+        // 0 reads as data, null does not), `uncovered` is OMITTED (the list was
+        // never built), and the ids that failed to parse are carried so a caller
+        // capturing stdout knows which decision to fix.
         const partialParse = decisions.length > 0;
         output({
             passed: false,
             skipped: false,
             reason: 'could-not-parse',
-            total: decisions.length,
-            covered: 0,
-            uncovered: [],
-            message: partialParse
+            total: null,
+            covered: null,
+            unreadable: unreadableIds,
+            message: (partialParse
                 ? 'Decision coverage gate: decisions could not be fully parsed — one or more ' +
                     '`- **D-NN ...**` bullets appear malformed (missing `:` or ` — ` separator, or a phase ' +
                     'prefix that is not a digit run, e.g. `D4x-01`). Fix the bullet format so all decisions ' +
@@ -353,7 +381,8 @@ function cmdDecisionCoveragePlan(projectDir, args, raw) {
                     'or D- tokens) but no decision bullets could be extracted. Check the formatting of the decisions ' +
                     'block and ensure bullets follow the `- **D-NN:** text`, `- **D4-NN:** text` (phase-prefixed), ' +
                     'or `- **D-NN — title** body` form. An ID grammar the parser does not support (e.g. `DEC-01`) ' +
-                    'also lands here.',
+                    'also lands here.')
+                + (unreadableIds.length > 0 ? ' Unreadable ids: ' + unreadableIds.join(', ') + '.' : ''),
         }, raw, undefined);
         return;
     }
@@ -546,8 +575,10 @@ function findUiSpecInDir(phaseDir) {
  * matches the token `dashboard` exactly like the real compound `micro-frontend`
  * (the boundary rule of #3718 is intentional and untouched). The gate therefore
  * blocks only when the token match is corroborated by static frontend evidence
- * in the repo tree (hasStaticFrontendEvidence: package.json UI-framework dep or
- * a component-framework file). This mirrors the sibling post-wave gate
+ * in the repo tree (hasStaticFrontendEvidence: package.json UI-framework dep, a
+ * component-framework file, or native UI evidence — a `.xaml` file or a
+ * `.swift`/`.kt`/`.dart` file carrying its ecosystem's UI import marker,
+ * #4658). This mirrors the sibling post-wave gate
  * computeUiSafetyGate, which requires `hasUiFiles` (git diff) before blocking.
  * matchedToken/matchedLine surface what tripped the sniffer so an operator can
  * judge the flag in one second instead of reaching for --skip-ui.
@@ -969,8 +1000,22 @@ function resolvePhaseDirOrEmpty(projectDir, phase) {
  * phase's `-PLAN.md` files against the filesystem WITHOUT executing anything —
  * see verify-command-grounding.cjs for the recognizer contract.
  *
- * Args: check verify-command-paths <phase>
+ * Args: check verify-command-paths <phase> | check verify-command-paths --dir <plan-dir>
  * Invocable as: gsd_run check verify-command-paths <phase>
+ *               gsd_run check verify-command-paths --dir <plan-dir>
+ *
+ * `--dir` (#4767) names a directory holding `-PLAN.md` files directly, for
+ * plans that live outside `.planning/phases/` — quick mode's
+ * `.planning/quick/<id>/` is the motivating caller, which until #4767 never ran
+ * this probe at all. The directory is resolved against the project root AND
+ * CONTAINED WITHIN IT — an absolute or climbing `--dir` that lands outside the
+ * root is `unresolvable`, never read — then probed exactly as a phase directory
+ * is; `projectRoot` stays the project root in both forms. `--dir <value>` is the
+ * only accepted spelling: `--dir=<value>` yields no `dir` flag and falls through to
+ * the no-argument arm, as does an empty value. Both are `partitionPredicateArgs`
+ * behaviour, inherited and unchanged. (How that parser resolves a REPEATED `--dir`
+ * is deliberately not characterised here — a malformed later occurrence does not
+ * displace an earlier valid one, so the obvious "last one wins" gloss is wrong.)
  *
  * When the phase cannot be resolved to a directory, this emits a non-throwing
  * degraded JSON payload (status/commands/counts all zeroed, `readError`
@@ -979,18 +1024,60 @@ function resolvePhaseDirOrEmpty(projectDir, phase) {
  * look", which a non-zero exit / thrown error would collapse.
  */
 function cmdVerifyCommandPaths(projectDir, args, raw) {
-    // args[0] = 'check', args[1] = 'verify-command-paths', args[2] = phase
-    const phase = args[2] || '';
-    if (!phase) {
+    // args[0] = 'check', args[1] = 'verify-command-paths', then either a phase
+    // positional or `--dir <plan-dir>` (#4767).
+    const { flags, positionals } = partitionPredicateArgs(args.slice(2));
+    const dirFlag = typeof flags['dir'] === 'string' ? flags['dir'] : '';
+    // First non-flag positional: `--raw` (valueless) lands in positionals too, and its position
+    // relative to the phase argument is the caller's choice.
+    const phase = positionals.find(p => !p.startsWith('--')) ?? '';
+    if (!phase && !dirFlag) {
         output({
             status: 'unresolvable',
             commands: [],
             counts: { blocker: 0, warning: 0, total: 0 },
-            readError: 'verify-command-paths requires a phase argument: check verify-command-paths <phase>',
+            readError: 'verify-command-paths requires a phase argument or --dir: check verify-command-paths <phase> | --dir <plan-dir>',
         }, raw, undefined);
         return;
     }
-    const phaseDir = resolvePhaseDirOrEmpty(projectDir, phase);
+    // `--dir` is CALLER-SUPPLIED, so it is contained before it reaches the
+    // `readdirSync`/`readFileSync` calls in probePhaseVerifyCommands (#4785 review).
+    // Same predicate and policy as `resolvePath` above, and for the reason ADR-4650
+    // gives at the other read site: the reads below FOLLOW SYMLINKS, so containment
+    // must be decided on the resolved target, not a lexical prefix — a link inside
+    // the root pointing outside it passes `tryWithinRootLexical` and is then read.
+    // Read the value the predicate RETURNED; never re-derive the path. An escape
+    // degrades to the same non-throwing payload the unresolvable-phase arm emits,
+    // because a consumer must be able to tell "could not look" from "nothing to
+    // report" (and `error()` would collapse them).
+    //
+    // RESIDUAL, stated rather than left to be rediscovered: this is check-then-use, so
+    // a symlink planted at the resolved path BETWEEN this call and the reads inside
+    // probePhaseVerifyCommands would be followed. A link already in place when the
+    // command runs IS refused — the predicate resolves it and returns null (driven) —
+    // so the window is the in-process gap, not the ordinary case. It is a property of
+    // every `tryWithinRoot` call site in this repo, including `resolvePath` above and
+    // the artifact scan below, not of this arm; closing it needs O_NOFOLLOW/dirfd
+    // semantics inside the ADR-4650 predicate, which is a wider change than the bug
+    // this fixes.
+    let phaseDir;
+    if (dirFlag) {
+        const candidate = node_path_1.default.isAbsolute(dirFlag) ? dirFlag : node_path_1.default.join(projectDir, dirFlag);
+        const contained = (0, security_cjs_1.tryWithinRoot)(candidate, projectDir, security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
+        if (contained === null) {
+            output({
+                status: 'unresolvable',
+                commands: [],
+                counts: { blocker: 0, warning: 0, total: 0 },
+                readError: `--dir resolves outside the project root: ${dirFlag}`,
+            }, raw, undefined);
+            return;
+        }
+        phaseDir = contained;
+    }
+    else {
+        phaseDir = resolvePhaseDirOrEmpty(projectDir, phase);
+    }
     if (!phaseDir) {
         output({
             status: 'unresolvable',

package/gsd-core/bin/lib/codex-agent-toml.cjs

@@ -382,9 +382,9 @@ function stripReasoningEffort(doc) {
 /**
  * The 17 roles measured as widening under derivation (declare Write/Edit,
  * never in the pre-#3897 `CODEX_AGENT_SANDBOX` map, so the old
- * `|| 'read-only'` fallback silently under-granted them). Pinned to
- * `read-only` pending the open question of whether Codex enforces
- * `sandbox_mode` or treats it as advisory (HALT.md). This list is CLOSED and
+ * `|| 'read-only'` fallback silently under-granted them) — pinned to
+ * `read-only` from 2026-09-08 (HALT.md) until #4770 lifted the hold on
+ * 2026-09-21. This list is CLOSED and
  * SHRINK-ONLY: a new writing role never lands here (S6, T26); it is validated
  * against the live tool contract every time it is consulted
  * ({@link _deriveCodexSandboxModeFromTools}) and against the real
@@ -401,29 +401,25 @@ function stripReasoningEffort(doc) {
  * parses the list correctly, so this role genuinely derives
  * `workspace-write` from its tool contract — HALT.md's original 16-role
  * count measured against the pre-fix (single-line) readers and undercounted
- * this role. It is held here for the same reason as the other 16: pending
- * Codex's `sandbox_mode` enforcement decision, not because the derivation is
- * wrong.
+ * this role.
+ *
+ * **LIFTED 2026-09-21 (#4770, maintainer decision: documented enforcement
+ * suffices).** The map is empty: the rung-3 hold's recorded reopen condition
+ * — official OpenAI documentation establishing Codex `sandbox_mode` as an
+ * enforced technical boundary that custom subagent TOML files honor — is
+ * satisfied, so every role now derives `sandbox_mode` purely from its own
+ * `tools:` frontmatter (`workspace-write` iff Write/Edit is declared). The
+ * shrink-to-zero invariant (ADR-3473 §8.3) is satisfied by reaching zero;
+ * the map is kept as an empty frozen structure so a future re-hold has a
+ * shape to land in, and {@link validateCodexSandboxHolds} keeps failing if
+ * the list ever grows a role that no longer exists in `agents/`. The
+ * #3897 security-review F1/F3 fail-closed pins are unchanged and
+ * map-independent: `suspicious` identities (non-ASCII after
+ * normalization) still pin `read-only`, and post-lift the sandbox derives
+ * from an artifact's own CONTENT, so the F1 identity-confusion attack no
+ * longer has a hold to ride.
  */
-exports.CODEX_SANDBOX_HOLDS = Object.freeze({
-    'gsd-ai-researcher': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-code-fixer': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-code-reviewer': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-debug-session-manager': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-doc-classifier': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-doc-synthesizer': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-doc-verifier': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-doc-writer': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-dom-verifier': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-domain-researcher': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-eval-auditor': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-eval-planner': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-intel-updater': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-pattern-mapper': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-ui-auditor': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-ui-researcher': 'declares Write/Edit; pending Codex sandbox_mode enforcement decision',
-    'gsd-nyquist-auditor': 'declares Write/Edit (YAML list-form tools:, surfaced by the list-form parse fix); pending Codex sandbox_mode enforcement decision',
-});
+exports.CODEX_SANDBOX_HOLDS = Object.freeze({});
 // True iff a `tools:` frontmatter value declares Write or Edit as a whole
 // token (never a substring match, so a hypothetical "Edith"-named tool could
 // never collide). Single predicate owner for both the emitter

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

@@ -30,7 +30,10 @@ const coreUtilsMod = require("./core-utils.cjs");
 const { toPosixPath, generateSlugInternal, extractOneLinerFromBody } = coreUtilsMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { normalizePhaseName, comparePhaseNum, extractPhaseToken, PHASE_NUMBER_TOKEN_SOURCE, isSentinelPhaseId, renderPhaseBranchName } = phaseIdMod;
+const { normalizePhaseName, comparePhaseNum, extractPhaseToken, PHASE_NUMBER_TOKEN_SOURCE, isSentinelPhaseId, renderPhaseBranchName, parsePhaseId, renderPhaseId, phaseHeadingPrefixSrcFor, PHASE_HEADING_BASELINE, } = phaseIdMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseIdDisplayMod = require("./phase-id-display.cjs");
+const { renderBracketMilestoneDisplay } = phaseIdDisplayMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
 const { getArchivedPhaseDirs, findPhaseInternal, listMilestonePhaseDirs } = phaseLocatorMod;
@@ -56,7 +59,7 @@ const codex_agent_toml_cjs_1 = require("./codex-agent-toml.cjs");
 const hostIntegrationMod = require("./host-integration.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
-const { planningDir, planningPaths, todosDir } = planningWorkspace;
+const { planningDir, planningPaths, todosDir, resolvePhaseIdConvention } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatter = require("./frontmatter.cjs");
 const { extractFrontmatter, agentScalarNeedsDoubleQuoting, escapeDoubleQuotedScalar } = frontmatter;
@@ -72,6 +75,32 @@ const { scanPhasePlans } = planScanMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- verification.cjs is an export= CommonJS module
 const verificationMod = require("./verification.cjs");
 const { resolveVerificationFile } = verificationMod;
+/**
+ * Project one canonical bracket directory onto its display identity and slug.
+ *
+ * The identity is deliberately obtained only through parsePhaseId/renderPhaseId;
+ * this helper owns no second bracket grammar. Callers invoke it only after the
+ * project's resolved convention is exactly `bracket`.
+ */
+function bracketPhaseDirProjection(dir) {
+    const id = parsePhaseId(dir);
+    const number = id.subphase ? `${id.phase}.${id.subphase}` : id.phase;
+    const identityPrefix = `${id.project}.${id.milestone}-${number}`;
+    const slug = dir.slice(identityPrefix.length).replace(/^-/, '');
+    return {
+        number,
+        display_id: renderPhaseId(id),
+        name: slug ? slug.replace(/-/g, ' ') : '',
+    };
+}
+function recoverBracketPhaseName(dir, phaseToken) {
+    const tokenBoundary = `-${phaseToken}`;
+    const tokenOffset = dir.indexOf(tokenBoundary);
+    if (tokenOffset === -1)
+        return '';
+    const afterToken = dir.slice(tokenOffset + tokenBoundary.length).replace(/^-/, '');
+    return afterToken ? afterToken.replace(/-/g, ' ') : '';
+}
 // ─── Phase Status ─────────────────────────────────────────────────────────────
 /**
  * Phase-status precedence ladder — furthest-along wins (#2408).
@@ -237,26 +266,43 @@ function cmdListTodos(cwd, area, raw) {
  * displayed field is passed through sanitizeForDisplay and each file path is
  * validated with requireSafePath before reading. Read-only — never mutates.
  */
+/**
+ * Seed id grammars. `SEED-YYMMDD-xxx` (date + 3 base36 chars, the shape
+ * `.planning/quick/` uses) is what plant-seed has minted since #4378 removed
+ * the shared `wc -l` counter; `SEED-NNN` is the legacy counter form, which
+ * keeps parsing forever — existing seeds must never lose their identity.
+ *
+ * Known (theoretical, documented-not-fixed per #4378 review): a frontmatter-less
+ * legacy file whose counter is exactly 6 digits and whose slug opens with
+ * exactly 3 base36 chars parses as new-format. Requires a counter >= 100000 AND
+ * a missing frontmatter id; with frontmatter the legacy id always wins.
+ */
+const CANONICAL_SEED_ID_RE = /^SEED-(?:\d{6}-[a-z0-9]{3}|\d+)$/i;
+const SEED_ID_PREFIX_RE = /^(SEED-(?:\d{6}-[a-z0-9]{3}|\d+))/i;
+const SEED_SLUG_RE = /^SEED-(?:\d{6}-[a-z0-9]{3}|\d+)-(.+)$/i;
 /**
  * Derive the canonical `{ seed_id, slug }` from a seed filename stem and the
  * frontmatter `id:` value. Pure (no I/O) so it can be property-tested directly.
  *
- * seed_id: frontmatter `id:` when it matches `SEED-NNN`, else the numeric prefix
- * of the filename (`SEED-NNN-…`), else the whole stem. slug: the descriptive
- * remainder after `SEED-NNN-`, else the stem with a leading `SEED-` stripped.
- * `rawFmId` is `unknown` because frontmatter values are not guaranteed strings.
+ * seed_id: frontmatter `id:` when it matches a seed id grammar (`SEED-YYMMDD-xxx`
+ * or legacy `SEED-NNN`), else the id prefix of the filename (`SEED-…-<slug>`),
+ * else the whole stem. The prefix fallback must keep the FULL new-format id —
+ * truncating at the date gives every same-day seed the same id (#4378).
+ * slug: the descriptive remainder after the id, else the stem with a leading
+ * `SEED-` stripped. `rawFmId` is `unknown` because frontmatter values are not
+ * guaranteed strings.
  */
 function deriveSeedIdentity(stem, rawFmId) {
     const fmId = typeof rawFmId === 'string' ? rawFmId.trim() : '';
     let seedId;
-    if (/^SEED-\d+$/i.test(fmId)) {
+    if (CANONICAL_SEED_ID_RE.test(fmId)) {
         seedId = fmId;
     }
     else {
-        const numMatch = stem.match(/^(SEED-\d+)/i);
-        seedId = numMatch ? numMatch[1] : stem;
+        const prefixMatch = stem.match(SEED_ID_PREFIX_RE);
+        seedId = prefixMatch ? prefixMatch[1] : stem;
     }
-    const slugMatch = stem.match(/^SEED-\d+-(.+)$/i);
+    const slugMatch = stem.match(SEED_SLUG_RE);
     const slug = slugMatch ? slugMatch[1] : stem.replace(/^SEED-/i, '');
     return { seed_id: seedId, slug };
 }
@@ -303,9 +349,11 @@ function cmdListSeeds(cwd, statusFilter, raw) {
         // sanitizeForDisplay is for output, not comparison.
         if (wantStatus && status !== wantStatus)
             continue;
-        // Canonical seed id is `SEED-NNN` (frontmatter `id:`, e.g. SEED-001). Fall
-        // back to the numeric prefix of the filename, then to the whole stem. The
-        // descriptive remainder of the filename (`SEED-NNN-<slug>.md`) is the slug.
+        // Canonical seed ids are `SEED-YYMMDD-xxx` (frontmatter `id:`, what
+        // plant-seed has minted since #4378) or legacy `SEED-NNN`; deriveSeedIdentity
+        // owns that grammar. Fall back to the id prefix of the filename, then to the
+        // whole stem. The descriptive remainder of the filename (`SEED-…-<slug>.md`)
+        // is the slug.
         const stem = node_path_1.default.basename(entry.name, '.md');
         const { seed_id: seedId, slug } = deriveSeedIdentity(stem, fm.id);
         let title = (0, security_cjs_1.sanitizeForDisplay)(fmStr(fm.title).slice(0, 100));
@@ -503,13 +551,10 @@ function cmdResolveExecution(cwd, agentType, raw, opts) {
     opts = opts || {};
     const config = loadConfig(cwd);
     const profile = config['model_profile'] || 'balanced';
-    // #2068: resolve the model per-attempt so dynamic_routing escalates the MODEL
-    // (heavy tier) alongside effort. Gated on an explicit --attempt exactly like the
-    // effort resolution below, so the two fields stay symmetric: with no --attempt
-    // the model comes from the classic profile path (unchanged for everyone,
-    // including dynamic_routing-enabled users who don't pass --attempt), and only an
-    // explicit attempt routes through the tier ladder. resolveModelForTier itself
-    // still falls back to resolveModelInternal when dynamic_routing is off.
+    // #2068: resolve the model per-attempt so dynamic_routing ESCALATES the MODEL
+    // (heavy tier) alongside effort. The FIRST-spawn tier now comes from
+    // resolveModelInternal's own dynamic_routing step (#4505), so the absent-attempt
+    // branch below reaches it too — this gate is only about escalation.
     let model = (opts.attempt !== undefined && opts.attempt !== null)
         ? resolveModelForTier(cwd, agentType, opts.attempt)
         : resolveModelInternal(cwd, agentType);
@@ -3006,6 +3051,11 @@ async function cmdWebsearch(query, options, raw) {
 function cmdProgressRender(cwd, format, raw) {
     const phasesDir = planningPaths(cwd).phases;
     const milestone = getMilestoneInfo(cwd).value;
+    const phaseIdConvention = resolvePhaseIdConvention(cwd);
+    const milestoneDisplay = phaseIdConvention === 'bracket'
+        ? renderBracketMilestoneDisplay(milestone?.version, loadConfig(cwd).project_code)
+        : null;
+    const milestoneVersion = milestoneDisplay ?? milestone?.version ?? null;
     const phases = [];
     let totalPlans = 0;
     let totalSummaries = 0;
@@ -3016,12 +3066,36 @@ function cmdProgressRender(cwd, format, raw) {
         // comparePhaseNum. This command previously read the phases directory
         // directly with neither, which is why `query progress` listed 999.*
         // backlog directories as current-milestone phases (#3167).
-        const { value: dirs, scope } = listMilestonePhaseDirs(phasesDir, { cwd });
+        const { value: dirs, scope } = listMilestonePhaseDirs(phasesDir, {
+            cwd,
+            phaseIdConvention,
+        });
         phaseScope = scope;
         for (const dir of dirs) {
-            const dm = dir.match(/^(\d+(?:\.\d+)*)-?(.*)/);
-            const phaseNum = dm ? dm[1] : dir;
-            const phaseName = dm && dm[2] ? dm[2].replace(/-/g, ' ') : '';
+            let phaseNum;
+            let phaseName;
+            let displayId;
+            if (phaseIdConvention === 'bracket') {
+                try {
+                    const projection = bracketPhaseDirProjection(dir);
+                    phaseNum = projection.number;
+                    phaseName = projection.name;
+                    displayId = projection.display_id;
+                }
+                catch {
+                    // A malformed/tolerated directory must not suppress every later row.
+                    // It cannot receive a canonical display_id because parsePhaseId
+                    // rejected it, but the convention-aware token keeps it observable.
+                    const phaseToken = extractPhaseToken(dir, phaseIdConvention);
+                    phaseNum = phaseToken || dir;
+                    phaseName = recoverBracketPhaseName(dir, phaseToken);
+                }
+            }
+            else {
+                const dm = dir.match(/^(\d+(?:\.\d+)*)-?(.*)/);
+                phaseNum = dm ? dm[1] : dir;
+                phaseName = dm && dm[2] ? dm[2].replace(/-/g, ' ') : '';
+            }
             // #3183: canonical plan/summary counts (root+nested, superseded-excluded,
             // canonical pairing) from the single owner.
             const phaseScan = scanPhasePlans(node_path_1.default.join(phasesDir, dir));
@@ -3030,7 +3104,14 @@ function cmdProgressRender(cwd, format, raw) {
             totalPlans += plans;
             totalSummaries += summaries;
             const status = determinePhaseStatus(plans, summaries, node_path_1.default.join(phasesDir, dir), 'Pending');
-            phases.push({ number: phaseNum, name: phaseName, plans, summaries, status });
+            phases.push({
+                number: phaseNum,
+                ...(displayId ? { display_id: displayId } : {}),
+                name: phaseName,
+                plans,
+                summaries,
+                status,
+            });
         }
     }
     catch { /* intentionally empty */ }
@@ -3048,12 +3129,12 @@ function cmdProgressRender(cwd, format, raw) {
         // Render markdown table
         const bar = (0, phase_lifecycle_cjs_1.renderProgressBar)(percent, 10);
         const percentSuffix = percent === null ? '' : ` (${percent}%)`;
-        let out = `# ${milestone?.version ?? ''} ${milestone?.name ?? ''}\n\n`;
+        let out = `# ${milestoneVersion ?? ''} ${milestone?.name ?? ''}\n\n`;
         out += `**Progress:** [${bar}] ${totalSummaries}/${totalPlans} plans${percentSuffix}\n\n`;
         out += `| Phase | Name | Plans | Status |\n`;
         out += `|-------|------|-------|--------|\n`;
         for (const p of phases) {
-            out += `| ${p.number} | ${p.name} | ${p.summaries}/${p.plans} | ${p.status} |\n`;
+            out += `| ${p.display_id ?? p.number} | ${p.name} | ${p.summaries}/${p.plans} | ${p.status} |\n`;
         }
         output({ rendered: out }, raw, out);
     }
@@ -3066,7 +3147,7 @@ function cmdProgressRender(cwd, format, raw) {
     else {
         // JSON format
         output({
-            milestone_version: milestone?.version ?? null,
+            milestone_version: milestoneVersion,
             milestone_name: milestone?.name ?? null,
             phases,
             total_plans: totalPlans,
@@ -3361,6 +3442,11 @@ function cmdStats(cwd, format, raw) {
     const reqPath = planningPaths(cwd).requirements;
     const statePath = planningPaths(cwd).state;
     const milestone = getMilestoneInfo(cwd).value;
+    const phaseIdConvention = resolvePhaseIdConvention(cwd);
+    const milestoneDisplay = phaseIdConvention === 'bracket'
+        ? renderBracketMilestoneDisplay(milestone?.version, loadConfig(cwd).project_code)
+        : null;
+    const milestoneVersion = milestoneDisplay ?? milestone?.version ?? null;
     // Phase & plan stats (reuse progress pattern)
     const phasesByNumber = new Map();
     let totalPlans = 0;
@@ -3380,20 +3466,43 @@ function cmdStats(cwd, format, raw) {
         // prose mentioning `### Phase N:` inside an inline code span produced a phantom
         // Not-Started row and made phases_total disagree with roadmap analyze.
         // phase-id-owner: uses the [.-] (dot-or-dash) separator variant, not the canonical dot-only token; a swap to PHASE_NUMBER_TOKEN_SOURCE would drop hyphenated phase-id matches.
-        const headingPattern = /#{2,4}\s*(?:\[[^\]]{1,200}\]\s*)?Phase\s+([A-Za-z]?\d+[A-Z]?(?:[.-]\d+)*)(?:\s*\([^)\n]{0,200}\))?\s*:\s*([^\n]+)/gi;
+        const capturesBracketId = phaseIdConvention === 'bracket';
+        const headingPrefix = phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.ANY_BRACKET, phaseIdConvention, capturesBracketId);
+        // phase-id-owner: this preserves cmdStats's shipped dot-or-dash heading
+        // token variant; PHASE_NUMBER_TOKEN_SOURCE is dot-only and would drop M-NN.
+        const headingPattern = new RegExp(
+        // phase-id-owner: cmdStats's shipped [.-] token variant; the canonical token is dot-only.
+        `#{2,4}\\s*${headingPrefix}([A-Za-z]?\\d+[A-Z]?(?:[.-]\\d+)*)(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gi');
         let match;
         while ((match = headingPattern.exec(roadmapContent)) !== null) {
+            const bracketId = capturesBracketId ? match[1] : undefined;
+            const phaseToken = capturesBracketId ? match[2] : match[1];
+            const phaseName = capturesBracketId ? match[3] : match[2];
             // #3185: the heading seed carried no sentinel filter, so a
             // `### Phase 999.1:` backlog heading produced a stats row even with no
             // directory on disk. Uses the canonical predicate (phase-id.cts), not a
             // local literal — the rule had five copies and three regex variants
             // before this phase, disagreeing about Phase 0.
-            if (isSentinelPhaseId(match[1]))
+            const sentinelId = bracketId ? `${bracketId}-${phaseToken}` : phaseToken;
+            if (capturesBracketId
+                ? isSentinelPhaseId(sentinelId, phaseIdConvention)
+                : isSentinelPhaseId(sentinelId))
                 continue;
-            const key = normalizePhaseName(match[1]);
+            const key = normalizePhaseName(phaseToken);
+            let displayId;
+            if (bracketId) {
+                try {
+                    displayId = renderPhaseId(parsePhaseId(`${bracketId}-${phaseToken}`));
+                }
+                catch {
+                    // Read tolerance can admit a non-canonical heading spelling; keep
+                    // the stats row but do not invent a canonical identity for it.
+                }
+            }
             phasesByNumber.set(key, {
                 number: key,
-                name: match[2].replace(/\(INSERTED\)/i, '').trim(),
+                ...(displayId ? { display_id: displayId } : {}),
+                name: phaseName.replace(/\(INSERTED\)/i, '').trim(),
                 plans: 0,
                 summaries: 0,
                 status: 'Not Started',
@@ -3407,15 +3516,36 @@ function cmdStats(cwd, format, raw) {
         // sentinel filter — and getMilestonePhaseFilter degrades to a pass-all
         // predicate when its heading set is empty, at which point every directory
         // on disk passed, backlog included (#3167).
-        const { value: dirs, scope } = listMilestonePhaseDirs(phasesDir, { cwd });
+        const { value: dirs, scope } = listMilestonePhaseDirs(phasesDir, {
+            cwd,
+            phaseIdConvention,
+        });
         phaseScope = scope;
         for (const dir of dirs) {
-            // Use extractPhaseToken to correctly parse M-NN-style and code-prefixed dir names.
-            const phaseToken = extractPhaseToken(dir);
-            const phaseNum = phaseToken || dir;
-            // phaseName is everything after the token (strip leading '-')
-            const afterToken = dir.slice(phaseToken ? phaseToken.length : 0).replace(/^-/, '');
-            const phaseName = afterToken ? afterToken.replace(/-/g, ' ') : '';
+            let phaseNum;
+            let phaseName;
+            let displayId;
+            if (phaseIdConvention === 'bracket') {
+                try {
+                    const projection = bracketPhaseDirProjection(dir);
+                    phaseNum = projection.number;
+                    phaseName = projection.name;
+                    displayId = projection.display_id;
+                }
+                catch {
+                    const phaseToken = extractPhaseToken(dir, phaseIdConvention);
+                    phaseNum = phaseToken || dir;
+                    phaseName = recoverBracketPhaseName(dir, phaseToken);
+                }
+            }
+            else {
+                // Use extractPhaseToken to correctly parse M-NN-style and code-prefixed dir names.
+                const phaseToken = extractPhaseToken(dir);
+                phaseNum = phaseToken || dir;
+                // phaseName is everything after the token (strip leading '-')
+                const afterToken = dir.slice(phaseToken ? phaseToken.length : 0).replace(/^-/, '');
+                phaseName = afterToken ? afterToken.replace(/-/g, ' ') : '';
+            }
             // #3183: canonical plan/summary counts (root+nested, superseded-excluded,
             // canonical pairing) from the single owner.
             const phaseScan = scanPhasePlans(node_path_1.default.join(phasesDir, dir));
@@ -3428,6 +3558,9 @@ function cmdStats(cwd, format, raw) {
             const existing = phasesByNumber.get(normalizedNum);
             phasesByNumber.set(normalizedNum, {
                 number: normalizedNum,
+                ...(existing?.display_id || displayId
+                    ? { display_id: existing?.display_id || displayId }
+                    : {}),
                 name: existing?.name || phaseName,
                 plans: (existing?.plans || 0) + plans,
                 summaries: (existing?.summaries || 0) + summaries,
@@ -3486,7 +3619,7 @@ function cmdStats(cwd, format, raw) {
         }
     }
     const result = {
-        milestone_version: milestone?.version ?? null,
+        milestone_version: milestoneVersion,
         milestone_name: milestone?.name ?? null,
         phases,
         phases_completed: completedPhases,
@@ -3506,7 +3639,7 @@ function cmdStats(cwd, format, raw) {
     };
     if (format === 'table') {
         const bar = (0, phase_lifecycle_cjs_1.renderProgressBar)(percent, 10);
-        let out = `# ${milestone?.version ?? ''} ${milestone?.name ?? ''} — Statistics\n\n`;
+        let out = `# ${milestoneVersion ?? ''} ${milestone?.name ?? ''} — Statistics\n\n`;
         const percentSuffix = percent === null ? '' : ` (${percent}%)`;
         out += `**Progress:** [${bar}] ${completedPhases}/${phases.length} phases${percentSuffix}\n`;
         if (totalPlans > 0 && planPercent !== null) {
@@ -3520,7 +3653,7 @@ function cmdStats(cwd, format, raw) {
         out += `| Phase | Name | Plans | Completed | Status |\n`;
         out += `|-------|------|-------|-----------|--------|\n`;
         for (const p of phases) {
-            out += `| ${p.number} | ${p.name} | ${p.plans} | ${p.summaries} | ${p.status} |\n`;
+            out += `| ${p.display_id ?? p.number} | ${p.name} | ${p.plans} | ${p.summaries} | ${p.status} |\n`;
         }
         if (gitCommits > 0) {
             out += `\n**Git:** ${gitCommits} commits`;