@opengsd/gsd-core 1.10.0 → 1.12.0

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

@@ -11,11 +11,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 const node_fs_1 = __importDefault(require("node:fs"));
 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 security_cjs_1 = require("./security.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
-const { output, error } = ioMod;
+const { output, error, ERROR_REASON } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const configLoaderMod = require("./config-loader.cjs");
 const { loadConfig, isGitIgnored } = configLoaderMod;
@@ -24,20 +26,28 @@ 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 } = phaseIdMod;
+const { normalizePhaseName, comparePhaseNum, extractPhaseToken, PHASE_NUMBER_TOKEN_SOURCE, isSentinelPhaseId } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { getArchivedPhaseDirs, findPhaseInternal } = phaseLocatorMod;
+const { getArchivedPhaseDirs, findPhaseInternal, listMilestonePhaseDirs } = phaseLocatorMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserMod = require("./roadmap-parser.cjs");
-const { extractCurrentMilestone, stripShippedMilestones: _stripShippedMilestones, getMilestoneInfo, getMilestonePhaseFilter, getRoadmapPhaseInternal } = roadmapParserMod;
+const { extractCurrentMilestone, stripShippedMilestones: _stripShippedMilestones, getMilestoneInfo, getRoadmapPhaseInternal } = roadmapParserMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("./planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const modelResolverMod = require("./model-resolver.cjs");
-const { resolveModelInternal, resolveModelForTier, resolveProviderEscalation, resolveEffortInternal, resolveFastModeInternal, resolveEffortForTier, resolveGranularityInternal, assertValidGranularityOverride } = modelResolverMod;
+const { resolveModelInternal, resolveTierInternal, resolveModelForTier, resolveProviderEscalation, resolveEffortInternal, resolveFastModeInternal, resolveEffortForTier, resolveGranularityInternal, assertValidGranularityOverride } = modelResolverMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const agentCommandRouterMod = require("./agent-command-router.cjs");
 const { AGENT_FAILURE_CLASSES } = agentCommandRouterMod;
 const model_catalog_cjs_1 = require("./model-catalog.cjs");
+// #3243 (ADR-2313 D7) — the Codex `.toml` sync's typed IR: parse/render/strip
+// primitives moved from agent-install-check.cts's Phase-2 parsing into this
+// leaf so both consumers share one block-range detector. See
+// codex-agent-toml.cts's module header for the reader/writer reconciliation.
+const codex_agent_toml_cjs_1 = require("./codex-agent-toml.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const hostIntegrationMod = require("./host-integration.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -45,12 +55,19 @@ const planningWorkspace = require("./planning-workspace.cjs");
 const { planningDir, planningPaths } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatter = require("./frontmatter.cjs");
-const { extractFrontmatter } = frontmatter;
+const { extractFrontmatter, agentScalarNeedsDoubleQuoting, escapeDoubleQuotedScalar } = frontmatter;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const modelProfiles = require("./model-profiles.cjs");
 const { MODEL_PROFILES, VALID_PHASE_TYPES } = modelProfiles;
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 const clock_cjs_1 = require("./clock.cjs");
+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
+const verificationMod = require("./verification.cjs");
+const { resolveVerificationFile } = verificationMod;
 // ─── Phase Status ─────────────────────────────────────────────────────────────
 /**
  * Phase-status precedence ladder — furthest-along wins (#2408).
@@ -104,7 +121,16 @@ function determinePhaseStatus(plans, summaries, phaseDir, defaultPending) {
     // summaries >= plans — check verification
     try {
         const files = node_fs_1.default.readdirSync(phaseDir);
-        const verificationFile = files.find(f => f === 'VERIFICATION.md' || f.endsWith('-VERIFICATION.md'));
+        // #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) || '';
@@ -134,16 +160,16 @@ function cmdGenerateSlug(text, raw) {
     if (!text) {
         error('text required for slug generation');
     }
-    const slug = text
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '')
-        .substring(0, 60);
+    // #3883 (ADR-3473 §8.3): delegate to the canonical slug formula
+    // (generateSlugInternal, core-utils.cts) instead of re-implementing it —
+    // this call site previously diverged from it (Cyrillic collapsed to "",
+    // and truncation could leave a trailing hyphen; #2848/#2849).
+    const slug = coreUtilsMod.generateSlugInternal(text) ?? '';
     const result = { slug };
     output(result, raw, slug);
 }
 function cmdCurrentTimestamp(format, raw) {
-    const now = new Date();
+    const now = new Date(clock_cjs_1.realClock.now());
     let result;
     switch (format) {
         case 'date':
@@ -348,7 +374,14 @@ function cmdHistoryDigest(cwd, raw) {
     }
     try {
         for (const { name: dir, fullPath: dirPath } of allPhaseDirs) {
-            const summaries = node_fs_1.default.readdirSync(dirPath).filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
+            // #3183: canonical summary set (root+nested) from the single owner.
+            // This call also opens every plan file's frontmatter to check
+            // superseded status even though cmdHistoryDigest never uses planFiles
+            // or the superseded distinction — that per-phase-dir cost is accepted
+            // deliberately (correctness/single-ownership over micro-optimization;
+            // summaryFiles itself is not superseded-filtered either way). Do not
+            // "optimize" this back into a second hand-rolled summary derivation.
+            const summaries = scanPhasePlans(dirPath).summaryFiles;
             for (const summary of summaries) {
                 const summaryFilePath = node_path_1.default.join(dirPath, summary);
                 const content = (0, shell_command_projection_cjs_1.platformReadSync)(summaryFilePath);
@@ -419,10 +452,20 @@ function cmdResolveModel(cwd, agentType, raw) {
     const profile = config['model_profile'] || 'balanced';
     const model = resolveModelInternal(cwd, agentType);
     const effort = resolveEffortInternal(cwd, agentType);
-    const agentModels = MODEL_PROFILES[agentType];
+    // Own-property guard: agentType is an unvalidated CLI positional, so a
+    // prototype-chain value ("toString", "constructor") would otherwise return
+    // an inherited truthy member from this plain object and misreport a
+    // genuinely unknown agent as known (unknown_agent dropped from the result).
+    const agentModelsMap = MODEL_PROFILES;
+    const agentModels = Object.hasOwn(agentModelsMap, agentType) ? agentModelsMap[agentType] : undefined;
+    // #2229: `tier` is additive — existing keys and their values are untouched, so
+    // every `--pick model` / `--pick profile` / `--raw` consumer is unaffected. It
+    // exists because the model id is deliberately blank under resolve_model_ids:"omit",
+    // which leaves a tier-sensitive guard with nothing to read.
+    const tier = resolveTierInternal(cwd, agentType);
     const result = agentModels
-        ? { model, profile, effort }
-        : { model, profile, effort, unknown_agent: true };
+        ? { model, profile, effort, tier }
+        : { model, profile, effort, tier, unknown_agent: true };
     output(result, raw, model);
 }
 function cmdResolveGranularity(cwd, phaseType, raw, override) {
@@ -487,9 +530,59 @@ function cmdResolveExecution(cwd, agentType, raw, opts) {
         : resolveEffortInternal(cwd, agentType, effortOpts);
     const fastMode = resolveFastModeInternal(cwd, agentType, fastModeOpts);
     const runtime = config['runtime'] || 'claude';
-    const rendered = (0, model_catalog_cjs_1.renderEffortForRuntime)(runtime, effort);
+    // #3007: pass the resolved model so the per-model advertised-effort ceiling
+    // (CODEX_MODEL_EFFORT) is reachable from this production seam. `model` may
+    // be a tier alias or a non-Codex id for other runtimes — that's fine and
+    // must not be special-cased here: advertisedCodexEffort() falls back to the
+    // family baseline for any id it doesn't recognize.
+    const rendered = (0, model_catalog_cjs_1.renderEffortForRuntime)(runtime, effort, model);
     const fastModeSupported = model_catalog_cjs_1.RUNTIMES_WITH_FAST_MODE.has(runtime);
-    const agentModels = MODEL_PROFILES[agentType];
+    // #3534 (10a): the effective effort — what the installed agent will actually
+    // run at. `effort` above is the config cascade; for the claude runtime the
+    // per-agent frontmatter key is the source of truth (Claude Code's Agent tool
+    // has no per-spawn effort parameter), so the query reads the installed file.
+    // An ABSENT key is a real state — the agent follows the session effort
+    // ('inherit'), not drift. No file / no frontmatter / any read failure means
+    // no evidence: the resolved value is reported, flagged 'resolved' so a
+    // consumer can tell evidence from echo. Additive only — every existing key
+    // is unchanged.
+    let effortEffectiveSource = 'resolved';
+    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 agentPath = node_path_1.default.join(agentsDirEff, `${agentType}.md`);
+            // 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).
+            if (!node_path_1.default.resolve(agentPath).startsWith(node_path_1.default.resolve(agentsDirEff) + node_path_1.default.sep)) {
+                throw new Error('agent path escapes the agents directory');
+            }
+            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]);
+                if (effortLine) {
+                    effortEffective = effortLine[1];
+                    effortEffectiveSource = 'frontmatter';
+                }
+                else {
+                    effortEffective = 'inherit';
+                    effortEffectiveSource = 'frontmatter-absent';
+                }
+            }
+        }
+        catch { /* no frontmatter evidence — stay on the resolved value */ }
+    }
+    // Own-property guard: agentType is an unvalidated CLI positional, so a
+    // prototype-chain value ("toString", "constructor") would otherwise return
+    // an inherited truthy member from this plain object and misreport a
+    // genuinely unknown agent as known (unknown_agent dropped from the result).
+    const agentModelsMap = MODEL_PROFILES;
+    const agentModels = Object.hasOwn(agentModelsMap, agentType) ? agentModelsMap[agentType] : undefined;
     const result = {
         model,
         profile,
@@ -497,6 +590,11 @@ function cmdResolveExecution(cwd, agentType, raw, opts) {
         effort_rendered: rendered.value,
         effort_param: rendered.param,
         effort_propagation: rendered.channel,
+        effort_requested: rendered.requested,
+        effort_clamped: rendered.clamped,
+        effort_clamp_reason: rendered.reason,
+        effort_effective: effortEffective,
+        effort_effective_source: effortEffectiveSource,
         fast_mode: fastMode,
         fast_mode_supported: fastModeSupported,
     };
@@ -549,22 +647,108 @@ function effortSurfaceForHost(cwd, host) {
     }
 }
 /**
- * #488 — Replace or inject the `effort:` value in YAML frontmatter.
+ * #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.
  */
-function setEffortFrontmatter(content, effortValue) {
-    const eol = /^---\r\n/.test(content) ? '\r\n' : '\n';
+function setFrontmatterKeyLine(content, key, value) {
     const fmRe = /^---\r?\n([\s\S]*?)^---\r?$/m;
     const match = fmRe.exec(content);
     if (!match)
         return content;
     const fmBody = match[1];
-    if (/^effort:/m.test(fmBody)) {
-        return content.replace(/^(effort:)[ \t]*.*$/m, `$1 ${effortValue}`);
+    // 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;
+    // #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.
+    const keyLineRe = new RegExp(`^(${(0, pattern_cjs_1.escapeRegex)(key)}:)[ \\t]*.*$`, 'm');
+    if (keyLineRe.test(fmBody)) {
+        // #3706: a duplicated `<key>:` line is already invalid YAML, but a
+        // non-first-wins reader (last-wins) would otherwise honour a stale
+        // second occurrence left behind by a naive single-hit replace, while
+        // this function's own single-hit read reports "in sync" — a
+        // permanently non-converging state. Use a GLOBAL replace with a
+        // first-hit flag so every occurrence collapses to exactly one, IN THE
+        // POSITION of the first occurrence (never delete-then-append, which
+        // would move the key to the end of the frontmatter and churn every
+        // already-generated single-occurrence file).
+        const escaped = (0, pattern_cjs_1.escapeRegex)(key);
+        let seen = false;
+        const newBody = fmBody.replace(new RegExp(`^${escaped}:[ \\t]*.*(\\r?\\n?)`, 'gm'), (_m, nl) => {
+            if (!seen) {
+                seen = true;
+                return `${key}: ${renderedValue}${nl}`;
+            }
+            return '';
+        });
+        // Replace INSIDE the frontmatter span only: a whole-file /m replace would
+        // rewrite an earlier preamble line that happens to start with this key.
+        return content.slice(0, bodyStart) + newBody + content.slice(closingStart);
     }
+    return content.slice(0, closingStart) + `${key}: ${renderedValue}${eol}` + content.slice(closingStart);
+}
+/**
+ * #3533 (10d) — remove exactly the frontmatter `<key>:` line (and its line
+ * ending) so an agent configured for `inherit` carries NO key. Mirrors the
+ * 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.
+ */
+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)
+        return content;
+    const fmBody = match[1];
+    // #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))
+        return content;
+    // A duplicate `<key>:` mapping key is already invalid YAML (a document with
+    // two `effort:`/`variant:` lines does not parse), so this is robustness
+    // against a malformed document, not a live corruption path. Still, "a null
+    // target means the key must not exist" is an invariant this function must
+    // leave true on disk — a non-global replace here would strip only the
+    // FIRST occurrence and require a second run to converge. Use a fresh
+    // global RegExp for the strip so every occurrence in the frontmatter body
+    // 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, closingStart) + `effort: ${effortValue}${eol}` + content.slice(closingStart);
+    return content.slice(0, match.index + openLen) + strippedFm + content.slice(closingStart);
+}
+/** #488 — Replace or inject the `effort:` value in YAML frontmatter. */
+function setEffortFrontmatter(content, effortValue) {
+    return setFrontmatterKeyLine(content, 'effort', effortValue);
+}
+/** #3533 (10d) — remove exactly the frontmatter `effort:` line (and its line ending). */
+function removeEffortFrontmatter(content) {
+    return removeFrontmatterKeyLine(content, 'effort');
 }
 /**
  * #488 — Re-sync effort: frontmatter in all installed gsd-*.md agent files to
@@ -581,6 +765,22 @@ function cmdEffortSync(cwd, raw, opts) {
     const dryRun = opts.dryRun !== false;
     const config = loadConfig(cwd);
     const runtime = opts.runtime || config['runtime'] || 'claude';
+    // ADR-2313 D7 (#3243) — Codex gets its own `.toml` sync path (strip a stale
+    // Anthropic/tier `model` and an orphaned `model_reasoning_effort`, leaving a
+    // legal pin untouched). Every other non-claude runtime keeps the prior
+    // early-return; the claude branch below is untouched byte-for-byte.
+    if (runtime === 'codex') {
+        cmdEffortSyncCodex(raw, dryRun, opts.configDir);
+        return;
+    }
+    // #3706: install now bakes OpenCode's resolved effort into agent
+    // frontmatter under the `variant:` key (not `effort:`), so OpenCode gets
+    // its own sync path — mirroring the codex branch above — rather than
+    // falling into the generic "does not use effort: frontmatter" skip.
+    if (runtime === 'opencode') {
+        cmdEffortSyncOpencode(cwd, raw, dryRun, opts.configDir);
+        return;
+    }
     if (runtime !== 'claude') {
         output({ synced: 0, skipped: 0, changes: [], dry_run: dryRun, reason: `runtime '${runtime}' does not use effort: frontmatter` }, raw, '');
         return;
@@ -609,16 +809,126 @@ function cmdEffortSync(cwd, raw, opts) {
         catch {
             return false;
         }
-    });
+    }).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.
     const changes = [];
     let synced = 0;
     let skipped = 0;
+    // Local-only counter: reads AND writes are both guarded in this loop (an
+    // unreadable or unwritable agent file must not abort the whole sweep), but
+    // this result shape (`{synced, skipped, changes, dry_run, agents_dir}`) is
+    // long-standing and widely consumed, so it deliberately gains NO new key
+    // (no `read_failures`/`write_failures`, unlike the codex/opencode branches
+    // below). Instead every per-file failure — read or write — is folded into
+    // `skipped` and rides the raw-mode summary token below — `output()`'s
+    // third argument is never merged into the emitted JSON object (see io.cts
+    // `output()`: it is only read when `raw === true`, entirely replacing the
+    // JSON payload), so flipping it to `'failed'` costs nothing in the wire
+    // shape while still surfacing the failure to a raw-mode caller. The three
+    // branches differ on that reporting shape, but are now also consistent in
+    // HOW they publish: every write below goes through the same tmp-file +
+    // chmod + retryRenameSync atomic-publish sequence used by
+    // cmdEffortSyncCodex and cmdEffortSyncOpencode, so a fault mid-write can
+    // never leave an agent file truncated or empty.
+    let fileFailureCount = 0;
     for (const file of files) {
         const agentName = file.replace(/\.md$/, '');
         const filePath = node_path_1.default.join(agentsDir, file);
-        const content = node_fs_1.default.readFileSync(filePath, 'utf8');
+        let content;
+        try {
+            content = node_fs_1.default.readFileSync(filePath, 'utf8');
+        }
+        catch {
+            // An unreadable agent file must not abort the whole sweep. Deliberately
+            // NOT adding a new field here: this result shape (`{synced, skipped,
+            // changes, dry_run, agents_dir}`) is long-standing and widely consumed,
+            // so the failure is folded into `skipped` only, with no
+            // read_failures/write_failures list — see `fileFailureCount` above.
+            skipped++;
+            fileFailureCount++;
+            continue;
+        }
         // Resolve using install-time logic: home defaults merged with project config.
         const universalEffort = resolveInstallTimeEffort(effortCfg, agentName);
+        // #3533 (10d): 'inherit' means the key must NOT exist. An absent key is
+        // the CORRECT state (in sync, skipped) — before #3533 absence read as null
+        // 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);
+            if (!fmMatchInherit) {
+                skipped++;
+                continue;
+            }
+            // Presence and value are distinct questions: `effort:` with an EMPTY
+            // value is a key that IS present but whose captured value is null (the
+            // `(.+?)` group requires at least one char). Deciding "already correct"
+            // 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]);
+            if (!effortPresentInherit) {
+                skipped++;
+                continue;
+            }
+            const effortMatchInherit = /^effort:[ \t]*(.+?)[ \t]*$/m.exec(fmMatchInherit[1]);
+            // `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
+            // with "absent" in the sync output.
+            if (!dryRun) {
+                // Atomic publish AND mode preservation, same discipline as
+                // cmdEffortSyncCodex/cmdEffortSyncOpencode: write to a sibling tmp
+                // file, chmod it to match filePath's existing (masked) mode, then
+                // retryRenameSync it over the target so filePath is either the old
+                // bytes or the new ones, never half-written and never dropped to a
+                // default mode. On any failure the tmp file is unlinked (best-effort)
+                // and the write is reported (folded into `skipped`/`fileFailureCount`,
+                // no new field), not thrown, so the remaining agents still get
+                // processed. ONE failure path for this site — no nested try/catch.
+                const tmpPathInherit = `${filePath}.tmp.${process.pid}`;
+                // Stat filePath BEFORE the write so its mode can be passed at
+                // CREATION time — a plain `writeFileSync(tmpPath, data)` creates the
+                // tmp file at the default `0666 & ~umask` even when filePath is more
+                // restrictive. Best-effort only: a stat failure must not abort the
+                // sync, since the content write is what matters, not the mode.
+                let originalModeInherit;
+                try {
+                    originalModeInherit = node_fs_1.default.statSync(filePath).mode & 0o7777;
+                }
+                catch { /* non-fatal: fall back to writing without an explicit mode */ }
+                try {
+                    node_fs_1.default.writeFileSync(tmpPathInherit, removeEffortFrontmatter(content), originalModeInherit !== undefined ? { mode: originalModeInherit } : 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 mode instead, and this chmod is what corrects that case.
+                    // Best-effort only: a chmod failure must not abort the sync, since
+                    // the content write is what matters, not the mode.
+                    try {
+                        if (originalModeInherit !== undefined)
+                            node_fs_1.default.chmodSync(tmpPathInherit, originalModeInherit);
+                    }
+                    catch { /* non-fatal: proceed with default tmp-file mode */ }
+                    (0, shell_command_projection_cjs_1.retryRenameSync)(tmpPathInherit, filePath);
+                }
+                catch {
+                    try {
+                        node_fs_1.default.unlinkSync(tmpPathInherit);
+                    }
+                    catch { /* already gone or never created */ }
+                    skipped++;
+                    fileFailureCount++;
+                    continue;
+                }
+            }
+            changes.push({ agent: agentName, from: effortMatchInherit ? effortMatchInherit[1] : '', to: null });
+            synced++;
+            continue;
+        }
+        // `runtime` is guaranteed 'claude' by the guard above (#3007: only
+        // 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);
@@ -626,19 +936,388 @@ function cmdEffortSync(cwd, raw, opts) {
             skipped++;
             continue;
         }
+        // Presence and value are distinct questions here too: `currentEffort`
+        // reads null both when the key is ABSENT and when it is present with an
+        // EMPTY value. `effortPresent` disambiguates those two for the reported
+        // `from` below (never `null` when the key is present but empty) — but it
+        // has no bearing on the skip check that follows: `newEffortValue` is
+        // 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 currentEffort = effortMatch ? effortMatch[1] : null;
+        // `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.
+        const currentEffort = effortPresent ? (effortMatch ? effortMatch[1] : '') : null;
         if (currentEffort === newEffortValue) {
             skipped++;
             continue;
         }
+        if (!dryRun) {
+            // Atomic publish AND mode preservation, same discipline as
+            // cmdEffortSyncCodex/cmdEffortSyncOpencode: write to a sibling tmp
+            // file, chmod it to match filePath's existing (masked) mode, then
+            // retryRenameSync it over the target so filePath is either the old
+            // bytes or the new ones, never half-written and never dropped to a
+            // default mode. On any failure the tmp file is unlinked (best-effort)
+            // and the write is reported (folded into `skipped`/`fileFailureCount`,
+            // no new field), not thrown, so the remaining agents still get
+            // processed. ONE failure path for this site — no nested try/catch.
+            const tmpPathSet = `${filePath}.tmp.${process.pid}`;
+            // Stat filePath BEFORE the write so its mode can be passed at CREATION
+            // time — a plain `writeFileSync(tmpPath, data)` creates the tmp file
+            // at the default `0666 & ~umask` even when filePath is more
+            // restrictive. Best-effort only: a stat failure must not abort the
+            // sync, since the content write is what matters, not the mode.
+            let originalModeSet;
+            try {
+                originalModeSet = node_fs_1.default.statSync(filePath).mode & 0o7777;
+            }
+            catch { /* non-fatal: fall back to writing without an explicit mode */ }
+            try {
+                node_fs_1.default.writeFileSync(tmpPathSet, setEffortFrontmatter(content, newEffortValue), originalModeSet !== undefined ? { mode: originalModeSet } : 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
+                // mode instead, and this chmod is what corrects that case.
+                // Best-effort only: a chmod failure must not abort the sync, since
+                // the content write is what matters, not the mode.
+                try {
+                    if (originalModeSet !== undefined)
+                        node_fs_1.default.chmodSync(tmpPathSet, originalModeSet);
+                }
+                catch { /* non-fatal: proceed with default tmp-file mode */ }
+                (0, shell_command_projection_cjs_1.retryRenameSync)(tmpPathSet, filePath);
+            }
+            catch {
+                try {
+                    node_fs_1.default.unlinkSync(tmpPathSet);
+                }
+                catch { /* already gone or never created */ }
+                skipped++;
+                fileFailureCount++;
+                continue;
+            }
+        }
         changes.push({ agent: agentName, from: currentEffort, to: newEffortValue });
         synced++;
+    }
+    output({ synced, skipped, changes, dry_run: dryRun, agents_dir: agentsDir }, raw, fileFailureCount > 0 ? 'failed' : synced > 0 ? 'changed' : 'ok');
+}
+/**
+ * ADR-2313 D7 (#3243) — the Codex branch of `cmdEffortSync`. Strips a stale
+ * Anthropic-flavored/tier `model` pin and an orphaned `model_reasoning_effort`
+ * from every installed `~/.codex/agents/<agent>.toml`, leaving a legal
+ * real-Codex pin (and its coupled effort) untouched. Dry-run by default; every
+ * strip reported as a structured `{agent, field, from}` change; an unparseable
+ * document is refused and reported, never partially rewritten (40-design.md
+ * "Reconciliation" — parseCodexAgentToml is the STRICT half of the reader/
+ * writer split). Result shape is additive over the claude branch's
+ * `{synced, skipped, changes, dry_run, agents_dir}` — `refused`,
+ * `write_failures`, and `read_failures` are new fields, never a reshape of
+ * the existing ones.
+ */
+function cmdEffortSyncCodex(raw, dryRun, configDir) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/unbound-method
+    const { getGlobalConfigDir } = require('./runtime-homes.cjs');
+    const agentsDir = node_path_1.default.join(configDir || getGlobalConfigDir('codex'), 'agents');
+    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;
+    }
+    // Skip symlinks — matches the claude branch's existing guard above (only
+    // write regular files, never follow a symlink into clobbering its target).
+    const files = node_fs_1.default
+        .readdirSync(agentsDir)
+        .filter(f => {
+        if (!f.endsWith('.toml'))
+            return false;
+        try {
+            return node_fs_1.default.lstatSync(node_path_1.default.join(agentsDir, f)).isFile();
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort();
+    const changes = [];
+    const refused = [];
+    const writeFailures = [];
+    const readFailures = [];
+    let synced = 0;
+    let skipped = 0;
+    for (const file of files) {
+        const agentName = file.replace(/\.toml$/, '');
+        const filePath = node_path_1.default.join(agentsDir, file);
+        let content;
+        try {
+            content = node_fs_1.default.readFileSync(filePath, 'utf8');
+        }
+        catch (err) {
+            // An unreadable agent file must not abort the whole sweep — mirrors the
+            // opencode branch's own read guard, reported under its own
+            // `read_failures` key so a caller can tell "never read" apart from
+            // "read but write failed".
+            skipped++;
+            readFailures.push({ agent: agentName, file: filePath, error: err instanceof Error ? err.message : String(err) });
+            continue;
+        }
+        const parsed = (0, codex_agent_toml_cjs_1.parseCodexAgentToml)(content);
+        if (!parsed.ok) {
+            // Never partially rewritten (40-design.md, ADR-2313 reader/writer
+            // boundary): an unparseable document is skipped and reported, not
+            // guessed at.
+            skipped++;
+            refused.push({ agent: agentName, file: filePath, reason: parsed.reason });
+            continue;
+        }
+        let doc = parsed.doc;
+        const stripModelNeeded = doc.model !== null && (0, model_catalog_cjs_1.isAnthropicFlavoredModel)(doc.model);
+        // #838 coupling: an orphaned effort (no model) is always stale; a stale
+        // model's effort is coupled to it and strips with it. A legal pin's effort
+        // (model present, not Anthropic-flavored) is left untouched (rows 4-5).
+        const stripEffortNeeded = doc.reasoningEffort !== null && (stripModelNeeded || doc.model === null);
+        if (!stripModelNeeded && !stripEffortNeeded) {
+            // Posture-clean, OR a legal pin (and its coupled effort) — reported
+            // skipped, never synced (ADR-2313 reader/writer boundary).
+            skipped++;
+            continue;
+        }
+        const pendingChanges = [];
+        if (stripModelNeeded) {
+            pendingChanges.push({ agent: agentName, field: 'model', from: doc.model, to: null });
+            doc = (0, codex_agent_toml_cjs_1.stripModel)(doc);
+        }
+        if (stripEffortNeeded) {
+            pendingChanges.push({ agent: agentName, field: 'model_reasoning_effort', from: doc.reasoningEffort, to: null });
+            doc = (0, codex_agent_toml_cjs_1.stripReasoningEffort)(doc);
+        }
         if (!dryRun) {
-            node_fs_1.default.writeFileSync(filePath, setEffortFrontmatter(content, newEffortValue));
+            // Atomic publish (ADR-2313 "never partially rewritten"): write the
+            // rendered TOML to a sibling tmp file, then rename it over the target.
+            // Same-filesystem rename is atomic, so filePath is either the old bytes
+            // or the new ones, never truncated/half-written mid-crash. Deliberately
+            // NOT platformWriteSync — its normalizeContent step rewrites CRLF/
+            // trailing-newline bytes, which would break the byte-identical
+            // round-trip (A14) this writer must preserve. retryRenameSync (not a
+            // bare fs.renameSync) carries the transient-Windows-lock retry per
+            // DEFECT.WINDOWS-FS-OPS.
+            const tmpPath = `${filePath}.tmp.${process.pid}`;
+            // Stat filePath BEFORE the write so the original mode is available to
+            // pass at creation time, not just at chmod time afterward — otherwise
+            // the tmp file is briefly created at the default `0666 & ~umask`
+            // (world-readable under a typical 022 umask) even when filePath is
+            // e.g. 0600, exposing its contents for the window between creation and
+            // chmod. Best-effort: a stat failure must not abort the sync, since the
+            // content write is what matters, not the mode.
+            let originalMode;
+            try {
+                originalMode = node_fs_1.default.statSync(filePath).mode & 0o7777;
+            }
+            catch { /* non-fatal: fall back to writing without an explicit mode */ }
+            try {
+                node_fs_1.default.writeFileSync(tmpPath, (0, codex_agent_toml_cjs_1.renderCodexAgentToml)(doc), 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
+                // mode instead, and this chmod is what corrects that case. Mask off
+                // the file-type bits fs.statSync().mode carries (POSIX leaves
+                // chmod's handling of those unspecified); best-effort only, since
+                // the content write is what matters, not the mode.
+                try {
+                    if (originalMode !== undefined)
+                        node_fs_1.default.chmodSync(tmpPath, originalMode);
+                }
+                catch { /* non-fatal: proceed with default tmp-file mode */ }
+                (0, shell_command_projection_cjs_1.retryRenameSync)(tmpPath, filePath);
+            }
+            catch (err) {
+                // Reported, not thrown — the remaining agents still get processed.
+                // Clean up the orphaned tmp file; filePath itself was never touched.
+                try {
+                    node_fs_1.default.unlinkSync(tmpPath);
+                }
+                catch { /* already gone or never created */ }
+                skipped++;
+                writeFailures.push({ agent: agentName, file: filePath, error: err instanceof Error ? err.message : String(err) });
+                continue;
+            }
         }
+        changes.push(...pendingChanges);
+        synced++;
     }
-    output({ synced, skipped, changes, dry_run: dryRun, agents_dir: agentsDir }, raw, synced > 0 ? 'changed' : 'ok');
+    output({ synced, skipped, changes, dry_run: dryRun, agents_dir: agentsDir, refused, write_failures: writeFailures, read_failures: readFailures }, raw, writeFailures.length > 0 || readFailures.length > 0 ? 'failed' : synced > 0 ? 'changed' : 'ok');
+}
+/**
+ * #3706 — the OpenCode branch of `cmdEffortSync`. Maintains the `variant:`
+ * frontmatter key install now bakes into every `~/.config/opencode/agents/
+ * gsd-*.md` (or configDir-relative equivalent), mirroring exactly what
+ * install writes: a resolved universal effort clamped through
+ * `clampEffortForHost('opencode', ...)`. Null means the key must be ABSENT —
+ * #3533 (10d): an absent key is the correct state under `inherit`, and a
+ * level OpenCode does not accept must never be written, so both collapse to
+ * the same `target: null` and the same removal path. Result shape is
+ * additive over the claude branch, matching the CODEX branch's
+ * `{synced, skipped, changes, dry_run, agents_dir, write_failures}`.
+ */
+function cmdEffortSyncOpencode(cwd, raw, dryRun, configDir) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/unbound-method
+    const { getGlobalConfigDir } = require('./runtime-homes.cjs');
+    const agentsDir = node_path_1.default.join(configDir || getGlobalConfigDir('opencode'), 'agents');
+    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;
+    }
+    // Skip symlinks — matches the claude branch's existing guard (only write
+    // regular files, never follow a symlink into clobbering its target).
+    const files = node_fs_1.default
+        .readdirSync(agentsDir)
+        .filter(f => {
+        if (!f.startsWith('gsd-') || !f.endsWith('.md'))
+            return false;
+        try {
+            return node_fs_1.default.lstatSync(node_path_1.default.join(agentsDir, f)).isFile();
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort();
+    // Use install-time resolvers: they merge ~/.gsd/defaults.json with project
+    // config, matching the exact logic used when agents were originally
+    // installed. Resolved once, outside the loop, like the claude branch.
+    // 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);
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/unbound-method
+    const { clampEffortForHost } = require('./model-catalog.cjs');
+    const changes = [];
+    const writeFailures = [];
+    const readFailures = [];
+    let synced = 0;
+    let skipped = 0;
+    for (const file of files) {
+        const agentName = file.replace(/\.md$/, '');
+        const filePath = node_path_1.default.join(agentsDir, file);
+        let content;
+        try {
+            content = node_fs_1.default.readFileSync(filePath, 'utf8');
+        }
+        catch (err) {
+            // An unreadable agent file must not abort the whole sweep — degrade
+            // like the write path below does, and report it under its own
+            // `read_failures` key so a caller can tell "never read" apart from
+            // "read but write failed".
+            skipped++;
+            readFailures.push({ agent: agentName, file: filePath, error: err instanceof Error ? err.message : String(err) });
+            continue;
+        }
+        // `target === null` covers both "no effort configured" (inherit) and "a
+        // level OpenCode does not accept" — both must produce NO `variant:` key,
+        // 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);
+        if (!fmMatch) {
+            skipped++;
+            continue;
+        }
+        // Presence and value are distinct questions: `variant:` with an EMPTY
+        // value is a key that IS present but whose captured value is null (the
+        // `(.+?)` group requires at least one char). Deciding "already correct"
+        // from a null-vs-null comparison alone is wrong when target is also
+        // 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]);
+        // `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) {
+                skipped++;
+                continue;
+            }
+        }
+        else if (variantPresent && currentVariant === target) {
+            skipped++;
+            continue;
+        }
+        changes.push({ agent: agentName, from: currentVariant, to: target });
+        synced++;
+        if (!dryRun) {
+            // Atomic publish AND mode preservation, same discipline as
+            // cmdEffortSyncCodex above: write to a sibling tmp file, chmod it to
+            // match filePath's existing (masked) mode, then retryRenameSync it over
+            // the target so filePath is either the old bytes or the new ones, never
+            // half-written and never dropped to a default mode. On failure the
+            // write is reported, not thrown, so the remaining agents still get
+            // processed.
+            const tmpPath = `${filePath}.tmp.${process.pid}`;
+            // Stat filePath BEFORE the write so its mode can be passed at CREATION
+            // time — a plain `writeFileSync(tmpPath, data)` creates the tmp file at
+            // the default `0666 & ~umask` (world-readable under a typical 022
+            // umask) even when filePath is e.g. 0600, exposing its contents for
+            // the window between creation and the chmod below. Mask off the
+            // file-type bits (e.g. S_IFREG 0o100000) that fs.statSync().mode
+            // carries alongside the permission bits — POSIX leaves chmod's
+            // handling of those bits unspecified, and the remote matrix runs Linux
+            // only (Darwin tolerating the full mode is not evidence it is safe
+            // there). Best-effort only: a stat failure must not abort the sync,
+            // since the content write is what matters, not the mode.
+            let originalMode;
+            try {
+                originalMode = node_fs_1.default.statSync(filePath).mode & 0o7777;
+            }
+            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);
+                // 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
+                // mode instead, and this chmod is what corrects that case.
+                // Best-effort only: a chmod failure must not abort the sync, since
+                // the content write is what matters, not the mode.
+                try {
+                    if (originalMode !== undefined)
+                        node_fs_1.default.chmodSync(tmpPath, originalMode);
+                }
+                catch { /* non-fatal: proceed with default tmp-file mode */ }
+                (0, shell_command_projection_cjs_1.retryRenameSync)(tmpPath, filePath);
+            }
+            catch (err) {
+                try {
+                    node_fs_1.default.unlinkSync(tmpPath);
+                }
+                catch { /* already gone or never created */ }
+                changes.pop();
+                synced--;
+                skipped++;
+                writeFailures.push({ agent: agentName, file: filePath, error: err instanceof Error ? err.message : String(err) });
+                continue;
+            }
+        }
+    }
+    // Any failure — a write OR a read — must not report 'ok' or 'changed':
+    // either would hide that at least one agent's on-disk state is now unknown
+    // (unread) or unchanged despite being reported as a pending change (write
+    // failed after being pushed onto `changes`/`synced`). `write_failures` and
+    // `read_failures` take priority over the synced-count-derived summary below,
+    // even when other agents in the same run succeeded.
+    //
+    // Known limitation, deliberately not fixed here: `output()` only honors its
+    // third argument when `raw === true`, and this command's process always
+    // exits 0 regardless of the summary string — so `if gsd-tools effort sync;
+    // then` reads success in a shell even on a run where every write failed.
+    // Making the exit code reflect failure would be a CLI-contract change
+    // affecting all three cmdEffortSync* branches (claude, codex, opencode) and
+    // is out of scope for this fix.
+    output({ synced, skipped, changes, dry_run: dryRun, agents_dir: agentsDir, write_failures: writeFailures, read_failures: readFailures }, raw, writeFailures.length > 0 || readFailures.length > 0 ? 'failed' : synced > 0 ? 'changed' : 'ok');
 }
 /**
  * Detect the phase number for a commit from its `--files` path list.
@@ -693,6 +1372,71 @@ function detectPhaseNumberFromFiles(files) {
     }
     return null;
 }
+/**
+ * #3587: resolve the `phase_commit_docs.<phase-id>` override for `phaseNum`
+ * against `config['phase_commit_docs']` (a `{ "<phase-id>": boolean }` map, the
+ * same shape `agent_skills`/`features` use for their dynamic key families).
+ * Returns `undefined` — "no override applies" — when: no phase is known (B7),
+ * the map carries no entry for THIS phase (B5: no cross-phase leak), or the
+ * entry exists but is not a boolean (B6: never silently coerced). Both sides of
+ * the comparison route through `normalizePhaseName` so `3`, `03`, and `PROJ-03`
+ * all resolve to the same entry (B4/B9), reusing the single-owner phase-id
+ * normalizer rather than a second, looser string-equality rule.
+ */
+function resolvePhaseCommitDocsOverride(config, phaseNum) {
+    if (!phaseNum)
+        return undefined;
+    const overrides = config['phase_commit_docs'];
+    if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides))
+        return undefined;
+    const target = normalizePhaseName(phaseNum);
+    for (const [key, value] of Object.entries(overrides)) {
+        if (normalizePhaseName(key) === target) {
+            return typeof value === 'boolean' ? value : undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * #3587: the four-tier `commit_docs` precedence chain for a single commit —
+ * `phase_commit_docs.<phase-id>` (tier 1, resolved HERE because this call site
+ * is the one place that knows the phase — see 40-design.md "Rejected" §1: NOT
+ * inside `loadConfig`, which has no phase context and is called by nearly every
+ * command), then the pre-existing explicit `commit_docs` (tier 2), `.gitignore`
+ * auto-detect (tier 3), and manifest default (tier 4). Tiers 2-4 are byte-for-
+ * behaviour identical to the pre-#3587 inline checks (epic #2292 AC4): when no
+ * phase override applies, `resolved` matches exactly what those checks computed
+ * and `source` merely labels which of the three decided it.
+ *
+ * `isPlanningGitIgnored` is a thunk, not a plain boolean, so the pre-existing
+ * short-circuit is preserved byte-for-behaviour: the original inline checks
+ * only ever ran `isGitIgnored` (a real `git check-ignore` subprocess) when
+ * `commit_docs` was truthy, and a phase override or an explicit `commit_docs:
+ * false` must keep skipping that call entirely, not just its result. Passing
+ * a thunk also keeps this function pure and directly property-testable
+ * (test matrix F1) without spawning git.
+ */
+function resolveCommitDocsPolicy(config, phaseNum, isPlanningGitIgnored) {
+    const phaseOverride = resolvePhaseCommitDocsOverride(config, phaseNum);
+    if (phaseOverride !== undefined)
+        return { resolved: phaseOverride, source: 'phase' };
+    if (!config['commit_docs'])
+        return { resolved: false, source: 'config' };
+    if (isPlanningGitIgnored())
+        return { resolved: false, source: 'gitignore' };
+    return { resolved: true, source: 'default' };
+}
+// Reason string per commit_docs-resolution source, for the tier-1/tier-2 skip
+// envelope below. `phase` gets its OWN reason (`skipped_commit_docs_phase_false`)
+// rather than reusing `skipped_commit_docs_false` — telling a user "commit_docs
+// is false" when their project setting is actually `true` would be actively
+// misleading (design "Rejected" §3). `config` keeps the pre-existing string
+// unchanged: `agents/gsd-executor.md` pattern-matches on it (D2).
+const COMMIT_DOCS_SKIP_REASON = {
+    phase: 'skipped_commit_docs_phase_false',
+    config: 'skipped_commit_docs_false',
+    gitignore: 'skipped_gitignored',
+};
 function cmdCommit(cwd, message, files, raw, amend, noVerify) {
     if (!message && !amend) {
         error('commit message required');
@@ -706,18 +1450,20 @@ function cmdCommit(cwd, message, files, raw, amend, noVerify) {
         sanitizedMessage = sanitizeForPrompt(sanitizedMessage);
     }
     const config = loadConfig(cwd);
-    // Check commit_docs config
+    // Check commit_docs config — #3587: resolved through the tier 1
+    // (phase_commit_docs.<phase-id>) → tier 2 (commit_docs) → tier 3 (.gitignore)
+    // → tier 4 (default) precedence chain; see resolveCommitDocsPolicy above.
     // `skipped: true` is explicit so agent prompts can match on a first-class
     // success signal rather than inferring "skip" from "committed is missing"
     // and improvising raw git fallbacks (#3678).
-    if (!config['commit_docs']) {
-        const result = { committed: false, skipped: true, hash: null, reason: 'skipped_commit_docs_false' };
-        output(result, raw, 'skipped');
-        return;
-    }
-    // Check if .planning is gitignored
-    if (isGitIgnored(cwd, '.planning')) {
-        const result = { committed: false, skipped: true, hash: null, reason: 'skipped_gitignored' };
+    const commitDocsPolicy = resolveCommitDocsPolicy(config, detectPhaseNumberFromFiles(files), () => isGitIgnored(cwd, '.planning'));
+    if (!commitDocsPolicy.resolved) {
+        const result = {
+            committed: false,
+            skipped: true,
+            hash: null,
+            reason: COMMIT_DOCS_SKIP_REASON[commitDocsPolicy.source],
+        };
         output(result, raw, 'skipped');
         return;
     }
@@ -742,7 +1488,10 @@ function cmdCommit(cwd, message, files, raw, amend, noVerify) {
             // — see #2528 for the parallel drift problem in phase-locator/phase),
             // so this is the canonical path-segment-bound read, not a fourth copy.
             const phaseNum = detectPhaseNumberFromFiles(files);
-            if (phaseNum) {
+            // #3734: a 999.x/0.x backlog sentinel is a parking-lot entry, not a real
+            // phase — the phase arm must never branch-mutate for it (isSentinelPhaseId
+            // is the invariant's single owner, src/phase-id.cts).
+            if (phaseNum && !isSentinelPhaseId(phaseNum)) {
                 const phaseInfo = findPhaseInternal(cwd, phaseNum);
                 if (phaseInfo) {
                     branchName = config['phase_branch_template']
@@ -752,7 +1501,19 @@ function cmdCommit(cwd, message, files, raw, amend, noVerify) {
             }
         }
         else if (branchingStrategy === 'milestone') {
-            const milestone = getMilestoneInfo(cwd);
+            const milestoneInfo = getMilestoneInfo(cwd);
+            // #3216 review Finding 3: explicit scope gate instead of plain truthiness.
+            // COMPLETE and TRUNCATED both carry a real `version` (ADR-3180 §7.2 rule
+            // 6 — TRUNCATED means the version resolved but the milestone's NAME did
+            // not), so a TRUNCATED identity is acceptable here: `milestone.version`
+            // only feeds a BRANCH NAME, and `generateSlugInternal(null) || 'milestone'`
+            // already degrades the missing name to the literal "milestone" slug on
+            // purpose. This differs from `archivePhaseDirectories` (milestone.cts),
+            // which uses the same value as a DIRECTORY NAME and therefore demands
+            // COMPLETE only — a real-but-unnamed version is not safe enough there.
+            const milestone = milestoneInfo.scope === SCOPE.COMPLETE || milestoneInfo.scope === SCOPE.TRUNCATED
+                ? milestoneInfo.value
+                : null;
             if (milestone && milestone.version) {
                 branchName = config['milestone_branch_template']
                     .replace('{milestone}', milestone.version)
@@ -762,22 +1523,28 @@ function cmdCommit(cwd, message, files, raw, amend, noVerify) {
         if (branchName) {
             const currentBranch = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--abbrev-ref', 'HEAD'], { cwd });
             if (currentBranch.exitCode === 0 && currentBranch.stdout.trim() !== branchName) {
-                // #2539/#3079: the #1278 intent is to CREATE the phase/milestone branch
-                // before the FIRST commit on it — not to force-switch an already-
-                // checked-out working branch onto a DIFFERENT existing branch. The
-                // prior `git checkout -b` both created AND switched (silently moving
-                // HEAD), which resurrected merged-and-deleted phase branches (#3079).
-                // Now: create-if-absent WITHOUT switching, using `git branch` instead
-                // of `git checkout -b`. The commit always lands on the current branch.
-                // If the resolved branch already exists, log the resolution so the
-                // operator sees that the phase branch was resolved and deliberately
-                // not switched to (#2539 AC2: an auto-checkout mid-commit must never
-                // happen silently).
+                // #2539/#3079/#3207: two cases the prior (#3079) code collapsed into one.
+                // #1278 intent: CREATE the phase/milestone branch before the FIRST commit
+                // on it so the phase's work accumulates there. #3079/#2539 hazard: never
+                // silently switch an already-checked-out working branch onto a DIFFERENT
+                // EXISTING branch — that resurrects merged-and-deleted phase branches and
+                // silently moves HEAD onto a stale ref (#2539 AC2: an auto-checkout
+                // mid-commit must never happen silently).
+                // Reconciliation (#3207): a brand-new branch has no resurrection target,
+                // so create-and-switch is safe here and is exactly the #1278 intent; an
+                // EXISTING branch is never switched to (the else arm logs + commits in
+                // place). The fresh create is logged so the first phase-scoped commit is
+                // not silent about where the work is landing (#3207 AC3).
                 const verify = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--verify', `refs/heads/${branchName}`], { cwd });
                 if (verify.exitCode !== 0) {
-                    // Branch does not exist — create it WITHOUT switching.
-                    const create = (0, shell_command_projection_cjs_1.execGit)(['branch', branchName], { cwd });
-                    if (create.exitCode !== 0) {
+                    // Branch does not exist — CREATE AND SWITCH (the #1278 first-commit
+                    // case). checkout -b cannot resurrect anything: the branch was just
+                    // verified absent, so it is created fresh at HEAD.
+                    const create = (0, shell_command_projection_cjs_1.execGit)(['checkout', '-b', branchName], { cwd });
+                    if (create.exitCode === 0) {
+                        process.stderr.write(`${branchingStrategy} branch "${branchName}" created; switched to it for this commit.\n`);
+                    }
+                    else {
                         process.stderr.write(`Warning: could not create ${branchingStrategy} branch "${branchName}" ` +
                             `(${create.stderr.trim()}); committing on the current branch "${currentBranch.stdout.trim()}".\n`);
                     }
@@ -904,8 +1671,26 @@ function cmdCommit(cwd, message, files, raw, amend, noVerify) {
     if (canScope) {
         commitArgs.push('--', ...stagedPaths);
     }
-    const commitResult = (0, shell_command_projection_cjs_1.execGit)(commitArgs, { cwd });
+    // #3886: `git commit` runs pre-commit hooks (husky/lint-staged routinely
+    // idles ~4s on Windows before any task) — 10s is too tight, and a timeout
+    // kill is NOT an ordinary failure. Same band as the push call below.
+    const commitResult = (0, shell_command_projection_cjs_1.execGit)(commitArgs, { cwd, timeout: COMMIT_TIMEOUT_MS });
     if (commitResult.exitCode !== 0) {
+        // #3886: a SIGTERM'd git commit is a timeout, not commit_failed — the
+        // partial stderr it flushed (often incidental CRLF warnings) is noise,
+        // and the kill can leave a stale index.lock that blocks the next
+        // attempt. Report the distinct reason and surface the lock path.
+        if ((0, shell_command_projection_cjs_1.isSpawnTimeout)(commitResult)) {
+            const result = {
+                committed: false,
+                hash: null,
+                reason: 'commit_timeout',
+                timed_out: true,
+                error: commitTimeoutMessage(cwd, commitResult.stderr, commitResult.stdout),
+            };
+            output(result, raw, 'failed');
+            return;
+        }
         if (commitResult.stdout.includes('nothing to commit') || commitResult.stderr.includes('nothing to commit')) {
             const result = { committed: false, hash: null, reason: 'nothing_to_commit' };
             output(result, raw, 'nothing');
@@ -1045,8 +1830,21 @@ function cmdCommitToSubrepo(cwd, message, files, raw) {
         const commitArgs = canScopeSub
             ? ['commit', '-m', message, '--', ...stagedRelPaths]
             : ['commit', '-m', message];
-        const commitResult = (0, shell_command_projection_cjs_1.execGit)(commitArgs, { cwd: repoCwd });
+        const commitResult = (0, shell_command_projection_cjs_1.execGit)(commitArgs, { cwd: repoCwd, timeout: COMMIT_TIMEOUT_MS });
         if (commitResult.exitCode !== 0) {
+            if ((0, shell_command_projection_cjs_1.isSpawnTimeout)(commitResult)) {
+                // #3886 (subrepo counterpart): timeout ≠ error; surface the stale-lock
+                // path a killed commit can leave in the subrepo.
+                repos[repo] = {
+                    committed: false,
+                    hash: null,
+                    files: repoFiles,
+                    reason: 'commit_timeout',
+                    timed_out: true,
+                    error: commitTimeoutMessage(repoCwd, commitResult.stderr, commitResult.stdout),
+                };
+                continue;
+            }
             if (commitResult.stdout.includes('nothing to commit') || commitResult.stderr.includes('nothing to commit')) {
                 repos[repo] = { committed: false, hash: null, files: repoFiles, reason: 'nothing_to_commit' };
                 continue;
@@ -1176,9 +1974,15 @@ function cmdPrSubrepo(cwd, repo, branch, commitMessage, raw) {
     const commitArgs = canScopePr
         ? ['commit', '-m', commitMessage, '--', ...changedFiles]
         : ['commit', '-m', commitMessage];
-    const commitResult = (0, shell_command_projection_cjs_1.execGit)(commitArgs, { cwd: repoCwd });
+    const commitResult = (0, shell_command_projection_cjs_1.execGit)(commitArgs, { cwd: repoCwd, timeout: COMMIT_TIMEOUT_MS });
     if (commitResult.exitCode !== 0) {
         rollback();
+        if ((0, shell_command_projection_cjs_1.isSpawnTimeout)(commitResult)) {
+            // #3886 (PR-subrepo counterpart): name the timeout and the stale lock
+            // instead of echoing the killed hook's partial stderr.
+            error(`git commit timed out after ${COMMIT_TIMEOUT_MS / 1000}s in ${repo} (killed mid-hook; ` +
+                `a stale lock may remain at ${resolveIndexLockPath(repoCwd)} — remove it if no git process is running)`);
+        }
         error(`Failed to commit in ${repo}: ${commitResult.stderr}`);
     }
     // 6. Capture commit hash
@@ -1384,20 +2188,28 @@ async function cmdWebsearch(query, options, raw) {
 }
 function cmdProgressRender(cwd, format, raw) {
     const phasesDir = planningPaths(cwd).phases;
-    const milestone = getMilestoneInfo(cwd);
+    const milestone = getMilestoneInfo(cwd).value;
     const phases = [];
     let totalPlans = 0;
     let totalSummaries = 0;
+    let phaseScope = null;
     try {
-        const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
-        const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort((a, b) => comparePhaseNum(a, b));
+        // #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 });
+        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, ' ') : '';
-            const phaseFiles = node_fs_1.default.readdirSync(node_path_1.default.join(phasesDir, dir));
-            const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').length;
-            const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').length;
+            // #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;
             totalPlans += plans;
             totalSummaries += summaries;
             const status = determinePhaseStatus(plans, summaries, node_path_1.default.join(phasesDir, dir), 'Pending');
@@ -1405,14 +2217,24 @@ function cmdProgressRender(cwd, format, raw) {
         }
     }
     catch { /* intentionally empty */ }
-    const percent = totalPlans > 0 ? Math.min(100, Math.round((totalSummaries / totalPlans) * 100)) : 0;
+    // #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 /
+    // UNSCOPED / UNREADABLE). Withhold the percentage itself (never `0` — a
+    // real `0` under COMPLETE must still render, rule 2's territory) when the
+    // scope is not COMPLETE. `phaseScope` stays `null` only if the try block
+    // above threw before assigning it; treat that the same as non-COMPLETE.
+    const percent = phaseScope === SCOPE.COMPLETE
+        ? (0, phase_lifecycle_cjs_1.clampPercent)(totalSummaries, totalPlans)
+        : null;
     if (format === 'table') {
         // Render markdown table
         const barWidth = 10;
-        const filled = Math.round((percent / 100) * barWidth);
+        const filled = percent === null ? 0 : Math.round((percent / 100) * barWidth);
         const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
-        let out = `# ${milestone.version} ${milestone.name}\n\n`;
-        out += `**Progress:** [${bar}] ${totalSummaries}/${totalPlans} plans (${percent}%)\n\n`;
+        const percentSuffix = percent === null ? '' : ` (${percent}%)`;
+        let out = `# ${milestone?.version ?? ''} ${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) {
@@ -1422,20 +2244,24 @@ function cmdProgressRender(cwd, format, raw) {
     }
     else if (format === 'bar') {
         const barWidth = 20;
-        const filled = Math.round((percent / 100) * barWidth);
+        const filled = percent === null ? 0 : Math.round((percent / 100) * barWidth);
         const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
-        const text = `[${bar}] ${totalSummaries}/${totalPlans} plans (${percent}%)`;
+        const percentSuffix = percent === null ? '' : ` (${percent}%)`;
+        const text = `[${bar}] ${totalSummaries}/${totalPlans} plans${percentSuffix}`;
         output({ bar: text, percent, completed: totalSummaries, total: totalPlans }, raw, text);
     }
     else {
         // JSON format
         output({
-            milestone_version: milestone.version,
-            milestone_name: milestone.name,
+            milestone_version: milestone?.version ?? null,
+            milestone_name: milestone?.name ?? null,
             phases,
             total_plans: totalPlans,
             total_summaries: totalSummaries,
             percent,
+            // #3185 (ADR-3180 Decision 2): the enumeration's scope, so a consumer
+            // can tell a genuinely-empty milestone from one it could not scope.
+            phase_scope: phaseScope,
         }, raw, undefined);
     }
 }
@@ -1492,7 +2318,9 @@ function cmdTodoMatchPhase(cwd, phase, raw) {
     if (phaseInfoDisk && phaseInfoDisk['found']) {
         try {
             const phaseDir = node_path_1.default.join(cwd, phaseInfoDisk['directory']);
-            const planFiles = node_fs_1.default.readdirSync(phaseDir).filter(f => f.endsWith('-PLAN.md'));
+            // #3183: canonical plan set (root+nested, superseded-excluded) from the
+            // single owner, rather than a root-only hand-rolled readdirSync filter.
+            const planFiles = scanPhasePlans(phaseDir).planFiles;
             for (const pf of planFiles) {
                 const planContent = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(phaseDir, pf));
                 if (planContent === null)
@@ -1629,12 +2457,12 @@ function cmdStats(cwd, format, raw) {
     const roadmapPath = planningPaths(cwd).roadmap;
     const reqPath = planningPaths(cwd).requirements;
     const statePath = planningPaths(cwd).state;
-    const milestone = getMilestoneInfo(cwd);
-    const isDirInMilestone = getMilestonePhaseFilter(cwd);
+    const milestone = getMilestoneInfo(cwd).value;
     // Phase & plan stats (reuse progress pattern)
     const phasesByNumber = new Map();
     let totalPlans = 0;
     let totalSummaries = 0;
+    let phaseScope = null;
     try {
         const roadmapRaw = (0, shell_command_projection_cjs_1.platformReadSync)(roadmapPath);
         if (roadmapRaw === null)
@@ -1643,9 +2471,22 @@ function cmdStats(cwd, format, raw) {
         // Matches both plain numeric (Phase 1:) and milestone-prefixed (Phase 2-01:) headings.
         // Also tolerates optional [bracket-token] scope prefix on phase headings.
         // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-        const headingPattern = /#{2,4}\s*(?:\[[^\]]{1,200}\]\s*)?Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]{0,200}\))?\s*:\s*([^\n]+)/gi;
+        // #3569: the id capture is the canonical #3036 shape (digit REQUIRED — incl.
+        // letter-prefixed B7, decimals, milestone 2-01), the same group roadmap.cts's
+        // collectAnalyzePhases uses. The former `([\w][\w.-]*)` matched ANY word, so
+        // 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;
         let match;
         while ((match = headingPattern.exec(roadmapContent)) !== null) {
+            // #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]))
+                continue;
             const key = normalizePhaseName(match[1]);
             phasesByNumber.set(key, {
                 number: key,
@@ -1658,12 +2499,13 @@ function cmdStats(cwd, format, raw) {
     }
     catch { /* intentionally empty */ }
     try {
-        const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
-        const dirs = entries
-            .filter(e => e.isDirectory())
-            .map(e => e.name)
-            .filter(isDirInMilestone)
-            .sort((a, b) => comparePhaseNum(a, b));
+        // #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 });
+        phaseScope = scope;
         for (const dir of dirs) {
             // Use extractPhaseToken to correctly parse M-NN-style and code-prefixed dir names.
             const phaseToken = extractPhaseToken(dir);
@@ -1671,9 +2513,11 @@ function cmdStats(cwd, format, raw) {
             // phaseName is everything after the token (strip leading '-')
             const afterToken = dir.slice(phaseToken ? phaseToken.length : 0).replace(/^-/, '');
             const phaseName = afterToken ? afterToken.replace(/-/g, ' ') : '';
-            const phaseFiles = node_fs_1.default.readdirSync(node_path_1.default.join(phasesDir, dir));
-            const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').length;
-            const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').length;
+            // #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;
             totalPlans += plans;
             totalSummaries += summaries;
             const status = determinePhaseStatus(plans, summaries, node_path_1.default.join(phasesDir, dir), 'Not Started');
@@ -1696,8 +2540,12 @@ function cmdStats(cwd, format, raw) {
     catch { /* intentionally empty */ }
     const phases = [...phasesByNumber.values()].sort((a, b) => comparePhaseNum(a.number, b.number));
     const completedPhases = phases.filter(p => p.status === 'Complete').length;
-    const planPercent = totalPlans > 0 ? Math.min(100, Math.round((totalSummaries / totalPlans) * 100)) : 0;
-    const percent = phases.length > 0 ? Math.min(100, Math.round((completedPhases / phases.length) * 100)) : 0;
+    // #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
+    // cmdProgressRender above. A real `0` under COMPLETE still renders.
+    const planPercent = phaseScope === SCOPE.COMPLETE ? (0, phase_lifecycle_cjs_1.clampPercent)(totalSummaries, totalPlans) : null;
+    const percent = phaseScope === SCOPE.COMPLETE ? (0, phase_lifecycle_cjs_1.clampPercent)(completedPhases, phases.length) : null;
     // Requirements stats
     let requirementsTotal = 0;
     let requirementsComplete = 0;
@@ -1735,8 +2583,8 @@ function cmdStats(cwd, format, raw) {
         }
     }
     const result = {
-        milestone_version: milestone.version,
-        milestone_name: milestone.name,
+        milestone_version: milestone?.version ?? null,
+        milestone_name: milestone?.name ?? null,
         phases,
         phases_completed: completedPhases,
         phases_total: phases.length,
@@ -1749,14 +2597,18 @@ function cmdStats(cwd, format, raw) {
         git_commits: gitCommits,
         git_first_commit_date: gitFirstCommitDate,
         last_activity: lastActivity,
+        // #3185 (ADR-3180 Decision 2): the enumeration's scope, so a consumer
+        // can tell a genuinely-empty milestone from one it could not scope.
+        phase_scope: phaseScope,
     };
     if (format === 'table') {
         const barWidth = 10;
-        const filled = Math.round((percent / 100) * barWidth);
+        const filled = percent === null ? 0 : Math.round((percent / 100) * barWidth);
         const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
-        let out = `# ${milestone.version} ${milestone.name} — Statistics\n\n`;
-        out += `**Progress:** [${bar}] ${completedPhases}/${phases.length} phases (${percent}%)\n`;
-        if (totalPlans > 0) {
+        let out = `# ${milestone?.version ?? ''} ${milestone?.name ?? ''} — Statistics\n\n`;
+        const percentSuffix = percent === null ? '' : ` (${percent}%)`;
+        out += `**Progress:** [${bar}] ${completedPhases}/${phases.length} phases${percentSuffix}\n`;
+        if (totalPlans > 0 && planPercent !== null) {
             out += `**Plans:** ${totalSummaries}/${totalPlans} complete (${planPercent}%)\n`;
         }
         out += `**Phases:** ${completedPhases}/${phases.length} complete\n`;
@@ -1784,30 +2636,234 @@ function cmdStats(cwd, format, raw) {
     }
 }
 /**
- * Check whether a commit should be allowed based on commit_docs config.
- * When commit_docs is false, rejects commits that stage .planning/ files.
- * Intended for use as a pre-commit hook guard.
+ * Check whether a commit should be allowed based on the `commit_docs`
+ * precedence chain, INCLUDING any `phase_commit_docs.<phase-id>` override
+ * (#3587/#3601). Rejects commits that stage `.planning/` files when the
+ * resolved policy is false. Intended for use as a pre-commit hook guard —
+ * see `commit-docs-guard enable` above.
+ *
+ * The phase is derived from the STAGED `.planning/` paths via the single-
+ * owner `detectPhaseNumberFromFiles` (the same helper `cmdCommit` uses), and
+ * the policy itself is resolved via the single-owner `resolveCommitDocsPolicy`
+ * (also shared with `cmdCommit`) — this function never re-derives phase
+ * detection or precedence, so it cannot diverge from `cmdCommit`'s decision
+ * for the same staged tree (#3588 Part 1: this guard was previously
+ * phase-blind, reading only project-level `commit_docs` and directly
+ * contradicting `gsd-tools query commit`'s phase-aware resolution).
+ *
+ * Staged paths are read via `git diff --cached --name-only -z`, NUL-
+ * delimited, rather than the LF-delimited default. Without `-z`, git
+ * C-style-quotes (wraps in double quotes, octal-escapes) any path containing
+ * a non-ASCII byte, a space-adjacent special character, or a literal quote —
+ * `.planning/café.md` is reported as `".planning/caf\303\251.md"`, which
+ * does not start with `.planning/`, so the old LF-based filter silently
+ * missed it and allowed the commit (#3588 F2: a false negative in the harm
+ * direction this guard exists to prevent). `-z` disables that quoting
+ * entirely and NUL-terminates each path instead, so every staged path is
+ * read as literal, unquoted bytes and no unquoting logic is needed.
  */
 function cmdCheckCommit(cwd, raw) {
     const config = loadConfig(cwd);
-    // If commit_docs is true (or not set), allow all commits
-    if (config['commit_docs'] !== false) {
-        output({ allowed: true, reason: 'commit_docs_enabled' }, raw, 'allowed');
-        return;
-    }
-    // commit_docs is false — check if any .planning/ files are staged
-    const stagedResult = (0, shell_command_projection_cjs_1.execGit)(['diff', '--cached', '--name-only'], { cwd });
+    const stagedResult = (0, shell_command_projection_cjs_1.execGit)(['diff', '--cached', '--name-only', '-z'], { cwd });
     if (stagedResult.exitCode === 0) {
-        const planningFiles = stagedResult.stdout.split('\n').filter(f => f.startsWith('.planning/') || f.startsWith('.planning\\'));
+        const files = stagedResult.stdout.split('\0').filter(Boolean);
+        const planningFiles = files.filter(f => f.startsWith('.planning/'));
         if (planningFiles.length > 0) {
-            error(`commit_docs is false but ${planningFiles.length} .planning/ file(s) are staged:\n` +
-                planningFiles.map(f => `  ${f}`).join('\n') +
-                `\n\nTo unstage: git reset HEAD ${planningFiles.join(' ')}`);
+            const policy = resolveCommitDocsPolicy(config, detectPhaseNumberFromFiles(planningFiles), () => isGitIgnored(cwd, '.planning'));
+            if (!policy.resolved) {
+                error(`commit_docs is false but ${planningFiles.length} .planning/ file(s) are staged:\n` +
+                    planningFiles.map(f => `  ${f}`).join('\n') +
+                    `\n\nTo unstage: git reset HEAD ${planningFiles.join(' ')}`);
+                return;
+            }
+            output({ allowed: true, reason: policy.source === 'phase' ? 'phase_commit_docs_true' : 'commit_docs_enabled' }, raw, 'allowed');
+            return;
         }
     }
-    // exitCode !== 0 → no staged files or not a git repo — allow
+    // exitCode !== 0 (no staged files / not a git repo) or no .planning/ files staged — allow
     output({ allowed: true, reason: 'no_planning_files_staged' }, raw, 'allowed');
 }
+// ─── commit-docs-guard: opt-in pre-commit hook (#3588) ─────────────────────
+/**
+ * Stable sentinel line identifying a `.git/hooks/pre-commit` file as ours.
+ * Detection is by PRESENCE of this line, not byte-equality (design "Identifying
+ * 'our' hook") — a user who appends a line to a GSD-written hook must not make
+ * it unrecognizable, and a hook lacking this line must never be overwritten or
+ * deleted by `commit-docs-guard enable`/`disable`.
+ */
+const COMMIT_DOCS_GUARD_MARKER = '# gsd-core:commit-docs-guard';
+/**
+ * Locate `gsd-core/workflows/_runtime-launcher.snippet.sh` — the SAME
+ * gsd-tools-resolution chain every shipped workflow/agent bash block uses
+ * (scripts/sync-runtime-launcher.cjs) — by walking up from this module's own
+ * compiled location rather than a fixed literal `../..` join, so the walk
+ * tolerates the module living at a different depth under an alternate build
+ * or bundling layout (same defensive shape as
+ * runtime-artifact-layout.cts#findInstallSourceRoot).
+ */
+function findRuntimeLauncherSnippet() {
+    let dir = __dirname;
+    for (let i = 0; i < 8; i++) {
+        const candidate = node_path_1.default.join(dir, 'workflows', '_runtime-launcher.snippet.sh');
+        if (node_fs_1.default.existsSync(candidate))
+            return candidate;
+        const parent = node_path_1.default.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error(`commit-docs-guard: could not locate workflows/_runtime-launcher.snippet.sh from ${__dirname}`);
+}
+/**
+ * Build the literal `.git/hooks/pre-commit` content `commit-docs-guard enable`
+ * writes. Reuses the canonical gsd_run resolution preamble byte-for-byte
+ * (read from disk, never hand-copied — see findRuntimeLauncherSnippet) so this
+ * hook resolves `gsd-tools` exactly the way every other shipped workflow bash
+ * block does, and cannot drift from it.
+ *
+ * LF-only (#3588 A2): the snippet file and every literal line here are joined
+ * with `\n`; platformWriteSync additionally normalizes CRLF→LF on write, so a
+ * CRLF shebang — which is not executable under Git Bash — cannot reach disk.
+ */
+function buildCommitDocsGuardHookScript() {
+    const snippetPath = findRuntimeLauncherSnippet();
+    const preamble = (0, text_lines_cjs_1.normalizeEol)(node_fs_1.default.readFileSync(snippetPath, 'utf8')).replace(/\n+$/, '');
+    const lines = [
+        '#!/usr/bin/env bash',
+        COMMIT_DOCS_GUARD_MARKER,
+        '# Refuses a commit that stages .planning/ files when `commit_docs` resolves',
+        '# false (honoring any per-phase override). Installed by',
+        '# `gsd-tools commit-docs-guard enable`; remove with',
+        '# `gsd-tools commit-docs-guard disable`. See',
+        '# docs/how-to/keep-planning-docs-private.md.',
+        'set -euo pipefail',
+        '',
+        preamble,
+        '',
+        'gsd_run check-commit --raw',
+    ];
+    return lines.join('\n') + '\n';
+}
+/**
+ * #3886: the timeout band for `git commit` — pre-commit hooks (husky +
+ * lint-staged idles ~4s on Windows before any task) routinely exceed the 10s
+ * plumbing default; 30s is the same band the push call uses. Shared by all
+ * three commit sites AND their timeout messages, so the number and the text
+ * cannot drift apart.
+ */
+const COMMIT_TIMEOUT_MS = 30_000;
+/**
+ * #3886: resolve where a killed `git commit` would leave its stale
+ * index.lock — via `git rev-parse --git-path index.lock`, never a literal
+ * `.git/index.lock` join (#3588 row 8's class: a linked worktree's `.git` is
+ * a FILE pointing at `<gitdir>/worktrees/<name>/`, so the literal path
+ * cannot exist there while the real lock blocks the next commit). Best
+ * effort: any resolution failure falls back to the literal join, and the
+ * message already hedges with "may remain".
+ */
+function resolveIndexLockPath(cwd) {
+    const result = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--git-path', 'index.lock'], { cwd });
+    if (result.exitCode !== 0)
+        return node_path_1.default.join(cwd, '.git', 'index.lock');
+    const raw = result.stdout.trim();
+    return raw ? (node_path_1.default.isAbsolute(raw) ? raw : node_path_1.default.join(cwd, raw)) : node_path_1.default.join(cwd, '.git', 'index.lock');
+}
+/** #3886: shared timeout message shape for all three commit sites. */
+function commitTimeoutMessage(cwd, stderr, stdout) {
+    return (`git commit timed out after ${COMMIT_TIMEOUT_MS / 1000}s (killed mid-hook; a stale lock may remain at ` +
+        `${resolveIndexLockPath(cwd)} — remove it if no git process is running). ` +
+        `Partial stderr: ${stderr || stdout || '(none)'}`);
+}
+/**
+ * Resolve the real git hooks directory for `cwd` via `git rev-parse
+ * --git-path hooks` — never a literal `.git/hooks` join (#3588 row 8: a
+ * linked worktree or submodule's `.git` is a FILE pointing elsewhere, and
+ * this is the one git-native call that already resolves that correctly).
+ */
+function resolveCommitDocsGuardHooksDir(cwd) {
+    const gitDirResult = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--git-dir'], { cwd });
+    if (gitDirResult.exitCode !== 0) {
+        return { ok: false, reason: 'not_a_git_repo' };
+    }
+    const hooksPathResult = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--git-path', 'hooks'], { cwd });
+    if (hooksPathResult.exitCode !== 0) {
+        return { ok: false, reason: 'not_a_git_repo' };
+    }
+    const hooksDirRaw = hooksPathResult.stdout.trim();
+    const hooksDir = node_path_1.default.isAbsolute(hooksDirRaw) ? hooksDirRaw : node_path_1.default.join(cwd, hooksDirRaw);
+    return { ok: true, dir: hooksDir };
+}
+/** Marker presence, not byte-equality (#3588 row B10). */
+function isCommitDocsGuardHook(content) {
+    return content.includes(COMMIT_DOCS_GUARD_MARKER);
+}
+/**
+ * `gsd-tools commit-docs-guard enable` — write `.git/hooks/pre-commit`.
+ * Behavior table (40-design.md rows 1-3, 8-9): refuses to clobber a foreign
+ * hook, refuses when `core.hooksPath` would make our own write inert, and is
+ * idempotent when already enabled.
+ */
+function cmdCommitDocsGuardEnable(cwd, raw) {
+    const hooksDir = resolveCommitDocsGuardHooksDir(cwd);
+    if (!hooksDir.ok || !hooksDir.dir) {
+        error('not a git repository (or any of the parent directories)', ERROR_REASON.COMMIT_DOCS_GUARD_NOT_A_REPO);
+        return;
+    }
+    // core.hooksPath already set: our .git/hooks/pre-commit would be inert —
+    // git would never invoke it. Silently writing an ignored file is worse
+    // than refusing (design row 9).
+    const hooksPathConfig = (0, shell_command_projection_cjs_1.execGit)(['config', '--get', 'core.hooksPath'], { cwd });
+    if (hooksPathConfig.exitCode === 0 && hooksPathConfig.stdout.trim() !== '') {
+        const configuredPath = hooksPathConfig.stdout.trim();
+        error(`core.hooksPath is set to "${configuredPath}"; a hook written to ${node_path_1.default.join(hooksDir.dir, 'pre-commit')} ` +
+            `would never run. Wire commit-docs-guard into "${configuredPath}" manually, or unset core.hooksPath first.`, ERROR_REASON.COMMIT_DOCS_GUARD_HOOKS_PATH_SET);
+        return;
+    }
+    const hookPath = node_path_1.default.join(hooksDir.dir, 'pre-commit');
+    const existing = (0, shell_command_projection_cjs_1.platformReadSync)(hookPath);
+    if (existing !== null) {
+        if (!isCommitDocsGuardHook(existing)) {
+            error(`refusing to overwrite an existing pre-commit hook at ${hookPath} that GSD did not write. ` +
+                `Remove or rename it, or wire commit-docs-guard into it by hand.`, ERROR_REASON.COMMIT_DOCS_GUARD_FOREIGN_HOOK);
+        }
+        // Already ours — idempotent no-op (row 3). Leave any user edits intact;
+        // just make sure the executable bit survived.
+        try {
+            node_fs_1.default.chmodSync(hookPath, 0o755);
+        }
+        catch { /* best-effort */ }
+        output({ enabled: true, action: 'already_enabled', path: hookPath }, raw, 'already_enabled');
+        return;
+    }
+    (0, shell_command_projection_cjs_1.platformWriteSync)(hookPath, buildCommitDocsGuardHookScript());
+    node_fs_1.default.chmodSync(hookPath, 0o755);
+    output({ enabled: true, action: 'written', path: hookPath }, raw, 'enabled');
+}
+/**
+ * `gsd-tools commit-docs-guard disable` — remove `.git/hooks/pre-commit`
+ * ONLY when it is the hook we wrote (marker presence). Never deletes a
+ * foreign hook (design row 5); a missing hook is a no-op success, not an
+ * error (row 6).
+ */
+function cmdCommitDocsGuardDisable(cwd, raw) {
+    const hooksDir = resolveCommitDocsGuardHooksDir(cwd);
+    if (!hooksDir.ok || !hooksDir.dir) {
+        error('not a git repository (or any of the parent directories)', ERROR_REASON.COMMIT_DOCS_GUARD_NOT_A_REPO);
+        return;
+    }
+    const hookPath = node_path_1.default.join(hooksDir.dir, 'pre-commit');
+    const existing = (0, shell_command_projection_cjs_1.platformReadSync)(hookPath);
+    if (existing === null) {
+        output({ disabled: true, action: 'noop', path: hookPath }, raw, 'noop');
+        return;
+    }
+    if (!isCommitDocsGuardHook(existing)) {
+        error(`refusing to remove the pre-commit hook at ${hookPath}: it does not carry the ` +
+            `${COMMIT_DOCS_GUARD_MARKER} marker, so GSD did not write it.`, ERROR_REASON.COMMIT_DOCS_GUARD_FOREIGN_HOOK);
+    }
+    node_fs_1.default.unlinkSync(hookPath);
+    output({ disabled: true, action: 'removed', path: hookPath }, raw, 'disabled');
+}
 module.exports = {
     groupFilesBySubrepo,
     determinePhaseStatus,
@@ -1824,6 +2880,10 @@ module.exports = {
     cmdResolveGranularity,
     cmdResolveExecution,
     cmdEffortSync,
+    detectPhaseNumberFromFiles,
+    resolvePhaseCommitDocsOverride,
+    resolveCommitDocsPolicy,
+    COMMIT_DOCS_SKIP_REASON,
     cmdCommit,
     cmdCommitToSubrepo,
     cmdPrSubrepo,
@@ -1835,5 +2895,9 @@ module.exports = {
     cmdScaffold,
     cmdStats,
     cmdCheckCommit,
+    COMMIT_DOCS_GUARD_MARKER,
+    buildCommitDocsGuardHookScript,
+    cmdCommitDocsGuardEnable,
+    cmdCommitDocsGuardDisable,
     _wsParseRetryAfter,
 };