@opengsd/gsd-core 1.4.0-rc.1 → 1.4.0-rc.2

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

@@ -26,6 +26,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const installProfiles = require("./install-profiles.cjs");
@@ -33,7 +34,7 @@ const { readActiveProfile, resolveProfile, loadSkillsManifest, } = installProfil
 const clusters_cjs_1 = require("./clusters.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const runtimeArtifactLayout = require("./runtime-artifact-layout.cjs");
-const { findInstallSourceRoot } = runtimeArtifactLayout;
+const { findInstallSourceRoot, getInstallExports } = runtimeArtifactLayout;
 const SURFACE_FILE_NAME = '.gsd-surface.json';
 /**
  * Read the surface state from a runtime config directory.
@@ -210,8 +211,29 @@ function applySurface(runtimeConfigDir, layout, manifest, clusterMap) {
     }
     const skillManifest = normalizeSkillManifest(layout.configDir, manifest);
     const resolved = resolveSurface(layout.configDir, skillManifest, clusterMap);
+    // Mirror installRuntimeArtifacts: skills kinds get per-runtime path rewrites
+    // so SKILL.md bodies reference the install target (pathPrefix), not the
+    // converter's default ~/.claude paths (#813). Computed lazily so command-only
+    // runtimes do not trigger the install.js require.
+    let pathPrefix = null;
     for (const kind of layout.kinds) {
         const staged = kind.stage(resolved);
+        if (kind.kind === 'skills') {
+            const installExports = getInstallExports();
+            if (pathPrefix === null) {
+                const scope = layout.scope ?? 'global';
+                const resolvedTarget = node_path_1.default.resolve(layout.configDir).replace(/\\/g, '/');
+                const homeDir = node_os_1.default.homedir().replace(/\\/g, '/');
+                pathPrefix = installExports.computePathPrefix({
+                    isGlobal: scope === 'global',
+                    isOpencode: layout.runtime === 'opencode',
+                    isWindowsHost: process.platform === 'win32',
+                    resolvedTarget,
+                    homeDir,
+                });
+            }
+            installExports.applyRuntimeContentRewritesInPlace(staged, layout.runtime, pathPrefix);
+        }
         const dest = node_path_1.default.join(layout.configDir, kind.destSubpath);
         _syncGsdDir(staged, dest, kind, skillManifest);
     }
@@ -335,20 +357,41 @@ function _syncGsdDir(stagedDir, destDir, kind, manifest) {
         pruneSkillDirs(destDir, stagedDirs, kindPrefix, manifest);
     }
     else {
-        // commands / agents kind: work with .md files
-        const stagedFiles = new Set(node_fs_1.default.readdirSync(stagedDir).filter(f => f.endsWith('.md')));
-        // Copy files from staged to dest (overwrite to keep content current)
+        // commands / agents kind: mirror installRuntimeArtifacts (_copyStaged /
+        // _removeGsdEntries in bin/install.js) so surface produces the SAME files as a
+        // fresh install (#816). Flat command dirs (opencode/cursor/augment/kilo) take
+        // the gsd- prefix on copy; namespaced command dirs (commands/gsd) and agents
+        // keep their staged names. Copying staged names verbatim previously diverged
+        // from install and orphaned the installed gsd-*.md files, and the unscoped
+        // prune deleted user-owned command files.
+        //
+        // NOTE: the destName rule below intentionally mirrors bin/install.js
+        // `_copyStaged` (the `namespacedByDir` decision). Keep them in sync.
+        const destLast = (typeof kind === 'object' && kind !== null && kind.destSubpath)
+            ? node_path_1.default.basename(kind.destSubpath)
+            : '';
+        const prefixStem = kindPrefix ? kindPrefix.replace(/-$/, '') : '';
+        const namespacedByDir = kindName === 'commands' && destLast === prefixStem;
+        const stagedFiles = node_fs_1.default.readdirSync(stagedDir).filter(f => f.endsWith('.md'));
+        const stagedDestNames = new Set();
         for (const file of stagedFiles) {
-            node_fs_1.default.copyFileSync(node_path_1.default.join(stagedDir, file), node_path_1.default.join(destDir, file));
+            const destName = (kindName === 'agents' || namespacedByDir)
+                ? file
+                : `${kindPrefix}${file.slice(0, -3)}.md`;
+            node_fs_1.default.copyFileSync(node_path_1.default.join(stagedDir, file), node_path_1.default.join(destDir, destName));
+            stagedDestNames.add(destName);
         }
-        // Remove gsd-only files from dest that aren't in staged set
-        // For commands dir: all .md files are gsd skills
-        // For agents dir: only gsd-* files
-        const destEntries = node_fs_1.default.readdirSync(destDir).filter(f => f.endsWith('.md'));
-        for (const file of destEntries) {
+        // Prune stale GSD-owned files not in the staged set, preserving user-owned files
+        // (mirrors install's prefix-scoped _removeGsdEntries):
+        //   - agents: only gsd-* are GSD-owned
+        //   - flat command dirs: only `${kindPrefix}`-prefixed are GSD-owned
+        //   - namespaced command dirs: the whole dir is GSD-owned
+        for (const file of node_fs_1.default.readdirSync(destDir).filter(f => f.endsWith('.md'))) {
             if (kindName === 'agents' && !file.startsWith('gsd-'))
                 continue;
-            if (!stagedFiles.has(file)) {
+            if (kindName === 'commands' && !namespacedByDir && kindPrefix && !file.startsWith(kindPrefix))
+                continue;
+            if (!stagedDestNames.has(file)) {
                 try {
                     node_fs_1.default.unlinkSync(node_path_1.default.join(destDir, file));
                 }

package/gsd-core/workflows/help/modes/full.md

@@ -550,11 +550,12 @@ Usage: `/gsd:help --full`
 Usage: `/gsd:help debug`
 Usage: `/gsd:help --brief debug`
 
-**`/gsd:update [--sync] [--reapply]`**
+**`/gsd:update [--sync] [--reapply] [--next | --rc]`**
 Update GSD to latest version with changelog preview.
 
 - `--sync` — sync managed GSD skills across runtime roots (replaces the former `gsd-sync-skills`)
 - `--reapply` — reapply local modifications after an update (replaces the former `gsd-reapply-patches`)
+- `--next` (alias `--rc`) — install/refresh from the `@next` RC dist-tag instead of `@latest` (ADR #660); omit for the stable channel
 
 - Shows installed vs latest version comparison
 - Displays changelog entries for versions you've missed

package/gsd-core/workflows/review.md

@@ -248,9 +248,9 @@ fi
 **Codex:**
 ```bash
 if [ -n "$CODEX_MODEL" ] && [ "$CODEX_MODEL" != "null" ]; then
-  cat /tmp/gsd-review-prompt-{phase}.md | codex exec --model "$CODEX_MODEL" --skip-git-repo-check - 2>/dev/null > /tmp/gsd-review-codex-{phase}.md
+  cat /tmp/gsd-review-prompt-{phase}.md | codex exec --ephemeral --dangerously-bypass-hook-trust --model "$CODEX_MODEL" --skip-git-repo-check - 2>/dev/null > /tmp/gsd-review-codex-{phase}.md
 else
-  cat /tmp/gsd-review-prompt-{phase}.md | codex exec --skip-git-repo-check - 2>/dev/null > /tmp/gsd-review-codex-{phase}.md
+  cat /tmp/gsd-review-prompt-{phase}.md | codex exec --ephemeral --dangerously-bypass-hook-trust --skip-git-repo-check - 2>/dev/null > /tmp/gsd-review-codex-{phase}.md
 fi
 ```
 

package/gsd-core/workflows/update.md

@@ -75,6 +75,25 @@ If multiple runtime installs are detected and the invoking runtime cannot be det
 **If VERSION file missing (version resolves to `0.0.0`):** report the installed version as Unknown and proceed to install (treated as `0.0.0` for comparison).
 </step>
 
+<step name="parse_update_channel">
+Determine the release channel from `$ARGUMENTS`. This selects which npm dist-tag the entire update flow targets — `latest` (stable) by default, or `next` (the RC channel established by ADR #660) when the user opts in with `--next`/`--rc`:
+
+```bash
+case " $ARGUMENTS " in
+  *" --next "*|*" --rc "*)
+    TAG="next"
+    CHANNEL_LABEL="next (RC)"
+    ;;
+  *)
+    TAG="latest"
+    CHANNEL_LABEL="latest (stable)"
+    ;;
+esac
+```
+
+`TAG` is restricted to `latest`/`next` by `check-latest-version.cjs` (it rejects any other value with exit 2), so no arbitrary dist-tag can leak through. Omitting `--next`/`--rc` reproduces the prior behavior exactly: `TAG=latest`.
+</step>
+
 <step name="check_latest_version">
 Check npm for latest version via the deterministic script. **Do NOT run `npm view` or `npm search` directly** — the package name must come from the script, not from a free choice at execution time. (#2992: LLM-driven prescriptions of npm package names produced wrong-package queries; moving the package name into a script constant closes that gap.)
 
@@ -91,7 +110,7 @@ if [ -z "$GSD_DIR" ]; then
   LATEST_VERSION=""
   LATEST_REASON="no_install_detected"
 else
-  LATEST_RESULT="$(node "$GSD_DIR/gsd-core/bin/check-latest-version.cjs" --json 2>/dev/null)"
+  LATEST_RESULT="$(node "$GSD_DIR/gsd-core/bin/check-latest-version.cjs" --json --tag "$TAG" 2>/dev/null)"
   LATEST_STATUS=$?
   # #2993 CR: when node is missing or the script doesn't exist, LATEST_RESULT
   # is empty and piping it to `jq` produces a parse error on stderr while
@@ -114,7 +133,7 @@ fi
 ```text
 Couldn't check for updates (reason: {LATEST_REASON}, exit: {LATEST_STATUS}).
 
-To update manually: `npx -y --package=@opengsd/gsd-core@latest -- gsd-core --global`
+To update manually: `npx -y --package=@opengsd/gsd-core@{TAG} -- gsd-core --global`
 ```
 
 Exit.
@@ -123,6 +142,14 @@ Exit.
 <step name="compare_versions">
 Compare installed vs latest:
 
+**Only when `TAG=next`** (the user passed `--next`/`--rc`), prepend a channel banner so they know they are leaving the stable line — add this line immediately after the `**Latest:**` line in whichever output block renders:
+
+**Channel:** {CHANNEL_LABEL}
+
+On the default stable channel (`TAG=latest`), do NOT add a channel line — the output must match the prior stable behavior exactly.
+
+When `TAG=next`, the "latest" value is the release candidate published under `@next` (e.g. `1.4.0-rc.1`). Apply standard semver precedence for prereleases (`1.4.0-rc.1` is newer than `1.3.1` but older than the final `1.4.0`). Do NOT treat an `-rc.N` suffix as a dev install or as "behind" — offer it as an available update.
+
 **If installed == latest:**
 ```
 ## GSD Update
@@ -327,17 +354,17 @@ RUNTIME_FLAG="--$TARGET_RUNTIME"
 
 **If LOCAL install:**
 ```bash
-npx -y --package=@opengsd/gsd-core@latest -- gsd-core "$RUNTIME_FLAG" --local
+npx -y --package=@opengsd/gsd-core@"$TAG" -- gsd-core "$RUNTIME_FLAG" --local
 ```
 
 **If GLOBAL install:**
 ```bash
-npx -y --package=@opengsd/gsd-core@latest -- gsd-core "$RUNTIME_FLAG" --global
+npx -y --package=@opengsd/gsd-core@"$TAG" -- gsd-core "$RUNTIME_FLAG" --global
 ```
 
 **If UNKNOWN install:**
 ```bash
-npx -y --package=@opengsd/gsd-core@latest -- gsd-core --claude --global
+npx -y --package=@opengsd/gsd-core@"$TAG" -- gsd-core --claude --global
 ```
 
 Capture output. If install fails, show error and exit.

package/hooks/dist/gsd-config-reload.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+// gsd-config-reload.js — FileChanged hook: hot-reload GSD config context
+// Fires when .planning/config.json is modified, created, or deleted.
+//
+// When the user edits .planning/config.json mid-session, this hook reads the
+// updated config and injects a summary as additionalContext so the agent knows
+// the new configuration without requiring a session restart.
+//
+// Input (from Claude Code):
+//   { session_id, cwd, hook_event_name: "FileChanged",
+//     file_path: "/abs/path/.planning/config.json", event: "change"|"add"|"unlink" }
+//
+// Output:
+//   { hookSpecificOutput: { hookEventName: "FileChanged", additionalContext: "..." } }
+//   or exits 0 silently (if config absent, unreadable, or event is "unlink").
+//
+// Enabled for all Claude Code installs. This hook is always-on — it is a
+// no-op when .planning/config.json is absent (ENOENT → exit 0).
+
+const fs = require('fs');
+const path = require('path');
+
+let input = '';
+// Timeout guard: if stdin does not close within 8s exit silently rather than
+// hanging until Claude Code kills the process and reports "hook error".
+const stdinTimeout = setTimeout(() => process.exit(0), 8000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => (input += chunk));
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const event = data.event; // "change" | "add" | "unlink"
+    const filePath = data.file_path || '';
+    const cwd = data.cwd || process.cwd();
+
+    // Only handle the GSD planning config — verify both basename and that the
+    // resolved path is .planning/config.json relative to cwd.  The hook
+    // matcher ('config.json') fires on any watched config.json; this guard
+    // ensures an unrelated config.json in node_modules/ or elsewhere does not
+    // inject spurious additionalContext.
+    const basename = path.basename(filePath);
+    if (basename !== 'config.json') {
+      process.exit(0);
+    }
+    const expectedPath = path.resolve(cwd, '.planning', 'config.json');
+    if (path.resolve(filePath) !== expectedPath) {
+      process.exit(0);
+    }
+
+    // On unlink (deletion) emit a brief notice and exit
+    if (event === 'unlink') {
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'FileChanged',
+          additionalContext:
+            'GSD config (.planning/config.json) was deleted. ' +
+            'Falling back to built-in defaults for this session.',
+        },
+      }));
+      process.exit(0);
+    }
+
+    // Read the updated config file
+    let config;
+    try {
+      const raw = fs.readFileSync(filePath, 'utf8');
+      config = JSON.parse(raw);
+    } catch (e) {
+      if (e && e.code === 'ENOENT') process.exit(0);
+      // Malformed JSON — inform the agent without crashing
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'FileChanged',
+          additionalContext:
+            'GSD config (.planning/config.json) was modified but could not be parsed. ' +
+            'Check the file for JSON syntax errors.',
+        },
+      }));
+      process.exit(0);
+    }
+
+    // Build a concise summary of key config fields the agent cares about
+    const lines = ['GSD config reloaded (.planning/config.json updated):'];
+
+    if (config.runtime) lines.push(`  runtime: ${config.runtime}`);
+    if (config.mode) lines.push(`  mode: ${config.mode}`);
+
+    // hooks section (opt-in toggles agents act on)
+    if (config.hooks && typeof config.hooks === 'object') {
+      const hookKeys = Object.entries(config.hooks)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(', ');
+      if (hookKeys) lines.push(`  hooks: { ${hookKeys} }`);
+    }
+
+    // workflow section (key toggles)
+    if (config.workflow && typeof config.workflow === 'object') {
+      const wfKeys = Object.entries(config.workflow)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(', ');
+      if (wfKeys) lines.push(`  workflow: { ${wfKeys} }`);
+    }
+
+    // model overrides (agents use these)
+    if (config.models && typeof config.models === 'object') {
+      const modelKeys = Object.entries(config.models)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(', ');
+      if (modelKeys) lines.push(`  models: { ${modelKeys} }`);
+    }
+
+    if (lines.length === 1) {
+      // No notable fields — still confirm the reload happened
+      lines.push('  (no notable keys changed)');
+    }
+
+    const additionalContext = lines.join('\n');
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'FileChanged',
+        additionalContext,
+      },
+    }));
+  } catch (e) {
+    // Silent fail — never block the session on a config reload error
+    process.exit(0);
+  }
+});

package/hooks/dist/gsd-cursor-post-tool.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+// gsd-cursor-post-tool.js — Cursor postToolUse hook (issue #777)
+//
+// Cursor invokes this script after each tool call completes.
+// Protocol: JSON from Cursor on stdin; JSON response on stdout.
+//
+// Input schema (cursor postToolUse):
+//   { tool_name, tool_input, tool_output, duration,
+//     conversation_id, generation_id, model, hook_event_name,
+//     cursor_version, workspace_roots, user_email, transcript_path }
+//
+// Output schema (cursor postToolUse):
+//   { additional_context?: string }   ← injected as context after the tool use
+//
+// Behaviour:
+//   - After a write-class tool that targets .planning/, reminds the agent
+//     to keep STATE.md current.
+//   - Fails open: any error silently exits 0.
+//
+// Cursor docs: https://cursor.com/docs/hooks
+
+'use strict';
+
+const WRITE_TOOL_RE = /write|edit|replace|create|delete|remove|append|apply|patch|insert|mkdir/i;
+const PATH_KEY_RE = /^(path|file|file_?path|filepath|target_?path|target|dir|directory|uri|filename)$/i;
+const PLANNING_PATH_RE = /(^|[\\/])\.planning([\\/]|$)/;
+
+let raw = '';
+const stdinTimeout = setTimeout(() => {
+  // Timeout guard: exit silently rather than hanging.
+  process.exit(0);
+}, 10000);
+
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { raw += chunk; });
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    let input;
+    try { input = JSON.parse(raw || '{}'); } catch { process.stdout.write(JSON.stringify({})); return; }
+
+    const toolName = String(
+      input.tool_name || input.toolName || ''
+    ).toLowerCase();
+
+    const isWrite = WRITE_TOOL_RE.test(toolName);
+    if (!isWrite) { process.stdout.write(JSON.stringify({})); return; }
+
+    // Collect only PATH-bearing field values (not free-form content).
+    const paths = [];
+    const walk = (v, depth) => {
+      if (depth > 5 || paths.length > 64) return;
+      if (Array.isArray(v)) { for (const x of v) walk(x, depth + 1); return; }
+      if (v && typeof v === 'object') {
+        for (const k of Object.keys(v)) {
+          const val = v[k];
+          if (typeof val === 'string' && PATH_KEY_RE.test(k)) paths.push(val);
+          else walk(val, depth + 1);
+        }
+      }
+    };
+    walk(input.tool_input || input.toolInput || {}, 0);
+
+    if (paths.some((p) => PLANNING_PATH_RE.test(p))) {
+      process.stdout.write(JSON.stringify({
+        additional_context:
+          'GSD: .planning/ artifact updated — ensure STATE.md reflects the latest phase and progress.',
+      }));
+      return;
+    }
+  } catch { /* fall through to empty response */ }
+
+  process.stdout.write(JSON.stringify({}));
+});

package/hooks/dist/gsd-cursor-session-start.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+// gsd-cursor-session-start.js — Cursor sessionStart hook (issue #777)
+//
+// Cursor invokes this script at the start of each agent session.
+// Protocol: JSON from Cursor on stdin; JSON response on stdout.
+//
+// Input schema (cursor sessionStart):
+//   { session_id, is_background_agent, composer_mode, conversation_id,
+//     generation_id, model, hook_event_name, cursor_version,
+//     workspace_roots, user_email, transcript_path }
+//
+// Output schema (cursor sessionStart):
+//   { additional_context?: string }   ← injected into the session as context
+//
+// Behaviour:
+//   - If .planning/STATE.md is present, injects a brief state reminder.
+//   - If absent, nudges the user toward /gsd:new-project.
+//   - Fails open: any error silently exits 0 so a hook bug never wedges Cursor.
+//
+// Cursor docs: https://cursor.com/docs/hooks
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const MSG_PRESENT =
+  'GSD: .planning/STATE.md is present — review the current phase and any blockers before acting.';
+const MSG_ABSENT =
+  'GSD: no .planning/ workflow found — run /gsd:new-project to start a tracked workflow.';
+
+let raw = '';
+const stdinTimeout = setTimeout(() => {
+  // Timeout guard: exit silently rather than hanging.
+  process.exit(0);
+}, 10000);
+
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { raw += chunk; });
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const statePath = path.join(process.cwd(), '.planning', 'STATE.md');
+    const statePresent = fs.existsSync(statePath);
+    const msg = statePresent ? MSG_PRESENT : MSG_ABSENT;
+    process.stdout.write(JSON.stringify({ additional_context: msg }));
+  } catch {
+    // Fail open — never block a Cursor session because of a GSD hook error.
+    process.stdout.write(JSON.stringify({}));
+  }
+});

package/hooks/dist/managed-hooks-registry.cjs

@@ -18,7 +18,10 @@
 const MANAGED_HOOKS = [
   'gsd-check-update-worker.js',
   'gsd-check-update.js',
+  'gsd-config-reload.js',
   'gsd-context-monitor.js',
+  'gsd-cursor-post-tool.js',
+  'gsd-cursor-session-start.js',
   'gsd-graphify-update.sh',
   'gsd-phase-boundary.sh',
   'gsd-prompt-guard.js',

package/hooks/gsd-config-reload.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+// gsd-config-reload.js — FileChanged hook: hot-reload GSD config context
+// Fires when .planning/config.json is modified, created, or deleted.
+//
+// When the user edits .planning/config.json mid-session, this hook reads the
+// updated config and injects a summary as additionalContext so the agent knows
+// the new configuration without requiring a session restart.
+//
+// Input (from Claude Code):
+//   { session_id, cwd, hook_event_name: "FileChanged",
+//     file_path: "/abs/path/.planning/config.json", event: "change"|"add"|"unlink" }
+//
+// Output:
+//   { hookSpecificOutput: { hookEventName: "FileChanged", additionalContext: "..." } }
+//   or exits 0 silently (if config absent, unreadable, or event is "unlink").
+//
+// Enabled for all Claude Code installs. This hook is always-on — it is a
+// no-op when .planning/config.json is absent (ENOENT → exit 0).
+
+const fs = require('fs');
+const path = require('path');
+
+let input = '';
+// Timeout guard: if stdin does not close within 8s exit silently rather than
+// hanging until Claude Code kills the process and reports "hook error".
+const stdinTimeout = setTimeout(() => process.exit(0), 8000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => (input += chunk));
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const event = data.event; // "change" | "add" | "unlink"
+    const filePath = data.file_path || '';
+    const cwd = data.cwd || process.cwd();
+
+    // Only handle the GSD planning config — verify both basename and that the
+    // resolved path is .planning/config.json relative to cwd.  The hook
+    // matcher ('config.json') fires on any watched config.json; this guard
+    // ensures an unrelated config.json in node_modules/ or elsewhere does not
+    // inject spurious additionalContext.
+    const basename = path.basename(filePath);
+    if (basename !== 'config.json') {
+      process.exit(0);
+    }
+    const expectedPath = path.resolve(cwd, '.planning', 'config.json');
+    if (path.resolve(filePath) !== expectedPath) {
+      process.exit(0);
+    }
+
+    // On unlink (deletion) emit a brief notice and exit
+    if (event === 'unlink') {
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'FileChanged',
+          additionalContext:
+            'GSD config (.planning/config.json) was deleted. ' +
+            'Falling back to built-in defaults for this session.',
+        },
+      }));
+      process.exit(0);
+    }
+
+    // Read the updated config file
+    let config;
+    try {
+      const raw = fs.readFileSync(filePath, 'utf8');
+      config = JSON.parse(raw);
+    } catch (e) {
+      if (e && e.code === 'ENOENT') process.exit(0);
+      // Malformed JSON — inform the agent without crashing
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'FileChanged',
+          additionalContext:
+            'GSD config (.planning/config.json) was modified but could not be parsed. ' +
+            'Check the file for JSON syntax errors.',
+        },
+      }));
+      process.exit(0);
+    }
+
+    // Build a concise summary of key config fields the agent cares about
+    const lines = ['GSD config reloaded (.planning/config.json updated):'];
+
+    if (config.runtime) lines.push(`  runtime: ${config.runtime}`);
+    if (config.mode) lines.push(`  mode: ${config.mode}`);
+
+    // hooks section (opt-in toggles agents act on)
+    if (config.hooks && typeof config.hooks === 'object') {
+      const hookKeys = Object.entries(config.hooks)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(', ');
+      if (hookKeys) lines.push(`  hooks: { ${hookKeys} }`);
+    }
+
+    // workflow section (key toggles)
+    if (config.workflow && typeof config.workflow === 'object') {
+      const wfKeys = Object.entries(config.workflow)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(', ');
+      if (wfKeys) lines.push(`  workflow: { ${wfKeys} }`);
+    }
+
+    // model overrides (agents use these)
+    if (config.models && typeof config.models === 'object') {
+      const modelKeys = Object.entries(config.models)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(', ');
+      if (modelKeys) lines.push(`  models: { ${modelKeys} }`);
+    }
+
+    if (lines.length === 1) {
+      // No notable fields — still confirm the reload happened
+      lines.push('  (no notable keys changed)');
+    }
+
+    const additionalContext = lines.join('\n');
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'FileChanged',
+        additionalContext,
+      },
+    }));
+  } catch (e) {
+    // Silent fail — never block the session on a config reload error
+    process.exit(0);
+  }
+});