@opengsd/gsd-core 1.10.0 → 1.12.0

package/hooks/lib/git-cmd.js

@@ -19,9 +19,19 @@
  * hook's own __dirname:
  *
  *   const { isGitSubcommand } = require(path.join(__dirname, 'lib', 'git-cmd.js'));
+ *
+ * `tokenize()` delegates to the shared `src/token-scanner.cts` seam (ADR-3212
+ * §4, epic #3212 Phase 3, #3414) — the built `gsd-core/bin/lib/token-scanner.cjs`
+ * artifact, not a sibling hooks/-tree file, because hook scripts are staged as
+ * standalone files at install time and a sibling require is a staging
+ * dependency that can fail silently (see gsd-workflow-guard.js's own
+ * KIMI_TOOL_NAMES comment for the precedent this follows). Re-exported here
+ * unchanged — every existing caller's behavior is identical (parity-asserted
+ * in tests/token-scanner.test.cjs row 5).
  */
 
 const path = require('path');
+const { tokenizeShellLike } = require(path.join(__dirname, '..', '..', 'gsd-core', 'bin', 'lib', 'token-scanner.cjs'));
 
 /**
  * Git global options that take a following argument.
@@ -29,6 +39,7 @@ const path = require('path');
  */
 const ARGUMENT_TAKING_FLAGS = new Set([
   '-C',                // working directory
+  '-c',                // config override (separate-arg form: `git -c k=v …`; #3504)
   '--git-dir',         // path to git repository
   '--work-tree',       // path to working tree
   '--namespace',       // git namespace
@@ -57,94 +68,116 @@ const BOOLEAN_FLAGS = new Set([
  * Handles single-quoted strings, double-quoted strings, and unquoted tokens.
  * Does NOT perform variable expansion or brace expansion.
  *
+ * Delegates to the shared `src/token-scanner.cts` seam — see the module
+ * header comment for why the built artifact, not a sibling require, is used.
+ *
  * @param {string} cmd
  * @returns {string[]}
  */
 function tokenize(cmd) {
-  const tokens = [];
-  let i = 0;
-  const len = cmd.length;
-
-  while (i < len) {
-    // Skip whitespace
-    while (i < len && /\s/.test(cmd[i])) i++;
-    if (i >= len) break;
-
-    let token = '';
-    while (i < len && !/\s/.test(cmd[i])) {
-      if (cmd[i] === "'") {
-        // Single-quoted string: take everything until closing '
-        i++;
-        while (i < len && cmd[i] !== "'") token += cmd[i++];
-        if (i < len) i++; // consume closing '
-      } else if (cmd[i] === '"') {
-        // Double-quoted string: take everything until closing " (no escape handling)
-        i++;
-        while (i < len && cmd[i] !== '"') token += cmd[i++];
-        if (i < len) i++; // consume closing "
-      } else {
-        token += cmd[i++];
-      }
-    }
-    if (token) tokens.push(token);
-  }
-
-  return tokens;
+  return tokenizeShellLike(cmd);
 }
 
 /**
- * Return true if `cmd` invokes the git subcommand `sub`.
+ * Walk past leading env-prefix assignments and global git options, same as
+ * `isGitSubcommand`'s phases 1-3. Returns the index of the subcommand token,
+ * or -1 if the command does not resolve to a git invocation at all.
  *
- * @param {string} cmd  - Full shell command string (may include env vars, full paths)
- * @param {string} sub  - Subcommand to test for, e.g. 'commit'
- * @returns {boolean}
+ * @param {string[]} tokens
+ * @returns {number}
  */
-function isGitSubcommand(cmd, sub) {
-  if (!cmd || !sub) return false;
-
-  const tokens = tokenize(cmd);
+function skipToSubcommand(tokens) {
   let i = 0;
-
-  // Phase 1: skip leading VAR=VALUE environment assignments
   while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i])) {
     i++;
   }
-
-  // Phase 2: the next token must be the git executable
-  if (i >= tokens.length) return false;
+  if (i >= tokens.length) return -1;
   const gitToken = tokens[i++];
-  if (path.basename(gitToken) !== 'git') return false;
+  if (path.basename(gitToken) !== 'git') return -1;
 
-  // Phase 3: consume git global options
   while (i < tokens.length) {
     const t = tokens[i];
-
-    // --flag=value form for argument-taking flags
     const eqIdx = t.indexOf('=');
     const flagName = eqIdx !== -1 ? t.slice(0, eqIdx) : t;
     if (ARGUMENT_TAKING_FLAGS.has(flagName)) {
-      if (eqIdx !== -1) {
-        // consumed as one token: --git-dir=.git
-        i++;
-      } else {
-        // consumed as two tokens: -C /path
-        i += 2;
-      }
+      i += eqIdx !== -1 ? 1 : 2;
+      continue;
+    }
+    // #3504: glued `-ckey=value` form — git accepts the config override with
+    // its argument attached (`git -cfoo.bar=1 …`). The eq-slice above yields
+    // flagName `-cfoo`, which no set contains, so without this arm the walk
+    // stops and the whole invocation is misclassified as not-git.
+    if (/^-c\S*=/.test(t)) {
+      i++;
       continue;
     }
-
     if (BOOLEAN_FLAGS.has(t)) {
       i++;
       continue;
     }
-
-    // Not a global option — this is the subcommand
     break;
   }
+  return i;
+}
+
+/**
+ * Extract the branch-name argument from a git command line that creates or
+ * references one — `git checkout -b <name>` or `git branch <name>`. Returns
+ * null for any other command, including plain `git checkout <ref>` (switches
+ * branches, does not create one) and commands where a checkout/branch-shaped
+ * substring appears only inside a quoted argument (e.g. a commit message).
+ *
+ * New capability (ADR-3212 §4, epic #3212 Phase 3, #3414) exercising the
+ * shared scanner on the domain the ADR names ("a branch name... [is] not
+ * regular") — not a migration of existing duplicated logic; no prior
+ * implementation of this existed in the repo (design doc §1.2).
+ *
+ * @param {string} cmd
+ * @returns {string | null}
+ */
+function extractBranchArgument(cmd) {
+  if (!cmd) return null;
+  const tokens = tokenizeShellLike(cmd);
+  const subIdx = skipToSubcommand(tokens);
+  if (subIdx === -1 || subIdx >= tokens.length) return null;
+  const sub = tokens[subIdx];
+
+  if (sub === 'checkout') {
+    for (let j = subIdx + 1; j < tokens.length; j++) {
+      if (tokens[j] === '-b' && j + 1 < tokens.length) return tokens[j + 1];
+    }
+    return null;
+  }
+
+  if (sub === 'branch') {
+    for (let j = subIdx + 1; j < tokens.length; j++) {
+      if (!tokens[j].startsWith('-')) return tokens[j];
+    }
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Return true if `cmd` invokes the git subcommand `sub`.
+ *
+ * @param {string} cmd  - Full shell command string (may include env vars, full paths)
+ * @param {string} sub  - Subcommand to test for, e.g. 'commit'
+ * @returns {boolean}
+ */
+function isGitSubcommand(cmd, sub) {
+  if (!cmd || !sub) return false;
+
+  // Phases 1-3 (env-prefix skip, git-executable check, global-option consume)
+  // extracted verbatim into skipToSubcommand — byte-identical logic, shared
+  // with extractBranchArgument rather than a second copy (#3212 Phase 3).
+  const tokens = tokenizeShellLike(cmd);
+  const subIdx = skipToSubcommand(tokens);
 
   // Phase 4: check the subcommand
-  if (i >= tokens.length) return false;
-  return tokens[i] === sub;
+  if (subIdx === -1 || subIdx >= tokens.length) return false;
+  return tokens[subIdx] === sub;
 }
 
-module.exports = { isGitSubcommand, tokenize };
+module.exports = { isGitSubcommand, tokenize, extractBranchArgument, skipToSubcommand };

package/hooks/lib/git-probe.js

@@ -0,0 +1,84 @@
+'use strict';
+// hooks/lib/git-probe.js — classify a bounded spawnSync(git, ...) result,
+// distinguishing a GENUINE negative answer (git ran and said "no") from
+// "could not determine" (timeout / spawn failure / signal kill) — #3911.
+//
+// Proven defect: hooks/gsd-worktree-path-guard.js, hooks/gsd-workflow-guard.js,
+// and hooks/gsd-windsurf-pre-write.js each treat spawnSync(git, ..., {timeout})
+// returning a non-zero/empty result as "not applicable" and allow silently.
+// A macOS CI run showed three deny cases land at 2084ms/2112ms/2177ms — just
+// past the 2000ms budget — each returning exit 0 with EMPTY stdout AND EMPTY
+// stderr: a timeout is INDISTINGUISHABLE, at the call site, from git cleanly
+// answering "not a repo" / "not this worktree" unless the spawnSync() result
+// itself is inspected for `error`/`signal`, not just `status`/`stdout`.
+//
+// This module does not change any hook's decision or exit code — it only
+// answers "was this probe's answer real?" so a caller can emit a diagnostic
+// on the undetermined branch while keeping the existing fail-open behavior.
+//
+// Classification mirrors tests/helpers/process-seam.cjs's OUTCOME vocabulary
+// (EXITED vs TIMED_OUT/SPAWN_FAILED/KILLED) — same evidence-over-classification
+// ordering (a populated `status` outranks an attached `error`, since Node can
+// report `error.code === 'ETIMEDOUT'` on a result that also carried a real
+// exit that beat the timer) — so a probe here and a subprocess outcome in the
+// test suite never disagree on the same raw spawnSync() shape.
+
+/**
+ * @param {{error?: (Error & {code?: string})|null, status: number|null, signal: string|null}} result
+ *   the raw return value of `spawnSync('git', ...)`.
+ * @returns {{determined: true} | {determined: false, reason: string}}
+ */
+function classifyGitProbe(result) {
+  const error = result && result.error;
+  const status = result ? result.status : null;
+  const signal = result ? result.signal : null;
+
+  if (!error && signal === null) {
+    // A real exit — status 0 or non-zero is a genuine, trustworthy answer.
+    return { determined: true };
+  }
+  if (status !== null) {
+    // `status` is only ever populated by a real exit; it outranks an attached
+    // `error` even at the exact timeout boundary (process-seam.cjs's own
+    // "evidence over classification" rule).
+    return { determined: true };
+  }
+
+  const code = error ? (error.code ?? null) : null;
+  let reason;
+  if (code === 'ETIMEDOUT' || signal !== null) {
+    reason = signal ? `timed out (signal ${signal})` : 'timed out';
+  } else if (code) {
+    reason = `spawn failed (${code})`;
+  } else {
+    reason = 'could not run (unknown reason)';
+  }
+  return { determined: false, reason };
+}
+
+/**
+ * If `result` could not be determined (timeout / spawn failure / signal
+ * kill), write a stderr diagnostic naming the probe and why — never changes
+ * any exit code, never throws. A no-op when the probe genuinely ran and
+ * answered (status 0 or non-zero with no error/signal).
+ *
+ * @param {string} hookName - e.g. 'gsd-worktree-path-guard'
+ * @param {string} probeLabel - e.g. "git rev-parse --show-toplevel"
+ * @param {*} result - the raw spawnSync() return value
+ */
+function reportIfUndetermined(hookName, probeLabel, result) {
+  const classification = classifyGitProbe(result);
+  if (classification.determined) return;
+  try {
+    process.stderr.write(
+      `${hookName}: git probe '${probeLabel}' ${classification.reason} — ` +
+      `allowing this call because the probe's answer is unknown, not because ` +
+      `git answered "no" (#3911).\n`
+    );
+  } catch {
+    // A stderr write failing (EPIPE, closed fd) must never itself change the
+    // hook's fail-open outcome.
+  }
+}
+
+module.exports = { classifyGitProbe, reportIfUndetermined };

package/hooks/lib/hook-exit.js

@@ -0,0 +1,81 @@
+'use strict';
+// hooks/lib/hook-exit.js — hand-written, NOT generated. A tiny hook-facing
+// vocabulary layered over hooks/lib/cli-exit.js's terminateNow (ADR-3889 §3),
+// for the 19 enforcement hooks P7/#3911 is migrating off raw process.exit().
+//
+// WHY onCrash is a REQUIRED argument, with no default (this is the entire
+// point of this module): every hook audited for #3911 ended its outer
+// try/catch in ONE of two ways — some `process.exit(0)` (fail open: a hook
+// error must never block a legitimate tool call), others `process.exit(2)`
+// (fail closed: a hook whose whole job is a security/safety denial must not
+// let its own bug wave the denial through). Both are legitimate policies for
+// DIFFERENT hooks — but neither is the "obviously correct" one, and a shared
+// helper that silently defaulted to either would let a future hook inherit
+// the wrong policy by omission, which is exactly the "nothing fails with
+// success" defect ADR-3889 exists to close. Requiring the caller to name its
+// policy at every call site — not just once at module load — makes "I forgot
+// to decide" a load-time/call-time crash instead of a silent behavior. A
+// caller that truly wants "allow on crash" must still write ALLOW; there is
+// no path that reaches terminateNow without a declared choice.
+//
+// crash() itself is total: it does not throw on a bad `onCrash`, because
+// throwing would unwind into the CALLER's own outer catch — the exact
+// fail-open-by-accident hazard this module removes. Instead an unrecognized
+// policy terminates via terminateNow('INTERNAL', ...) with a diagnostic
+// payload naming the offending value, so a typo'd/misspelled policy is
+// debuggable on stderr rather than silently reinterpreted as ALLOW or DENY.
+const { terminateNow } = require('./cli-exit.js');
+
+/** Frozen enum of the two declarable crash policies. No third option. */
+const HOOK_ON_CRASH = Object.freeze({
+  ALLOW: 'allow',
+  DENY: 'deny',
+});
+
+/** Terminate with the hook-protocol PASS outcome (exit 0). */
+function allow(payload) {
+  terminateNow('PASS', payload);
+}
+
+/**
+ * Terminate with the hook-protocol deny outcome (exit 2, stdout+stderr).
+ *
+ * @param {*} payload - JSON-serializable value written to fd 1 (and, when
+ *   `stderrPayload` is omitted, fd 2 too).
+ * @param {*} [stderrPayload] - optional distinct value for fd 2, forwarded
+ *   verbatim to terminateNow's own `stderrPayload` param — a string is
+ *   written raw, anything else is JSON-stringified.
+ */
+function deny(payload, stderrPayload) {
+  terminateNow('HOOK_DENY', payload, stderrPayload);
+}
+
+/**
+ * Dispatch to allow()/deny() per a DECLARED crash policy. `onCrash` is
+ * required — see the module header for why there is no default.
+ *
+ * @param {'allow'|'deny'} onCrash - one of HOOK_ON_CRASH's two values.
+ * @param {*} payload - JSON-serializable value forwarded to terminateNow.
+ */
+function crash(onCrash, payload) {
+  if (onCrash === HOOK_ON_CRASH.ALLOW) {
+    allow(payload);
+    return;
+  }
+  if (onCrash === HOOK_ON_CRASH.DENY) {
+    deny(payload);
+    return;
+  }
+  // Never guess a policy and never throw (a throw would unwind into the
+  // caller's own outer catch — the fail-open-by-accident defect this module
+  // exists to remove). Terminate deterministically with INTERNAL, naming the
+  // offending value so a misspelled/omitted policy is diagnosable.
+  terminateNow('INTERNAL', {
+    error: 'hook-exit: crash() called with an unrecognized onCrash policy',
+    receivedOnCrash: onCrash,
+    expectedOneOf: [HOOK_ON_CRASH.ALLOW, HOOK_ON_CRASH.DENY],
+    originalPayload: payload,
+  });
+}
+
+module.exports = { HOOK_ON_CRASH, allow, deny, crash };

package/hooks/lib/injection-patterns.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/**
+ * injection-patterns.js — the shared prompt-injection pattern list (#3504, epic #1900).
+ *
+ * Single source of truth for the standard injection signatures used by BOTH
+ * gsd-prompt-guard.js (PreToolUse scan of writes into .planning/) and
+ * gsd-read-injection-scanner.js (PostToolUse scan of Read/WebFetch/WebSearch
+ * content). Previously each hook carried a byte-identical copy ("inlined for
+ * hook independence") that could silently drift — a pattern tightened in one
+ * would stop protecting the other surface.
+ *
+ * Why a shared lib require is safe here (the old inlining rationale, retired):
+ * the installer stages hooks/lib/ from the GSD_HOOK_LIB_FILES allowlist for the
+ * shared-bundle surfaces (Claude-family settings.json runtimes and Kimi), the
+ * Cursor stager auto-discovers require('./lib/...') in staged scripts and fails
+ * the install loudly when a helper is missing (#2587), and the plugin path
+ * ships this directory wholesale.
+ *
+ * Deliberately NOT unified with src/security.cts's scanForInjection set: that
+ * set runs inside the compiled lib tree; hooks must stay loadable standalone
+ * without it. The two lists are different surfaces by design, not drift.
+ *
+ * Keep this file free of literal 'gsd:' text — the stager rewrites that marker
+ * in staged hook content.
+ */
+
+const INJECTION_PATTERNS = Object.freeze([
+  /ignore\s+(all\s+)?previous\s+instructions/i,
+  /ignore\s+(all\s+)?above\s+instructions/i,
+  /disregard\s+(all\s+)?previous/i,
+  /forget\s+(all\s+)?(your\s+)?instructions/i,
+  /override\s+(system|previous)\s+(prompt|instructions)/i,
+  /you\s+are\s+now\s+(?:a|an|the)\s+/i,
+  /act\s+as\s+(?:a|an|the)\s+(?!plan|phase|wave)/i,
+  /pretend\s+(?:you(?:'re| are)\s+|to\s+be\s+)/i,
+  /from\s+now\s+on,?\s+you\s+(?:are|will|should|must)/i,
+  /(?:print|output|reveal|show|display|repeat)\s+(?:your\s+)?(?:system\s+)?(?:prompt|instructions)/i,
+  /<\/?(?:system|assistant|human)>/i,
+  /\[SYSTEM\]/i,
+  /\[INST\]/i,
+  /<<\s*SYS\s*>>/i,
+]);
+
+module.exports = { INJECTION_PATTERNS };

package/hooks/lib/isolation-deny-reason.js

@@ -0,0 +1,39 @@
+'use strict';
+// hooks/lib/isolation-deny-reason.js — shared, frozen reason-code enum for
+// the #3045 dispatch-isolation guards' block/deny decisions
+// (hooks/gsd-agent-isolation-guard.js, hooks/gsd-cursor-subagent-start.js).
+//
+// CONTRIBUTING.md ("Prohibited: Raw Text Matching on Test Outputs") bans
+// asserting on a hook's free-form, human-readable reason/user_message prose
+// — that text is for the operator/model reading the denial and may change
+// wording without notice. Every block/deny decision therefore ALSO carries
+// one of these STABLE codes (surfaced on the hook's stdout JSON as
+// `reason_code`), so tests assert `out.reason_code === REASON_CODE.X`
+// instead of regexing the message (mirrors the REASON enum convention in
+// gsd-core/bin/verify-reapply-patches.cjs).
+//
+// Adding a new code requires updating this enum AND any test that locks the
+// documented set.
+const REASON_CODE = Object.freeze({
+  // The compiled runtime library (gsd-core/bin/lib/*.cjs) is missing and
+  // could not be self-built (ensure-runtime-build.cjs's RuntimeBuildError).
+  RUNTIME_BUILD_FAILED: 'runtime_build_failed',
+  // The project's dispatch-isolation configuration ('.planning/config.json')
+  // could not be read or resolved for a reason OTHER than a runtime-build
+  // failure (unreadable/malformed config, unexpected resolver error).
+  CONFIG_UNREADABLE: 'config_unreadable',
+  // Isolation resolves to "harness-worktree" but the Agent()/Task() dispatch
+  // is missing the harness's isolation flag/kwarg.
+  HARNESS_FLAG_MISSING: 'harness_flag_missing',
+  // Isolation resolves to "harness-worktree" but the dispatch payload carries
+  // no usable subagent_type, so the guard cannot confirm it is a GSD executor.
+  NO_SUBAGENT_TYPE: 'no_subagent_type',
+  // Isolation resolves to "harness-worktree" but whether the workspace root
+  // is an isolated worktree could not be determined (e.g. git unresponsive).
+  CANNOT_DETERMINE_ISOLATION: 'cannot_determine_isolation',
+  // Isolation resolves to "harness-worktree" and the workspace root is
+  // confirmed NOT an isolated worktree.
+  NOT_ISOLATED_WORKTREE: 'not_isolated_worktree',
+});
+
+module.exports = { REASON_CODE };

package/hooks/lib/isolation-sentinel.js

@@ -130,6 +130,15 @@ function resolveSentinelRoot(cwd) {
     if (fs.existsSync(path.join(cwd, '.planning'))) {
       return cwd;
     }
+    // #3582: worktree-safety.cjs / project-root.cjs are tsc build artifacts
+    // (ADR-457), gitignored and absent on a raw plugin-marketplace / git-clone
+    // install that never ran `npm run build:lib`. Self-heal before either
+    // require below; a RuntimeBuildError (or any other failure) falls through
+    // to the existing catch's degrade-to-raw-`cwd` — unchanged behavior, just
+    // now attempted-healed-first rather than silently degrading on the first
+    // cold-tree encounter.
+    const { ensureRuntimeBuild } = require('../../gsd-core/bin/ensure-runtime-build.cjs');
+    ensureRuntimeBuild();
     const { resolveWorktreeRoot } = require('../../gsd-core/bin/lib/worktree-safety.cjs');
     const { root } = resolveWorktreeRoot(cwd);
     const { findProjectRoot } = require('../../gsd-core/bin/lib/project-root.cjs');

package/hooks/managed-hooks-registry.cjs

@@ -29,6 +29,9 @@ const MANAGED_HOOKS = [
   'gsd-cursor-subagent-stop.js',
   'gsd-ensure-canonical-path.js',
   'gsd-graphify-update.sh',
+  // #3662: portable node resolver (helper staged in hooks/; managed JS hook
+  // commands route through it under --portable-hooks).
+  'gsd-node-runner.sh',
   'gsd-phase-boundary.sh',
   'gsd-prompt-guard.js',
   'gsd-read-guard.js',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/gsd-core",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "main": ".opencode/plugins/gsd-core.js",
   "bin": {
@@ -23,6 +23,12 @@
     "scripts",
     "!scripts/gen-emitted-baseline.cjs",
     "!scripts/qa-smell-ratchet.cjs",
+    "!scripts/live-config-guard.cjs",
+    "!scripts/run-tests.cjs",
+    "!scripts/affected-tests-lib.cjs",
+    "!scripts/run-affected-tests.cjs",
+    "!scripts/lint-no-adhoc-regex-escape.cjs",
+    "!scripts/lint-allow-test-rule-refs.cjs",
     "pi",
     "vscode"
   ],
@@ -50,7 +56,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=22.0.0",
+    "node": ">=24.0.0",
     "npm": ">=10.0.0"
   },
   "dependencies": {
@@ -60,14 +66,18 @@
   "devDependencies": {
     "@eslint/js": "^9.39.4",
     "@stryker-mutator/core": "^9.6.1",
+    "@stryker-mutator/tap-runner": "^9.6.1",
     "@types/node": "^22.19.19",
     "c8": "^11.0.0",
     "eslint": "^9.39.4",
     "eslint-plugin-n": "^17.24.0",
     "eslint-plugin-no-only-tests": "^3.4.0",
+    "espree": "^10.4.0",
     "fast-check": "^4.8.0",
     "globals": "^16.5.0",
-    "js-yaml": "^4.2.1",
+    "js-yaml": "^4.3.1",
+    "mutation-testing-metrics": "^3.7.3",
+    "re2js": "^2.8.6",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.60.0"
   },
@@ -81,6 +91,7 @@
   },
   "scripts": {
     "sync:launcher": "node scripts/sync-runtime-launcher.cjs",
+    "check:contract-drift": "node scripts/check-contract-drift.cjs",
     "check:env": "node scripts/check-env.cjs",
     "check:alias-drift": "node scripts/check-alias-drift.cjs",
     "check:identity-drift": "node scripts/lint-package-identity-drift.cjs",
@@ -97,7 +108,7 @@
     "gen:registry": "node scripts/gen-registry.cjs --write",
     "gen:install-tree": "node scripts/gen-install-tree-fixtures.cjs",
     "gen:section-manifest": "node scripts/gen-section-manifest.cjs --write",
-    "regen:derived": "npm run build && npm run gen:registry && node scripts/gen-adr-index.cjs --write && node scripts/gen-capability-matrix.cjs --write && node scripts/gen-inventory-manifest.cjs --write && node scripts/gen-context-index.cjs --write && npm run gen:section-manifest && node scripts/sync-manifest-versions.cjs && npm run gen:install-tree",
+    "regen:derived": "npm run build && npm run gen:registry && node scripts/gen-adr-index.cjs --write && node scripts/gen-features.cjs --write && node scripts/gen-capability-matrix.cjs --write && node scripts/gen-inventory-manifest.cjs --write && node scripts/gen-context-index.cjs --write && node scripts/gen-state-md-docs.cjs --write && npm run gen:section-manifest && node scripts/sync-manifest-versions.cjs && npm run gen:install-tree && node scripts/gen-scripts-cli-exit.cjs --write && node scripts/gen-hooks-cli-exit.cjs --write && node scripts/gen-exit-code-registry.cjs --write && node scripts/gen-exit-code-docs.cjs --write",
     "validate:registry": "node scripts/validate-registry.cjs",
     "prepack": "npm run build:lib",
     "prepare": "npm run build:lib",
@@ -105,10 +116,12 @@
     "prepublishOnly": "npm run build:lib && npm run build:hooks",
     "pretest": "npm run build:lib && npm run lint:skill-deps",
     "pretest:coverage": "npm run build:lib && npm run lint:skill-deps",
-    "lint": "eslint . --cache --cache-location node_modules/.cache/eslint/",
+    "lint": "eslint . --cache --cache-location node_modules/.cache/eslint/ --max-warnings 0",
     "lint:fix": "eslint . --fix",
     "lint:table-schema-drift": "node scripts/lint-table-schema-drift.cjs",
-    "lint:ci": "npm run lint && npm run lint:skill-deps && npm run lint:generated-sync && node scripts/lint-test-file-count.cjs && node scripts/lint-command-contract.cjs && node scripts/lint-pr-check-project-dir.cjs && npm run lint:legacy-name && node scripts/lint-regression-test-names.cjs && node scripts/lint-allow-test-rule-refs.cjs && node scripts/lint-resolution-provenance.cjs && node scripts/lint-emitted-drift-ack.cjs && node scripts/lint-portable-timeout.cjs && node scripts/validate-registry.cjs && node scripts/lint-table-schema-drift.cjs && node scripts/lint-fix-has-regression-test.cjs && node scripts/lint-example-parser-parity.cjs && node scripts/lint-docs-command-form.cjs",
+    "lint:frontmatter-scalar-broad-grep": "node scripts/lint-frontmatter-scalar-broad-grep.cjs",
+    "lint:removed-but-needed": "node scripts/lint-removed-but-needed.cjs",
+    "lint:ci": "npm run lint && npm run lint:skill-deps && npm run lint:generated-sync && node scripts/lint-test-file-count.cjs && node scripts/lint-command-contract.cjs && node scripts/lint-pr-check-project-dir.cjs && npm run lint:legacy-name && node scripts/lint-regression-test-names.cjs && node scripts/lint-allow-test-rule-refs.cjs && node scripts/lint-resolution-provenance.cjs && node scripts/lint-portable-timeout.cjs && node scripts/validate-registry.cjs && node scripts/lint-table-schema-drift.cjs && node scripts/lint-fix-has-regression-tests.cjs && node scripts/lint-example-parser-parity.cjs && node scripts/lint-docs-command-form.cjs && node scripts/lint-plan-count-drift.cjs && node scripts/lint-milestone-window-drift.cjs && node scripts/lint-phase-enumeration-drift.cjs && node scripts/lint-planning-prompt-drift.cjs && node scripts/lint-unreachable-guard-drift.cjs && node scripts/lint-completion-ratio-drift.cjs && node scripts/lint-slug-derivation-drift.cjs && node scripts/lint-state-field-drift.cjs && node scripts/lint-state-write-path-drift.cjs && node scripts/lint-completion-predicate-drift.cjs && node scripts/lint-planning-snapshot-bypass-drift.cjs && node scripts/lint-health-diagnostic-rule-table.cjs && node scripts/lint-planning-artifact-writer-drift.cjs && node scripts/lint-frontmatter-scalar-broad-grep.cjs && node scripts/lint-removed-but-needed.cjs && node scripts/lint-no-adhoc-regex-escape.cjs && node scripts/lint-vendored-deps.cjs && node scripts/lint-docs-guard-registration.cjs && node scripts/lint-source-test-name-collision.cjs && npm run lint:hooks-runtime-build-seam && node scripts/check-contract-drift.cjs && node scripts/lint-mutation-test-derivation-drift.cjs && node scripts/lint-seam-enforcement.cjs",
     "lint:allow-test-rule-refs": "node scripts/lint-allow-test-rule-refs.cjs",
     "lint:regression-names": "node scripts/lint-regression-test-names.cjs",
     "lint:descriptions": "node scripts/lint-descriptions.cjs",
@@ -116,11 +129,13 @@
     "lint:test-file-count": "node scripts/lint-test-file-count.cjs",
     "lint:pr-checks": "node scripts/lint-pr-check-project-dir.cjs",
     "lint:changeset": "node scripts/changeset/lint.cjs",
-    "lint:generated-sync": "node scripts/gen-capability-registry.cjs --check && node scripts/gen-loop-host-contract.cjs --check && node scripts/gen-capability-matrix.cjs --check && node scripts/sync-manifest-versions.cjs --check && node scripts/gen-inventory-manifest.cjs --check && node scripts/generate-package-identity.cjs --check && node scripts/gen-plugin-skills.cjs --check && node scripts/gen-registry.cjs --check && node scripts/gen-adr-index.cjs --check && node scripts/check-glossary-refs.cjs --check && node scripts/lint-compiled-artifact-sync.cjs --check && node scripts/gen-context-index.cjs --check && node scripts/gen-section-manifest.cjs --check",
+    "lint:generated-sync": "node scripts/gen-capability-registry.cjs --check && node scripts/gen-loop-host-contract.cjs --check && node scripts/gen-capability-matrix.cjs --check && node scripts/sync-manifest-versions.cjs --check && node scripts/gen-inventory-manifest.cjs --check && node scripts/generate-package-identity.cjs --check && node scripts/gen-plugin-skills.cjs --check && node scripts/gen-registry.cjs --check && node scripts/gen-adr-index.cjs --check && node scripts/gen-features.cjs --check && node scripts/check-glossary-refs.cjs --check && node scripts/lint-compiled-artifact-sync.cjs --check && node scripts/gen-context-index.cjs --check && node scripts/gen-section-manifest.cjs --check && node scripts/gen-health-docs.cjs --check && node scripts/gen-state-md-docs.cjs --check && node scripts/gen-scripts-cli-exit.cjs --check && node scripts/gen-hooks-cli-exit.cjs --check && node scripts/gen-exit-code-registry.cjs --check && node scripts/gen-exit-code-docs.cjs --check",
     "lint:docs": "node scripts/lint-docs-required.cjs",
     "lint:qa-smells": "node scripts/qa-smell-ratchet.cjs",
     "lint:legacy-name": "node scripts/lint-legacy-dir-name.cjs",
+    "lint:seam-enforcement": "node scripts/lint-seam-enforcement.cjs",
     "lint:docs-command-form": "node scripts/lint-docs-command-form.cjs",
+    "lint:hooks-runtime-build-seam": "node scripts/lint-hooks-runtime-build-seam.cjs",
     "ci:test-scope": "node scripts/ci-test-scope.cjs",
     "changeset": "node scripts/changeset/new.cjs",
     "changelog:render": "node scripts/changeset/cli.cjs render",
@@ -132,14 +147,16 @@
     "test:slow": "node scripts/run-tests.cjs --suite slow",
     "test:qa": "node scripts/run-tests.cjs --suite qa",
     "test:affected": "node scripts/run-affected-tests.cjs",
-    "test:coverage": "c8 --check-coverage --lines 70 --branches 60 --reporter text --include 'gsd-core/bin/lib/*.cjs' --exclude 'tests/**' --all node scripts/run-tests.cjs",
+    "test:coverage": "c8 --check-coverage --lines 70 --branches 60 --reporter text --include 'gsd-core/bin/lib/**/*.cjs' --exclude 'tests/**' --all node scripts/run-tests.cjs",
     "test:coverage:scripts-floor": "c8 check-coverage --lines 55 --include 'scripts/**/*.cjs' --exclude 'tests/**' --all",
-    "test:coverage:unit": "c8 --reporter text --reporter json-summary --include 'gsd-core/bin/lib/*.cjs' --exclude 'tests/**' --all node scripts/run-tests.cjs --suite unit && node scripts/check-coverage-gate.cjs",
+    "test:coverage:unit": "c8 --reporter text --reporter json-summary --merge-async --include 'gsd-core/bin/lib/**/*.cjs' --exclude 'tests/**' --all node scripts/run-tests.cjs --suite unit && node scripts/check-coverage-gate.cjs",
     "test:coverage:unit:raw": "c8 --reporter none node scripts/run-tests.cjs --suite unit",
-    "test:coverage:report": "c8 report --reporter text --reporter json-summary --include 'gsd-core/bin/lib/*.cjs' --exclude 'tests/**' --all && node scripts/check-coverage-gate.cjs",
+    "test:coverage:report": "c8 report --reporter text --reporter json-summary --merge-async --include 'gsd-core/bin/lib/**/*.cjs' --exclude 'tests/**' --all && node scripts/check-coverage-gate.cjs",
     "test:coverage:all": "npm run test:coverage",
     "test:mutation": "stryker run",
-    "test:mutation:since": "stryker run --incremental --since origin/next"
+    "test:mutation:since": "stryker run --incremental --since origin/next",
+    "gen:features": "node scripts/gen-features.cjs",
+    "gen:state-md-docs": "node scripts/gen-state-md-docs.cjs"
   },
   "allowScripts": {
     "fallow@2.70.0": true

package/pi/gsd.cjs

@@ -320,21 +320,35 @@ module.exports = function gsdPiExtension(pi) {
     getArgumentCompletions,
     handler: async (args, ctx) => {
       const cwd = (ctx && ctx.cwd) || process.cwd();
+      // #3456: Pi's command dispatcher awaits the handler and DISCARDS its
+      // return value (agent-session.ts: `await command.handler(args, ctx);
+      // return true;`) — #3097's `{ content: [...] }` return was silently
+      // dropped exactly like the pre-#3097 bare string. The ONLY command-
+      // output mechanism Pi consumes is `ctx.ui.notify(message, type)`
+      // (pi docs: extensions.md#piregistercommandname-options), so the output
+      // is pushed as a side effect on both the success and error paths.
+      // Guarded so a host ctx without `ui` degrades silently instead of
+      // crashing the command.
+      const notify = (ctx && ctx.ui && typeof ctx.ui.notify === 'function')
+        ? (message, type) => ctx.ui.notify(message, type)
+        : null;
       const { family, subcommand, args: rest } = parseGsdCommandArgs(args);
       let dispatchGsdCommand;
       try {
         ({ dispatchGsdCommand } = require(path.join(GSD_CORE, 'bin', 'lib', 'shell-command-projection.cjs')));
       } catch (e) {
-        // #2991: return the structured { content } shape Pi's ExtensionAPI
-        // displays, not a bare string (which Pi silently drops).
-        return { content: [{ type: 'text', text: `GSD engine unavailable: ${e && e.message ? e.message : String(e)}` }] };
+        if (notify) {
+          notify(`GSD engine unavailable: ${e && e.message ? e.message : String(e)}`, 'error');
+        }
+        return;
       }
       const result = dispatchGsdCommand({ family, subcommand, args: rest, cwd });
-      // #2991: match gsd_invoke's proven output shape so Pi actually displays it.
       const text = result.ok
         ? result.stdout
         : `GSD error: ${result.stderr || result.stdout || `dispatch failed (exit ${result.code})`}`;
-      return { content: [{ type: 'text', text }] };
+      if (notify) {
+        notify(text, result.ok ? 'info' : 'error');
+      }
     },
   });