@opengsd/gsd-core 1.9.1 → 1.11.0

package/hooks/lib/isolation-sentinel.js

@@ -0,0 +1,277 @@
+'use strict';
+// hooks/lib/isolation-sentinel.js — shared sentinel reader for the #3045
+// agent-dispatch isolation guards (hooks/gsd-agent-isolation-guard.js,
+// hooks/gsd-cursor-subagent-start.js).
+//
+// #3045 BLOCKER: the guards previously keyed enforcement on the capability
+// REGISTRY's `dispatch.isolation` ("this host CAN isolate"), not the
+// workflow's resolved per-dispatch ISOLATION ("this dispatch SHOULD be
+// isolated"). Sequential ISOLATION=none legitimately happens on a
+// harness-worktree-capable host — project-level `workflow.use_worktrees:
+// false`, the #2474 per-plan submodule degrade, and the #683/#3060
+// base-check auto-degrade all resolve to `none` and are NOT bugs
+// (gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md:
+// "Sequential mode … Omit isolation=\"worktree\" from the Agent call").
+//
+// The workflow already computes ISOLATION deterministically in shell before
+// any executor dispatch. CORE REDESIGN (two-review follow-up): the PRIMARY
+// write path is now `dispatch-isolation` itself (gsd-tools.cjs
+// routeDispatchIsolation) — it persists mode + harnessFlag + phase/plan
+// identifiers to the sentinel as an unconditional side effect of resolving
+// them, since the workflow must call it to learn ISOLATION at all.
+// `record-dispatch-isolation` (routeRecordDispatchIsolation) remains as an
+// explicit fallback for the per-plan submodule-degrade override and shares
+// the exact same atomic-write implementation.
+//
+// Sentinel path: `<cwd>/.gsd/dispatch-isolation-sentinel.json`. `.gsd` is
+// gitignored (root `.gitignore`'s bare `.gsd` entry matches at any depth),
+// and lives inside the checkout that ran the workflow — concurrent worktrees
+// of the same repo are separate directories on disk, so each gets its own
+// sentinel with no cross-worktree collision, no lock file needed.
+//
+// #3045 SECURITY F3 (LOW, accepted risk — documented, not redesigned for):
+// the sentinel lives at a fixed, predictable, gitignored path inside the
+// PRIMARY checkout. An agent already running inside a legitimately isolated
+// worktree (i.e. one that has shell/filesystem access to the primary
+// checkout's absolute path, which every worktree-isolated agent does by
+// construction) could write a fabricated fresh `{isolation:"none"}` sentinel
+// into the primary checkout to silence this guard for that checkout's next
+// dispatch.
+//   - This grants NO NEW write privilege: that same agent could already edit
+//     any file in the primary checkout directly (worktree isolation protects
+//     the primary checkout from an UNTRUSTED executor's own dispatch, not
+//     from a trusted orchestrator process choosing to reach across).
+//   - It DOES add an evasion path: silencing the guard via the sentinel
+//     leaves no trace in `git status` (`.gsd/` is gitignored), where a direct
+//     edit to a tracked file would.
+// Accepted because the threat model this guard defends against is an
+// UNCONSENTED, UNVERIFIED dispatch — not a deliberately adversarial
+// orchestrator process, which already has strictly more direct means to
+// cause harm than forging this one file. If that threat model changes (e.g.
+// executors become mutually distrusting / sandboxed from the orchestrator's
+// own filesystem), the hardening path is a SESSION-KEYED sentinel written
+// outside any worktree the executor can reach (e.g. under the harness's own
+// config dir, keyed by a session/run id neither the executor nor a forged
+// file can predict) rather than a path derivable from `cwd`.
+
+const fs = require('fs');
+const path = require('path');
+
+// Isolation modes ADR-1239 declares (mirrors gsd-tools.cjs
+// routeDispatchIsolation / routeRecordDispatchIsolation).
+const VALID_ISOLATION = new Set(['harness-worktree', 'orchestrator-worktree', 'none']);
+
+const SENTINEL_RELATIVE_PATH = path.join('.gsd', 'dispatch-isolation-sentinel.json');
+
+// #3045 SECURITY F2 fix: how long a written sentinel is trusted as "this
+// dispatch's decision" before a reader falls back to the conservative
+// registry+config check.
+//
+// Previously 4h, on the theory that a slow multi-wave phase execution could
+// span well over an hour. That reasoning no longer holds: the #3045 CORE
+// REDESIGN makes `dispatch-isolation` (gsd-tools.cjs routeDispatchIsolation)
+// the sole write path, called as a side effect of resolving ISOLATION — and
+// the workflow now re-resolves (and therefore re-records) immediately before
+// EVERY plan's dispatch, at the per-plan worktree gate
+// (execute-phase/steps/per-plan-worktree-gate.md), not once per phase. A long
+// trust window no longer buys the workflow anything and only widens the
+// window in which a stale sentinel from an EARLIER, DIFFERENT phase/plan
+// (e.g. one that legitimately degraded to `none`) could be misread as
+// authorizing a LATER dispatch that never got its own fresh record (a model
+// skipping the kwarg on a harness-worktree phase while a same-session
+// same-project stale `none` from a prior phase is still "fresh" by the old
+// 4h window).
+//
+// 10 minutes generously covers the real latency between a per-plan gate's
+// resolve call and that same plan's `Agent()`/`Task()` dispatch (worktree
+// creation, orphan-worktree sweep, base-check, prompt composition) — all
+// bounded, sub-minute operations per their own repo-mandated subprocess
+// timeouts — while being far too short for a sentinel to survive into a
+// later, unrelated phase.
+const SENTINEL_STALE_MS = 10 * 60 * 1000; // 10 minutes
+
+function sentinelPath(cwd) {
+  return path.join(cwd, SENTINEL_RELATIVE_PATH);
+}
+
+/**
+ * Resolve the project root a sentinel should be read from/written to, using
+ * the SAME derivation gsd-tools.cjs's dispatcher applies to every `--cwd`
+ * before invoking a route handler: `findProjectRoot(resolveMainWorktreeCwd(cwd))`
+ * (gsd-core/bin/gsd-tools.cjs main(), :3506/:3603 — `record-dispatch-isolation`
+ * and `dispatch-isolation` are not in SKIP_ROOT_RESOLUTION, so every write
+ * goes through both steps).
+ *
+ * #3045 MINOR fix: the guard hooks previously read the sentinel from the raw
+ * `data.cwd` / `workspace_roots[i]` the harness reports, with NO equivalent
+ * resolution. For a linked worktree that does not itself own a `.planning/`
+ * (the common shape — `.planning/` lives in the main worktree only), the
+ * writer resolves up to the MAIN worktree and writes there, while the reader
+ * checked `.planning/config.json` at the raw (unresolved) linked-worktree
+ * path, found nothing, and silently treated the dispatch as "not a GSD
+ * project" (inert allow) — the guard was reading a sentinel that was never
+ * written where it looked. Deriving both sides through this one function
+ * closes that divergence.
+ *
+ * `findProjectRoot`/`resolveWorktreeRoot` are read from the sibling
+ * `gsd-core/bin/lib/*.cjs` modules staged alongside these hooks at install
+ * time (same pattern the guard hooks already use for
+ * capability-registry.cjs/runtime-name-policy.cjs) — two directories up from
+ * `hooks/lib/` (`hooks/lib/isolation-sentinel.js` -> `hooks/` -> repo/install
+ * root -> `gsd-core/bin/lib/`), mirroring the one-directory-up requires the
+ * top-level `hooks/*.js` guard scripts already use successfully.
+ *
+ * Never throws; any resolution failure (module missing, git unavailable,
+ * git timeout) degrades to the raw `cwd` unchanged — the caller's existing
+ * "sentinel absent -> conservative fallback" path already covers that safely.
+ */
+function resolveSentinelRoot(cwd) {
+  try {
+    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');
+    return findProjectRoot(root);
+  } catch {
+    return cwd;
+  }
+}
+
+/**
+ * Read and validate the dispatch-isolation sentinel for `cwd`. Never throws.
+ * `cwd` is resolved through `resolveSentinelRoot` first (#3045 MINOR — see
+ * its doc comment), so callers may pass the raw, unresolved dispatch cwd
+ * directly.
+ *
+ * Returns one of:
+ *   { present: false }
+ *   { present: true, stale: true,  malformed: true }
+ *   { present: true, stale: true,  malformed: false, isolation, harnessFlag, phase, plan, writtenAt }
+ *   { present: true, stale: false, malformed: false, isolation, harnessFlag, phase, plan, writtenAt }
+ *
+ * A malformed/unparseable sentinel is treated as STALE, never fatal — the
+ * caller's conservative fallback path covers both "absent" and "stale"
+ * identically.
+ *
+ * `clock` is injectable (`{ now(): number }`, defaults to the real `Date`)
+ * per the repo's clock-seam convention, so staleness is testable without
+ * asserting on wall-clock time.
+ */
+function readSentinel(cwd, { clock = Date } = {}) {
+  const root = resolveSentinelRoot(cwd);
+  let raw;
+  try {
+    raw = fs.readFileSync(sentinelPath(root), 'utf-8');
+  } catch {
+    return { present: false };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { present: true, stale: true, malformed: true };
+  }
+
+  if (
+    !parsed || typeof parsed !== 'object' ||
+    !VALID_ISOLATION.has(parsed.isolation) ||
+    typeof parsed.written_at !== 'number' || !Number.isFinite(parsed.written_at)
+  ) {
+    return { present: true, stale: true, malformed: true };
+  }
+
+  const harnessFlag = typeof parsed.harness_flag === 'string' && parsed.harness_flag.length > 0
+    ? parsed.harness_flag
+    : null;
+  const phase = typeof parsed.phase === 'string' && parsed.phase.length > 0 ? parsed.phase : null;
+  // #3045 SECURITY F2: `plan` was not previously part of the sentinel shape.
+  // Recorded so a phase-level-only sentinel (plan: null) is distinguishable
+  // from a plan-scoped one — see the guards' dispatch-matching logic, which
+  // treats a plan/phase MISMATCH (both sides present and disagreeing) as "no
+  // applicable sentinel", not an allow.
+  const plan = typeof parsed.plan === 'string' && parsed.plan.length > 0 ? parsed.plan : null;
+
+  const now = clock.now();
+  const age = now - parsed.written_at;
+  // Negative age beyond a small tolerance means the sentinel claims to be
+  // written in the future — never trust it, but still surface the parsed
+  // fields so callers can log an actionable reason.
+  const stale = age >= SENTINEL_STALE_MS || age < -5000;
+
+  return {
+    present: true,
+    stale,
+    malformed: false,
+    isolation: parsed.isolation,
+    harnessFlag,
+    phase,
+    plan,
+    writtenAt: parsed.written_at,
+  };
+}
+
+/**
+ * #3045 SECURITY F2: extract the `{plan, phase}` a specific Agent()/Task()
+ * dispatch is FOR, from the one place that data is reliably embedded today —
+ * the dispatch prompt/description text (`execute-phase.md`'s Agent() block
+ * uses the literal shape `description="Execute plan {plan_number} of phase
+ * {phase_number}"`, and the prompt body's `<objective>` repeats "Execute plan
+ * {plan_number} of phase {phase_number}-{phase_name}." verbatim — the SAME
+ * text the orchestrator-worktree EXECUTOR_PROMPT template and Cursor's `task`
+ * field carry, since Cursor dispatches the same prompt content). There is no
+ * structured per-dispatch kwarg carrying plan/phase identifiers today (#3045
+ * would need a larger dispatch-protocol change to add one) — this is
+ * therefore a best-effort, NOT a guaranteed, extraction: a dispatch whose
+ * text doesn't match the expected shape returns `{ plan: null, phase: null }`
+ * and the caller must NOT treat that as a mismatch (see
+ * `sentinelAppliesToDispatch`).
+ */
+function extractDispatchIdentifiers(text) {
+  if (typeof text !== 'string' || text.length === 0) return { plan: null, phase: null };
+  const m = /execute\s+plan\s+(\S+)\s+of\s+phase\s+(\S+)/i.exec(text);
+  if (!m) return { plan: null, phase: null };
+  return { plan: m[1], phase: m[2] };
+}
+
+/**
+ * #3045 SECURITY F2: does a fresh, non-malformed sentinel apply to THIS
+ * dispatch? `dispatchIds` is the `{plan, phase}` extracted from the
+ * dispatch's own text via `extractDispatchIdentifiers` (or manually supplied
+ * by a caller with a more reliable source).
+ *
+ * Returns false (mismatch — "no applicable sentinel") ONLY when both sides
+ * carry a value for the SAME identifier and they disagree. Any side missing
+ * a value (sentinel predates this fix, or the dispatch text didn't match the
+ * expected shape) is treated as "cannot compare" and does NOT itself produce
+ * a mismatch — this stays a defense-in-depth narrowing of an otherwise-fresh
+ * sentinel's applicability, not a new fail-open/fail-closed axis on its own.
+ */
+function sentinelAppliesToDispatch(sentinel, dispatchIds) {
+  if (!sentinel || !dispatchIds) return true;
+  if (sentinel.phase && dispatchIds.phase && sentinel.phase !== dispatchIds.phase) return false;
+  if (sentinel.plan && dispatchIds.plan && sentinel.plan !== dispatchIds.plan) return false;
+  return true;
+}
+
+module.exports = {
+  VALID_ISOLATION,
+  SENTINEL_RELATIVE_PATH,
+  SENTINEL_STALE_MS,
+  sentinelPath,
+  resolveSentinelRoot,
+  readSentinel,
+  extractDispatchIdentifiers,
+  sentinelAppliesToDispatch,
+};

package/hooks/managed-hooks-registry.cjs

@@ -16,6 +16,7 @@
  * stale warnings for users who haven't cleaned up manually (#1750).
  */
 const MANAGED_HOOKS = [
+  'gsd-agent-isolation-guard.js',
   'gsd-check-update-worker.js',
   'gsd-check-update.js',
   'gsd-config-reload.js',
@@ -40,6 +41,7 @@ const MANAGED_HOOKS = [
   'gsd-windsurf-pre-write.js',
   'gsd-workflow-guard.js',
   'gsd-worktree-path-guard.js',
+  'gsd-write-guard.js',
 ];
 
 module.exports = { MANAGED_HOOKS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/gsd-core",
-  "version": "1.9.1",
+  "version": "1.11.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": {
@@ -21,6 +21,14 @@
     "GEMINI.md",
     "hooks",
     "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"
   ],
@@ -48,7 +56,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=22.0.0",
+    "node": ">=24.0.0",
     "npm": ">=10.0.0"
   },
   "dependencies": {
@@ -63,9 +71,11 @@
     "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",
+    "re2js": "^2.8.6",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.60.0"
   },
@@ -79,21 +89,24 @@
   },
   "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",
     "check:phase-id-drift": "node scripts/lint-phase-id-drift.cjs",
     "check:integrity": "node scripts/check-npm-integrity.cjs",
-    "build": "npm run generate:identity && npm run build:lib && npm run gen:plugin-skills && npm run gen:loop-host-contract && npm run gen:capability-registry && npm run build:hooks",
+    "build": "npm run generate:identity && npm run build:lib && npm run gen:section-manifest && npm run gen:context-index && npm run gen:plugin-skills && npm run gen:loop-host-contract && npm run gen:capability-registry && npm run build:hooks",
     "build:hooks": "node scripts/build-hooks.js",
     "build:lib": "tsc -p tsconfig.build.json",
     "generate:identity": "node scripts/generate-package-identity.cjs",
+    "gen:context-index": "node scripts/gen-context-index.cjs --write",
     "gen:loop-host-contract": "node scripts/gen-loop-host-contract.cjs --write",
     "gen:plugin-skills": "node scripts/gen-plugin-skills.cjs --write",
     "gen:capability-registry": "node scripts/gen-capability-registry.cjs --write",
     "gen:registry": "node scripts/gen-registry.cjs --write",
     "gen:install-tree": "node scripts/gen-install-tree-fixtures.cjs",
-    "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/sync-manifest-versions.cjs && npm run gen:install-tree",
+    "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",
     "validate:registry": "node scripts/validate-registry.cjs",
     "prepack": "npm run build:lib",
     "prepare": "npm run build:lib",
@@ -101,10 +114,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",
+    "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-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 && 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-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 && npm run lint:hooks-runtime-build-seam && node scripts/check-contract-drift.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",
@@ -112,9 +127,12 @@
     "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",
+    "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 && node scripts/gen-health-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: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",
@@ -124,10 +142,13 @@
     "test:install": "node scripts/run-tests.cjs --suite install",
     "test:security": "node scripts/run-tests.cjs --suite security",
     "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 --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:all": "npm run test:coverage",
     "test:mutation": "stryker run",
     "test:mutation:since": "stryker run --incremental --since origin/next"

package/pi/gsd.cjs

@@ -63,6 +63,43 @@ function resolveEngineRoot(startDir) {
 const ENGINE_ROOT = resolveEngineRoot(__dirname);
 const GSD_CORE = path.join(ENGINE_ROOT, 'gsd-core');
 
+// #3023: pi reserves `hooks/` as its (now deprecated) extension directory and
+// warns on every startup when one exists, so the installer stages GSD's shared
+// hook bundle under `gsd-hooks/` for pi. Probe in preference order rather than
+// hardcoding either name: an installed pi tree has `gsd-hooks/`, a dev checkout
+// has the repo-root `hooks/`, and a half-upgraded tree can transiently have both
+// — in which case the renamed bundle is the current one and wins.
+const SHARED_HOOKS_DIR_CANDIDATES = ['gsd-hooks', 'hooks'];
+
+/**
+ * Absolute path to the staged shared-hook bundle, or null when none is present.
+ * Never throws — a stat failure on any candidate is treated as "not this one".
+ *
+ * A candidate qualifies only when it is a directory AND non-empty. An install
+ * can be interrupted between `mkdirSync(gsd-hooks)` and the file copy, leaving
+ * a directory that exists but is empty; `gsd-hooks` is probed FIRST (it is the
+ * preferred, current name), so an empty `gsd-hooks/` would otherwise win over
+ * a fully-staged legacy `hooks/` and every hook would silently no-op —
+ * `runHook`'s `fs.existsSync(hookPath)` guard degrades per-file, so binding to
+ * an empty bundle produces no error at all, just silent inaction. A
+ * partially-staged bundle must lose to a fully-staged one for that reason.
+ * @param {string} engineRoot
+ * @returns {string|null}
+ */
+function resolveSharedHooksDir(engineRoot) {
+  for (const name of SHARED_HOOKS_DIR_CANDIDATES) {
+    const candidate = path.join(engineRoot, name);
+    try {
+      if (!fs.statSync(candidate).isDirectory()) continue;
+      if (fs.readdirSync(candidate).length === 0) continue;
+      return candidate;
+    } catch { /* absent or unreadable — try the next candidate */ }
+  }
+  return null;
+}
+
+const SHARED_HOOKS_DIR = resolveSharedHooksDir(ENGINE_ROOT);
+
 // ── curated top-level command families (gsd-tools.cjs TOP_LEVEL_USAGE) ──────
 // readCmdNames() (scripts/fix-slash-commands.cjs) reads commands/, which pi
 // does NOT install (it ships a single native-extension file, no shared
@@ -95,8 +132,8 @@ function getArgumentCompletions(prefix) {
 /**
  * Tokenize the raw `/gsd <args>` string into { family, subcommand, args }.
  * Reuses the quote-aware whitespace tokenizer already shipped for hooks
- * (hooks/lib/git-cmd.js's `tokenize`) rather than re-implementing shell-word
- * splitting a second time. #2102 Stage 2: pi's capability descriptor no
+ * (the staged shared-hook bundle's `lib/git-cmd.js`'s `tokenize`) rather than
+ * re-implementing shell-word splitting a second time. #2102 Stage 2: pi's capability descriptor no
  * longer sets `hostBehaviors.skipSharedHooksInstall` (adversarial-review
  * finding #1/#2 — pi ships NO hooks/ with that flag set, so this require was
  * dead in a real install), so the shared hooks/ bundle — including
@@ -112,7 +149,8 @@ function getArgumentCompletions(prefix) {
 function parseGsdCommandArgs(rawArgs) {
   let tokenize;
   try {
-    ({ tokenize } = require(path.join(ENGINE_ROOT, 'hooks', 'lib', 'git-cmd.js')));
+    if (!SHARED_HOOKS_DIR) throw new Error('no staged hook bundle');
+    ({ tokenize } = require(path.join(SHARED_HOOKS_DIR, 'lib', 'git-cmd.js')));
   } catch {
     tokenize = (s) => String(s || '').split(/\s+/).filter(Boolean);
   }
@@ -148,11 +186,10 @@ function buildGsdInvokeParameters() {
       });
     }
   } catch {
-    // typebox is not installed in this environment — fall through.
+    // typebox is not installed in this environment — fall through to the
+    // plain JSON-Schema fallback below. This is the normal path (typebox is
+    // NOT a gsd-core dependency), so no warning is emitted (#3022).
   }
-  process.stderr.write(
-    'gsd: typebox unavailable — gsd_invoke "parameters" falling back to a plain JSON-schema object.\n',
-  );
   return {
     type: 'object',
     properties: {
@@ -245,13 +282,14 @@ function buildBeforeProviderRequestHandler({ tier = 'sonnet' } = {}) {
  * `node <hooks/hookFile>` with the payload piped to stdin, on a bounded
  * timeout. NEVER throws — a missing hook file, a spawn error, or a timeout
  * all degrade to a silent-allow result so a hook problem can never block pi.
- * @param {string} hookFile  filename under hooks/, e.g. "gsd-context-monitor.js"
+ * @param {string} hookFile  filename under the resolved shared-hook bundle, e.g. "gsd-context-monitor.js"
  * @param {object} payload
  * @param {{ timeout?: number, cwd?: string }} [opts]
  * @returns {{ stdout: string, exitCode: number, timedOut: boolean }}
  */
 function runHook(hookFile, payload, opts = {}) {
-  const hookPath = path.join(ENGINE_ROOT, 'hooks', hookFile);
+  if (!SHARED_HOOKS_DIR) return { stdout: '', exitCode: 0, timedOut: false };
+  const hookPath = path.join(SHARED_HOOKS_DIR, hookFile);
   if (!fs.existsSync(hookPath)) return { stdout: '', exitCode: 0, timedOut: false };
   const timeout = opts.timeout || 8000;
   let result;
@@ -282,16 +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) {
-        return `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 });
-      if (result.ok) return result.stdout;
-      return `GSD error: ${result.stderr || result.stdout || `dispatch failed (exit ${result.code})`}`;
+      const text = result.ok
+        ? result.stdout
+        : `GSD error: ${result.stderr || result.stdout || `dispatch failed (exit ${result.code})`}`;
+      if (notify) {
+        notify(text, result.ok ? 'info' : 'error');
+      }
     },
   });
 
@@ -376,6 +433,8 @@ module.exports = function gsdPiExtension(pi) {
 // resolution WITHOUT a live pi runtime.
 module.exports._internals = {
   resolveEngineRoot,
+  resolveSharedHooksDir,
+  SHARED_HOOKS_DIR_CANDIDATES,
   parseGsdCommandArgs,
   getArgumentCompletions,
   PI_COMMAND_FAMILIES,

package/scripts/baselines/planning-prompt-drift-baseline.json

@@ -0,0 +1,4 @@
+{
+  "$comment": "ADR-3180 Decision 4(e) ratchet, owned by Phase 8 (#3218). See scripts/lint-planning-prompt-drift.cjs. SHRINK-ONLY: entries are removed as sites migrate to the gsd-core CLI; new or changed entries fail lint:ci. `count` is the number of byte-identical (file, text) occurrences acknowledged at this site — a run producing fewer fails as a partial migration, more fails as an unacknowledged new copy. Emptied by #3218: all 6 recorded sites (7 occurrences) migrated to `gsd_run query find-phase` — see gsd-core/workflows/{execute-plan,plan-phase,plan-review-convergence,progress}.md.",
+  "entries": []
+}

package/scripts/baselines/planning-snapshot-bypass-baseline.json

@@ -0,0 +1,12 @@
+{
+  "$comment": "ADR-3180 §8.1 rule 2 ratchet, owned by Phase 11 (#3309). See scripts/lint-planning-snapshot-bypass-drift.cjs. SHRINK-ONLY: entries are removed as cmdValidateHealth migrates onto src/planning-snapshot.cts; new or changed entries fail lint:ci. `count` is the number of byte-identical (file, text) occurrences acknowledged at this site — a run producing fewer fails as a partial migration, more fails as an unacknowledged new copy.",
+  "entries": [
+    {
+      "file": "src/verify.cts",
+      "text": "const stateContent = fs.readFileSync(statePath, 'utf-8');",
+      "derivation": "planning-snapshot-bypass",
+      "owner_issue": "#3309",
+      "count": 1
+    }
+  ]
+}

package/scripts/baselines/unreachable-guard-drift-baseline.json

@@ -0,0 +1,4 @@
+{
+  "$comment": "#3409 unreachable-shell-guard ratchet. See scripts/lint-unreachable-guard-drift.cjs. SHRINK-ONLY: entries are removed as sites migrate off the unreachable-arm shape; new or changed entries fail lint:ci. `count` is the number of byte-identical (file, text) occurrences acknowledged at this site — a run producing fewer fails as a partial migration, more fails as an unacknowledged new copy.",
+  "entries": []
+}

package/scripts/build-hooks.js

@@ -51,6 +51,13 @@ const HOOKS_TO_COPY = [
   // .planning/config.json changes mid-session. Must ship to dist so the
   // installer can copy it to the target hooks/ dir and register FileChanged.
   'gsd-config-reload.js',
+  // Agent-dispatch isolation guard (#3045): blocks an executor Agent()
+  // dispatch missing its harness isolation parameter when the project
+  // resolves to harness-worktree. Requires the sibling
+  // gsd-core/bin/lib/{runtime-name-policy,capability-registry}.cjs modules
+  // at runtime — those ship as part of the full gsd-core/ tree, not via this
+  // list.
+  'gsd-agent-isolation-guard.js',
   'gsd-prompt-guard.js',
   'gsd-read-guard.js',
   'gsd-read-injection-scanner.js',
@@ -58,6 +65,8 @@ const HOOKS_TO_COPY = [
   'gsd-update-banner.js',
   'gsd-workflow-guard.js',
   'gsd-worktree-path-guard.js',
+  // Catastrophic-shrink guard for curated .planning/ artifacts (#2255, fix 3 of #973)
+  'gsd-write-guard.js',
   // Community hooks (bash, opt-in via .planning/config.json hooks.community)
   'gsd-session-state.sh',
   'gsd-validate-commit.sh',