heyspex 0.1.0 → 0.2.1

package/scripts/lib/customer-kit.mjs

@@ -0,0 +1,1203 @@
+// customer-kit.mjs — what `hs install` ships into a CUSTOMER repo, in one place.
+//
+// Owner decision 2026-10-02 (follow-through of
+// [[HS-EN4F-F4V2-DIAG-a-repo-set-up-with-hs-install-gets-no]]): every customer
+// repo gets the full HeySpex agent kit — the lifecycle hooks and the /hs-*
+// commands. The platform's own `.claude/settings.json` registers every hook as
+// `node "$CLAUDE_PROJECT_DIR/scripts/claude-hooks/_run.mjs" <hook>` and its
+// commands run `node dev-factory/...` / `node bin/hs.mjs ...` repo-relative;
+// both only resolve inside heyspex-app, so in a customer repo they failed with
+// MODULE_NOT_FOUND — a non-blocking error, i.e. every gate silently off.
+//
+// PORTABLE PATHS ([[HS-0AF8-WW9R-TASK-portable-hook-and-command-paths-in]],
+// epic [[HS-O4Y6-WW9R-EPIC-customer-kit-packaging-hooks-in-the-npm]]). The
+// first kit (2026-10-02) addressed the shim by the platform checkout's ABSOLUTE
+// path, which a customer then committed — on any other machine every hook was
+// a dead command (invariant 8). Nothing written into a customer repo names
+// this machine any more:
+//   - hooks run `node "$CLAUDE_PROJECT_DIR/.claude/heyspex/run-hook.mjs" <hook>`
+//     — a small committed LAUNCHER ({@link renderCustomerLauncher}) that finds
+//     the `heyspex` package from the repo (node_modules/heyspex first, a
+//     machine-local env override second, the global npm root last) and hands
+//     off in-process to the package's shim;
+//   - commands call `hs <verb>` or `node node_modules/heyspex/<file>`;
+//   - `.mcp.json` / `.cursor/mcp.json` point at `node_modules/heyspex` through
+//     the client's own project-dir variable (install.ts).
+// The platform checkout is its own kit and keeps its `$CLAUDE_PROJECT_DIR/
+// scripts/...` form ({@link samePlatformPath}). A legacy absolute row is
+// recognized ({@link ourHookTail}) and REPAIRED in place by the next `hs
+// install` / `hs connect [--fix-commands]`.
+//
+// This module is the reviewable table plus the pure helpers every consumer
+// shares:
+//   - spex-console/src/lib/cli/install.ts     (`hs install` writes the kit)
+//   - spex-console/src/lib/cli/connect-checks.ts / connect.ts (drift check +
+//     `hs connect --fix-commands` ship the same rendered commands)
+//   - scripts/install-cursor-hooks.mjs        (Cursor hooks, same scope table)
+//   - scripts/heyspex-doctor.mjs              (`customer-kit` check)
+//   - plugins/heyspex/hooks/hooks.json        (generated: `--write-plugin-hooks`)
+//
+// SCOPE RULE. A hook is `customer` when it acts on the session's project
+// (CLAUDE_PROJECT_DIR / the active vault / the MCP server's state) and makes
+// sense in any repo HeySpex is installed in. It is `platform` when its subject
+// is heyspex-app's own development machinery (the spex-console dev server and
+// Neon, dev-factory seats and the COO window, the platform's env vault, the
+// vendored MCP build) or when it still resolves its state from the platform
+// checkout's own location instead of the project. A new hook in
+// `.claude/settings.json` without a row here fails customer-kit.test.mjs, so
+// the decision is always made explicitly, never by omission.
+
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { dispositionFor } from './hook-dispositions.mjs';
+
+/** @typedef {'customer' | 'platform'} KitScope */
+
+/**
+ * One scope decision per hook name (the token after `_run.mjs`).
+ * @type {Readonly<Record<string, { scope: KitScope, why: string }>>}
+ */
+export const HOOK_SCOPES = Object.freeze({
+  // ── customer: vault / workflow / safety gates ─────────────────────────────
+  'wip-checkpoint': { scope: 'customer', why: 'Previous-session WIP handoff, read from the active vault.' },
+  'inject-doctrine': {
+    scope: 'customer',
+    why:
+      'Owner ruling 2026-10-03 (HS-A2PO): ships. A customer session gets the baseline edition of SpexCode Doctrine ' +
+      '(CUSTOMER_HOOK_DATA), the foundation its own learned layer is built on; never the platform\'s learned file.',
+  },
+  'check-auto-memory-budget': { scope: 'customer', why: 'Auto-memory index budget for the session project.' },
+  'check-claude-md-budget': { scope: 'customer', why: 'Budget check on the project\'s always-loaded agent contract.' },
+  'git-reflog-audit': { scope: 'customer', why: 'Session-close git audit backstop (stash/reset/rebase witness).' },
+  'preflight-reminder': { scope: 'customer', why: 'Names the required procedure before filing/destructive turns.' },
+  'intent-classifier-trigger': { scope: 'customer', why: 'Routes capture/research/settings/defer intents.' },
+  'inject-communication-style': { scope: 'customer', why: 'Plain-language communication rules each turn.' },
+  'inject-vault-context': { scope: 'customer', why: 'Lexical vault retrieval for the prompt.' },
+  'git-identity-guard': { scope: 'customer', why: 'Agents never write git identity (owner ruling 2026-09-19).' },
+  'vault-write-tier-guard': { scope: 'customer', why: 'Cloud write mode: disk edits to vault specs are a mirror the console never reads back (HS-FCNH).' },
+  'settings-write-gate': { scope: 'customer', why: 'Approval before the vault\'s .heyspex/config.yaml changes.' },
+  'emit-claim-status': { scope: 'customer', why: 'Claim liveness heartbeat to the console.' },
+  'enforce-vault-naming': { scope: 'customer', why: 'Naming V3 filename guard (HS-RY2N).' },
+  'guard-auto-memory-writes': { scope: 'customer', why: 'No new topic files in the auto-memory directory.' },
+  'plan-review-gate': { scope: 'customer', why: 'Plan review + QC markers before ExitPlanMode.' },
+  'plan-exit-ingest-gate': { scope: 'customer', why: 'Plan ingest on ExitPlanMode; arms claim-before-code.' },
+  'claim-before-code-gate': { scope: 'customer', why: 'First code edit after plan exit needs a claim.' },
+  'directive-obligation-gate': { scope: 'customer', why: 'A capture_on_idea directive leaves a durable obligation; an unmet one denies sub-agent spawns, product-code writes and builds, and re-drives Stop once. Also claim-before-build (HS-20SW).' },
+  'capture-workflow-gate': { scope: 'customer', why: 'No implementation spec straight out of an open capture.' },
+  'vault-mirror-catchup': { scope: 'customer', why: 'Cloud write mode: a SessionStart detached `hs pull --apply` closes a stale disk mirror before the first tool call (HS-XJFQ).' },
+  'diagnose-capture-reminder': { scope: 'customer', why: 'Warn when a diagnose is filed with no capture holding the owner\'s words (HS-IK2D).' },
+  'git-stash-gate': { scope: 'customer', why: 'Always ask before a mutating git stash.' },
+  'research-method-guard': { scope: 'customer', why: 'Research method guard (HS-EN4F).' },
+  'deep-research-cost-gate': { scope: 'customer', why: 'Cost confirmation before a paid deep-research launch.' },
+  'research-protocol-gate': { scope: 'customer', why: 'WebSearch/WebFetch refused until research preflight ran (HS-K0ZP, HS-EN4F).' },
+  'naughty-list-gate': { scope: 'customer', why: 'Re-drive a final message that uses banned jargon.' },
+  'id-display-format-gate': { scope: 'customer', why: 'Naming V3 display-id format in replies.' },
+  'epic-milestone-phrasing-gate': { scope: 'customer', why: 'Epic/milestone phrasing rules in replies.' },
+  'enforce-session-sequence': { scope: 'customer', why: 'Re-drive a turn that shipped without record_wip.' },
+  'notify-status-flip': { scope: 'customer', why: 'Sound on an in_review status flip.' },
+  'close-terminal-on-ship': { scope: 'customer', why: 'Close the launch terminal once the spec ships.' },
+  'scripts/stamp-provenance-on-edit.mjs': { scope: 'customer', why: 'Stamp assisted_by provenance on direct spec edits (active vault).' },
+  'session-end': { scope: 'customer', why: 'Release the claim and export session events.' },
+
+  // ── platform: heyspex-app's own development machinery ─────────────────────
+  'inject-dev-server-awareness': { scope: 'platform', why: 'About the spex-console dev server in heyspex-app.' },
+  'inject-coo-seat': { scope: 'platform', why: 'dev-factory COO seat mandate.' },
+  'coo-guard-check': { scope: 'platform', why: 'dev-factory breakdown-delegation guard.' },
+  'coo-denylist-gate': { scope: 'platform', why: 'dev-factory COO window deny list.' },
+  'agent-spawn-delegation-gate': { scope: 'platform', why: 'dev-factory seat routing for subagents.' },
+  'capture-execution-gate': { scope: 'platform', why: 'Blocks dev-factory research/paid-model/routing surfaces past an ungrounded capture (HS-KNJ8).' },
+  'check-mcp-freshness-hook': { scope: 'platform', why: 'Freshness of the vendored MCP build — a platform-dev concern.' },
+  'dev-server-task-reminder': { scope: 'platform', why: 'spex-console dev server + Neon DB safety.' },
+  'env-vault-guard': { scope: 'platform', why: 'Guards heyspex-app\'s encrypted env vault paths.' },
+  'log-session-activity': { scope: 'platform', why: 'Resolves .heyspex state from the platform checkout\'s own location, not the project — would log customer sessions into heyspex-app.' },
+});
+
+/**
+ * Data files (not static imports, so verify-mcp-package's hookTargets closure walk cannot
+ * see them) a customer-scoped hook reads at run time from the installed package. Each must
+ * be listed in package.json `files` and exist on disk; customer-kit.test.mjs asserts both.
+ * The inject-doctrine entry is the ONLY doctrine content that ships: the learned
+ * spexharness/doctrine/SPEXCODE-DOCTRINE.json is distilled from the owner's own sessions and
+ * must never match a `files` entry (same test).
+ * @type {Readonly<Record<string, readonly string[]>>}
+ */
+export const CUSTOMER_HOOK_DATA = Object.freeze({
+  'inject-doctrine': Object.freeze(['spexharness/doctrine/baseline/SPEXCODE-DOCTRINE.baseline.json']),
+});
+
+/**
+ * Every Claude Code hook registration, mirroring the platform's
+ * `.claude/settings.json` row for row (customer-kit.test.mjs asserts parity).
+ * `matcher` is the platform's own matcher; MCP tool names are widened to the
+ * plugin-scoped spelling at render time ({@link widenMcpMatcher}).
+ * @type {ReadonlyArray<{ event: string, matcher?: string, hook: string, args?: string[], timeout: number }>}
+ */
+export const CLAUDE_HOOK_ROWS = Object.freeze([
+  { event: 'SessionStart', hook: 'wip-checkpoint', timeout: 5 },
+  { event: 'SessionStart', hook: 'inject-dev-server-awareness', timeout: 5 },
+  { event: 'SessionStart', hook: 'inject-coo-seat', timeout: 5 },
+  { event: 'SessionStart', hook: 'inject-doctrine', timeout: 5 },
+  { event: 'SessionStart', hook: 'coo-guard-check', timeout: 5 },
+  { event: 'SessionStart', hook: 'check-auto-memory-budget', timeout: 5 },
+  { event: 'SessionStart', hook: 'check-claude-md-budget', timeout: 5 },
+  { event: 'SessionStart', hook: 'check-mcp-freshness-hook', timeout: 5 },
+  { event: 'SessionStart', hook: 'git-reflog-audit', timeout: 5 },
+  { event: 'SessionStart', hook: 'vault-mirror-catchup', timeout: 5 },
+  { event: 'PreCompact', hook: 'wip-checkpoint', timeout: 5 },
+  { event: 'UserPromptSubmit', hook: 'preflight-reminder', timeout: 5 },
+  { event: 'UserPromptSubmit', hook: 'intent-classifier-trigger', timeout: 5 },
+  { event: 'UserPromptSubmit', hook: 'inject-communication-style', timeout: 5 },
+  { event: 'UserPromptSubmit', hook: 'inject-vault-context', timeout: 10 },
+  { event: 'PreToolUse', matcher: 'Write|Edit|MultiEdit|NotebookEdit|Bash|PowerShell', hook: 'env-vault-guard', timeout: 5 },
+  { event: 'PreToolUse', matcher: 'Bash|PowerShell', hook: 'git-identity-guard', timeout: 5 },
+  { event: 'PreToolUse', matcher: 'Write|Edit|MultiEdit|NotebookEdit|Bash|PowerShell', hook: 'vault-write-tier-guard', timeout: 5 },
+  { event: 'PreToolUse', matcher: 'Write|Edit|NotebookEdit|Bash|PowerShell|mcp__heyspex__heyspex_settings_set', hook: 'settings-write-gate', timeout: 5 },
+  { event: 'PreToolUse', matcher: '.*', hook: 'emit-claim-status', args: ['--event=PreToolUse'], timeout: 5 },
+  { event: 'PreToolUse', matcher: '.*', hook: 'coo-denylist-gate', timeout: 5 },
+  { event: 'PreToolUse', matcher: 'Agent|Task', hook: 'agent-spawn-delegation-gate', timeout: 5 },
+  { event: 'PreToolUse', matcher: 'Bash|PowerShell|Agent|Task', hook: 'capture-execution-gate', timeout: 5 },
+  { event: 'PreToolUse', matcher: 'Agent|Task|Edit|Write|MultiEdit|NotebookEdit|Bash|PowerShell', hook: 'directive-obligation-gate', timeout: 5 },
+  { event: 'PreToolUse', matcher: 'mcp__heyspex__heyspex_claim_spec', hook: 'coo-guard-check', timeout: 5 },
+  { event: 'PreToolUse', matcher: 'Write|NotebookEdit|Bash|PowerShell', hook: 'enforce-vault-naming', timeout: 5 },
+  { event: 'PreToolUse', matcher: 'Write|NotebookEdit|Bash|PowerShell', hook: 'guard-auto-memory-writes', timeout: 5 },
+  { event: 'PreToolUse', matcher: 'Edit|MultiEdit|Write|Bash|PowerShell', hook: 'preflight-reminder', timeout: 5 },
+  { event: 'PreToolUse', matcher: 'ExitPlanMode', hook: 'plan-review-gate', timeout: 8 },
+  { event: 'PreToolUse', matcher: 'ExitPlanMode', hook: 'plan-exit-ingest-gate', timeout: 5 },
+  { event: 'PreToolUse', matcher: 'Edit|MultiEdit|Write', hook: 'claim-before-code-gate', timeout: 5 },
+  { event: 'PreToolUse', matcher: 'mcp__heyspex__heyspex_file_spec', hook: 'capture-workflow-gate', timeout: 8 },
+  { event: 'PreToolUse', matcher: 'mcp__heyspex__heyspex_file_spec', hook: 'diagnose-capture-reminder', timeout: 5 },
+  { event: 'PreToolUse', matcher: 'Bash|PowerShell|mcp__neon__prepare_database_migration|mcp__neon__complete_database_migration|mcp__neon__reset_from_parent|mcp__neon__delete_branch|mcp__Neon__prepare_database_migration|mcp__Neon__complete_database_migration|mcp__Neon__reset_from_parent|mcp__Neon__delete_branch', hook: 'dev-server-task-reminder', timeout: 10 },
+  { event: 'PreToolUse', matcher: 'Bash|PowerShell', hook: 'git-stash-gate', timeout: 10 },
+  { event: 'PreToolUse', matcher: 'Skill|Workflow', hook: 'research-method-guard', timeout: 5 },
+  { event: 'PreToolUse', matcher: 'Workflow|Skill', hook: 'deep-research-cost-gate', timeout: 5 },
+  { event: 'PreToolUse', matcher: 'WebSearch|WebFetch|mcp__heyspex__heyspex_save_research|mcp__plugin_heyspex_heyspex__heyspex_save_research', hook: 'research-protocol-gate', timeout: 5 },
+  { event: 'PreToolUse', matcher: '.*', hook: 'log-session-activity', timeout: 5 },
+  { event: 'Stop', hook: 'emit-claim-status', args: ['--event=Stop'], timeout: 5 },
+  { event: 'Stop', hook: 'naughty-list-gate', timeout: 5 },
+  { event: 'Stop', hook: 'id-display-format-gate', timeout: 5 },
+  { event: 'Stop', hook: 'epic-milestone-phrasing-gate', timeout: 5 },
+  { event: 'Stop', hook: 'git-reflog-audit', timeout: 5 },
+  { event: 'Stop', hook: 'enforce-session-sequence', timeout: 5 },
+  { event: 'Stop', hook: 'directive-obligation-gate', timeout: 5 },
+  { event: 'PostToolUse', matcher: '.*', hook: 'emit-claim-status', args: ['--event=PostToolUse'], timeout: 5 },
+  { event: 'PostToolUse', matcher: 'Skill|mcp__heyspex__heyspex_update_capture|mcp__heyspex__heyspex_promote_capture.*|mcp__heyspex__heyspex_file_spec|mcp__heyspex__heyspex_claim_spec|mcp__heyspex__heyspex_release_spec|mcp__heyspex__heyspex_defer_spec', hook: 'directive-obligation-gate', timeout: 5 },
+  { event: 'PostToolUse', matcher: 'Edit|Write|MultiEdit', hook: 'notify-status-flip', timeout: 5 },
+  { event: 'PostToolUse', matcher: 'Edit|Write|MultiEdit', hook: 'close-terminal-on-ship', timeout: 5 },
+  { event: 'PostToolUse', matcher: 'Edit|Write|MultiEdit', hook: 'scripts/stamp-provenance-on-edit.mjs', timeout: 5 },
+  { event: 'PostToolUse', matcher: '.*', hook: 'log-session-activity', timeout: 5 },
+  { event: 'SessionEnd', hook: 'session-end', timeout: 5 },
+  { event: 'SessionEnd', hook: 'close-terminal-on-ship', timeout: 5 },
+]);
+
+/**
+ * One scope decision per harness command file (`.claude/commands/<name>.md`,
+ * mirrored into `.cursor/commands/`). Only `customer` files ship.
+ * @type {Readonly<Record<string, { scope: KitScope, why: string }>>}
+ */
+export const COMMAND_SCOPES = Object.freeze({
+  'hs-backfill.md': { scope: 'customer', why: 'Backfill completed work into the vault.' },
+  'hs-capture.md': { scope: 'customer', why: 'Capture intake.' },
+  'hs-defer.md': { scope: 'customer', why: 'Split + defer remaining work.' },
+  'hs-doctor.md': { scope: 'customer', why: 'Install-surface repair when heyspex_* tools are missing.' },
+  'hs-ground.md': { scope: 'customer', why: 'Pre-plan grounding report.' },
+  'hs-handoff.md': { scope: 'customer', why: 'Short-code lane handoff.' },
+  'hs-next.md': { scope: 'customer', why: 'On-deck prompt + claim handshake.' },
+  'hs-promote.md': { scope: 'customer', why: 'Capture → research → milestone promotion.' },
+  'hs-push.md': { scope: 'customer', why: 'Push an epic plan into the vault.' },
+  'hs-qc.md': { scope: 'customer', why: 'Post-plan QC gate.' },
+  'hs-res.md': { scope: 'customer', why: 'Research method entrypoint (SpexCrawl/DeepSeek).' },
+  'hs-resolve.md': { scope: 'customer', why: 'Resolution lane.' },
+  'hs-review.md': { scope: 'customer', why: 'Review queue.' },
+  'hs-view.md': { scope: 'customer', why: 'Open a console surface.' },
+  'hs-auto.md': { scope: 'platform', why: 'Routes work into dev-factory (platform build system).' },
+  'hs-dev.md': { scope: 'platform', why: 'Admin/dev-only HeySpex dev/prod mode switch.' },
+  'hs-log.md': { scope: 'platform', why: 'Admin/dev-only dev-server log watcher.' },
+  'kill-ports.md': { scope: 'platform', why: 'Kills local dev-server ports.' },
+  'prototype.md': { scope: 'platform', why: 'Console design-preview prototypes inside spex-console.' },
+});
+
+/** @param {string} hook */
+export function hookScope(hook) {
+  return HOOK_SCOPES[hook]?.scope ?? null;
+}
+
+/** @param {string} file basename, e.g. `hs-res.md` */
+export function isCustomerCommand(file) {
+  return COMMAND_SCOPES[file]?.scope === 'customer';
+}
+
+/** Forward-slash form of an absolute path (node accepts it on Windows; no shell eats it). */
+export function toPosixPath(p) {
+  return String(p).replace(/\\/g, '/').replace(/\/+$/, '');
+}
+
+/** Case-insensitive on Windows, separator-agnostic path equality. */
+export function samePlatformPath(a, b) {
+  if (!a || !b) return false;
+  const norm = (p) => {
+    const s = toPosixPath(path.resolve(p));
+    return process.platform === 'win32' ? s.toLowerCase() : s;
+  };
+  return norm(a) === norm(b);
+}
+
+// ---------------------------------------------------------------------------
+// Claude Code hooks
+// ---------------------------------------------------------------------------
+
+const MCP_PROJECT_PREFIX = 'mcp__heyspex__';
+const MCP_PLUGIN_PREFIX = 'mcp__plugin_heyspex_heyspex__';
+
+/**
+ * A project-scoped MCP tool name in a matcher also needs its plugin-scoped
+ * spelling, so the gate holds under either wiring (.mcp.json or the plugin).
+ * @param {string | undefined} matcher
+ */
+export function widenMcpMatcher(matcher) {
+  if (!matcher) return matcher;
+  const parts = matcher.split('|');
+  const out = [];
+  for (const part of parts) {
+    if (!out.includes(part)) out.push(part);
+    if (part.startsWith(MCP_PROJECT_PREFIX)) {
+      const plugin = MCP_PLUGIN_PREFIX + part.slice(MCP_PROJECT_PREFIX.length);
+      if (!parts.includes(plugin) && !out.includes(plugin)) out.push(plugin);
+    }
+  }
+  return out.join('|');
+}
+
+/** The hook rows a customer repo gets. */
+export function customerHookRows() {
+  return CLAUDE_HOOK_ROWS.filter((r) => hookScope(r.hook) === 'customer');
+}
+
+/** `<hook> [args...]` — the identity of a registration within one event. */
+export function hookTail(row) {
+  return [row.hook, ...(row.args ?? [])].join(' ');
+}
+
+// ---------------------------------------------------------------------------
+// The committed launcher a customer repo carries
+// ---------------------------------------------------------------------------
+
+/** The Claude Code hook shim, relative to the `heyspex` package root. */
+export const CLAUDE_HOOK_SHIM = 'scripts/claude-hooks/_run.mjs';
+/** The Cursor hook shim, relative to the `heyspex` package root. */
+export const CURSOR_HOOK_SHIM = 'scripts/cursor-hooks/_run.mjs';
+
+/**
+ * Where each harness's launcher lives inside a customer repo, and the
+ * project-dir variable that harness expands in a hook command.
+ * @type {Readonly<Record<'claude' | 'cursor', { rel: readonly string[], projectDirEnv: string, shim: string, registry: string }>>}
+ */
+export const CUSTOMER_LAUNCHERS = Object.freeze({
+  claude: Object.freeze({
+    rel: Object.freeze(['.claude', 'heyspex', 'run-hook.mjs']),
+    projectDirEnv: 'CLAUDE_PROJECT_DIR',
+    shim: CLAUDE_HOOK_SHIM,
+    registry: '.claude/settings.json',
+  }),
+  cursor: Object.freeze({
+    rel: Object.freeze(['.cursor', 'heyspex', 'run-hook.mjs']),
+    projectDirEnv: 'CURSOR_PROJECT_DIR',
+    shim: CURSOR_HOOK_SHIM,
+    registry: '.cursor/hooks.json',
+  }),
+});
+
+/**
+ * Runner prefix for a customer repo: the committed launcher, addressed from the
+ * harness's project-dir variable — never this machine's path. The platform
+ * root is accepted (and ignored) so every caller keeps its signature; the
+ * launcher file itself is what {@link renderCustomerLauncher} renders.
+ * @param {string} [_platformRoot]
+ * @param {'claude' | 'cursor'} [surface]
+ */
+export function customerRunnerPrefix(_platformRoot, surface = 'claude') {
+  const l = CUSTOMER_LAUNCHERS[surface];
+  // Claude rows are self-locating (Copilot CLI loads .claude/settings.json and does not document CLAUDE_PROJECT_DIR).
+  if (surface === 'claude') return CUSTOMER_RUNNER_PREFIX;
+  return `node "$${l.projectDirEnv}/${l.rel.join('/')}"`;
+}
+
+/** Runner prefix inside the plugin: its own launcher, which finds the platform. */
+const BOOTSTRAP_WALK =
+  "var d=process.cwd(),r=e.CLAUDE_PROJECT_DIR;if(!r||!f.existsSync(p.join(r,...n))){r='';for(;;){if(f.existsSync(p.join(d,...n))){r=d;break}var q=p.dirname(d);if(q===d)break;d=q}}";
+
+/**
+ * SELF-LOCATING BOOTSTRAP ([[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]], Copilot compatibility).
+ *
+ * GitHub Copilot CLI runs the hooks in .claude/settings.json too, but it is not documented to set
+ * CLAUDE_PROJECT_DIR / CLAUDE_PLUGIN_ROOT, and a PowerShell-run command expands an unset $VAR to
+ * nothing - so \`node "$CLAUDE_PROJECT_DIR/scripts/claude-hooks/_run.mjs"\` became \`node /scripts/...\`,
+ * MODULE_NOT_FOUND, exit 1, and Copilot turns ANY non-zero exit into a DENY (on a \`.*\` matcher: every tool
+ * call). A registered command must therefore (a) work with no env var at all, under bash AND PowerShell, and
+ * (b) FAIL OPEN when it cannot find the runtime. It is an inline \`node -e\` script, single-quoted JS only
+ * (no double quote, backslash, dollar or backtick), so it survives JSON and every shell unchanged:
+ *   root = CLAUDE_PROJECT_DIR if it holds the shim, else walk up from cwd looking for scripts/claude-hooks/_run.mjs;
+ *   not found -> exit 0; found -> import the shim in-process with the same argv and stdin (the shim owns both).
+ * The plugin variant first tries <CLAUDE_PLUGIN_ROOT|PLUGIN_ROOT>/bin/run-hook.mjs. The trailing //comment is
+ * deliberate: it keeps the recognisable ...scripts/claude-hooks/_run.mjs" <hook> tail every drift check,
+ * ourHookTail and the doctor already parse.
+ * @param {{ plugin?: boolean }} [opts]
+ */
+export function buildBootstrap({ plugin = false } = {}) {
+  const walk = BOOTSTRAP_WALK;
+  const body = plugin
+    ? "var f=require('fs'),p=require('path'),u=require('url'),e=process.env,n=['scripts','claude-hooks','_run.mjs'],s='',m=e.CLAUDE_PLUGIN_ROOT||e.COPILOT_PLUGIN_ROOT||e.PLUGIN_ROOT;" +
+      "if(m&&f.existsSync(p.join(m,'bin','run-hook.mjs')))s=p.join(m,'bin','run-hook.mjs');" +
+      "if(!s){" + walk + "if(r){e.CLAUDE_PROJECT_DIR=r;s=p.join(r,...n)}}"
+    : "var f=require('fs'),p=require('path'),u=require('url'),e=process.env,n=['scripts','claude-hooks','_run.mjs'],s='';" +
+      walk + "if(r){e.CLAUDE_PROJECT_DIR=r;s=p.join(r,...n)}";
+  return (
+    body +
+    "if(!s)process.exit(0);process.argv=[process.argv[0],s].concat(process.argv.slice(1));" +
+    "import(u.pathToFileURL(s).href).catch(function(){process.exit(0)});" +
+    (plugin ? '//bin/run-hook.mjs' : '//scripts/claude-hooks/_run.mjs')
+  );
+}
+
+/** Platform checkout runner (.claude/settings.json): self-locating, env-independent, fail-open. */
+export const PLATFORM_RUNNER_PREFIX = 'node -e "' + buildBootstrap() + '"';
+
+/** Runner prefix inside the plugin: self-locating too (plugin root env, then cwd walk-up), fail-open. */
+export const PLUGIN_RUNNER_PREFIX = 'node -e "' + buildBootstrap({ plugin: true }) + '"';
+
+/**
+ * Customer-repo bootstrap (same defect, same fix as {@link buildBootstrap}): the committed launcher
+ * `.claude/heyspex/run-hook.mjs` is resolved from CLAUDE_PROJECT_DIR if it holds the launcher, else by walking up
+ * from cwd, else exit 0 (fail open). Sets CLAUDE_PROJECT_DIR to the found root so the shim reads
+ * <project>/.heyspex/mode.json (`hs mode off`). Single-quoted JS only; survives JSON, bash and PowerShell.
+ */
+export function buildCustomerBootstrap() {
+  const rel = CUSTOMER_LAUNCHERS.claude.rel.map((s) => "'" + s + "'").join(',');
+  return (
+    "var f=require('fs'),p=require('path'),u=require('url'),e=process.env,n=[" + rel + "],s='';" +
+    BOOTSTRAP_WALK + "if(r){e.CLAUDE_PROJECT_DIR=r;s=p.join(r,...n)}" +
+    "if(!s)process.exit(0);process.argv=[process.argv[0],s].concat(process.argv.slice(1));" +
+    "import(u.pathToFileURL(s).href).catch(function(){process.exit(0)});" +
+    '//' + CUSTOMER_LAUNCHERS.claude.rel.join('/')
+  );
+}
+
+/** Customer repo runner (.claude/settings.json): self-locating, env-independent, fail-open. */
+export const CUSTOMER_RUNNER_PREFIX = 'node -e "' + buildCustomerBootstrap() + '"';
+
+// The launcher is kept as ONE template string (not a sibling file) so the
+// bundled CLI (`dist/cli/*.mjs`, built from install.ts) carries it by
+// construction — a file read relative to this module would miss once bundled.
+// `__TOKENS__` are substituted per surface; no backticks inside, on purpose.
+const LAUNCHER_TEMPLATE = [
+  '#!/usr/bin/env node',
+  '// HeySpex hook launcher -- GENERATED by hs install / hs connect. Commit it with this repo.',
+  '//',
+  '// Every HeySpex hook registered in __REGISTRY__ runs',
+  '//   node "$__ENV__/__LAUNCHER__" <hook> [args]',
+  '// This file carries NO machine-specific path. It finds the heyspex package this',
+  '// repo depends on (node_modules/heyspex) and hands off in-process to the',
+  '// package\'s hook shim (__SHIM__), so the same committed command works on every',
+  '// machine the repo is cloned to.',
+  '//',
+  '// Resolution order (the first root that carries the shim wins):',
+  '//   1. HEYSPEX_PLATFORM_ROOT                    explicit machine-local override',
+  '//   2. HEYSPEX_MCP_ENTRY -> its package root    machine-local override',
+  '//   3. node_modules/heyspex, walking up from this file   (the repo-local dependency)',
+  '//   4. node_modules/heyspex up from $__ENV__, $CLAUDE_PROJECT_DIR, $CURSOR_PROJECT_DIR, cwd',
+  '//   5. <npm root -g>/heyspex                    a global install, last resort',
+  '// Nothing found -> one stderr line and exit 0 (fail-open, like the shim itself).',
+  "import { spawnSync } from 'node:child_process';",
+  "import { existsSync } from 'node:fs';",
+  "import { dirname, resolve } from 'node:path';",
+  "import { fileURLToPath, pathToFileURL } from 'node:url';",
+  '',
+  "const SHIM = '__SHIM__'.split('/');",
+  'const here = dirname(fileURLToPath(import.meta.url));',
+  'const env = process.env;',
+  'const text = (v) => (typeof v === \'string\' && v.trim() ? v.trim() : null);',
+  'const hasShim = (root) => Boolean(root) && existsSync(resolve(root, ...SHIM));',
+  '',
+  'function packageUpFrom(start) {',
+  '  let dir = resolve(start);',
+  '  for (;;) {',
+  "    const candidate = resolve(dir, 'node_modules', 'heyspex');",
+  '    if (hasShim(candidate)) return candidate;',
+  '    const parent = dirname(dir);',
+  '    if (parent === dir) return null;',
+  '    dir = parent;',
+  '  }',
+  '}',
+  '',
+  'function globalPackage() {',
+  '  try {',
+  '    // One command string through the shell: npm is a .cmd on Windows, and a',
+  '    // shell + args array is what node deprecates (DEP0190).',
+  "    const res = spawnSync('npm root -g', { encoding: 'utf8', timeout: 5000, shell: true });",
+  "    const root = String(res.stdout ?? '').trim();",
+  "    return root ? resolve(root, 'heyspex') : null;",
+  '  } catch {',
+  '    return null;',
+  '  }',
+  '}',
+  '',
+  'const mcpEntry = text(env.HEYSPEX_MCP_ENTRY);',
+  'const starts = [...new Set([here, text(env.__ENV__), text(env.CLAUDE_PROJECT_DIR), text(env.CURSOR_PROJECT_DIR), process.cwd()].filter(Boolean))];',
+  'let root =',
+  "  [text(env.HEYSPEX_PLATFORM_ROOT), mcpEntry && resolve(mcpEntry, '..', '..', '..')].find(hasShim) ??",
+  '  starts.map(packageUpFrom).find(Boolean) ??',
+  '  null;',
+  'if (!root) {',
+  '  const global = globalPackage();',
+  '  if (hasShim(global)) root = global;',
+  '}',
+  '',
+  'if (!root) {',
+  '  process.stderr.write(',
+  "    '[heyspex] hook ' + (process.argv[2] ?? '?') + ' skipped: no heyspex package found ' +",
+  "      '(run \"npm install heyspex\" in this repo, or set HEYSPEX_PLATFORM_ROOT). Looked for __SHIM__ under ' +",
+  "      'HEYSPEX_PLATFORM_ROOT, HEYSPEX_MCP_ENTRY, node_modules/heyspex up from ' + starts.join(', ') + ', and npm root -g.\\n',",
+  '  );',
+  '  process.exit(0);',
+  '}',
+  '',
+  '// argv is already [node, <this file>, <hook>, ...args] -- the shape the shim',
+  '// reads; the shim path replaces this file so a shim guarded by "am I main?"',
+  '// (the Cursor one) runs exactly as if Cursor had invoked it directly.',
+  'const shim = resolve(root, ...SHIM);',
+  'process.argv[1] = shim;',
+  'try {',
+  '  await import(pathToFileURL(shim).href);',
+  '} catch (err) {',
+  "  process.stderr.write('[heyspex] hook ' + (process.argv[2] ?? '?') + ' skipped: ' + (err && err.message ? err.message : err) + '\\n');",
+  '  process.exit(0);',
+  '}',
+  '',
+].join('\n');
+
+/**
+ * The launcher file `hs install` / `hs connect` write into a customer repo
+ * (`.claude/heyspex/run-hook.mjs`; the Cursor copy at
+ * `.cursor/heyspex/run-hook.mjs`). Pure: a string, no machine path in it.
+ * @param {'claude' | 'cursor'} [surface]
+ */
+export function renderCustomerLauncher(surface = 'claude') {
+  const l = CUSTOMER_LAUNCHERS[surface];
+  return LAUNCHER_TEMPLATE.replace(/__(REGISTRY|ENV|LAUNCHER|SHIM)__/g, (_m, token) =>
+    token === 'REGISTRY' ? l.registry : token === 'ENV' ? l.projectDirEnv : token === 'LAUNCHER' ? l.rel.join('/') : l.shim,
+  );
+}
+
+/**
+ * Whether the launcher on disk needs (re)writing. EOL-insensitive: git's
+ * autocrlf may check the committed copy out with CRLF.
+ * @param {string | null | undefined} existing
+ * @param {'claude' | 'cursor'} [surface]
+ * @returns {{ write: boolean, reason: 'missing' | 'unchanged' | 'update', text: string }}
+ */
+export function planCustomerLauncherWrite(existing, surface = 'claude') {
+  const text = renderCustomerLauncher(surface);
+  if (existing === null || existing === undefined) return { write: true, reason: 'missing', text };
+  if (String(existing).replace(/\r\n/g, '\n') === text) return { write: false, reason: 'unchanged', text };
+  return { write: true, reason: 'update', text };
+}
+
+/**
+ * A HeySpex hook command that still names a machine path: a quoted script
+ * that starts with a drive letter or a root slash rather than a `$VAR`. The
+ * legacy 2026-10-02 kit form; what `hs doctor` reports as a stale path and
+ * what the next install/connect repairs.
+ * @param {unknown} command
+ */
+export function isAbsoluteHookCommand(command) {
+  if (typeof command !== 'string' || ourHookTail(command) === null) return false;
+  return /^\s*node\s+"(?:[A-Za-z]:)?[\\/](?!\$)/.test(command) || /^\s*node\s+(?:[A-Za-z]:)?[\\/]\S*(?:_run|run-hook)\.mjs/.test(command);
+}
+
+/**
+ * `event: <hook> [args]` for every HeySpex row in a parsed settings object
+ * whose command is still an absolute machine path.
+ * @param {Record<string, unknown>} settings
+ * @returns {string[]}
+ */
+export function legacyAbsoluteHookRows(settings) {
+  const out = [];
+  const hooks = settings?.hooks && typeof settings.hooks === 'object' ? settings.hooks : {};
+  for (const [event, groups] of Object.entries(hooks)) {
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      for (const h of Array.isArray(group?.hooks) ? group.hooks : []) {
+        if (isAbsoluteHookCommand(h?.command)) out.push(`${event}: ${ourHookTail(h.command)}`);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Desired registrations for a runner prefix.
+ * @param {string} runnerPrefix
+ * @returns {{ event: string, matcher?: string, command: string, timeout: number, tail: string }[]}
+ */
+export function renderCustomerHooks(runnerPrefix) {
+  return customerHookRows().map((row) => ({
+    event: row.event,
+    ...(row.matcher ? { matcher: widenMcpMatcher(row.matcher) } : {}),
+    command: `${runnerPrefix} ${hookTail(row)}`,
+    timeout: row.timeout,
+    tail: hookTail(row),
+  }));
+}
+
+/**
+ * Ours = any command routed through a HeySpex runner: the platform shim
+ * (`scripts/claude-hooks/_run.mjs`, by `$CLAUDE_PROJECT_DIR` or a legacy
+ * absolute path), the plugin launcher (`bin/run-hook.mjs`) or the committed
+ * customer launcher (`.claude/heyspex/run-hook.mjs`).
+ */
+const OUR_RUNNER_RE = /(?:scripts\/claude-hooks\/_run\.mjs|(?:bin|heyspex)\/run-hook\.mjs)"?\s+(.+)$/;
+
+/** The `<hook> [args]` tail of one of our commands, or null for a foreign one. */
+export function ourHookTail(command) {
+  if (typeof command !== 'string') return null;
+  const m = command.replace(/\\/g, '/').match(OUR_RUNNER_RE);
+  return m ? m[1].trim() : null;
+}
+
+/**
+ * Merge the customer hook kit into a parsed `.claude/settings.json` object, in
+ * place. Merge-not-clobber: other keys, other events and foreign hooks
+ * survive untouched. An existing HeySpex entry (any `_run.mjs`/`run-hook.mjs`
+ * command: an older platform path, a copied `$CLAUDE_PROJECT_DIR` form) is
+ * REPAIRED in place when it matches a kit row, and removed when it does not
+ * (a platform-only hook, a duplicate, a retired hook) — never duplicated.
+ * Idempotent: a second call reports no change.
+ *
+ * @param {Record<string, unknown>} settings
+ * @param {string} runnerPrefix e.g. {@link customerRunnerPrefix}(platformRoot)
+ * @returns {{ changed: boolean, added: string[], repaired: string[], removed: string[], total: number }}
+ */
+export function mergeCustomerKitHooks(settings, runnerPrefix) {
+  const desired = renderCustomerHooks(runnerPrefix);
+  const hooks =
+    settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks)
+      ? /** @type {Record<string, unknown>} */ (settings.hooks)
+      : {};
+  const claimed = new Set();
+  const added = [];
+  const repaired = [];
+  const removed = [];
+  const key = (event, tail) => `${event}::${tail}`;
+  const desiredByKey = new Map(desired.map((d) => [key(d.event, d.tail), d]));
+
+  for (const [event, groups] of Object.entries(hooks)) {
+    if (!Array.isArray(groups)) continue;
+    const keptGroups = [];
+    for (const group of groups) {
+      if (!group || typeof group !== 'object' || !Array.isArray(group.hooks)) {
+        keptGroups.push(group);
+        continue;
+      }
+      const before = group.hooks.length;
+      const keptHooks = [];
+      for (const h of group.hooks) {
+        const tail = ourHookTail(h?.command);
+        if (tail === null) {
+          keptHooks.push(h);
+          continue;
+        }
+        const k = key(event, tail);
+        const want = desiredByKey.get(k);
+        const matcherOk = want && (group.matcher ?? '') === (want.matcher ?? '');
+        if (!want || claimed.has(k) || !matcherOk) {
+          removed.push(`${event}: ${tail}`);
+          continue;
+        }
+        claimed.add(k);
+        if (h.command !== want.command || h.timeout !== want.timeout || h.type !== 'command') {
+          h.type = 'command';
+          h.command = want.command;
+          h.timeout = want.timeout;
+          repaired.push(`${event}: ${tail}`);
+        }
+        keptHooks.push(h);
+      }
+      group.hooks = keptHooks;
+      // Drop a group only when THIS merge emptied it.
+      if (keptHooks.length > 0 || before === 0) keptGroups.push(group);
+    }
+    hooks[event] = keptGroups;
+  }
+
+  for (const d of desired) {
+    const k = key(d.event, d.tail);
+    if (claimed.has(k)) continue;
+    const list = Array.isArray(hooks[d.event]) ? /** @type {unknown[]} */ (hooks[d.event]) : [];
+    list.push({
+      ...(d.matcher ? { matcher: d.matcher } : {}),
+      hooks: [{ type: 'command', command: d.command, timeout: d.timeout }],
+    });
+    hooks[d.event] = list;
+    added.push(`${d.event}: ${d.tail}`);
+  }
+
+  const changed = added.length + repaired.length + removed.length > 0;
+  if (changed) settings.hooks = hooks;
+  return { changed, added, repaired, removed, total: desired.length };
+}
+
+/** The plugin's hooks.json document, generated from the same rows. */
+export function renderPluginHooksDocument() {
+  const hooks = {};
+  for (const d of renderCustomerHooks(PLUGIN_RUNNER_PREFIX)) {
+    (hooks[d.event] ??= []).push({
+      ...(d.matcher ? { matcher: d.matcher } : {}),
+      hooks: [{ type: 'command', command: d.command, timeout: d.timeout }],
+    });
+  }
+  // No top-level `_comment`: GitHub Copilot loads this file too and a strict reader may reject unknown keys. The
+  // provenance note lives in plugins/heyspex/README.md (GENERATED from this file's customer-scoped rows; edit
+  // scripts/lib/customer-kit.mjs and run `node scripts/lib/customer-kit.mjs --write-plugin-hooks`).
+  return {
+    hooks,
+  };
+}
+
+export function renderPluginHooksText() {
+  return `${JSON.stringify(renderPluginHooksDocument(), null, 2)}\n`;
+}
+
+// ---------------------------------------------------------------------------
+// GitHub Copilot cloud agent: .github/hooks/heyspex.json
+// ---------------------------------------------------------------------------
+// The cloud agent loads NO plugins and no user-level hook files; its only hook source is
+// `.github/hooks/*.json` on the default branch. This is the one place a generated Copilot
+// manifest is justified ([[HS-0GBS-CTF8-RES-copilot-plugin-parity-with-the-spexcode]], option 3).
+// Generated from the SAME customer rows as hooks.json, restricted to the hooks whose Copilot
+// disposition (scripts/lib/hook-dispositions.mjs) is 'mapped'. The cloud agent is Linux bash only,
+// so every entry is `type: "command"` with a `bash` command; no PowerShell, no node -e bootstrap.
+
+/** Claude hook event -> Copilot hooks event (camelCase, as documented for the CLI and the cloud agent). */
+export const COPILOT_EVENT_NAMES = Object.freeze({
+  SessionStart: 'sessionStart',
+  SessionEnd: 'sessionEnd',
+  UserPromptSubmit: 'userPromptSubmitted',
+  PreToolUse: 'preToolUse',
+  PostToolUse: 'postToolUse',
+  Stop: 'agentStop',
+  PreCompact: 'preCompact',
+});
+
+/**
+ * Hooks shipped to the cloud agent although their Copilot disposition is 'advisory-degraded': their
+ * prompt-time OUTPUT is dropped, but they still run and ARM state (the HS-20SW capture obligation), and
+ * the 'mapped' directive-obligation-gate is inert without that arming.
+ */
+export const GITHUB_HOOKS_STATE_ARMING = Object.freeze(['intent-classifier-trigger']);
+
+/** Claude tool name -> Copilot tool name (documented: ask_user bash create edit glob grep powershell task view web_fetch). */
+const COPILOT_TOOL_NAMES = Object.freeze({
+  Write: 'create',
+  Edit: 'edit',
+  MultiEdit: 'edit',
+  NotebookEdit: 'edit',
+  Bash: 'bash',
+  PowerShell: 'powershell',
+  Agent: 'task',
+  Task: 'task',
+  WebFetch: 'web_fetch',
+  WebSearch: 'web_search',
+});
+
+/**
+ * Translate a Claude matcher to Copilot tool names. MCP tools become a suffix regex because the MCP
+ * tool-name spelling inside hook payloads is not documented (unverified live); tools with no Copilot
+ * counterpart (Skill, Workflow, ExitPlanMode) are dropped.
+ * @param {string | undefined} matcher
+ * @returns {string | null | undefined} undefined = no matcher, null = nothing translatable
+ */
+export function toCopilotMatcher(matcher) {
+  if (!matcher) return undefined;
+  const out = [];
+  for (const part of matcher.split('|')) {
+    let t = null;
+    if (part === '.*') t = '.*';
+    else if (COPILOT_TOOL_NAMES[part]) t = COPILOT_TOOL_NAMES[part];
+    else if (part.startsWith(MCP_PROJECT_PREFIX)) t = '.*' + part.slice(MCP_PROJECT_PREFIX.length);
+    else if (part.startsWith(MCP_PLUGIN_PREFIX)) t = '.*' + part.slice(MCP_PLUGIN_PREFIX.length);
+    if (t && !out.includes(t)) out.push(t);
+  }
+  if (out.includes('.*')) return '.*';
+  return out.length ? out.join('|') : null;
+}
+
+/** Hooks the cloud-agent manifest carries (see the module comment above). */
+export function githubHookNames() {
+  const names = new Set();
+  for (const r of customerHookRows()) {
+    if (dispositionFor(r.hook, 'copilot')?.disposition === 'mapped' || GITHUB_HOOKS_STATE_ARMING.includes(r.hook)) names.add(r.hook);
+  }
+  return names;
+}
+
+/**
+ * The bash command for one hook: resolve the runtime from node_modules/heyspex first, then the checkout's own
+ * scripts/, else exit 0 (fail open; Copilot turns any non-zero exit into a deny).
+ * @param {{ hook: string, args?: string[] }} row
+ */
+export function githubHookCommand(row) {
+  const tail = hookTail(row);
+  return (
+    'R=node_modules/heyspex/scripts/claude-hooks/_run.mjs; ' +
+    '[ -f "$R" ] || R=./scripts/claude-hooks/_run.mjs; ' +
+    '[ -f "$R" ] || exit 0; ' +
+    `exec node "$R" ${tail}`
+  );
+}
+
+/** The cloud agent's .github/hooks/heyspex.json document, generated from the customer rows. */
+export function renderGithubHooksDocument() {
+  const allowed = githubHookNames();
+  const hooks = {};
+  for (const row of customerHookRows()) {
+    if (!allowed.has(row.hook)) continue;
+    const event = COPILOT_EVENT_NAMES[row.event];
+    if (!event) continue;
+    const matcher = toCopilotMatcher(row.matcher);
+    if (matcher === null) continue; // a tool-scoped row with no Copilot tool to match
+    (hooks[event] ??= []).push({
+      type: 'command',
+      ...(matcher ? { matcher } : {}),
+      bash: githubHookCommand(row),
+      timeoutSec: row.timeout,
+    });
+  }
+  return { version: 1, hooks };
+}
+
+export function renderGithubHooksText() {
+  return `${JSON.stringify(renderGithubHooksDocument(), null, 2)}\n`;
+}
+
+// ---------------------------------------------------------------------------
+// Double-firing detector (plugin AND repo hooks)
+// ---------------------------------------------------------------------------
+// Copilot CLI reads hooks from the plugin AND from .claude/settings.json / .github/hooks in the repo, and
+// Claude Code does the same for plugin + .claude/settings.json: with both present every hook runs twice.
+// Rule: pick one of plugin OR repo hooks. This detector is pure (injected fs), so the doctor and a test share it.
+
+const readJsonFile = (deps, file) => {
+  try {
+    const text = deps.readFile(file);
+    return text == null ? undefined : JSON.parse(text);
+  } catch {
+    return null; // present but unparseable
+  }
+};
+
+/** @param {unknown} settings */
+function countOurRows(settings) {
+  let n = 0;
+  const hooks = settings && typeof settings === 'object' && settings.hooks && typeof settings.hooks === 'object' ? settings.hooks : {};
+  for (const groups of Object.values(hooks)) {
+    for (const g of Array.isArray(groups) ? groups : []) {
+      // Claude shape: { matcher, hooks: [{ command }] }; Copilot .github/hooks shape: { bash } / { command }.
+      const cmds = Array.isArray(g?.hooks) ? g.hooks.map((h) => h?.command) : [g?.command, g?.bash];
+      for (const c of cmds) if (typeof c === 'string' && (ourHookTail(c) !== null || /claude-hooks\/_run\.mjs/.test(c))) n++;
+    }
+  }
+  return n;
+}
+
+/**
+ * Whether BOTH repo-level HeySpex hooks AND an installed heyspex plugin are present for a project.
+ *
+ * Repo hooks: HeySpex rows in <project>/.claude/settings.json, .claude/settings.local.json or
+ * <project>/.github/hooks/*.json. Plugin evidence (any of): ~/.claude/plugins/installed_plugins.json with a
+ * "heyspex@..." key; `enabledPlugins` naming heyspex in ~/.claude/settings.json or the project's Claude settings;
+ * a heyspex directory under ~/.copilot/installed-plugins or ~/.copilot/plugins (best effort: the Copilot plugin
+ * list file is not documented, `copilot plugin list` is the authority). If no plugin registry can be read at all
+ * and repo hooks exist, the answer is 'unknown' (never a failure).
+ * @param {{ targetRoot: string, home?: string, deps?: { readFile: (p: string) => string | null, listDir?: (p: string) => string[] } }} opts
+ * @returns {{ status: 'ok' | 'warn' | 'unknown', detail: string, repoHooks: number, plugin: boolean | null, evidence: string[] }}
+ */
+export function detectDoubleFire({ targetRoot, home = os.homedir(), deps = fsDeps }) {
+  const evidence = [];
+  const repoFiles = ['.claude/settings.json', '.claude/settings.local.json'].map((f) => path.join(targetRoot, f));
+  let repoHooks = 0;
+  for (const f of repoFiles) {
+    const n = countOurRows(readJsonFile(deps, f));
+    if (n) { repoHooks += n; evidence.push(`${n} HeySpex hook row(s) in ${f}`); }
+  }
+  const ghDir = path.join(targetRoot, '.github', 'hooks');
+  for (const name of (deps.listDir ? deps.listDir(ghDir) : []).filter((x) => x.endsWith('.json'))) {
+    const n = countOurRows(readJsonFile(deps, path.join(ghDir, name)));
+    if (n) { repoHooks += n; evidence.push(`${n} HeySpex hook row(s) in .github/hooks/${name}`); }
+  }
+
+  let readable = 0;
+  let plugin = false;
+  const installed = readJsonFile(deps, path.join(home, '.claude', 'plugins', 'installed_plugins.json'));
+  if (installed !== undefined) {
+    readable++;
+    const keys = Object.keys(installed?.plugins ?? installed ?? {});
+    if (keys.some((k) => /^heyspex(@|$)/i.test(k))) { plugin = true; evidence.push('heyspex in ~/.claude/plugins/installed_plugins.json'); }
+  }
+  const userSettings = path.join(home, '.claude', 'settings.json');
+  for (const f of [userSettings, ...repoFiles]) {
+    const st = readJsonFile(deps, f);
+    if (st === undefined) continue;
+    if (f === userSettings) readable++; // a project file proves nothing about what is installed elsewhere
+    const ep = st?.enabledPlugins;
+    if (ep && typeof ep === 'object' && Object.entries(ep).some(([k, v]) => /^heyspex(@|$)/i.test(k) && v !== false)) {
+      plugin = true;
+      evidence.push(`heyspex in enabledPlugins of ${f}`);
+    }
+  }
+  if (deps.listDir) {
+    for (const sub of ['installed-plugins', 'plugins']) {
+      const dir = path.join(home, '.copilot', sub);
+      const names = deps.listDir(dir);
+      if (names.length) readable++;
+      if (names.some((n) => /heyspex/i.test(n))) {
+        plugin = true;
+        evidence.push(`heyspex under ${dir}`);
+      } else {
+        // one level deeper: <marketplace>/<plugin> layouts
+        for (const n of names) {
+          if (deps.listDir(path.join(dir, n)).some((m) => /heyspex/i.test(m))) {
+            plugin = true;
+            evidence.push(`heyspex under ${path.join(dir, n)}`);
+          }
+        }
+      }
+    }
+  }
+
+  if (repoHooks === 0) return { status: 'ok', detail: 'no repo-level HeySpex hooks to double up with a plugin', repoHooks, plugin: plugin || null, evidence };
+  if (plugin) {
+    return {
+      status: 'warn',
+      detail: `HeySpex hooks are registered in the repo AND the heyspex plugin is installed, so every hook fires twice (${evidence.join('; ')})`,
+      repoHooks,
+      plugin: true,
+      evidence,
+    };
+  }
+  if (readable === 0) {
+    return { status: 'unknown', detail: 'repo-level HeySpex hooks present, but no plugin registry could be read to rule out a second copy', repoHooks, plugin: null, evidence };
+  }
+  return { status: 'ok', detail: 'repo-level hooks only; no heyspex plugin found', repoHooks, plugin: false, evidence };
+}
+
+
+// ---------------------------------------------------------------------------
+// Harness commands (.claude/commands, .cursor/commands)
+// ---------------------------------------------------------------------------
+
+/**
+ * The two harness-command trees `scripts/sync-skills.mjs` generates. Each
+ * names the INSTALLED tree (what a target repo carries) and, in priority
+ * order, where its CANONICAL content is read from: the packaged mirror
+ * (`dist/cli-templates/harness-commands/**`, a published install) then the
+ * platform checkout's own tree (a dev checkout before the first build).
+ * Re-exported by connect-checks.ts — one definition.
+ */
+export const HARNESS_COMMAND_SURFACES = Object.freeze([
+  {
+    installedDir: Object.freeze(['.claude', 'commands']),
+    packagedDir: Object.freeze(['dist', 'cli-templates', 'harness-commands', 'claude']),
+    devSourceDir: Object.freeze(['.claude', 'commands']),
+  },
+  {
+    installedDir: Object.freeze(['.cursor', 'commands']),
+    packagedDir: Object.freeze(['dist', 'cli-templates', 'harness-commands', 'cursor']),
+    devSourceDir: Object.freeze(['.cursor', 'commands']),
+  },
+]);
+
+/**
+ * Directory holding the canonical content for one surface, or null.
+ * @param {string} platformRoot
+ * @param {(typeof HARNESS_COMMAND_SURFACES)[number]} surface
+ * @param {{ joinPath: (...s: string[]) => string, listDir: (dir: string) => string[] }} deps
+ * @returns {string | null}
+ */
+export function resolveCanonicalCommandDir(platformRoot, surface, deps) {
+  const hasMd = (dir) => deps.listDir(dir).some((f) => f.endsWith('.md'));
+  const packaged = deps.joinPath(platformRoot, ...surface.packagedDir);
+  if (hasMd(packaged)) return packaged;
+  const devSource = deps.joinPath(platformRoot, ...surface.devSourceDir);
+  if (hasMd(devSource)) return devSource;
+  return null;
+}
+
+/** Launcher aliases: npm scripts that have an `hs` verb. */
+const NPM_ALIASES = Object.freeze({ doctor: 'doctor', setup: 'doctor --fix' });
+const REPO_DIRS = 'bin|scripts|dev-factory|vendor|spexharness';
+
+/**
+ * Platform scripts the shipped commands invoke directly that have an `hs`
+ * verb (`bin/hs.mjs` SPAWN_TARGETS) — the verb is what a customer runs.
+ */
+const SCRIPT_VERBS = Object.freeze({
+  'scripts/heyspex-doctor.mjs': 'doctor',
+  'scripts/hs-view.mjs': 'view',
+  'scripts/hs-capture-cli.mjs': 'capture',
+  'scripts/hs-next.mjs': 'next',
+  'scripts/hs-mode.mjs': 'mode',
+  'scripts/hs-settings.mjs': 'settings',
+  'scripts/hs-companion.mjs': 'companion',
+  'scripts/wip-ledger-health.mjs': 'wip',
+  'scripts/dev-server-status.mjs': 'server status',
+  'scripts/dev-server-stop.mjs': 'server stop',
+});
+
+/** Where the `heyspex` package sits in a customer repo, repo-relative. */
+export const PORTABLE_PACKAGE_DIR = 'node_modules/heyspex';
+
+/**
+ * Rewrite repo-relative platform invocations to PORTABLE ones — forms that
+ * resolve from the customer repo on any machine, never this machine's path:
+ *   `node bin/hs.mjs <args>`         → `hs <args>`
+ *   `node scripts/heyspex-doctor.mjs`→ `hs doctor`           (SCRIPT_VERBS)
+ *   `node dev-factory/x.mjs`         → `node node_modules/heyspex/dev-factory/x.mjs`
+ *   `npm run doctor|setup`           → `hs doctor [--fix]`
+ *   `npm run <script>`               → `npm --prefix node_modules/heyspex run <script>`
+ * Prose mentions of a path (no `node ` in front) are left alone. The platform
+ * root is accepted (and ignored) so every caller keeps its signature.
+ * @param {string} content
+ * @param {string} [_platformRoot]
+ */
+export function rewritePlatformPaths(content, _platformRoot) {
+  return String(content)
+    .replace(/\bnode bin\/hs\.mjs\b/g, 'hs')
+    .replace(new RegExp(`\\bnode (${REPO_DIRS})/([\\w./-]+\\.m?js)\\b`, 'g'), (_m, dir, rest) => {
+      const rel = `${dir}/${rest}`;
+      return SCRIPT_VERBS[rel] ? `hs ${SCRIPT_VERBS[rel]}` : `node ${PORTABLE_PACKAGE_DIR}/${rel}`;
+    })
+    .replace(/\bnpm run ([\w:.-]+)/g, (_m, script) =>
+      NPM_ALIASES[script] ? `hs ${NPM_ALIASES[script]}` : `npm --prefix ${PORTABLE_PACKAGE_DIR} run ${script}`,
+    );
+}
+
+const MARKER_RE = /\n<!-- heyspex-kit: managed by hs install \(sha256:([0-9a-f]{16})\)[^\n]*-->\n?$/;
+
+function shortHash(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex').slice(0, 16);
+}
+
+/**
+ * The customer copy of a canonical command: platform paths made portable,
+ * then a trailing marker carrying the hash of the body. The marker is how a
+ * re-run tells "ours, untouched, safe to update" from "the customer edited
+ * it, leave it alone".
+ */
+export function renderKitCommand(content, platformRoot) {
+  const body = `${rewritePlatformPaths(content, platformRoot).replace(/\s+$/, '')}\n`;
+  return (
+    `${body}\n<!-- heyspex-kit: managed by hs install (sha256:${shortHash(body)}). ` +
+    'Edit freely: once edited, hs install leaves this file alone. -->\n'
+  );
+}
+
+/**
+ * @param {string} content
+ * @returns {'managed' | 'customized' | 'unmanaged'}
+ */
+export function kitFileState(content) {
+  const m = String(content).match(MARKER_RE);
+  if (!m) return 'unmanaged';
+  const body = String(content).slice(0, m.index).replace(/\n$/, '');
+  return shortHash(`${body}\n`) === m[1] ? 'managed' : 'customized';
+}
+
+/**
+ * Whether to write one kit file. `raw` is the canonical (unrendered) content:
+ * an existing file equal to it is an old verbatim copy (`hs connect
+ * --fix-commands` before this change) and is safe to replace.
+ * @returns {{ write: boolean, reason: 'missing' | 'unchanged' | 'update' | 'legacy-copy' | 'customized' | 'forced' }}
+ */
+export function planKitFileWrite({ existing, rendered, raw, force }) {
+  if (existing === null || existing === undefined) return { write: true, reason: 'missing' };
+  if (existing === rendered) return { write: false, reason: 'unchanged' };
+  if (kitFileState(existing) === 'managed') return { write: true, reason: 'update' };
+  if (existing === raw) return { write: true, reason: 'legacy-copy' };
+  return force ? { write: true, reason: 'forced' } : { write: false, reason: 'customized' };
+}
+
+/**
+ * Every canonical harness command file, as `(installedDir, file, content,
+ * raw)`. With `targetRoot` set to a repo other than the platform, the list is
+ * filtered to customer-scoped commands and `content` is the rendered customer
+ * copy; otherwise `content === raw` (the platform's own trees).
+ * @param {string} platformRoot
+ * @param {{ joinPath: (...s: string[]) => string, readFile: (p: string) => string | null, listDir: (dir: string) => string[] }} deps
+ * @param {{ targetRoot?: string, isPlatformTarget?: boolean }} [opts]
+ * @returns {{ installedDir: readonly string[], file: string, content: string, raw: string }[]}
+ */
+export function listKitCommandFiles(platformRoot, deps, opts = {}) {
+  const customer =
+    opts.targetRoot !== undefined &&
+    !(opts.isPlatformTarget ?? samePlatformPath(opts.targetRoot, platformRoot));
+  const out = [];
+  for (const surface of HARNESS_COMMAND_SURFACES) {
+    const dir = resolveCanonicalCommandDir(platformRoot, surface, deps);
+    if (!dir) continue;
+    const files = deps
+      .listDir(dir)
+      .filter((f) => f.endsWith('.md'))
+      .sort();
+    for (const file of files) {
+      if (customer && !isCustomerCommand(file)) continue;
+      const raw = deps.readFile(deps.joinPath(dir, file));
+      if (raw === null) continue;
+      out.push({
+        installedDir: surface.installedDir,
+        file,
+        raw,
+        content: customer ? renderKitCommand(raw, platformRoot) : raw,
+      });
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Audit (hs doctor)
+// ---------------------------------------------------------------------------
+
+const fsDeps = {
+  joinPath: (...s) => path.join(...s),
+  readFile: (p) => {
+    try {
+      return fs.readFileSync(p, 'utf8');
+    } catch {
+      return null;
+    }
+  },
+  listDir: (d) => {
+    try {
+      return fs.readdirSync(d);
+    } catch {
+      return [];
+    }
+  },
+};
+
+/**
+ * What a customer repo is missing or carries stale, without writing anything.
+ * @param {{ targetRoot: string, platformRoot: string, deps?: typeof fsDeps }} opts
+ */
+export function auditCustomerKit({ targetRoot, platformRoot, deps = fsDeps }) {
+  const report = {
+    settingsError: null,
+    /** `stalePaths`: rows still on the legacy absolute machine path (a subset of `repaired`). */
+    hooks: { added: [], repaired: [], removed: [], stalePaths: [], total: 0 },
+    /** The committed launcher the hook rows point at. */
+    launcher: { path: [...CUSTOMER_LAUNCHERS.claude.rel].join('/'), state: 'missing' },
+    commands: { missing: [], stale: [], customized: [] },
+  };
+  const settingsPath = deps.joinPath(targetRoot, '.claude', 'settings.json');
+  const raw = deps.readFile(settingsPath);
+  let settings = {};
+  if (raw !== null) {
+    try {
+      const parsed = JSON.parse(raw);
+      settings = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    } catch (err) {
+      report.settingsError = `${settingsPath}: ${err instanceof Error ? err.message : String(err)}`;
+    }
+  }
+  if (!report.settingsError) {
+    const stalePaths = legacyAbsoluteHookRows(settings);
+    const r = mergeCustomerKitHooks(structuredClone(settings), customerRunnerPrefix(platformRoot));
+    report.hooks = { added: r.added, repaired: r.repaired, removed: r.removed, stalePaths, total: r.total };
+  }
+  const launcherPlan = planCustomerLauncherWrite(
+    deps.readFile(deps.joinPath(targetRoot, ...CUSTOMER_LAUNCHERS.claude.rel)),
+  );
+  report.launcher.state = launcherPlan.reason === 'update' ? 'stale' : launcherPlan.reason === 'missing' ? 'missing' : 'current';
+  for (const f of listKitCommandFiles(platformRoot, deps, { targetRoot, isPlatformTarget: false })) {
+    if (f.installedDir[0] !== '.claude') continue; // .cursor is the cursor-hooks/connect checks' business
+    const rel = [...f.installedDir, f.file].join('/');
+    const existing = deps.readFile(deps.joinPath(targetRoot, ...f.installedDir, f.file));
+    const plan = planKitFileWrite({ existing, rendered: f.content, raw: f.raw, force: false });
+    if (plan.reason === 'missing') report.commands.missing.push(rel);
+    else if (plan.reason === 'update' || plan.reason === 'legacy-copy') report.commands.stale.push(rel);
+    else if (plan.reason === 'customized') report.commands.customized.push(rel);
+  }
+  return report;
+}
+
+// ---------------------------------------------------------------------------
+// CLI: regenerate plugins/heyspex/hooks/hooks.json
+// ---------------------------------------------------------------------------
+
+/**
+ * "Was THIS module the script node was started with?" — bundle-safe.
+ *
+ * The plain comparison every script in this repo used (`import.meta.url ===
+ * pathToFileURL(argv[1])`) is wrong inside the esbuild CLI bundle
+ * (`dist/cli/*.mjs`, scripts/build-cli-bundle.mjs): there `import.meta.url`
+ * is the BUNDLE file's url for every module in it, and the bundle IS argv[1],
+ * so the test reads true for all of them at once and this file's CLI entry
+ * hijacked `hs connect --check` (it printed the usage line and no report).
+ * Requiring the module's own basename in the url rules the bundle out: a
+ * bundle is named after its entry (`hs-connect.mjs`), never after a library.
+ * Pure (every input injectable) so the three shapes are unit-tested.
+ *
+ * @param {string} importMetaUrl   The module's `import.meta.url`.
+ * @param {string} selfBasename    The module's own file name, e.g. `customer-kit.mjs`.
+ * @param {string | undefined} [argv1] `process.argv[1]` (default: the real one).
+ */
+export function invokedDirectly(importMetaUrl, selfBasename, argv1 = process.argv[1]) {
+  try {
+    if (!argv1) return false;
+    const self = fileURLToPath(importMetaUrl);
+    if (path.basename(self) !== selfBasename) return false;
+    return pathToFileURL(path.resolve(argv1)).href === pathToFileURL(self).href;
+  } catch {
+    return false;
+  }
+}
+
+const SELF = fileURLToPath(import.meta.url);
+if (invokedDirectly(import.meta.url, 'customer-kit.mjs')) {
+  const platformRoot = path.resolve(path.dirname(SELF), '..', '..');
+  const target = path.join(platformRoot, 'plugins', 'heyspex', 'hooks', 'hooks.json');
+  const want = renderPluginHooksText();
+  // EOL-insensitive: git's autocrlf may check the file out with CRLF.
+  const same = (fsDeps.readFile(target) ?? '').replace(/\r\n/g, '\n') === want;
+  if (process.argv.includes('--write-plugin-hooks')) {
+    if (!same) fs.writeFileSync(target, want, 'utf8');
+    console.log(`customer-kit: ${same ? 'unchanged' : 'wrote'} ${path.relative(platformRoot, target)}`);
+  } else if (process.argv.includes('--check-plugin-hooks')) {
+    if (!same) {
+      console.error('customer-kit: plugins/heyspex/hooks/hooks.json is stale — run `node scripts/lib/customer-kit.mjs --write-plugin-hooks`');
+      process.exit(1);
+    }
+    console.log('customer-kit: plugins/heyspex/hooks/hooks.json up to date');
+  } else if (process.argv.includes('--write-github-hooks') || process.argv.includes('--check-github-hooks')) {
+    const ghTarget = path.join(platformRoot, '.github', 'hooks', 'heyspex.json');
+    const ghWant = renderGithubHooksText();
+    const ghSame = (fsDeps.readFile(ghTarget) ?? '').replace(/\r\n/g, '\n') === ghWant;
+    if (process.argv.includes('--write-github-hooks')) {
+      if (!ghSame) {
+        fs.mkdirSync(path.dirname(ghTarget), { recursive: true });
+        fs.writeFileSync(ghTarget, ghWant, 'utf8');
+      }
+      console.log(`customer-kit: ${ghSame ? 'unchanged' : 'wrote'} ${path.relative(platformRoot, ghTarget).replace(/\\/g, '/')}`);
+    } else if (!ghSame) {
+      console.error('customer-kit: .github/hooks/heyspex.json is stale - run `node scripts/lib/customer-kit.mjs --write-github-hooks`');
+      process.exit(1);
+    } else {
+      console.log('customer-kit: .github/hooks/heyspex.json up to date');
+    }
+  } else {
+    console.log('usage: node scripts/lib/customer-kit.mjs --write-plugin-hooks | --check-plugin-hooks');
+  }
+}