@opengsd/gsd-core 1.7.0-rc.4 → 1.7.0-rc.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/gsd-core",
-  "version": "1.7.0-rc.4",
+  "version": "1.7.0-rc.6",
   "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": {
@@ -20,7 +20,9 @@
     ".opencode",
     "GEMINI.md",
     "hooks",
-    "scripts"
+    "scripts",
+    "pi",
+    "vscode"
   ],
   "keywords": [
     "claude",
@@ -78,6 +80,7 @@
     "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:hooks": "node scripts/build-hooks.js",
@@ -86,6 +89,8 @@
     "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",
+    "validate:registry": "node scripts/validate-registry.cjs",
     "prepack": "npm run build:lib",
     "prepare": "npm run build:lib",
     "version": "node scripts/sync-manifest-versions.cjs --stage && node scripts/gen-capability-registry.cjs --write && git add gsd-core/bin/lib/capability-registry.cjs",
@@ -94,7 +99,7 @@
     "pretest:coverage": "npm run build:lib && npm run lint:skill-deps",
     "lint": "eslint . --cache --cache-location node_modules/.cache/eslint/",
     "lint:fix": "eslint . --fix",
-    "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",
+    "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/validate-registry.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",
@@ -102,7 +107,7 @@
     "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",
+    "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",
     "lint:docs": "node scripts/lint-docs-required.cjs",
     "lint:legacy-name": "node scripts/lint-legacy-dir-name.cjs",
     "ci:test-scope": "node scripts/ci-test-scope.cjs",

package/pi/gsd.cjs

@@ -0,0 +1,354 @@
+'use strict';
+
+/**
+ * GSD extension for pi (pi.dev) — ADR-1239 Phase D / #1944, upgraded #2102 Stage 2.
+ *
+ * pi is a Programmatic-CLI host whose TS extensions implement the ExtensionAPI
+ * (`@earendil-works/pi-coding-agent`): registerCommand({handler(args, ctx)}) /
+ * registerTool({execute(toolCallId, params, signal, onUpdate, ctx)}) / pi.on(event, handler).
+ * This extension binds GSD's command surface to pi via the imperative adapter
+ * path — the programmatic-CLI peer of the OpenCode worked binding.
+ *
+ * Installation: copy this file to ~/.pi/agent/extensions/gsd.cjs (pi loads
+ * extensions via jiti from that dir). The engine is resolved from the installed
+ * GSD tree (walk-up like the OpenCode plugin). pi's shared hooks/ bundle
+ * (hooks/*.js + hooks/lib/git-cmd.js) is installed alongside the extension —
+ * capabilities/pi/capability.json does NOT set
+ * `hostBehaviors.skipSharedHooksInstall` (#2102 Stage 2 fix; pi is
+ * architecturally identical to OpenCode here: `hooksSurface: 'none'` +  a
+ * native extension that spawns the staged hooks — not Kilo/ZCode's
+ * no-plugin-surface case, where the same hooks would be genuine dead weight).
+ * This is what makes the event bridges below (and the tokenizer require)
+ * resolve for real in an installed tree, not just in this dev repo.
+ *
+ * Engine entry: dispatch is SUBPROCESS-REUSE to gsd-tools.cjs (bounded,
+ * no-throw — dispatchGsdCommand in shell-command-projection.cjs), NOT an
+ * in-process command-routing hub. No fully-populated hub factory exists
+ * anywhere in gsd-core — every createHub() caller in the tree builds a
+ * single-family hub for its own narrow purpose — so the "in-process createHub"
+ * framing of the original #1944 cut was aspirational and is not achievable
+ * without a hub factory that doesn't exist. This mirrors the precedent already
+ * established for the OpenCode/Kilo hook bridge (.opencode/plugins/gsd-core.js
+ * header: "Architecture: SUBPROCESS REUSE ... spawns existing hook scripts as
+ * child processes") — the same pattern, applied to command dispatch. The
+ * companion MCP server (gsd-mcp-server) dispatches through the SAME shared
+ * helper for out-of-process hosts.
+ *
+ * @param {object} pi  pi ExtensionAPI (registerTool/registerCommand/on/…)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+// Resolve the GSD engine tree (the dir holding gsd-core/ + hooks/).
+// Works across dev (<root>/pi/gsd.cjs → <root>) and installed layouts.
+function resolveEngineRoot(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 6; i++) {
+    if (fs.existsSync(path.join(dir, 'gsd-core'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return path.resolve(startDir, '..');
+}
+
+const ENGINE_ROOT = resolveEngineRoot(__dirname);
+const GSD_CORE = path.join(ENGINE_ROOT, 'gsd-core');
+
+// ── 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
+// commands/ dir) — it would always return []. This is a self-contained,
+// hand-curated subset of the STABLE top-level families documented by
+// `node gsd-core/bin/gsd-tools.cjs --help` (gsd-tools.cjs:689-705). Named +
+// exported (via _internals) so a test can assert against it directly.
+const PI_COMMAND_FAMILIES = Object.freeze([
+  'agent', 'capability', 'check', 'commit', 'config-get', 'config-path',
+  'config-set', 'effort', 'git', 'graphify', 'init', 'intel', 'learnings',
+  'list-todos', 'loop', 'milestone', 'phase', 'phases', 'progress',
+  'requirements', 'research-plan', 'research-store', 'resolve-granularity',
+  'resolve-model', 'roadmap', 'scaffold', 'smart-entry', 'state', 'task',
+  'template', 'user-story', 'validate', 'verify', 'workstream', 'worktree',
+]);
+
+/**
+ * Filter PI_COMMAND_FAMILIES by prefix (startsWith). Returns null when there
+ * are no matches, per pi's `AutocompleteItem[]|null` contract.
+ * @param {string} prefix
+ * @returns {{value: string, label: string}[] | null}
+ */
+function getArgumentCompletions(prefix) {
+  const p = typeof prefix === 'string' ? prefix : '';
+  const matches = PI_COMMAND_FAMILIES.filter((name) => name.startsWith(p));
+  if (matches.length === 0) return null;
+  return matches.map((value) => ({ value, label: value }));
+}
+
+/**
+ * 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
+ * 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
+ * hooks/lib/git-cmd.js — is installed alongside the extension for real
+ * (mirrors OpenCode, whose native plugin also spawns the staged hooks/*.js
+ * bundle). The require below is therefore the PRIMARY, live path in an
+ * installed pi tree; the whitespace-split fallback stays as defense-in-depth
+ * for a corrupted/partial install (e.g. a user who deleted hooks/lib/ by
+ * hand) rather than the only-ever-taken path.
+ * @param {string} rawArgs
+ * @returns {{ family: string, subcommand?: string, args: string[] }}
+ */
+function parseGsdCommandArgs(rawArgs) {
+  let tokenize;
+  try {
+    ({ tokenize } = require(path.join(ENGINE_ROOT, 'hooks', 'lib', 'git-cmd.js')));
+  } catch {
+    tokenize = (s) => String(s || '').split(/\s+/).filter(Boolean);
+  }
+  const tokens = tokenize(typeof rawArgs === 'string' ? rawArgs : '');
+  return {
+    // Empty args → dispatch gsd-tools.cjs's own --help surface (a real,
+    // working, ok:true default — NOT the 'query'/'help' pairing the original
+    // #1944 cut used, which is not a valid gsd-tools.cjs command).
+    family: tokens[0] || '--help',
+    subcommand: tokens[1],
+    args: tokens.slice(2),
+  };
+}
+
+/**
+ * Best-effort TypeBox schema for gsd_invoke's `parameters`, falling back to a
+ * plain JSON-Schema object when the `typebox` package is unavailable (it is
+ * NOT a gsd-core dependency — pi's own ExtensionAPI contract expects TypeBox,
+ * but nothing in this repo installs it). TypeBox schemas ARE JSON Schema, so
+ * the fallback object is structurally equivalent for hosts that accept plain
+ * JSON Schema; this is a best-effort shim for the flat-file extension case.
+ * @returns {object}
+ */
+function buildGsdInvokeParameters() {
+  try {
+    const typebox = require('typebox');
+    const Type = typebox && typebox.Type;
+    if (Type) {
+      return Type.Object({
+        family: Type.String(),
+        subcommand: Type.Optional(Type.String()),
+        args: Type.Optional(Type.Array(Type.String())),
+      });
+    }
+  } catch {
+    // typebox is not installed in this environment — fall through.
+  }
+  process.stderr.write(
+    'gsd: typebox unavailable — gsd_invoke "parameters" falling back to a plain JSON-schema object.\n',
+  );
+  return {
+    type: 'object',
+    properties: {
+      family: { type: 'string' },
+      subcommand: { type: 'string' },
+      args: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['family'],
+  };
+}
+
+/**
+ * Build the `before_provider_request` handler that steers pi's model
+ * selection to GSD's tier-resolved id (modelMode: 'active' per
+ * capabilities/pi/capability.json). GSD does NOT call `pi.registerProvider` —
+ * that registers a NEW model provider; GSD's job here is only to pick a
+ * tier-appropriate id AMONG pi's EXISTING built-in anthropic models, so
+ * registerProvider would be the wrong primitive (it would wrongly add a fake
+ * provider instead of steering the real one).
+ *
+ * v1 tier policy: GSD does not yet expose a per-turn/per-agent tier signal to
+ * this event, so a conservative fixed default tier is used (parameterized —
+ * default 'sonnet' — so a future richer signal, or a test, can override it).
+ *
+ * ASSUMPTION (flagged — verify against a live pi host): the event payload's
+ * model field is named `model`, matching the anthropic-messages payload shape
+ * (Context7-confirmed for the wire protocol; pi's own before_provider_request
+ * event schema was not independently verifiable in this environment). If pi's
+ * actual field name differs, this returns the WRONG key and pi's fail-open
+ * default takes over only because bare-model-id mismatches degrade to
+ * provider-level errors, not GSD-level ones — a discrepancy here needs a
+ * live-host smoke test before shipping past this stage.
+ *
+ * Fail-open: any resolution failure (or a null/falsy resolved model — e.g. an
+ * unrecognized tier) returns `undefined`, leaving pi's model choice untouched.
+ * NEVER returns a payload with a missing/empty model id.
+ *
+ * @param {{ tier?: string }} [opts]
+ * @returns {(event: object, ctx: object) => Promise<object|undefined>}
+ */
+function buildBeforeProviderRequestHandler({ tier = 'sonnet' } = {}) {
+  return async function onBeforeProviderRequest(event, ctx) {
+    try {
+      const effectiveCwd = (ctx && ctx.cwd) || process.cwd();
+      const { resolveTierEntry } = require(path.join(GSD_CORE, 'bin', 'lib', 'model-resolver.cjs'));
+      const { loadConfig } = require(path.join(GSD_CORE, 'bin', 'lib', 'config-loader.cjs'));
+      const config = loadConfig(effectiveCwd);
+      const overrides = (config && config.model_profile_overrides) || undefined;
+      const entry = resolveTierEntry({ runtime: 'pi', tier, overrides });
+      const modelId = entry && typeof entry.model === 'string' && entry.model.length > 0 ? entry.model : null;
+      if (!modelId) return undefined; // fail-open — leave pi's model untouched
+      const basePayload = (event && typeof event === 'object' && event.payload && typeof event.payload === 'object')
+        ? event.payload
+        : {};
+      return { ...basePayload, model: modelId };
+    } catch {
+      return undefined; // fail-open on any resolution error
+    }
+  };
+}
+
+/**
+ * Bounded subprocess bridge to GSD's Claude Code hook scripts. Mirrors
+ * .opencode/plugins/gsd-core.js's `runHook` (SUBPROCESS-REUSE): spawns
+ * `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 {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 (!fs.existsSync(hookPath)) return { stdout: '', exitCode: 0, timedOut: false };
+  const timeout = opts.timeout || 8000;
+  let result;
+  try {
+    result = spawnSync(process.execPath, [hookPath], {
+      input: JSON.stringify(payload || {}),
+      encoding: 'utf8',
+      timeout,
+      cwd: opts.cwd || process.cwd(),
+      windowsHide: true,
+    });
+  } catch {
+    return { stdout: '', exitCode: 0, timedOut: false };
+  }
+  const stdout = (result && typeof result.stdout === 'string') ? result.stdout.trim() : '';
+  const exitCode = (result && result.status != null) ? result.status : 0;
+  return { stdout, exitCode, timedOut: !!(result && result.signal === 'SIGTERM') };
+}
+
+module.exports = function gsdPiExtension(pi) {
+  if (!pi || typeof pi !== 'object') {
+    throw new TypeError('gsdPiExtension: pi ExtensionAPI is required');
+  }
+
+  // ── /gsd command: dispatch through gsd-tools.cjs (subprocess-reuse) ──────
+  pi.registerCommand('gsd', {
+    description: 'Invoke a GSD command via the embedded engine (subprocess-reuse adapter).',
+    getArgumentCompletions,
+    handler: async (args, ctx) => {
+      const cwd = (ctx && ctx.cwd) || process.cwd();
+      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)}`;
+      }
+      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})`}`;
+    },
+  });
+
+  // ── gsd_invoke tool: programmatic command invocation ────────────────────
+  pi.registerTool({
+    name: 'gsd_invoke',
+    label: 'GSD Invoke',
+    description: 'Invoke a GSD command family/subcommand through the engine.',
+    parameters: buildGsdInvokeParameters(),
+    execute: async (toolCallId, params, signal, onUpdate, ctx) => {
+      const p = (params && typeof params === 'object') ? params : {};
+      const family = typeof p.family === 'string' ? p.family : '';
+      if (!family) {
+        return { content: [{ type: 'text', text: 'gsd_invoke requires a non-empty string "family".' }] };
+      }
+      const subcommand = typeof p.subcommand === 'string' ? p.subcommand : undefined;
+      const invokeArgs = Array.isArray(p.args) ? p.args : [];
+      const cwd = (ctx && ctx.cwd) || process.cwd();
+      let dispatchGsdCommand;
+      try {
+        ({ dispatchGsdCommand } = require(path.join(GSD_CORE, 'bin', 'lib', 'shell-command-projection.cjs')));
+      } catch (e) {
+        return { content: [{ type: 'text', text: `GSD engine unavailable: ${e && e.message ? e.message : String(e)}` }] };
+      }
+      const result = dispatchGsdCommand({ family, subcommand, args: invokeArgs, cwd });
+      const text = result.ok ? result.stdout : (result.stderr || result.stdout || `dispatch failed (exit ${result.code})`);
+      return { content: [{ type: 'text', text }] };
+    },
+  });
+
+  // ── before_provider_request: active-model steering (modelMode: 'active') ──
+  // GSD steers pi's EXISTING built-in anthropic models; it does NOT call
+  // pi.registerProvider (that would wrongly register a NEW fake provider —
+  // see buildBeforeProviderRequestHandler's doc comment).
+  pi.on('before_provider_request', buildBeforeProviderRequestHandler());
+
+  // ── Event bindings: bounded subprocess bridge to GSD's hook scripts ──────
+  // Each binding fails open — a hook error/timeout/missing-file never blocks
+  // pi (mirrors .opencode/plugins/gsd-core.js's runHook SUBPROCESS-REUSE
+  // pattern, applied to pi's ExtensionAPI event names).
+
+  // session_start → SessionStart-equivalent bootstrap.
+  pi.on('session_start', async (event, ctx) => {
+    try {
+      const cwd = (ctx && ctx.cwd) || process.cwd();
+      runHook('gsd-ensure-canonical-path.js', { hook_event_name: 'SessionStart', cwd }, { cwd });
+    } catch { /* fail-open */ }
+  });
+
+  // before_agent_start → workflow-guard bridge. Forward-compatible binding:
+  // gsd-workflow-guard.js's current triggers are tool-scoped (Write/Edit/
+  // Bash via tool_name/tool_input), so with no tool_name in the payload it
+  // fires as a safe no-op today — wired so a future agent-start-scoped check
+  // can attach without a plugin change (mirrors the OpenCode session.idle
+  // recognized-but-unused sentinel pattern).
+  pi.on('before_agent_start', async (event, ctx) => {
+    try {
+      const cwd = (ctx && ctx.cwd) || process.cwd();
+      runHook('gsd-workflow-guard.js', { hook_event_name: 'before_agent_start', cwd }, { cwd });
+    } catch { /* fail-open */ }
+  });
+
+  // session_before_compact → PreCompact-equivalent (context-usage bridge).
+  pi.on('session_before_compact', async (event, ctx) => {
+    try {
+      const cwd = (ctx && ctx.cwd) || process.cwd();
+      runHook('gsd-context-monitor.js', { hook_event_name: 'PreCompact', cwd }, { cwd });
+    } catch { /* fail-open */ }
+  });
+
+  // tool_call event: lifecycle hook bridge attachment point (kept from the
+  // original cut — the PreToolUse/PostToolUse tool_name/tool_input mapping
+  // is a follow-up once pi's tool_call payload shape is verified against a
+  // live host).
+  pi.on('tool_call', async function () {
+    /* GSD hook bridge attachment point (PreToolUse/PostToolUse mapping). */
+  });
+};
+
+// Test-only internals (mirrors the OpenCode plugin pattern) — wired to the
+// real functions (not stubs) so tests can exercise parsing/completions/model
+// resolution WITHOUT a live pi runtime.
+module.exports._internals = {
+  resolveEngineRoot,
+  parseGsdCommandArgs,
+  getArgumentCompletions,
+  PI_COMMAND_FAMILIES,
+  buildBeforeProviderRequestHandler,
+  buildGsdInvokeParameters,
+  runHook,
+};

package/scripts/build-hooks.js

@@ -37,9 +37,16 @@ const HOOKS_TO_COPY = [
   // so require('./managed-hooks-registry.cjs') resolves in the installed hooks/ dir.
   'managed-hooks-registry.cjs',
   'gsd-context-monitor.js',
-  // Cursor lifecycle hooks (issue #777): sessionStart context injection + postToolUse monitor
+  // Cursor lifecycle hooks (#777 + ADR-1239/#2089): 6 managed events
   'gsd-cursor-session-start.js',
   'gsd-cursor-post-tool.js',
+  'gsd-cursor-pre-tool.js',
+  'gsd-cursor-stop.js',
+  'gsd-cursor-subagent-start.js',
+  'gsd-cursor-subagent-stop.js',
+  // Windsurf/Cascade lifecycle hooks (ADR-1239/#2100 Stage 2): 2 blocking events
+  'gsd-windsurf-pre-write.js',
+  'gsd-windsurf-pre-command.js',
   // Claude Code FileChanged hook (#770) — hot-reloads gsd config when
   // .planning/config.json changes mid-session. Must ship to dist so the
   // installer can copy it to the target hooks/ dir and register FileChanged.

package/scripts/gen-golden-install-parity-zcode.cjs

@@ -26,7 +26,16 @@ const VOLATILE_FILES = new Set([
   '.gsd-source',
   'gsd-core/CHANGELOG.md',
 ]);
-const HOOK_CONFIG_FILES = new Set(['settings.json', 'hooks.json']);
+// Must match tests/golden-install-parity.test.cjs exactly — settings.local.json
+// (Claude LOCAL hook surface, #338/#2086) embeds the same platform-varying
+// node-runner command and is excluded there; omitting it here mis-generated the
+// claude-local fixture (#2100).
+const HOOK_CONFIG_FILES = new Set(['settings.json', 'settings.local.json', 'hooks.json']);
+// Kimi's native config.toml (#2095) — see tests/golden-install-parity.test.cjs'
+// HOOK_CONFIG_RELATIVE_PATHS comment for why this is an exact relative-path
+// exclusion rather than a HOOK_CONFIG_FILES basename entry (a basename entry
+// would also blind Codex's stable, platform-independent config.toml fixture).
+const HOOK_CONFIG_RELATIVE_PATHS = new Set(['.kimi/config.toml']);
 const EXCLUDED_PREFIXES = ['gsd-core/bin/lib/'];
 
 function buildParityManifest(configDir, root) {
@@ -36,6 +45,7 @@ function buildParityManifest(configDir, root) {
     const rel = path.relative(configDir, full).split(path.sep).join('/');
     if (VOLATILE_FILES.has(rel)) continue;
     if (HOOK_CONFIG_FILES.has(path.basename(rel))) continue;
+    if (HOOK_CONFIG_RELATIVE_PATHS.has(rel)) continue;
     if (EXCLUDED_PREFIXES.some((p) => rel.startsWith(p))) continue;
     const content = fs.readFileSync(full);
     const normalized = content.toString('utf8').split(root).join('<HOME>').split(PKG_VERSION).join('<VERSION>');

package/scripts/gen-registry.cjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * scripts/gen-registry.cjs — generates docs/registries/capability-registry.md
+ * (and, once PR2 ships docs/registries/eos.json, docs/registries/eos-registry.md)
+ * from the corresponding source JSON, via registry-schema.cjs#renderMarkdown.
+ * Issue #2182.
+ *
+ * NOT to be confused with `scripts/gen-capability-registry.cjs`: that script
+ * generates the RUNTIME capability manifest consumed by the host at runtime
+ * (`gsd-core/bin/lib/capability-registry.cjs`, built from every
+ * `capabilities/<id>/capability.json` declaration). THIS script instead
+ * generates the human-facing DOCUMENTATION catalog pages
+ * (`docs/registries/*.md`) from the third-party discoverability registry
+ * source JSON (`docs/registries/{capabilities,eos}.json`). The two pipelines
+ * are independent — do not conflate them.
+ *
+ * Usage:
+ *   node scripts/gen-registry.cjs              # print rendered markdown(s) to stdout
+ *   node scripts/gen-registry.cjs --write      # write the *-registry.md file(s)
+ *   node scripts/gen-registry.cjs --check      # exit 1 if a committed *-registry.md is stale
+ *
+ * Root is resolved from process.cwd() (not __dirname) — mirrors
+ * scripts/validate-registry.cjs so both are drivable as subprocesses against
+ * isolated temp-fixture directories via `cwd`.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+const { renderMarkdown } = require('./registry-schema.cjs');
+
+const SOURCES = [
+  { type: 'capability', jsonFile: 'capabilities.json', mdFile: 'capability-registry.md' },
+  { type: 'eos', jsonFile: 'eos.json', mdFile: 'eos-registry.md' },
+];
+
+/**
+ * The generator always writes LF; a Windows checkout (autocrlf) may present
+ * committed files with CRLF. Normalize before comparing so `--check` only
+ * fails on real content drift, not checkout-introduced line-ending noise.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+function normalizeLineEndings(content) {
+  return content.replace(/\r/g, '');
+}
+
+function getRegistriesDir() {
+  return path.join(process.cwd(), 'docs', 'registries');
+}
+
+/**
+ * Render the markdown for a single registry type from its committed source
+ * JSON.
+ *
+ * Only `eos.json` is optional (pre-PR2, before that source JSON ships) —
+ * an absent `eos.json` returns null and callers treat that as "nothing to
+ * do". `capabilities.json` is the primary registry source: a missing
+ * `capabilities.json` is ALWAYS an error (never a silent "up to date"
+ * pass), mirroring the type distinction in `scripts/validate-registry.cjs`
+ * (`type === 'eos' && !exists → continue`).
+ *
+ * @param {'capability'|'eos'} type
+ * @returns {string|null}
+ */
+function renderFor(type) {
+  const source = SOURCES.find((s) => s.type === type);
+  if (!source) throw new Error(`gen-registry: unknown registry type "${type}"`);
+
+  const jsonPath = path.join(getRegistriesDir(), source.jsonFile);
+  if (!fs.existsSync(jsonPath)) {
+    if (type === 'eos') return null;
+    throw new ExitError(
+      1,
+      `${source.jsonFile} does not exist at ${jsonPath}. Run:\n  node scripts/gen-registry.cjs --write\n(after adding docs/registries/${source.jsonFile})`,
+    );
+  }
+
+  const entries = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+  return renderMarkdown(entries, { type, sourceFile: source.jsonFile });
+}
+
+function main() {
+  const [, , flag] = process.argv;
+  const registriesDir = getRegistriesDir();
+  let anyDrift = false;
+
+  for (const { type, mdFile } of SOURCES) {
+    const rendered = renderFor(type);
+    if (rendered === null) continue; // source JSON absent (eos.json before PR2)
+
+    const mdPath = path.join(registriesDir, mdFile);
+
+    if (flag === '--check') {
+      if (!fs.existsSync(mdPath)) {
+        process.stderr.write(`${mdFile} does not exist. Run:\n  node scripts/gen-registry.cjs --write\n`);
+        anyDrift = true;
+        continue;
+      }
+      const committed = fs.readFileSync(mdPath, 'utf8');
+      if (normalizeLineEndings(committed) !== normalizeLineEndings(rendered)) {
+        process.stderr.write(`${mdFile} is stale. Run:\n  node scripts/gen-registry.cjs --write\n`);
+        anyDrift = true;
+      }
+    } else if (flag === '--write') {
+      fs.mkdirSync(registriesDir, { recursive: true });
+      fs.writeFileSync(mdPath, rendered);
+      process.stdout.write(`Wrote ${mdPath}\n`);
+    } else {
+      process.stdout.write(rendered + '\n');
+    }
+  }
+
+  if (flag === '--check') {
+    if (anyDrift) throw new ExitError(1, 'registry markdown is stale');
+    process.stdout.write('docs/registries/*.md are up to date.\n');
+  }
+
+  return 0;
+}
+
+if (require.main === module) runMain(main);
+
+module.exports = { main, renderFor, SOURCES, normalizeLineEndings };