@opengsd/gsd-core 1.9.0 → 1.10.0

package/gsd-core/bin/lib/section-manifest.cjs

@@ -0,0 +1,209 @@
+"use strict";
+/**
+ * Section Manifest — pure `when=` evaluator over `InvocationFacts`, mapping
+ * a document-order list of parsed `<!-- gsd:section -->` sections (Phase 3,
+ * `src/workflow-fragments.cts`) to an included/excluded partition for one
+ * concrete invocation (ADR-1671 epic #1671, Phase 5 / issue #2932,
+ * `.gsd/phase/chore-2932-init-section-manifest/40-design.md`).
+ *
+ * Pure module: no I/O, no dependency beyond node built-ins and the sibling
+ * compiled module `workflow-fragments.cjs`, whose {@link
+ * workflowFragments.WHEN_VOCABULARY} is imported and never redeclared here
+ * (DEFECT.GENERATIVE-FIX — a second frozen copy of the same 4 strings would
+ * silently desync from the source of truth the moment either side is edited
+ * without the other).
+ *
+ * ## The evaluator is a LOOKUP, not a parser
+ *
+ * Derived from Greenspun's Tenth Rule (ADR-1671:69 cites it by name) and
+ * binding on this implementation: `when=` is a closed vocabulary, widened
+ * from 4 to 14 entries via the ADR-1671 amendment for #2992 (epic #1671
+ * Phase 6.1; see `.gsd/phase/chore-2992-widen-when-vocabulary/
+ * 40-design.md`), then from 14 to 19 via the ADR-1671 amendment for #2993
+ * (epic #1671 Phase 6.2; see `.gsd/phase/chore-2993-fragmentize-plan-phase/
+ * 40-design.md`), then from 19 to 20 via the ADR-1671 amendment for #2994
+ * (epic #1671 Phase 6.3), then from 20 to 23 via a further #2994 amendment
+ * fragmentizing `code-review.md` and `complete-milestone.md`, then from 23
+ * to 24 via a still further #2994 amendment fragmentizing `autonomous.md`,
+ * then from 24 to 26 via a still further #2994 amendment fragmentizing
+ * `review.md` and `discuss-phase-assumptions.md`, then from 26 to 30 — and
+ * finally to 29, `flag:--full` having been retired as dead vocabulary — via the
+ * final #2994 slice fragmentizing `docs-update.md`, `update.md`,
+ * `transition.md`, and `new-milestone.md`.
+ * {@link WHEN_PREDICATES} is a total map from each frozen
+ * vocabulary entry to exactly one predicate over {@link InvocationFacts}.
+ * It MUST NOT tokenize, split on operators, or interpret structure in the
+ * `when=` string — the moment it parses, the ad-hoc language has begun.
+ * Every entry below is therefore a HAND-WRITTEN LITERAL: deriving a
+ * predicate's flag/state name from its atom string (e.g. slicing `--fix`
+ * out of `'flag:--fix'`) is tokenization relocated into this map and is
+ * forbidden even though it would be shorter — the redundancy between each
+ * key and its literal token is deliberate, and the bidirectional parity
+ * test below catches any desync a hand-written entry could introduce. An
+ * unrecognized `when=` value fails closed via {@link selectSections}
+ * throwing a `TypeError` carrying `.reason = REASON.UNKNOWN_WHEN`; it is
+ * never silently excluded (Postel's Law: liberal on FORMAT elsewhere in the
+ * pipeline, strict on this SEMANTIC boundary — matching the discipline
+ * Phase 3 already established for the same vocabulary at parse time).
+ *
+ * ## Totality over facts
+ *
+ * Every predicate treats an absent/missing fact key as falsy WITHOUT
+ * throwing — {@link InvocationFacts} is a plain data object handed in by a
+ * caller (the init CLI seam) that may not always populate every field, and
+ * this module must never surprise that caller with an exception for an
+ * omission rather than a malformed `when=` value.
+ *
+ * ## Partition invariant
+ *
+ * {@link selectSections} returns `included` and `excluded` id arrays that
+ * together contain every input section's `id` exactly once, in the SAME
+ * relative document order they appeared in the input — never mutating the
+ * input array or its elements.
+ *
+ * ADR-457 build-at-publish: compiled by tsc to
+ * gsd-core/bin/lib/section-manifest.cjs (gitignored).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WHEN_PREDICATES = exports.REASON = void 0;
+exports.selectSections = selectSections;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- workflow-fragments.cjs is a CommonJS module compiled from a sibling .cts source; `import x = require()` reads its module.exports namespace directly.
+const workflowFragments = require("./workflow-fragments.cjs");
+/**
+ * Frozen, stable reason codes for every `fail()` throw site in this module.
+ * Tests assert via `assert.equal(err.reason, REASON.X)` rather than
+ * regex-/substring-matching the human-readable message (CONTRIBUTING.md
+ * "Prohibited: Raw Text Matching on Test Outputs"; shape copied from
+ * `src/workflow-fragments.cts`'s own `REASON` export) — a message reword
+ * must never silently pass a test that exists to catch a behavior
+ * regression.
+ *
+ * Adding a new reason requires updating this map AND the test that locks
+ * `Object.keys(REASON).sort()` as a coordinated change.
+ */
+exports.REASON = Object.freeze({
+    UNKNOWN_WHEN: 'unknown_when',
+});
+/**
+ * Throws a `TypeError` naming the offending `when` value, carrying `reason`
+ * (one of {@link REASON}) as a typed property so callers/tests never need
+ * to pattern-match the message prose.
+ */
+function fail(reason, message) {
+    const err = new TypeError(`section-manifest: ${message}`);
+    err.reason = reason;
+    throw err;
+}
+/**
+ * Safely tests whether `facts.flags` contains `flag`, tolerating an absent,
+ * `null`, or non-`Set` (e.g. array) `flags` value without throwing —
+ * `.has` is checked to be callable before it is called, rather than
+ * assuming every {@link InvocationFacts.flags} is a real `Set` (totality
+ * over facts; not duck-typed — an array `flags` degrades to "not present",
+ * it is never iterated or `.includes`-checked).
+ */
+function hasFlag(facts, flag) {
+    return typeof facts.flags?.has === 'function' && facts.flags.has(flag) === true;
+}
+/**
+ * Total map from each frozen {@link workflowFragments.WHEN_VOCABULARY}
+ * entry to exactly one predicate over {@link InvocationFacts}. This is a
+ * LOOKUP, never a parser — see the module doc comment's "The evaluator is a
+ * LOOKUP, not a parser" section. Every entry is a hand-written literal; see
+ * the module doc comment for why deriving a predicate from its atom string
+ * is forbidden. Semantics confirmed against the section bodies themselves
+ * (design doc "Semantics confirmed against the section bodies themselves,
+ * not inferred from the id"):
+ *
+ * - `gap-closure-artifacts` — "For decimal/polish phases only (X.Y
+ *   pattern) … Skip if phase number has no decimal" -> `state:gap-closure-phase`.
+ * - `regression-gate` — "Skip if: this is the first phase (no prior
+ *   phases)" -> `state:has-prior-phases`.
+ * - `partial-wave` — "If `WAVE_FILTER` was used" -> `flag:--wave`.
+ */
+exports.WHEN_PREDICATES = Object.freeze(Object.assign(Object.create(null), {
+    always: () => true,
+    'flag:--wave': (facts) => hasFlag(facts, '--wave'),
+    'state:gap-closure-phase': (facts) => typeof facts.phaseNumber === 'string' && facts.phaseNumber.includes('.'),
+    'state:has-prior-phases': (facts) => facts.hasPriorPhases === true,
+    'flag:--auto': (facts) => hasFlag(facts, '--auto'),
+    'flag:--discuss': (facts) => hasFlag(facts, '--discuss'),
+    'flag:--fix': (facts) => hasFlag(facts, '--fix'),
+    'flag:--forensic': (facts) => hasFlag(facts, '--forensic'),
+    'flag:--ingest': (facts) => hasFlag(facts, '--ingest'),
+    'flag:--prd': (facts) => hasFlag(facts, '--prd'),
+    'flag:--research': (facts) => hasFlag(facts, '--research'),
+    'flag:--research-phase': (facts) => hasFlag(facts, '--research-phase'),
+    'flag:--reset-phase-numbers': (facts) => hasFlag(facts, '--reset-phase-numbers'),
+    'flag:--reviews': (facts) => hasFlag(facts, '--reviews'),
+    'flag:--validate': (facts) => hasFlag(facts, '--validate'),
+    'state:auto-advance-active': (facts) => facts.autoAdvanceActive === true,
+    'state:chunked-mode': (facts) => facts.chunkedMode === true,
+    'state:fallow-enabled': (facts) => facts.fallowEnabled === true,
+    'state:flat-mode': (facts) => facts.flatMode === true,
+    'state:git-create-tag': (facts) => facts.gitCreateTag === true,
+    'state:is-monorepo': (facts) => facts.isMonorepo === true,
+    'state:needs-codebase-map': (facts) => facts.needsCodebaseMap === true,
+    'state:next-channel': (facts) => facts.nextChannel === true,
+    'state:phase-mvp-mode': (facts) => facts.phaseMvpMode === true,
+    'state:plan-strategy-converge': (facts) => facts.planStrategyConverge === true,
+    'state:reviewer-instances-configured': (facts) => facts.reviewerInstancesConfigured === true,
+    'state:ui-phase-active': (facts) => facts.uiPhaseActive === true,
+    'state:workstream-active': (facts) => facts.workstreamActive === true,
+    'state:worktrees-enabled': (facts) => facts.worktreesEnabled === true,
+}));
+// Coordinated-change guard, checked at module load: every entry of the
+// frozen WHEN_VOCABULARY (imported, never redeclared — see module doc
+// comment) must have exactly one predicate here, and vice versa. This is
+// the load-bearing half of the DEFECT.GENERATIVE-FIX parity contract; the
+// test-level half (50-test-matrix.md rows 21-23) additionally asserts it
+// from the vocabulary's own export so a 5th vocabulary entry added without
+// a predicate fails loudly rather than silently falling through to
+// REASON.UNKNOWN_WHEN only at run time.
+for (const when of workflowFragments.WHEN_VOCABULARY) {
+    if (!Object.hasOwn(exports.WHEN_PREDICATES, when)) {
+        throw new Error(`section-manifest: WHEN_VOCABULARY entry "${when}" has no predicate in WHEN_PREDICATES`);
+    }
+}
+// Reverse half of the same coordinated-change guard: every own key of
+// WHEN_PREDICATES must also appear in WHEN_VOCABULARY. Without this, a
+// predicate key with no vocabulary entry would let the evaluator accept an
+// atom that the parser (classifyMarker) rejects — a real divergence between
+// the two shared-constant halves (DEFECT.GENERATIVE-FIX; B9/B10 in
+// `.gsd/phase/chore-2992-widen-when-vocabulary/50-test-matrix.md`).
+const VOCABULARY_SET = new Set(workflowFragments.WHEN_VOCABULARY);
+for (const predicateKey of Object.keys(exports.WHEN_PREDICATES)) {
+    if (!VOCABULARY_SET.has(predicateKey)) {
+        throw new Error(`section-manifest: WHEN_PREDICATES entry "${predicateKey}" has no matching WHEN_VOCABULARY entry`);
+    }
+}
+/**
+ * Partition `sections` (document order) into `included`/`excluded` id
+ * arrays for one set of `facts`, per {@link WHEN_PREDICATES}. Exact
+ * partition: every input id appears in exactly one of the two output
+ * arrays, in the same relative order it appeared in `sections`. Never
+ * mutates `sections` or its elements.
+ *
+ * @param sections - document-order sections carrying at least `{id, when}`
+ * @param facts - the concrete invocation's resolved facts
+ * @throws {SectionManifestError} with `.reason = REASON.UNKNOWN_WHEN` when a
+ *   section's `when` value has no entry in {@link WHEN_PREDICATES} (fail
+ *   closed — never silently excluded).
+ */
+function selectSections(sections, facts) {
+    const included = [];
+    const excluded = [];
+    for (const section of sections) {
+        if (!Object.hasOwn(exports.WHEN_PREDICATES, section.when)) {
+            fail(exports.REASON.UNKNOWN_WHEN, `section "${section.id}" has unrecognized when= value "${section.when}"`);
+        }
+        const predicate = exports.WHEN_PREDICATES[section.when];
+        if (predicate(facts)) {
+            included.push(section.id);
+        }
+        else {
+            excluded.push(section.id);
+        }
+    }
+    return { included, excluded };
+}

package/gsd-core/bin/lib/shell-command-projection.cjs

@@ -15,6 +15,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PATH_ACTION_REASON = void 0;
 exports.toPosixPath = toPosixPath;
 exports.toNativePath = toNativePath;
 exports.posixNormalize = posixNormalize;
@@ -35,9 +36,11 @@ exports.projectCodexHookTomlCommand = projectCodexHookTomlCommand;
 exports.escapePowerShellSingleQuoted = escapePowerShellSingleQuoted;
 exports.escapePosixDoubleQuoted = escapePosixDoubleQuoted;
 exports.escapeSingleQuotedShellLiteral = escapeSingleQuotedShellLiteral;
+exports.projectPathExportLine = projectPathExportLine;
 exports.renderShellActionLines = renderShellActionLines;
 exports.projectPathActionProjection = projectPathActionProjection;
 exports.projectPersistentPathExportActions = projectPersistentPathExportActions;
+exports.isSpawnTimeout = isSpawnTimeout;
 exports.execGit = execGit;
 exports.execNpm = execNpm;
 exports.execTool = execTool;
@@ -351,8 +354,34 @@ function projectLegacySettingsHookCommand({ absoluteRunner, scriptPath, scriptTo
         platform,
     });
 }
+// Implements the TOML v1.0.0 basic-string escaping grammar (toml.md, "Basic
+// strings" section, https://toml.io/en/v1.0.0#string): a basic string must
+// escape the quotation mark, backslash, and control characters other than
+// tab (U+0000-U+0008, U+000A-U+001F, U+007F). Compact escapes are used where
+// TOML defines them (\b \t \n \f \r \" \\); every other character in the
+// required ranges falls back to \uXXXX. See #3118 — an earlier version
+// escaped only backslash and quote, so a raw newline/CR/NUL in a value
+// produced an unparseable config.toml.
+const TOML_COMPACT_ESCAPES = {
+    '\x08': '\\b',
+    '\x09': '\\t',
+    '\x0A': '\\n',
+    '\x0C': '\\f',
+    '\x0D': '\\r',
+};
+// U+0000-U+0008, U+000A-U+001F, U+007F — control characters other than tab
+// (U+0009), which the grammar permits unescaped.
+const TOML_MUST_ESCAPE_CONTROL_CHARS = /[\x00-\x08\x0A-\x1F\x7F]/g;
 function escapeTomlDoubleQuotedString(value) {
-    return String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    return String(value)
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(TOML_MUST_ESCAPE_CONTROL_CHARS, (ch) => {
+        const compact = TOML_COMPACT_ESCAPES[ch];
+        if (compact)
+            return compact;
+        return `\\u${ch.codePointAt(0).toString(16).padStart(4, '0')}`;
+    });
 }
 function projectCodexHookTomlCommand({ absoluteRunner, scriptPath, platform = process.platform }) {
     const command = projectManagedHookCommand({
@@ -372,6 +401,27 @@ function escapePosixDoubleQuoted(value) {
 function escapeSingleQuotedShellLiteral(value) {
     return String(value).replace(/'/g, "'\\''");
 }
+/**
+ * The `export PATH="<dir>:$PATH"` line every persistence lane appends, plus the escaped directory
+ * token it embeds. One builder because three lanes emit this line: a lane that re-escapes it
+ * locally is how #3118 shipped a `$(…)` into ~/.bashrc, where it ran on every new shell. The
+ * escaping is for the line's FINAL context — a double-quoted string in an rc file — not for
+ * whatever transport (an `echo`, a paste) it passes through on the way there.
+ */
+function projectPathExportLine(targetDir) {
+    const escapedDir = escapePosixDoubleQuoted(String(targetDir));
+    return { escapedDir, line: `export PATH="${escapedDir}:$PATH"` };
+}
+/**
+ * Why a PATH suggestion produced no actions. An empty `shellActions` alone folds two different
+ * facts together — "no target directory was given" and "this target directory cannot be
+ * expressed as a shell command" — and a caller that cannot tell them apart prints a header with
+ * nothing under it (#3118).
+ */
+exports.PATH_ACTION_REASON = Object.freeze({
+    NO_TARGET_DIR: 'no_target_dir',
+    WIN32_RESERVED_QUOTE: 'win32_reserved_quote',
+});
 function renderShellActionLines(shellActions = []) {
     return shellActions.map((action) => {
         if (!action || !action.command)
@@ -381,12 +431,18 @@ function renderShellActionLines(shellActions = []) {
 }
 function projectPathActionProjection({ mode = 'repair', targetDir, platform = process.platform, }) {
     if (!targetDir)
-        return { shellActions: [], actionLines: [] };
+        return { shellActions: [], actionLines: [], reason: exports.PATH_ACTION_REASON.NO_TARGET_DIR };
+    // #3118: `"` is reserved on Windows, so a path containing one cannot exist — and it would close
+    // cmd's quoted region in the `powershell -Command "…"` lane below, turning the rest into cmd
+    // input. There is no correct command to suggest for an impossible path: fail closed rather than
+    // emit one whose quoting can be broken.
+    if (platform === 'win32' && String(targetDir).includes('"'))
+        return { shellActions: [], actionLines: [], reason: exports.PATH_ACTION_REASON.WIN32_RESERVED_QUOTE };
     const isWin32 = platform === 'win32';
     let shellActions;
     if (isWin32) {
         const psTargetDir = escapePowerShellSingleQuoted(targetDir);
-        const bashTargetDir = escapeSingleQuotedShellLiteral(posixNormalize(String(targetDir)));
+        const bashExportLine = escapeSingleQuotedShellLiteral(projectPathExportLine(posixNormalize(String(targetDir))).line);
         shellActions = [
             {
                 label: 'PowerShell',
@@ -401,42 +457,51 @@ function projectPathActionProjection({ mode = 'repair', targetDir, platform = pr
             {
                 label: 'Git Bash',
                 shell: 'bash',
-                command: `echo 'export PATH="${bashTargetDir}:$PATH"' >> ~/.bashrc`,
+                command: `echo '${bashExportLine}' >> ~/.bashrc`,
             },
         ];
     }
     else if (mode === 'persist') {
-        const bashTargetDir = escapeSingleQuotedShellLiteral(String(targetDir));
+        const exportLine = escapeSingleQuotedShellLiteral(projectPathExportLine(targetDir).line);
+        const fishTargetDir = escapeSingleQuotedShellLiteral(String(targetDir));
         shellActions = [
             {
                 label: 'zsh',
                 shell: 'zsh',
-                command: `echo 'export PATH="${bashTargetDir}:$PATH"' >> ~/.zshrc`,
+                command: `echo '${exportLine}' >> ~/.zshrc`,
             },
             {
                 label: 'bash',
                 shell: 'bash',
-                command: `echo 'export PATH="${bashTargetDir}:$PATH"' >> ~/.bashrc`,
+                command: `echo '${exportLine}' >> ~/.bashrc`,
             },
             // #323: fish has no `export`/`$PATH`-list syntax. `fish_add_path` is the
             // fish-native API (>= fish 3.2, 2021) that persists to the universal
             // variable store and de-duplicates. The directory is single-quoted with
             // the same POSIX literal escaping as the zsh/bash siblings — `'\''` is
             // also a valid escaped single quote in fish between quote spans.
+            //
+            // #3118 review MINOR: a `targetDir` with a leading `-` (e.g. `-v`) is a
+            // legal directory name, but fish's argparse-based option scanning
+            // treats a leading-dash token as a flag REGARDLESS of quoting, so
+            // `fish_add_path '-v'` misparses it and prints "No paths to add, not
+            // setting anything." (exit 1) instead of adding the path. `--` is
+            // fish's standard end-of-options separator; verified empirically
+            // against a real fish 4.8.1 install that `fish_add_path -- '-v'`
+            // succeeds where the unseparated form fails.
             {
                 label: 'fish',
                 shell: 'fish',
-                command: `fish_add_path '${bashTargetDir}'`,
+                command: `fish_add_path -- '${fishTargetDir}'`,
             },
         ];
     }
     else {
-        const posixTargetDir = escapePosixDoubleQuoted(targetDir);
         shellActions = [
             {
                 label: null,
                 shell: 'posix',
-                command: `export PATH="${posixTargetDir}:$PATH"`,
+                command: projectPathExportLine(targetDir).line,
             },
         ];
     }
@@ -451,18 +516,46 @@ function projectPersistentPathExportActions({ targetDir, platform = process.plat
         targetDir,
         platform,
     });
-    return { shellActions: projected.shellActions };
+    return projected.reason === undefined
+        ? { shellActions: projected.shellActions }
+        : { shellActions: projected.shellActions, reason: projected.reason };
+}
+/**
+ * Returns true when a spawn/exec result indicates the subprocess was killed
+ * by a timeout, i.e. it never completed and reported a real answer. This is
+ * the single shared definition of "did this subprocess time out" — worktree
+ * safety (src/worktree-safety.cts) and worktree base-ref detection
+ * (src/worktree-base-ref.cts) both call this instead of maintaining their
+ * own copies (#3050 — "Generative Fix Divergence").
+ *
+ * Only `error.code === 'ETIMEDOUT'` is checked. Node.js guarantees this
+ * cross-platform when `spawnSync`'s `timeout` option fires. The `signal ===
+ * 'SIGTERM'` check some earlier code paired with it is platform-fragile —
+ * Windows does not necessarily report SIGTERM the same way — and pairing it
+ * in as a REQUIRED conjunct risks a false NEGATIVE (a timeout that silently
+ * fails to trip the guard) on that platform. There is no false-positive risk
+ * from dropping it: an externally-delivered SIGTERM (not a timeout) leaves
+ * `error` null, so `error.code === 'ETIMEDOUT'` alone still won't match it.
+ */
+function isSpawnTimeout(result) {
+    return result.error?.code === 'ETIMEDOUT';
 }
 function _spawnResult(result, program) {
     if (result.error && result.error.code === 'ENOENT') {
-        return { exitCode: 127, stdout: '', stderr: `${program}: not found`, signal: null, error: result.error };
+        return { exitCode: 127, stdout: '', stderr: `${program}: not found`, signal: null, error: result.error, timedOut: false };
     }
+    const signal = result.signal ?? null;
+    const error = result.error ?? null;
     return {
         exitCode: result.status ?? 1,
         stdout: (result.stdout ?? '').toString().trim(),
         stderr: (result.stderr ?? '').toString().trim(),
-        signal: result.signal ?? null,
-        error: result.error ?? null,
+        signal,
+        error,
+        // Reuse the single shared timeout predicate (isSpawnTimeout, below) rather
+        // than re-deriving it here — see that function's docstring for why only
+        // error.code === 'ETIMEDOUT' is checked (not signal === 'SIGTERM').
+        timedOut: isSpawnTimeout({ error }),
     };
 }
 function execGit(args, opts = {}) {
@@ -549,9 +642,9 @@ function resolveGsdToolsPath() {
  * NEVER throws. Degrades to `{ ok:false, ... }` on:
  *   - a missing/invalid "family" (validated locally, no subprocess spawned)
  *   - ENOENT / a missing gsd-tools.cjs (via the injectable `gsdToolsPath`)
- *   - a wall-clock timeout (`timedOut:true`, mirroring the
- *     `signal === 'SIGTERM' && error.code === 'ETIMEDOUT'` idiom already used
- *     by worktree-safety.cts)
+ *   - a wall-clock timeout (`timedOut:true`, via the shared `isSpawnTimeout`
+ *     predicate defined above in this file — also used by worktree-safety.cts
+ *     and worktree-base-ref.cts)
  *   - any other unanticipated throw from the underlying spawn (defensive
  *     try/catch — execTool itself is spawnSync-based and does not throw).
  */
@@ -592,16 +685,9 @@ function dispatchGsdCommand({ family, subcommand, args = [], cwd, timeout = 30_0
             timedOut: false,
         };
     }
-    // Mirrors the established `result.error && (result.error as
-    // NodeJS.ErrnoException).code === ...` idiom (graphify.cts, worktree-safety.cts):
-    // narrow away null via `!== null` FIRST, then cast — asserting `Error | null`
-    // to `NodeJS.ErrnoException | null` directly (paired with optional chaining)
-    // trips a typescript-eslint no-unnecessary-type-assertion false positive for
-    // this exact narrowing shape (all of ErrnoException's extra fields over Error
-    // are optional).
-    const timedOut = result.signal === 'SIGTERM'
-        && result.error !== null
-        && result.error.code === 'ETIMEDOUT';
+    // Delegates to the single shared predicate defined above in this file
+    // (#3050 — "Generative Fix Divergence") instead of a local inline copy.
+    const timedOut = isSpawnTimeout(result);
     return {
         ok: result.exitCode === 0 && !timedOut,
         stdout: result.stdout,

package/gsd-core/bin/lib/smart-entry.cjs

@@ -61,6 +61,9 @@ const { stateExtractField } = stateDocument;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseId = require("./phase-id.cjs");
 const { comparePhaseNum, extractPhaseToken, normalizePhaseName, phaseTokenMatches } = phaseId;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const unusableInput = require("./unusable-input.cjs");
+const { warnUnusableInput, UNUSABLE_REASON } = unusableInput;
 // ─── Constants ────────────────────────────────────────────────────────────────
 /**
  * Staleness threshold for idle-stranded detection. A clean tree whose last
@@ -290,7 +293,16 @@ function detectSignals(cwd, now = Date.now) {
     // Stale = no recorded activity for IDLE_STALE_MS. Used only by idle-stranded.
     // Computed here (with the clock seam) so the pure classify() stays a function
     // of (signals, staleActivity) and detectSignals owns all disk reads.
+    // #3099 (ADR-1411 amendment): if last_activity is present but unparseable,
+    // emit a diagnostic so the silent fallback (stale_activity: false) is visible.
+    // The fallback itself stays — continuity is correct, the silence was the defect.
     const lastActivityMs = parseActivityTimestamp(lastActivityRaw);
+    if (lastActivityRaw && lastActivityMs === null) {
+        warnUnusableInput({
+            reason: UNUSABLE_REASON.LAST_ACTIVITY_UNPARSEABLE,
+            source: paths.state,
+        });
+    }
     const staleActivity = lastActivityMs !== null && now() - lastActivityMs > IDLE_STALE_MS;
     // Verify-failed may be signalled either by STATE.md status or by a failed
     // STATUS: marker on the current phase's summary/verify artifact.

package/gsd-core/bin/lib/state-transition.cjs

@@ -111,8 +111,28 @@ function applyStatePreservation(input) {
             const derived = (postFm['progress'] ?? {});
             const merged = { ...derived };
             if (curated) {
+                // #2440: total_plans and total_phases always take the derived value.
+                // #2969: completed_plans and completed_phases take the derived value
+                // when it is GREATER than the curated value (gap-closure plans that
+                // completed after the plan count grew) — ratcheting UP only, never
+                // deriving downward (preserves the #3242 curated-progress protection
+                // for cases unrelated to plan-count growth, e.g. a deleted SUMMARY).
+                // percent also takes the derived value — the resync recomputed it from
+                // disk counts, and a stale curated percent would be incoherent against
+                // the ratcheted-up completed counts (e.g. 54/54 at 93%).
+                const ratchetUpKeys = new Set(['completed_plans', 'completed_phases']);
                 for (const [key, value] of Object.entries(curated)) {
-                    if (key !== 'total_plans' && key !== 'total_phases') {
+                    if (key === 'total_plans' || key === 'total_phases' || key === 'percent')
+                        continue;
+                    if (ratchetUpKeys.has(key)) {
+                        const derivedNum = typeof derived[key] === 'number' ? derived[key] : -Infinity;
+                        const curatedNum = typeof value === 'number' ? value : -Infinity;
+                        // Take the derived value only when it ratchets up; else keep curated.
+                        if (derivedNum > curatedNum)
+                            continue;
+                        merged[key] = value;
+                    }
+                    else {
                         merged[key] = value;
                     }
                 }
@@ -339,7 +359,24 @@ function locateCurrentPosition(body) {
     let end = body.length;
     for (let j = idx + 1; j < hs.length; j++) {
         if (STOP_H2_PLUS(hs[j].level)) {
-            end = hs[j].offset - 1;
+            // Exclude the newline that separates this section from the next
+            // heading. Walk back over a bare `\n`, then over a `\r` if one
+            // immediately precedes it (CRLF), so a CRLF document's slice does not
+            // retain a stray unpaired trailing `\r` (#3118).
+            let e = hs[j].offset;
+            if (e > 0 && body[e - 1] === '\n') {
+                e -= 1;
+                if (e > 0 && body[e - 1] === '\r')
+                    e -= 1;
+            }
+            // Clamp so the span can never invert (#3118 review): when the section
+            // is empty and the next heading follows with no blank line between,
+            // walking back over the newline(s) can land `e` before `start`. An
+            // inverted span makes every mutator's `body.slice(0, start) +
+            // sectionBody + body.slice(end)` reassembly duplicate the bytes in
+            // `[end, start)`. A zero-length span (`end === start`) is the correct
+            // representation of an empty-but-present section.
+            end = Math.max(e, start);
             break;
         }
     }
@@ -744,8 +781,17 @@ function completePhaseCore(content, intent, deps) {
             if (derived.totalPhases !== null)
                 derivedTotalPhases = derived.totalPhases;
         }
+        // #3057 B9: only mark 'Completed Phases' updated when the text actually
+        // changed. `stateReplaceField` returns the full (re-)substituted content
+        // whenever the field pattern matches, REGARDLESS of whether newCompleted
+        // differs from the value already in `body` — so a truthy-only check here
+        // marked the field 'updated' even when the roadmap was unavailable and
+        // newCompleted is just completedRaw parsed back to itself. That collapsed
+        // "recomputed from roadmap" and "left as-is" into the same `updated`
+        // signal. Comparing to `body` (the idiom every other field in this
+        // function already uses) restores the distinction.
         const completedAfter = (0, state_document_cjs_1.stateReplaceField)(body, 'Completed Phases', String(newCompleted));
-        if (completedAfter) {
+        if (completedAfter !== null && completedAfter !== body) {
             body = completedAfter;
             updated.push('Completed Phases');
         }
@@ -753,8 +799,9 @@ function completePhaseCore(content, intent, deps) {
         const totalPhases = derivedTotalPhases || (totalRaw ? parseInt(totalRaw, 10) : null);
         if (totalPhases && totalPhases > 0) {
             const newPercent = (0, phase_lifecycle_cjs_1.clampPercent)(newCompleted, totalPhases);
+            // Same guard as 'Completed Phases' above, and for the same reason.
             const progAfter = (0, state_document_cjs_1.stateReplaceField)(body, 'Progress', `${newPercent}%`);
-            if (progAfter) {
+            if (progAfter !== null && progAfter !== body) {
                 body = progAfter;
                 updated.push('Progress');
             }
@@ -1352,13 +1399,14 @@ function truncateForLog(s) {
 function rebuildCore(content, _intent, deps) {
     const timestamp = deps.clock.nowIso();
     const log = [];
+    const phaseInventoryScan = { failed: false, reason: null };
     let modified = content;
     // §2 Decision: re-derive derived sections, preserve others. Order is
     // oldest-section-first so log entries appear in body order.
     // sourcePath threaded so `state rebuild --dry-run` names the file: that branch reads STATE.md
     // directly rather than through readModifyWriteStateMd, so nothing upstream has named it yet.
     modified = reconcileCurrentPosition(modified, timestamp, log, deps.sourcePath);
-    modified = reconcileByPhaseTable(modified, deps, timestamp, log);
+    modified = reconcileByPhaseTable(modified, deps, timestamp, log, phaseInventoryScan);
     modified = stripTemplatePlaceholders(modified, timestamp, log);
     modified = deduplicateSessionArchive(modified, timestamp, log);
     // §3 + §4: append the audit log ONLY when mutations occurred. The
@@ -1375,6 +1423,11 @@ function rebuildCore(content, _intent, deps) {
             mutated: log.length > 0,
             mutations: log.length,
             log,
+            // #3057 B1: distinguishable from a clean "nothing to reconcile" — a
+            // failed phase-inventory scan means the by-phase table was NOT
+            // verified against disk, even though `mutated` may still be false.
+            phase_inventory_scan_failed: phaseInventoryScan.failed,
+            ...(phaseInventoryScan.reason !== null ? { phase_inventory_scan_reason: phaseInventoryScan.reason } : {}),
         },
     };
 }
@@ -1451,12 +1504,24 @@ function reconcileCurrentPosition(content, timestamp, log, sourcePath) {
  * Leaky-Abstractions guard (ADR-1817 §1): when `phaseInventoryProvider` is
  * absent (no disk scan wired), this step is a no-op. The core stays pure and
  * testable without disk I/O.
+ *
+ * A DIFFERENT case is a scan that ran but failed (`ok:false`): that is NOT a
+ * no-op-equivalent "nothing to reconcile" — the table is left untouched (we
+ * have no trustworthy inventory to reconcile against) but the failure is
+ * recorded into `meta` so the caller (`rebuildCore`) can surface it instead
+ * of reporting a clean, fully-reconciled rebuild (#3057 B1).
  */
-function reconcileByPhaseTable(content, deps, timestamp, log) {
+function reconcileByPhaseTable(content, deps, timestamp, log, meta) {
     if (!deps.phaseInventoryProvider)
         return content;
-    const inventory = deps.phaseInventoryProvider();
-    if (!inventory || inventory.length === 0)
+    const result = deps.phaseInventoryProvider();
+    if (!result.ok) {
+        meta.failed = true;
+        meta.reason = result.reason;
+        return content; // cannot reconcile without a trustworthy inventory — leave the table as-is
+    }
+    const inventory = result.phases;
+    if (inventory.length === 0)
         return content;
     // The canonical table shape (from gsd-core/templates/state.md):
     //   | Phase | Plans | Total | Avg/Plan |