@opengsd/gsd-core 1.15.0 → 1.17.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");
@@ -62,7 +63,7 @@ const planningWorkspace = require("./planning-workspace.cjs");
 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;
@@ -72,9 +73,40 @@ 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;
+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');
+}
 /**
  * Project one canonical bracket directory onto its display identity and slug.
  *
@@ -101,94 +133,6 @@ function recoverBracketPhaseName(dir, phaseToken) {
     const afterToken = dir.slice(tokenOffset + tokenBoundary.length).replace(/^-/, '');
     return afterToken ? afterToken.replace(/-/g, ' ') : '';
 }
-// ─── Phase Status ─────────────────────────────────────────────────────────────
-/**
- * Phase-status precedence ladder — furthest-along wins (#2408).
- *
- * `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).
- */
-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;
-}
-/**
- * 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 cmdGenerateSlug(text, raw) {
     if (!text) {
         error('text required for slug generation');
@@ -602,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';
@@ -701,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.
@@ -763,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))
@@ -790,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) {
@@ -840,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
@@ -849,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;
@@ -867,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;
@@ -911,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;
@@ -922,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
@@ -986,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;
@@ -999,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.
@@ -1273,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;
@@ -1285,25 +1233,45 @@ 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]);
+        // Native OpenCode 2.x form (ADR-5331 D5): the effort rides on the model reference as
+        // `provider/model#variant`, with no separate `variant:` key. When the agent's `model:` carries a
+        // `#` suffix that suffix IS the effort, so the sync edits the model instead of adding a second,
+        // conflicting `variant:` line.
+        const modelLineMatch = /^model:[ \t]*(.+?)[ \t]*$/m.exec(fmMatch.body);
+        const modelValue = modelLineMatch ? modelLineMatch[1].replace(/\r$/, '').replace(/^(["'])(.*)\1$/, '$2') : null;
+        const hashAt = modelValue === null ? -1 : modelValue.lastIndexOf('#');
+        let modelFormContent = null;
+        let modelFormFrom = null;
+        if (modelValue !== null && hashAt > 0) {
+            const base = modelValue.slice(0, hashAt);
+            modelFormFrom = modelValue.slice(hashAt + 1);
+            if (target !== null && modelFormFrom === target) {
+                skipped++;
+                continue;
+            }
+            modelFormContent = setFrontmatterKeyLine(content, 'model', target === null ? base : `${base}#${target}`);
+        }
+        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
         // "empty key" indistinguishable in the sync output, even though only one
         // of them actually has a `variant:` line to remove.
         const currentVariant = variantPresent ? (variantMatch ? variantMatch[1] : '') : null;
-        if (target === null) {
-            if (!variantPresent) {
+        if (modelFormContent === null) {
+            if (target === null) {
+                if (!variantPresent) {
+                    skipped++;
+                    continue;
+                }
+            }
+            else if (variantPresent && currentVariant === target) {
                 skipped++;
                 continue;
             }
         }
-        else if (variantPresent && currentVariant === target) {
-            skipped++;
-            continue;
-        }
-        changes.push({ agent: agentName, from: currentVariant, to: target });
+        changes.push({ agent: agentName, from: modelFormContent === null ? currentVariant : modelFormFrom, to: target });
         synced++;
         if (!dryRun) {
             // Atomic publish AND mode preservation, same discipline as
@@ -1331,7 +1299,7 @@ function cmdEffortSyncOpencode(cwd, raw, dryRun, configDir) {
             }
             catch { /* non-fatal: fall back to writing without an explicit mode */ }
             try {
-                node_fs_1.default.writeFileSync(tmpPath, target === null ? removeFrontmatterKeyLine(content, 'variant') : setFrontmatterKeyLine(content, 'variant', target), originalMode !== undefined ? { mode: originalMode } : undefined);
+                node_fs_1.default.writeFileSync(tmpPath, modelFormContent ?? (target === null ? removeFrontmatterKeyLine(content, 'variant') : setFrontmatterKeyLine(content, 'variant', target)), originalMode !== undefined ? { mode: originalMode } : undefined);
                 // Not redundant with the `mode` option above: `mode` only applies
                 // when the file is actually created (O_CREAT). A leftover tmp file
                 // from an earlier crashed run would be reused (truncated) at its OLD
@@ -2883,13 +2851,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))
@@ -3060,6 +3053,8 @@ function cmdProgressRender(cwd, format, raw) {
     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
@@ -3096,14 +3091,16 @@ function cmdProgressRender(cwd, format, raw) {
                 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));
-            const plans = phaseScan.planCount;
-            const summaries = phaseScan.summaryCount;
+            // #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');
+            const status = (0, phase_status_cjs_1.toDisplayLabel)(ps.value.status, { pendingWord: 'Pending' });
             phases.push({
                 number: phaseNum,
                 ...(displayId ? { display_id: displayId } : {}),
@@ -3115,6 +3112,9 @@ function cmdProgressRender(cwd, format, raw) {
         }
     }
     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 /
@@ -3273,29 +3273,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) {
@@ -3313,7 +3319,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.
@@ -3448,6 +3454,9 @@ function cmdStats(cwd, format, raw) {
         : 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;
@@ -3505,11 +3514,14 @@ function cmdStats(cwd, format, raw) {
                 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
@@ -3546,14 +3558,15 @@ function cmdStats(cwd, format, raw) {
                 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));
-            const plans = phaseScan.planCount;
-            const summaries = phaseScan.summaryCount;
+            // #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, {
@@ -3569,13 +3582,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
@@ -3901,9 +3927,6 @@ function cmdCommitDocsGuardDisable(cwd, raw) {
 module.exports = {
     effortSurfaceForHost,
     groupFilesBySubrepo,
-    determinePhaseStatus,
-    foldPhaseStatus,
-    PHASE_STATUS_PRECEDENCE,
     cmdGenerateSlug,
     cmdCurrentTimestamp,
     cmdListTodos,