@opengsd/gsd-core 1.9.0 → 1.10.0

package/hooks/lib/isolation-sentinel.js

@@ -0,0 +1,268 @@
+'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;
+    }
+    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.0",
+  "version": "1.10.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,8 @@
     "GEMINI.md",
     "hooks",
     "scripts",
+    "!scripts/gen-emitted-baseline.cjs",
+    "!scripts/qa-smell-ratchet.cjs",
     "pi",
     "vscode"
   ],
@@ -84,16 +86,18 @@
     "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",
@@ -104,7 +108,7 @@
     "lint": "eslint . --cache --cache-location node_modules/.cache/eslint/",
     "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: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: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 +116,11 @@
     "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",
     "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",
     "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 +130,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: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: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;
@@ -287,11 +325,16 @@ module.exports = function gsdPiExtension(pi) {
       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)}`;
+        // #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)}` }] };
       }
       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})`}`;
+      // #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 }] };
     },
   });
 
@@ -376,6 +419,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/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',

package/scripts/changeset/lint.cjs

@@ -12,6 +12,10 @@
  * Tests assert on the typed verdict, never on free text.
  */
 
+// #2988: the repo's integration/default branch — the base every PR targets.
+// Used as the local fallback when GITHUB_BASE_REF is unset (CI sets it).
+const DEFAULT_BASE = 'next';
+
 const LINT_REASON = Object.freeze({
   OK_FRAGMENT_PRESENT: 'ok_fragment_present',
   OK_OPT_OUT_LABEL: 'ok_opt_out_label',
@@ -80,7 +84,10 @@ function main() {
       labels = (event.pull_request?.labels || []).map((l) => l.name);
     } catch { /* fall through */ }
   }
-  const base = process.env.GITHUB_BASE_REF || 'main';
+  // #2988: local fallback must match the repo's integration branch (`next`),
+  // not the release branch (`main`). CI sets GITHUB_BASE_REF explicitly; the
+  // fallback only fires locally, where `next` is the base every PR targets.
+  const base = process.env.GITHUB_BASE_REF || DEFAULT_BASE;
   let changedFiles = [];
   try {
     // Use execFileSync with an argv array — the base ref is interpolated
@@ -145,4 +152,4 @@ function main() {
 
 if (require.main === module) runMain(main);
 
-module.exports = { evaluateLint, LINT_REASON, OPT_OUT_LABEL, isUserFacing, isFragment };
+module.exports = { evaluateLint, LINT_REASON, OPT_OUT_LABEL, isUserFacing, isFragment, DEFAULT_BASE };

package/scripts/changeset/serialize.cjs

@@ -26,7 +26,11 @@ function serializeChangelog(ir) {
     lines.push(`### ${section.type}`);
     lines.push('');
     for (const b of section.bullets) {
-      lines.push(`- ${b.body} (#${b.pr})`);
+      // #3001: indent continuation lines so parseChangelog's continuation-fold
+      // (/^\s+/) picks them up instead of terminating the bullet at the first
+      // blank line. A multi-paragraph body round-trips with content preserved.
+      const body = b.body.replace(/\n/g, '\n  ');
+      lines.push(`- ${body} (#${b.pr})`);
     }
     lines.push('');
   }

package/scripts/gen-capability-matrix.cjs

@@ -190,7 +190,7 @@ ${runtimeTable}
 ### Reviewer capabilities (role: reviewer) — ${reviewerCount}
 
 Reviewer capabilities declare a cross-AI **reviewer lane** — one external CLI or
-model endpoint \`/gsd:review\` hands a plan to (ADR-2782 D3). They are not install
+model endpoint \`/gsd-review\` hands a plan to (ADR-2782 D3). They are not install
 targets: they emit no skills, agents, hooks or surface files, so their
 extension-point and hook-kind cells are \`—\`. A host that is *also* a reviewer
 (Claude, Codex, Cursor, OpenCode, Qwen, Antigravity) keeps one manifest and