@opengsd/gsd-core 1.9.1 → 1.11.0

package/gsd-core/bin/lib/runtime-hooks-surface.cjs

@@ -21,13 +21,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
  * BEHAVIOR-PRESERVING RELOCATION: all logic is copied verbatim from
  * bin/install.js. No behavior change, no descriptor reads, no new IO.
  *
- * bin/install.js re-exports every symbol from this module so existing
- * consumers that do require('../bin/install.js').writeCursorHooksJson
- * (etc.) continue to work unchanged.
+ * #2876 (epic #2866 Phase 7): bin/install.js previously re-exported every
+ * symbol from this module, but a repo-wide audit found zero production
+ * consumers of those re-exports — no `require('../bin/install.js').
+ * writeCursorHooksJson` (or any sibling) exists outside a doc comment
+ * anywhere in the tree. The re-exports were test-suite-only pass-throughs;
+ * tests now require this module directly instead.
  */
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
+// #2544: the single source of truth for the CommonJS module-type marker. The
+// two helpers below are thin boolean-returning shims over these — see the
+// marker section for why this file no longer carries its own copy.
+const commonjs_marker_cjs_1 = require("./commonjs-marker.cjs");
 const imperative_hook_bus_cjs_1 = require("./host-integration-adapters/imperative-hook-bus.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const shellCmdProjection = require("./shell-command-projection.cjs");
@@ -166,62 +173,51 @@ function atomicWriteFileSync(target, data, options) {
 //
 // The marker content is byte-identical to installSharedHooksBundle's
 // (bin/install.js installSharedHooksBundle): {"type":"commonjs"}\n.
+//
+// #2544: the two helpers below no longer carry their own copy of the write and
+// remove rules — they DELEGATE to src/commonjs-marker.cts, which #2544 makes the
+// single place both rules are enforced. Keeping a second copy here was not
+// merely redundant; the copies had drifted apart on exactly the two properties
+// that matter:
+//
+//   - ownership probe: `fs.existsSync` FOLLOWS symlinks and reports `false` for
+//     a DANGLING one, so a dangling `package.json` symlink classified as absent
+//     and the write below followed the link outside the directory GSD owns.
+//     `classifyMarker` uses `lstat` + `isFile()`, so a symlink or a directory at
+//     the marker path is classified `foreign` and left strictly alone.
+//   - create: a plain `writeFileSync` leaves the classify->write window open.
+//     `ensureCommonJsMarker` creates with `flag: 'wx'` (O_EXCL), so anything
+//     that appears at the path in between fails with EEXIST instead of being
+//     followed or overwritten.
+//
+// The exported signatures are unchanged (both still return a boolean), so every
+// caller and the #2717 tests are unaffected.
 // ---------------------------------------------------------------------------
-/** The exact marker content GSD writes, matching installSharedHooksBundle. */
-const COMMONJS_MARKER_CONTENT = '{"type":"commonjs"}\n';
 /**
  * Ensure a `package.json` forcing CommonJS mode exists in `dir` (the directory
  * holding GSD-staged `.js` hook scripts). Idempotent: a no-op if the marker is
- * already present with GSD's content. Overwrites only when the file is absent
- * or already carries GSD's exact marker — it never clobbers a distinct
- * user-authored package.json (it leaves such a file in place; the user owns it).
+ * already present with GSD's content. Never clobbers a distinct user-authored
+ * package.json (it leaves such a file in place; the user owns it).
  *
  * @param dir - absolute path to the directory holding the staged .js hooks
- * @returns `true` if the marker is present after the call (written or already there)
+ * @returns `true` if GSD's marker is present after the call (written or already there)
  */
 function ensureCommonJsMarker(dir) {
-    const markerPath = node_path_1.default.join(dir, 'package.json');
-    try {
-        if (node_fs_1.default.existsSync(markerPath)) {
-            const existing = node_fs_1.default.readFileSync(markerPath, 'utf8');
-            // Already GSD's marker (tolerant of trailing-whitespace variants) — done.
-            if (existing.trim() === '{"type":"commonjs"}')
-                return true;
-            // A distinct package.json the user owns — do NOT clobber. The hook will
-            // load as whatever type the user declared; that is the user's choice.
-            return false;
-        }
-        node_fs_1.default.writeFileSync(markerPath, COMMONJS_MARKER_CONTENT);
-        return true;
-    }
-    catch {
-        // Best-effort: a marker write failure must not fail the whole install.
-        return false;
-    }
+    // 'written' | 'unchanged' -> the marker is ours and present.
+    // 'preserved-foreign'     -> a file GSD does not own is there; left untouched.
+    // 'failed'                -> environmental (EACCES/EROFS/ENOSPC); best-effort.
+    const outcome = (0, commonjs_marker_cjs_1.ensureCommonJsMarker)(dir);
+    return outcome === 'written' || outcome === 'unchanged';
 }
 /**
  * Remove the CommonJS marker from `dir` on uninstall — but ONLY if it carries
  * GSD's exact marker content. A user-authored package.json is never deleted.
- * Mirrors the kimi uninstall guard in bin/install.js.
  *
  * @param dir - absolute path to the directory that held the staged .js hooks
  * @returns `true` if a GSD-owned marker was removed
  */
 function removeCommonJsMarkerIfGsdOwned(dir) {
-    const markerPath = node_path_1.default.join(dir, 'package.json');
-    try {
-        if (!node_fs_1.default.existsSync(markerPath))
-            return false;
-        const content = node_fs_1.default.readFileSync(markerPath, 'utf8').trim();
-        if (content === '{"type":"commonjs"}') {
-            node_fs_1.default.unlinkSync(markerPath);
-            return true;
-        }
-        return false;
-    }
-    catch {
-        return false;
-    }
+    return (0, commonjs_marker_cjs_1.removeCommonJsMarker)(dir);
 }
 // ---------------------------------------------------------------------------
 // parseTomlValue + findMultilineBasicStringClose
@@ -495,6 +491,98 @@ function rewriteLegacyManagedNodeHookCommands(settings, absoluteRunner, opts) {
     }
     return changed;
 }
+// ---------------------------------------------------------------------------
+// Shared: reconcileManagedShellHookCommands (#3329)
+// ---------------------------------------------------------------------------
+/**
+ * Rewrite already-registered managed `.sh` hook `command` strings to the shape
+ * the current installer would generate (#3329).
+ *
+ * applySettingsJsonHooks registers the four `.sh` managed hooks only-if-absent,
+ * so an entry registered by an older installer keeps its old command forever —
+ * `/gsd-update` (which re-invokes the installer) never re-derived it. On
+ * Claude/win32 that left the pre-#580/#3393 bash-runner-prefixed commands
+ * (`bash "<script>.sh"`, `"<git>/bash.exe" "<script>.sh"`) in place, spawning a
+ * nested bash on every hook fire. The #2979 rewriter above cannot help: it is
+ * Node-only by design (its basename gate contains only `.js` filenames).
+ *
+ * Scoping / safety:
+ * - Inert unless `shellHookOmitsBashRunner({ platform, runtime, isShellHook:
+ *   true })` — the exact combination whose correct command shape changed. Where
+ *   the bash runner is still correct (non-Windows, non-claude), nothing is
+ *   rewritten, so the reconcile cannot churn unrelated installs.
+ * - Only entries whose parsed script token's basename exactly equals one of the
+ *   expected managed `.sh` filenames are touched. A user hook would have to
+ *   live at a path ending in exactly `gsd-session-state.sh` etc. — i.e. the
+ *   GSD-installed file — to match. Extra-token commands (env prefixes, extra
+ *   args) and args-form launcher entries (#976) never match the strict
+ *   `[runner ]<script>` two-token shape and are left alone.
+ * - A null/empty expected command disables rewriting for that hook (a
+ *   bash-runner-unavailable install must not have its entry nulled).
+ *
+ * @param settings settings.json-shaped object; mutated in place
+ * @param expected map of managed `.sh` filename → the command this install
+ *   would register today (from buildHookCommand / buildLocalShellHookCommand)
+ * @param opts platform/runtime override (default: current process)
+ * @returns true when any command was rewritten
+ */
+function reconcileManagedShellHookCommands(settings, expected, opts) {
+    if (!settings || !settings.hooks || !expected)
+        return false;
+    if (!opts)
+        opts = {};
+    const platform = opts.platform || process.platform;
+    const runtime = opts.runtime || 'generic';
+    if (!shellHookOmitsBashRunner({ platform, runtime, isShellHook: true }))
+        return false;
+    const expectedByBasename = new Map();
+    for (const [hookFile, command] of Object.entries(expected)) {
+        if (typeof command === 'string' && command.length > 0) {
+            expectedByBasename.set(hookFile, command);
+        }
+    }
+    if (expectedByBasename.size === 0)
+        return false;
+    let changed = false;
+    for (const entries of Object.values(settings.hooks)) {
+        if (!Array.isArray(entries))
+            continue;
+        for (const entry of entries) {
+            if (!entry || !Array.isArray(entry.hooks))
+                continue;
+            for (const h of entry.hooks) {
+                if (!h || typeof h.command !== 'string')
+                    continue;
+                if (Array.isArray(h.args) && h.args.length > 0)
+                    continue;
+                let trimmed = h.command.trim();
+                const hadPowerShellCallOperator = platform === 'win32' && /^&\s+/.test(trimmed);
+                if (hadPowerShellCallOperator) {
+                    trimmed = trimmed.replace(/^&\s+/, '').trim();
+                }
+                // Strict `[runner ]<script>` shape: an optional single runner token
+                // (bare, 'single-quoted', or "double-quoted") followed by the script
+                // token. Anything else (env prefixes, extra flags, pipelines) does not
+                // match and is left untouched.
+                const m = trimmed.match(/^(?:(?:"([^"]+)"|'([^']+)'|(\S+))\s+)?(?:"([^"]+)"|'([^']+)'|(\S+))\s*$/);
+                if (!m)
+                    continue;
+                const scriptToken = m[4] || m[5] || m[6] || '';
+                if (!scriptToken)
+                    continue;
+                const basename = shellCmdProjection.posixNormalize(scriptToken).split('/').pop() || '';
+                const expectedCommand = expectedByBasename.get(basename);
+                if (!expectedCommand)
+                    continue;
+                if (h.command === expectedCommand)
+                    continue;
+                h.command = expectedCommand;
+                changed = true;
+            }
+        }
+    }
+    return changed;
+}
 function buildCodexHookBlock(targetDir, opts) {
     const absoluteRunner = opts && opts.absoluteRunner;
     if (!absoluteRunner)
@@ -1072,7 +1160,15 @@ function writeCursorHooksJson(targetDir, src, opts) {
     // installSharedHooksBundle (the only other writer of this marker); without
     // it, a ~/.cursor/package.json declaring {"type":"module"} makes Node load
     // these require()-using scripts as ESM and every Cursor hook fails silently.
-    ensureCommonJsMarker(hooksDir);
+    //
+    // #2544: gated on having actually staged a script, mirroring
+    // installSharedHooksBundle's `stagedHooks` gate. hooks/ is shared space, and
+    // this function mkdirs it unconditionally — so an ungated write drops a GSD
+    // marker into a directory GSD created but did not fill, which is the same
+    // write-into-someone-else's-territory this issue is about.
+    if (installedScripts.size > 0) {
+        ensureCommonJsMarker(hooksDir);
+    }
     const hookOpts = { runtime: 'cursor', platform: opts.platform || process.platform };
     const commands = {};
     for (const ev of events) {
@@ -1266,7 +1362,12 @@ function writeWindsurfHooksJson(targetDir, src, opts) {
     // installSharedHooksBundle (the only other writer of this marker); without
     // it, a config-root package.json declaring {"type":"module"} makes Node load
     // these require()-using scripts as ESM and the Windsurf hooks fail silently.
-    ensureCommonJsMarker(hooksDir);
+    //
+    // #2544: gated on having actually staged a script — see the identical gate in
+    // the Cursor writer above and `stagedHooks` in installSharedHooksBundle.
+    if (installedScripts.size > 0) {
+        ensureCommonJsMarker(hooksDir);
+    }
     const hookOpts = { runtime: 'windsurf', platform: opts.platform || process.platform };
     const commands = {};
     for (const ev of WINDSURF_HOOK_EVENTS) {
@@ -1597,6 +1698,63 @@ function applySettingsJsonHooks(settings, opts) {
         else if (!hasWorktreePathGuardHook && !node_fs_1.default.existsSync(worktreePathGuardFile)) {
             console.warn(`  ${yellow}⚠${reset}  Skipped worktree path guard hook — gsd-worktree-path-guard.js not found at target`);
         }
+        // Configure PreToolUse hook for Agent-dispatch isolation (#3045)
+        // Hard-blocks an executor Agent() dispatch (subagent_type="gsd-executor")
+        // missing its harness isolation parameter when this project's resolved
+        // dispatch isolation is harness-worktree. Prevents the executor from
+        // silently running and committing in the primary checkout when the
+        // model-authored dispatch omits isolation="worktree".
+        const agentIsolationGuardCommand = isGlobal
+            ? buildHookCommand(targetDir, 'gsd-agent-isolation-guard.js', hookOpts)
+            : localCmd('gsd-agent-isolation-guard.js');
+        const hasAgentIsolationGuardHook = settings.hooks[preToolEvent].some((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-agent-isolation-guard')));
+        const agentIsolationGuardFile = node_path_1.default.join(targetDir, 'hooks', 'gsd-agent-isolation-guard.js');
+        if (!hasAgentIsolationGuardHook && node_fs_1.default.existsSync(agentIsolationGuardFile) && agentIsolationGuardCommand) {
+            settings.hooks[preToolEvent].push({
+                // #3045 MAJOR 1: widened from "Agent"-only — hooks.json's own
+                // PostToolUse precedent (context-monitor) already hedges both names,
+                // and the hook itself now accepts tool_name "Task" too.
+                matcher: 'Agent|Task',
+                hooks: [
+                    {
+                        type: 'command',
+                        command: agentIsolationGuardCommand,
+                        timeout: 5
+                    }
+                ]
+            });
+            console.log(`  ${green}✓${reset} Configured agent isolation dispatch guard hook`);
+        }
+        else if (!hasAgentIsolationGuardHook && !node_fs_1.default.existsSync(agentIsolationGuardFile)) {
+            console.warn(`  ${yellow}⚠${reset}  Skipped agent isolation guard hook — gsd-agent-isolation-guard.js not found at target`);
+        }
+        // Configure PreToolUse hook for catastrophic-shrink protection (#2255, fix 3 of #973)
+        // Hard-blocks a whole-file Write that collapses a curated .planning/ artifact
+        // (ROADMAP.md, milestone roadmaps, STATE.md) far below its on-disk size.
+        // Escape hatches (both named in the block message): the single-use
+        // sentinel .planning/.gsd-allow-shrink (workflow steps — a per-step env
+        // cannot reach a hook) and GSD_ALLOW_PLANNING_SHRINK=1 (interactive).
+        const writeGuardCommand = isGlobal
+            ? buildHookCommand(targetDir, 'gsd-write-guard.js', hookOpts)
+            : localCmd('gsd-write-guard.js');
+        const hasWriteGuardHook = settings.hooks[preToolEvent].some((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-write-guard')));
+        const writeGuardFile = node_path_1.default.join(targetDir, 'hooks', 'gsd-write-guard.js');
+        if (!hasWriteGuardHook && node_fs_1.default.existsSync(writeGuardFile) && writeGuardCommand) {
+            settings.hooks[preToolEvent].push({
+                matcher: 'Write',
+                hooks: [
+                    {
+                        type: 'command',
+                        command: writeGuardCommand,
+                        timeout: 5
+                    }
+                ]
+            });
+            console.log(`  ${green}✓${reset} Configured write guard hook (catastrophic-shrink protection)`);
+        }
+        else if (!hasWriteGuardHook && !node_fs_1.default.existsSync(writeGuardFile)) {
+            console.warn(`  ${yellow}⚠${reset}  Skipped write guard hook — gsd-write-guard.js not found at target`);
+        }
         // Configure commit validation hook (Conventional Commits enforcement, opt-in)
         const validateCommitCommand = isGlobal
             ? buildHookCommand(targetDir, 'gsd-validate-commit.sh', hookOpts)
@@ -1701,6 +1859,22 @@ function applySettingsJsonHooks(settings, opts) {
         else if (!hasPhaseBoundaryHook && !phaseBoundaryCommand) {
             console.warn(`  ${yellow}⚠${reset}  Skipped phase boundary hook — Bash executable path unavailable (#3393)`);
         }
+        // #3329: the four `.sh` sites above register only-if-absent, so an entry
+        // registered by an older installer keeps its old command forever —
+        // /gsd-update (which re-invokes the installer) never re-derived it. On
+        // Claude/win32 that left the pre-#580/#3393 bash-runner-prefixed commands
+        // in settings.json indefinitely. Reconcile existing managed `.sh` entries
+        // to the command this install would generate today. Inert wherever the
+        // bash runner is still the correct shape; scoped to exact managed
+        // basenames so user-authored hooks are never touched.
+        if (reconcileManagedShellHookCommands(settings, {
+            'gsd-validate-commit.sh': validateCommitCommand,
+            'gsd-graphify-update.sh': graphifyUpdateCommand,
+            'gsd-session-state.sh': sessionStateCommand,
+            'gsd-phase-boundary.sh': phaseBoundaryCommand,
+        }, { platform: hookOpts.platform, runtime })) {
+            console.log(`  ${green}✓${reset} Reconciled managed .sh hook commands to current format (#3329)`);
+        }
         // ── Extended hook events: SubagentStop / Stop / PreCompact / SubagentStart
         //    (#788 + #770 + #2092) ────────────────────────────────────────────────
         // Claude Code (since #770) and Qwen Code (since #788) both support the
@@ -1925,6 +2099,7 @@ function buildKimiHooksTomlBlock(targetDir, opts) {
         { event: 'PreToolUse', command: cmd('gsd-prompt-guard.js'), matcher: 'WriteFile|StrReplaceFile', timeout: 5 },
         { event: 'PreToolUse', command: cmd('gsd-read-guard.js'), matcher: 'WriteFile|StrReplaceFile', timeout: 5 },
         { event: 'PreToolUse', command: cmd('gsd-worktree-path-guard.js'), matcher: 'WriteFile|StrReplaceFile', timeout: 5 },
+        { event: 'PreToolUse', command: cmd('gsd-write-guard.js'), matcher: 'WriteFile', timeout: 5 },
         { event: 'PreToolUse', command: cmd('gsd-workflow-guard.js'), matcher: 'Shell|WriteFile|StrReplaceFile', timeout: 5 },
         { event: 'PreToolUse', command: cmd('gsd-validate-commit.sh'), matcher: 'Shell', timeout: 5 },
         // PostToolUse
@@ -2131,6 +2306,7 @@ module.exports = {
     applySettingsJsonHooks,
     referencesHook,
     rewriteLegacyManagedNodeHookCommands,
+    reconcileManagedShellHookCommands,
     normalizeNodePath,
     resolveNodeRunner,
     resolveBashRunner,

package/gsd-core/bin/lib/runtime-name-policy.cjs

@@ -193,7 +193,9 @@ exports.NO_LOCAL_CONFIG_DIR_SENTINEL = '(no-local-config-dir)';
  * Pure runtime-identity projection. Relocated from `bin/install.js` per
  * ADR-1508 (epic #1507, #1510 Phase 1) so the Runtime Artifact Conversion
  * Module's rewrite engine can consume it without importing the installer.
- * `bin/install.js` re-exports this same function for back-compat.
+ * Consumers import it from here. `bin/install.js` used to re-export it for
+ * back-compat; that re-export was retired in #2876, once an audit found the
+ * compatibility spine had no production consumer at all.
  */
 function getDirName(runtime) {
     if (!runtime)

package/gsd-core/bin/lib/runtime-slash.cjs

@@ -29,6 +29,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatGsdSlash = formatGsdSlash;
+exports.resolveExplicitRuntime = resolveExplicitRuntime;
 exports.resolveRuntime = resolveRuntime;
 exports.formatGsdSlashFor = formatGsdSlashFor;
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -75,19 +76,21 @@ function formatGsdSlash(commandName, runtime) {
     return `/gsd-${token}${tail}`;
 }
 /**
- * Resolve the effective runtime for a project directory.
+ * Resolve the explicit runtime for a project directory, from the two
+ * explicit sources only — no default is applied.
  *
- *   process.env.GSD_RUNTIME  >  config.runtime  >  'claude'
+ *   env.GSD_RUNTIME  >  config.runtime  >  null
  *
- * Mirrors the precedence already used by profile-output.cjs and the rest of
- * the runtime resolution chain. Returns a lowercased string so downstream
- * comparisons can be case-blind.
+ * Returns null when neither explicit source is set, so a caller can
+ * distinguish "config said claude" from "nothing was set" (needed by
+ * #3245's host-detection rung, which must only run when this returns null).
  *
  * @param projectDir - path to the project directory, or null/undefined
- * @returns the resolved runtime name
+ * @param env - environment variables to read GSD_RUNTIME from; defaults to process.env
+ * @returns the resolved runtime name, or null if neither source is set
  */
-function resolveRuntime(projectDir) {
-    const envRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(process.env['GSD_RUNTIME']);
+function resolveExplicitRuntime(projectDir, env = process.env) {
+    const envRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(env['GSD_RUNTIME']);
     if (envRuntime)
         return envRuntime;
     if (projectDir) {
@@ -113,7 +116,22 @@ function resolveRuntime(projectDir) {
             // runtime output formatting.
         }
     }
-    return 'claude';
+    return null;
+}
+/**
+ * Resolve the effective runtime for a project directory.
+ *
+ *   process.env.GSD_RUNTIME  >  config.runtime  >  'claude'
+ *
+ * Mirrors the precedence already used by profile-output.cjs and the rest of
+ * the runtime resolution chain. Returns a lowercased string so downstream
+ * comparisons can be case-blind.
+ *
+ * @param projectDir - path to the project directory, or null/undefined
+ * @returns the resolved runtime name
+ */
+function resolveRuntime(projectDir) {
+    return resolveExplicitRuntime(projectDir) ?? 'claude';
 }
 /**
  * Convenience: format using the runtime resolved from a project directory.

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 };
+}