@opengsd/gsd-core 1.14.0 → 1.16.0

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

@@ -14,6 +14,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const text_lines_cjs_1 = require("./text-lines.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const pattern_cjs_1 = require("./pattern.cjs");
+const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
 const security_cjs_1 = require("./security.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
@@ -30,7 +31,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,10 +60,10 @@ 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;
+const { extractFrontmatter, agentScalarNeedsDoubleQuoting, escapeDoubleQuotedScalar, FRONTMATTER_UNPARSEABLE } = frontmatter;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const modelProfiles = require("./model-profiles.cjs");
 const { MODEL_PROFILES, VALID_PHASE_TYPES } = modelProfiles;
@@ -69,96 +73,65 @@ const phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planScanMod = require("./plan-scan.cjs");
 const { scanPhasePlans } = planScanMod;
-// eslint-disable-next-line @typescript-eslint/no-require-imports -- verification.cjs is an export= CommonJS module
+// #5060: Phase Status Module — the single owner of "what state is phase P
+// in?" (ADR-5057 §1/§2). Replaces this file's own precedence ladder and
+// determinePhaseStatus derivation.
+const phase_status_cjs_1 = require("./phase-status.cjs");
+// #5118: an aggregate over a refused verification report fails through the owner.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const verificationMod = require("./verification.cjs");
-const { resolveVerificationFile } = verificationMod;
-// ─── Phase Status ─────────────────────────────────────────────────────────────
+const { failOnVerificationStatusError, firstStatusError } = verificationMod;
+/** The effort-sync line editors' fence reading: a block behind a preamble is still edited (#3706). */
+const EFFORT_SYNC_FENCE = Object.freeze({ allowPreamble: true });
+/** Prefer the Claude agents beside the running local install over the global home. */
+function claudeEffortAgentsDir(explicitDir) {
+    if (explicitDir)
+        return node_path_1.default.join(explicitDir, 'agents');
+    // Compiled commands.cjs lives at <configDir>/gsd-core/bin/lib. In a source
+    // checkout the same path leads to the repository root, where no install
+    // manifest exists; keep the existing global fallback in that case.
+    const configDir = node_path_1.default.resolve(__dirname, '..', '..', '..');
+    try {
+        const manifestPath = node_path_1.default.join(configDir, 'gsd-file-manifest.json');
+        if (node_fs_1.default.lstatSync(manifestPath).isFile()) {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const migrations = require('./installer-migrations.cjs');
+            const manifest = migrations.readInstallManifest(configDir);
+            if (manifest.runtime === 'claude' && manifest.scope === 'local') {
+                return node_path_1.default.join(configDir, 'agents');
+            }
+        }
+    }
+    catch { /* an absent or unreadable manifest retains the global fallback */ }
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/unbound-method
+    const { getGlobalConfigDir } = require('./runtime-homes.cjs');
+    return node_path_1.default.join(getGlobalConfigDir('claude'), 'agents');
+}
 /**
- * Phase-status precedence ladder — furthest-along wins (#2408).
+ * Project one canonical bracket directory onto its display identity and slug.
  *
- * `cmdStats` builds `phasesByNumber` by scanning on-disk phase directories.
- * When two directories normalize to the same phase key (e.g. `05-real/` and
- * `05-real-stray/`), the status field must be folded by precedence rather
- * than overwritten last-write-wins — otherwise `/gsd-stats` reports whatever
- * directory `fs.readdirSync` happened to yield last, which is non-deterministic
- * across platforms and can silently call a `Complete` phase `Not Started`.
- */
-const PHASE_STATUS_PRECEDENCE = [
-    'Complete',
-    'Needs Review',
-    'Executed',
-    'In Progress',
-    'Planned',
-    'Not Started',
-    'Pending',
-];
-const PHASE_STATUS_RANK = new Map(PHASE_STATUS_PRECEDENCE.map((s, i) => [s, i]));
-/**
- * Fold two phase statuses by precedence — returns whichever is further along
- * the {@link PHASE_STATUS_PRECEDENCE} ladder. Unrecognized statuses fall behind
- * every recognized one (so a recognized status always wins over an unknown one;
- * two unrecognized statuses favor `a` for determinism).
+ * 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 foldPhaseStatus(a, b) {
-    const ra = PHASE_STATUS_RANK.get(a);
-    const rb = PHASE_STATUS_RANK.get(b);
-    if (ra === undefined && rb === undefined)
-        return a;
-    if (ra === undefined)
-        return b;
-    if (rb === undefined)
-        return a;
-    // Lower rank = higher precedence (Complete=0 wins over Not Started=5).
-    return ra <= rb ? a : b;
+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, ' ') : '',
+    };
 }
-/**
- * Determine phase status by checking plan/summary counts AND verification state.
- * Introduces "Executed" for phases with all summaries but no passing verification.
- */
-function determinePhaseStatus(plans, summaries, phaseDir, defaultPending) {
-    if (plans === 0)
-        return defaultPending;
-    if (summaries < plans && summaries > 0)
-        return 'In Progress';
-    if (summaries < plans)
-        return 'Planned';
-    // summaries >= plans — check verification
-    try {
-        const files = node_fs_1.default.readdirSync(phaseDir);
-        // #3473 F2: routed through the shared resolver (readdir order is
-        // filesystem-dependent, so the prior hand-rolled `.find()` could pick
-        // either file when a phase held both a canonical report and an ad-hoc
-        // `-CORRECTION-VERIFICATION.md` worksheet — see #3357).
-        // #3492: pin selection to THIS phase's own token so a stray cross-phase
-        // or sentinel-numbered canonically-shaped file cannot outrank this
-        // phase's own (possibly non-canonical) report.
-        const phaseDirName = node_path_1.default.basename(phaseDir);
-        const phaseToken = extractPhaseToken(phaseDirName);
-        const verificationFile = resolveVerificationFile(files, { allowBare: true, phaseToken, phaseDirName });
-        if (verificationFile) {
-            const verificationFilePath = node_path_1.default.join(phaseDir, verificationFile);
-            const content = (0, shell_command_projection_cjs_1.platformReadSync)(verificationFilePath) || '';
-            // #1159 (Defect A): read ONLY the frontmatter `status` key to avoid false
-            // matches from historical body metadata such as `previous_status: gaps_found`.
-            // Full-text regexes like /status:\s*gaps_found/ match the substring inside
-            // `previous_status: gaps_found`, producing incorrect phase status labels.
-            const fm = extractFrontmatter(content, verificationFilePath);
-            // Normalise to lower-case to preserve the prior case-insensitive behaviour
-            // while reading only the frontmatter `status` key (not the full body text).
-            const fmStatus = typeof fm['status'] === 'string' ? fm['status'].trim().toLowerCase() : '';
-            if (fmStatus === 'passed')
-                return 'Complete';
-            if (fmStatus === 'human_needed')
-                return 'Needs Review';
-            if (fmStatus === 'gaps_found')
-                return 'Executed';
-            // Verification exists but unrecognized status — treat as executed
-            return 'Executed';
-        }
-    }
-    catch { /* directory read failed — fall through */ }
-    // No verification file — executed but not verified
-    return 'Executed';
+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, ' ') : '';
 }
 function cmdGenerateSlug(text, raw) {
     if (!text) {
@@ -237,26 +210,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 +293,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 +495,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);
@@ -557,19 +546,19 @@ function cmdResolveExecution(cwd, agentType, raw, opts) {
     let effortEffective = effort;
     if (runtime === 'claude') {
         try {
-            // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/unbound-method
-            const { getGlobalConfigDir } = require('./runtime-homes.cjs');
-            const agentsDirEff = node_path_1.default.join(getGlobalConfigDir(runtime), 'agents');
+            const agentsDirEff = claudeEffortAgentsDir();
             // agentType is an unvalidated CLI positional: keep the read inside the
             // agents dir so `../../x` cannot point it elsewhere (defense in depth —
             // the reflected surface is only a frontmatter effort line). Untrusted
             // input feeding a real read → realpath family (ADR-4650 decision 6).
             const agentPath = (0, security_cjs_1.assertWithinRoot)(`${agentType}.md`, agentsDirEff, 'agent file');
             const agentContent = node_fs_1.default.readFileSync(agentPath, 'utf8');
-            // eslint-disable-next-line local/no-unbounded-quantifier -- same lazy `*?` bounded by the `^---$/m` closing anchor as the sibling frontmatter regexes in this file
-            const fmMatchEff = /^---\r?\n([\s\S]*?)^---\r?$/m.exec(agentContent);
-            if (fmMatchEff) {
-                const effortLine = /^effort:[ \t]*(.+?)[ \t]*$/m.exec(fmMatchEff[1]);
+            // Byte-0 read: the runtime only honors a frontmatter block that opens at
+            // byte 0, so a block behind a preamble is not frontmatter to the loader
+            // and this reports what the installed agent will actually run at (#5105).
+            const fmSpanEff = agentFrontmatterSpan(agentContent);
+            if (fmSpanEff) {
+                const effortLine = /^effort:[ \t]*(.+?)[ \t]*$/m.exec(fmSpanEff.body);
                 if (effortLine) {
                     effortEffective = effortLine[1];
                     effortEffectiveSource = 'frontmatter';
@@ -656,33 +645,42 @@ function effortSurfaceForHost(cwd, host) {
         return 'none';
     }
 }
+/**
+ * The leading frontmatter block of an installed agent file, as the one fence owner
+ * (`locateFrontmatterFence`) finds it: `body` is the text between the two fences (the last
+ * content line's line ending included), `bodyStart`/`closingStart` bound it, and `eol` is the
+ * opening fence's line ending. Null when the file has no closed block. By default a block that
+ * does not open at byte 0 is not one, exactly as the runtime that loads the agent reads it;
+ * the effort-sync line editors pass `EFFORT_SYNC_FENCE` to edit a block behind a preamble too
+ * (#3706 pinned that).
+ */
+function agentFrontmatterSpan(content, options) {
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(content, options);
+    if (!fence?.closed)
+        return null;
+    return { body: content.slice(fence.openEnd, fence.closingStart), bodyStart: fence.openEnd, closingStart: fence.closingStart, eol: fence.eol };
+}
 /**
  * #488 — Replace or inject the `<key>:` value in YAML frontmatter.
  * Unlike injectEffortFrontmatter (install.js), this overwrites an existing value.
  * #3706: key-parameterised so the same line-editor serves both claude's
- * `effort:` and OpenCode's `variant:`. #3706: all offsets (eol, openLen,
- * closingStart) are derived from the MATCHED BLOCK, not the start of the
- * file, and the existing-key replace is scoped to the frontmatter span only.
+ * `effort:` and OpenCode's `variant:`. #3706: all offsets (eol, bodyStart,
+ * closingStart) come from the block `agentFrontmatterSpan` found, and the
+ * existing-key replace is scoped to the frontmatter span only.
  */
 function setFrontmatterKeyLine(content, key, value) {
-    const fmRe = /^---\r?\n([\s\S]*?)^---\r?$/m;
-    const match = fmRe.exec(content);
-    if (!match)
+    const span = agentFrontmatterSpan(content, EFFORT_SYNC_FENCE);
+    if (!span)
         return content;
-    const fmBody = match[1];
+    const fmBody = span.body;
     // Both writers of these frontmatter keys — this sync path and the
     // install-side `frontmatterScalar` in runtime-artifact-conversion.cts —
     // now share one escaping rule: quote via `agentScalarNeedsDoubleQuoting` +
     // `escapeDoubleQuotedScalar` (both from frontmatter.cts) rather than each
     // interpolating `value` raw/differently.
     const renderedValue = agentScalarNeedsDoubleQuoting(value) ? `"${escapeDoubleQuotedScalar(value)}"` : value;
-    // EOL comes from the MATCHED BLOCK, not the start of the file. With a
-    // preamble the two can disagree, and on a CRLF document that misaligns every
-    // offset below by one byte and mangles the opening fence.
-    const eol = /^---\r\n/.test(match[0]) ? '\r\n' : '\n';
-    const openLen = 3 + eol.length;
-    const bodyStart = match.index + openLen;
-    const closingStart = bodyStart + fmBody.length;
+    // Every offset and the EOL come from the block the fence owner found (#3706).
+    const { eol, bodyStart, closingStart } = span;
     // #3706: key is now generic (not just the literal 'effort'/'variant'
     // callers happen to pass today) — escape it before interpolating into the
     // RegExp so a future caller can't have its key metacharacters reinterpreted.
@@ -718,19 +716,17 @@ function setFrontmatterKeyLine(content, key, value) {
  * codex-agent-toml strip discipline: targeted line removal, EOL-aware, every
  * other byte (comments, sibling keys, the body) untouched.
  * #3706: key-parameterised so the same line-editor serves both claude's
- * `effort:` and OpenCode's `variant:`. #3706: openLen is derived from the
- * MATCHED BLOCK, not the start of the file — a preamble on a CRLF document
- * would otherwise misalign every offset below.
+ * `effort:` and OpenCode's `variant:`. #3706: every offset comes from the
+ * block `agentFrontmatterSpan` found.
  */
 function removeFrontmatterKeyLine(content, key) {
     // Scoped to the FIRST frontmatter block (not a whole-file /m match): a
     // preamble or body line starting with `<key>:` (a fenced config example,
     // a thematic-break flanked fragment) must never be the line removed.
-    const fmRe = /^---\r?\n([\s\S]*?)^---\r?$/m;
-    const match = fmRe.exec(content);
-    if (!match)
+    const span = agentFrontmatterSpan(content, EFFORT_SYNC_FENCE);
+    if (!span)
         return content;
-    const fmBody = match[1];
+    const fmBody = span.body;
     // #3706: same generic-key escape as setFrontmatterKeyLine above.
     const lineRe = new RegExp(`^${(0, pattern_cjs_1.escapeRegex)(key)}:[ \\t]*.*\\r?\\n?`, 'm');
     if (!lineRe.test(fmBody))
@@ -745,12 +741,7 @@ function removeFrontmatterKeyLine(content, key) {
     // is removed in one pass.
     const stripAllRe = new RegExp(`^${(0, pattern_cjs_1.escapeRegex)(key)}:[ \\t]*.*\\r?\\n?`, 'gm');
     const strippedFm = fmBody.replace(stripAllRe, '');
-    // Same rule as setFrontmatterKeyLine: the EOL must come from the matched
-    // block, not the start of the file, or a preambled CRLF document misaligns.
-    const eol = /^---\r\n/.test(match[0]) ? '\r\n' : '\n';
-    const openLen = 3 + eol.length;
-    const closingStart = match.index + openLen + fmBody.length;
-    return content.slice(0, match.index + openLen) + strippedFm + content.slice(closingStart);
+    return content.slice(0, span.bodyStart) + strippedFm + content.slice(span.closingStart);
 }
 /** #488 — Replace or inject the `effort:` value in YAML frontmatter. */
 function setEffortFrontmatter(content, effortValue) {
@@ -795,8 +786,6 @@ function cmdEffortSync(cwd, raw, opts) {
         output({ synced: 0, skipped: 0, changes: [], dry_run: dryRun, reason: `runtime '${runtime}' does not use effort: frontmatter` }, raw, '');
         return;
     }
-    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/unbound-method
-    const { getGlobalConfigDir } = require('./runtime-homes.cjs');
     // Use install-time resolvers: they merge ~/.gsd/defaults.json with project config,
     // matching the exact logic used when agents were originally installed. #2071: these
     // live in the shipped sibling install-effort-resolver.cjs (extracted from the
@@ -804,7 +793,7 @@ function cmdEffortSync(cwd, raw, opts) {
     // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/unbound-method
     const { readGsdEffectiveEffortConfig, resolveInstallTimeEffort } = require('./install-effort-resolver.cjs');
     const effortCfg = readGsdEffectiveEffortConfig(cwd);
-    const agentsDir = node_path_1.default.join(opts.configDir || getGlobalConfigDir(runtime), 'agents');
+    const agentsDir = claudeEffortAgentsDir(opts.configDir);
     if (!node_fs_1.default.existsSync(agentsDir)) {
         output({ synced: 0, skipped: 0, changes: [], dry_run: dryRun, agents_dir: agentsDir, reason: 'agents directory not found' }, raw, '');
         return;
@@ -822,6 +811,10 @@ function cmdEffortSync(cwd, raw, opts) {
     }).sort(); // #3706: sorted like the codex and
     // opencode branches — readdir order is platform-dependent, so leaving it unsorted makes the
     // reported `changes` ordering differ across machines for identical inputs.
+    if (files.length === 0) {
+        output({ synced: 0, skipped: 0, changes: [], dry_run: dryRun, agents_dir: agentsDir, reason: 'no GSD agent files found' }, raw, '');
+        return;
+    }
     const changes = [];
     let synced = 0;
     let skipped = 0;
@@ -866,7 +859,7 @@ function cmdEffortSync(cwd, raw, opts) {
         // drift and the sync re-added a hand-stripped key on every apply. A
         // present key under inherit is stripped, reported as {from, to: null}.
         if (universalEffort === 'inherit') {
-            const fmMatchInherit = /^---\r?\n([\s\S]*?)^---\r?$/m.exec(content);
+            const fmMatchInherit = agentFrontmatterSpan(content, EFFORT_SYNC_FENCE);
             if (!fmMatchInherit) {
                 skipped++;
                 continue;
@@ -877,12 +870,12 @@ function cmdEffortSync(cwd, raw, opts) {
             // from a null value alone is wrong here — it would leave an
             // unresolvable `effort: null` key on disk forever. Test presence with
             // its own regex, and only compare values once presence is known.
-            const effortPresentInherit = /^effort:/m.test(fmMatchInherit[1]);
+            const effortPresentInherit = /^effort:/m.test(fmMatchInherit.body);
             if (!effortPresentInherit) {
                 skipped++;
                 continue;
             }
-            const effortMatchInherit = /^effort:[ \t]*(.+?)[ \t]*$/m.exec(fmMatchInherit[1]);
+            const effortMatchInherit = /^effort:[ \t]*(.+?)[ \t]*$/m.exec(fmMatchInherit.body);
             // `effortPresentInherit` is guaranteed true here (checked above), so a
             // failed value match means the key is present with an EMPTY value —
             // report `''`, not `null`, so "present-but-empty" is never conflated
@@ -941,7 +934,7 @@ function cmdEffortSync(cwd, raw, opts) {
         // codex's 'ultra' rejection can produce a null value).
         const rendered = (0, model_catalog_cjs_1.renderEffortForRuntime)(runtime, universalEffort);
         const newEffortValue = rendered.value;
-        const fmMatch = /^---\r?\n([\s\S]*?)^---\r?$/m.exec(content);
+        const fmMatch = agentFrontmatterSpan(content, EFFORT_SYNC_FENCE);
         if (!fmMatch) {
             skipped++;
             continue;
@@ -954,8 +947,8 @@ function cmdEffortSync(cwd, raw, opts) {
         // never null on this path (guarded above), so an absent key already
         // yields `currentEffort === null !== newEffortValue` without consulting
         // presence separately.
-        const effortPresent = /^effort:/m.test(fmMatch[1]);
-        const effortMatch = /^effort:[ \t]*(.+?)[ \t]*$/m.exec(fmMatch[1]);
+        const effortPresent = /^effort:/m.test(fmMatch.body);
+        const effortMatch = /^effort:[ \t]*(.+?)[ \t]*$/m.exec(fmMatch.body);
         // `null` (key absent) and `''` (key present, value empty) are distinct
         // states `effortPresent` deliberately disambiguates — collapsing both to
         // `null` here would make the reported `from` lie about which case fired.
@@ -1228,7 +1221,7 @@ function cmdEffortSyncOpencode(cwd, raw, dryRun, configDir) {
         // exactly what install writes.
         const universal = effortCfg ? resolveInstallTimeEffort(effortCfg, agentName) : null;
         const target = universal ? clampEffortForHost('opencode', universal) : null;
-        const fmMatch = /^---\r?\n([\s\S]*?)^---\r?$/m.exec(content);
+        const fmMatch = agentFrontmatterSpan(content, EFFORT_SYNC_FENCE);
         if (!fmMatch) {
             skipped++;
             continue;
@@ -1240,8 +1233,8 @@ function cmdEffortSyncOpencode(cwd, raw, dryRun, configDir) {
         // null — it would leave an unresolvable `variant: null` key on disk
         // forever. Test presence with its own regex, and only compare values
         // once presence is known.
-        const variantPresent = /^variant:/m.test(fmMatch[1]);
-        const variantMatch = /^variant:[ \t]*(.+?)[ \t]*$/m.exec(fmMatch[1]);
+        const variantPresent = /^variant:/m.test(fmMatch.body);
+        const variantMatch = /^variant:[ \t]*(.+?)[ \t]*$/m.exec(fmMatch.body);
         // `null` (key absent) and `''` (key present, value empty) are distinct
         // states this code deliberately tracks via `variantPresent` above — a
         // reported `from` that collapses both to `null` would make "no key" and
@@ -2838,13 +2831,38 @@ function cmdSummaryExtract(cwd, summaryPath, fields, raw) {
     if (!summaryPath) {
         error('summary-path required for summary-extract');
     }
-    const fullPath = node_path_1.default.join(cwd, summaryPath);
+    // #5013: requireSafePath (not path.join) so an absolute summaryPath resolves to
+    // that literal path instead of being concatenated onto cwd — path.join has no
+    // special case for an absolute second argument the way path.resolve does. Uses
+    // requireSafePath (the same PathAcceptance.AbsoluteInsideRoot pattern
+    // cmdAuditAcknowledge's write-side counterpart already uses in audit.cts)
+    // rather than a bare path.resolve: a plain path.resolve would also have made
+    // an absolute summaryPath anywhere on the filesystem resolve and have its
+    // content echoed back (this command reads and returns file content, unlike
+    // cmdVerifyPathExists's exists-only check) — an orthogonal-review finding on
+    // this same fix. requireSafePath keeps the acceptance criterion (an absolute
+    // path within the project resolves correctly) while refusing one that
+    // escapes cwd, and rejects relative `../` escapes the same way (pre-existing
+    // in this function, closed as a direct consequence, not separately in scope).
+    const fullPath = (0, security_cjs_1.requireSafePath)(summaryPath, cwd, 'summary-extract target', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
     if (!node_fs_1.default.existsSync(fullPath)) {
         output({ error: 'File not found', path: summaryPath }, raw, undefined);
         return;
     }
     const content = node_fs_1.default.readFileSync(fullPath, 'utf-8');
     const fm = extractFrontmatter(content, fullPath);
+    // #5013: an unparseable frontmatter block (malformed YAML in the fence) is
+    // NOT the same as an absent/empty one — extractFrontmatter marks it with
+    // FRONTMATTER_UNPARSEABLE (mirrors state.cts's isUnparseableFrontmatter /
+    // state-transition.cts's identical helper). Left unchecked, every field
+    // below silently falls back to its empty default and this command exits 0,
+    // so a milestone audit reading requirements_completed through it would
+    // report "zero requirements completed" for a plan that completed several,
+    // with nothing on stderr. Refuse instead, naming the file, the same way
+    // cmdAuditAcknowledge (audit.cts) refuses on the write-side counterpart.
+    if (fm[FRONTMATTER_UNPARSEABLE] === true) {
+        error(`summary-extract: the frontmatter of "${summaryPath}" is not parseable YAML — fix the syntax error in the file (e.g. an unquoted ": " inside a block-sequence item) before re-running; every field would otherwise silently read as empty`, ERROR_REASON.SUMMARY_EXTRACT_UNPARSEABLE, { path: summaryPath });
+    }
     // Parse key-decisions into structured format
     const parseDecisions = (decisionsList) => {
         if (!decisionsList || !Array.isArray(decisionsList))
@@ -3006,34 +3024,77 @@ 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;
     let phaseScope = null;
+    // #5118: carried out of the scan below and failed on after it.
+    let statusError;
     try {
         // #3185 (ADR-3180 Decision 1): the single owner applies the milestone
         // window AND the sentinel filter and returns dirs already sorted by
         // 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, ' ') : '';
-            // #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));
-            const plans = phaseScan.planCount;
-            const summaries = phaseScan.summaryCount;
+            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/#5060: canonical plan/summary counts and lifecycle status
+            // (root+nested, superseded-excluded, canonical pairing) from the
+            // single owner (Phase Status Module, ADR-5057).
+            const ps = (0, phase_status_cjs_1.phaseStatus)(node_path_1.default.join(phasesDir, dir), { convention: phaseIdConvention });
+            statusError = firstStatusError(statusError, ps.value.statusError);
+            const plans = ps.value.planCount;
+            const summaries = ps.value.summaryCount;
             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 });
+            const status = (0, phase_status_cjs_1.toDisplayLabel)(ps.value.status, { pendingWord: 'Pending' });
+            phases.push({
+                number: phaseNum,
+                ...(displayId ? { display_id: displayId } : {}),
+                name: phaseName,
+                plans,
+                summaries,
+                status,
+            });
         }
     }
     catch { /* intentionally empty */ }
+    // #5118: a read-only aggregate over a refused report prints nothing.
+    if (statusError)
+        failOnVerificationStatusError(statusError);
     // #3217 (ADR-3180 §7.6 rule 4): `phaseScope` was already computed above
     // (Phase 3, #3222) but never consulted before rendering — a percentage was
     // rendered from counts the scope said were not answers (TRUNCATED /
@@ -3048,12 +3109,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 +3127,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,
@@ -3192,29 +3253,35 @@ function cmdTodoMatchPhase(cwd, phase, raw) {
 // #4096: upsert completion keys INSIDE the leading frontmatter block. Never a
 // bare prefix line above the opening `---` (that displaces the fence to line 2
 // and breaks every fence-locating reader). A file with no well-formed block
-// (absent, or an unterminated opening fence) gains a complete block.
+// (absent, or an unterminated opening fence) gains a complete block. The block is
+// the one the one fence owner (`locateFrontmatterFence`) finds, so this writer and
+// every todo reader agree on where it is.
 function upsertTodoCompletionFields(content, today) {
-    const lines = content.split('\n');
     const fields = [`completed: ${today}`, 'status: completed'];
-    const hasOpeningFence = lines[0] !== undefined && lines[0].trim() === '---';
-    const closeIdx = hasOpeningFence ? lines.findIndex((l, i) => i > 0 && l.trim() === '---') : -1;
-    if (!hasOpeningFence || closeIdx === -1) {
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(content);
+    if (!fence?.closed) {
         // No parseable frontmatter: wrap the whole content in a complete block
-        // rather than prefixing bare keys (#4096 fix 2).
-        return `---\n${fields.join('\n')}\n---\n\n${content}`;
-    }
-    const block = lines.slice(1, closeIdx);
+        // rather than prefixing bare keys (#4096 fix 2). A leading BOM (#2977) stays
+        // the document's first character, ahead of the new fence.
+        const bom = content.charCodeAt(0) === 0xFEFF ? content.slice(0, 1) : '';
+        return `${bom}---\n${fields.join('\n')}\n---\n\n${content.slice(bom.length)}`;
+    }
+    // The block's lines, split on a bare '\n' so a CRLF line keeps its '\r' — and a
+    // written field line carries one too, so a CRLF block never gains LF-only lines.
+    const inner = content.slice(fence.openEnd, fence.closingStart);
+    const block = inner === '' ? [] : inner.slice(0, -1).split('\n');
+    const cr = fence.eol === '\r\n' ? '\r' : '';
     for (const field of fields) {
         const key = `${field.slice(0, field.indexOf(':'))}:`;
         const idx = block.findIndex(l => l.startsWith(key));
         if (idx === -1) {
-            block.push(field);
+            block.push(field + cr);
         }
         else {
-            block[idx] = field;
+            block[idx] = field + cr;
         }
     }
-    return [...lines.slice(0, 1), ...block, ...lines.slice(closeIdx)].join('\n');
+    return `${content.slice(0, fence.openEnd)}${block.join('\n')}\n${content.slice(fence.closingStart)}`;
 }
 function cmdTodoComplete(cwd, filename, options, raw) {
     if (!filename) {
@@ -3232,7 +3299,7 @@ function cmdTodoComplete(cwd, filename, options, raw) {
     // to a location inside todosRoot (or inside pending/) and would pass
     // containment, yet none of them is a bare filename. Reject on basename
     // shape FIRST, before any path is even joined — same predicate shape as
-    // findPhaseArtifact in check-command-router.cts. Checking both `/` and
+    // findPhaseArtifact in gate-predicate.cts. Checking both `/` and
     // `\` explicitly (not just path.basename) matters on POSIX, where a
     // literal backslash is just an ordinary filename character to
     // path.basename but not to path.win32.basename or to the user's intent.
@@ -3361,7 +3428,15 @@ 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)
+    // #5060: `phaseStatus` here is the internal PHASE_STATUS ladder value, never
+    // a display label — the output projection below is the only place a label
+    // is produced (toDisplayLabel).
     const phasesByNumber = new Map();
     let totalPlans = 0;
     let totalSummaries = 0;
@@ -3380,54 +3455,105 @@ 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',
+                phaseStatus: phase_status_cjs_1.PHASE_STATUS.NOT_STARTED,
             });
         }
     }
     catch { /* intentionally empty */ }
+    // #5118: the first phase whose verification report `status` is outside the
+    // closed set — carried out of the scan below and failed on after it.
+    let statusError;
     try {
         // #3185 (ADR-3180 Decision 1): route through the single owner. This
         // previously applied the milestone window but NOT a directory-level
         // 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, ' ') : '';
-            // #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));
-            const plans = phaseScan.planCount;
-            const summaries = phaseScan.summaryCount;
+            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/#5060: canonical plan/summary counts and lifecycle status
+            // (root+nested, superseded-excluded, canonical pairing) from the
+            // single owner (Phase Status Module, ADR-5057).
+            const ps = (0, phase_status_cjs_1.phaseStatus)(node_path_1.default.join(phasesDir, dir), { convention: phaseIdConvention });
+            statusError = firstStatusError(statusError, ps.value.statusError);
+            const plans = ps.value.planCount;
+            const summaries = ps.value.summaryCount;
             totalPlans += plans;
             totalSummaries += summaries;
-            const status = determinePhaseStatus(plans, summaries, node_path_1.default.join(phasesDir, dir), 'Not Started');
             const normalizedNum = normalizePhaseName(phaseNum);
             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,
@@ -3436,13 +3562,26 @@ function cmdStats(cwd, format, raw) {
                 // platforms, so a naive overwrite can report a Complete phase as Not
                 // Started (or vice versa) depending on read order. The fold picks the
                 // furthest-along status, matching what an operator expects.
-                status: existing ? foldPhaseStatus(existing.status, status) : status,
+                phaseStatus: existing ? (0, phase_status_cjs_1.foldPhaseStatuses)(existing.phaseStatus, ps.value.status) : ps.value.status,
             });
         }
     }
     catch { /* intentionally empty */ }
-    const phases = [...phasesByNumber.values()].sort((a, b) => comparePhaseNum(a.number, b.number));
-    const completedPhases = phases.filter(p => p.status === 'Complete').length;
+    // #5118: a read-only aggregate over a refused report prints nothing.
+    if (statusError)
+        failOnVerificationStatusError(statusError);
+    const internalPhases = [...phasesByNumber.values()].sort((a, b) => comparePhaseNum(a.number, b.number));
+    const completedPhases = internalPhases.filter(p => p.phaseStatus === phase_status_cjs_1.PHASE_STATUS.COMPLETE).length;
+    // #5060: project the internal PHASE_STATUS ladder to the display label at
+    // the output boundary only — the internal `phaseStatus` field is never emitted.
+    const phases = internalPhases.map(p => ({
+        number: p.number,
+        ...(p.display_id ? { display_id: p.display_id } : {}),
+        name: p.name,
+        plans: p.plans,
+        summaries: p.summaries,
+        status: (0, phase_status_cjs_1.toDisplayLabel)(p.phaseStatus, { pendingWord: 'Not Started' }),
+    }));
     // #3217 (ADR-3180 §7.6 rule 4): both percentages here are derived from the
     // same `phaseScope`-carrying directory enumeration above (Phase 3, #3222) —
     // withhold both when that scope is not COMPLETE, same rationale as
@@ -3486,7 +3625,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 +3645,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 +3659,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`;
@@ -3768,9 +3907,6 @@ function cmdCommitDocsGuardDisable(cwd, raw) {
 module.exports = {
     effortSurfaceForHost,
     groupFilesBySubrepo,
-    determinePhaseStatus,
-    foldPhaseStatus,
-    PHASE_STATUS_PRECEDENCE,
     cmdGenerateSlug,
     cmdCurrentTimestamp,
     cmdListTodos,