heyspex 0.1.0 → 0.2.0

package/scripts/claude-hooks/intent-classifier-trigger.mjs

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+// Claude Code hook → the HeySpex Intent Classifier's SINGLE UserPromptSubmit entry point.
+//
+// HS-5ISS ENGINE CUTOVER: this hook now classifies through the engine module
+// (spexharness/src/intent-classifier.mjs's classifyPrompt) instead of the old
+// per-prompt Layer 2 "self_check" prose block (_intent-classifier-router.mjs's
+// buildSelfCheckBlock — ~4,200 tokens / ~6.5 KB, pasted into EVERY prompt that missed
+// every lexical pattern, i.e. almost every ordinary work order). The engine module is
+// LEXICAL ONLY: a prompt that matches none of the five classifier rules
+// (capture-on-idea, research-before-decision, settings-intent, defer-intent,
+// spec-reference-lookup) now injects NOTHING — under 500 bytes, usually zero — instead
+// of the old self-check block (AC3, [[HS-5ISS]]).
+//
+// A rule the engine matches still has to clear the SAME gating the old lexical sweep
+// applied (env kill switch, agent_behaviors.<key>.enabled, the injected-content guard)
+// before it fires — the engine module itself knows only patterns, not config or env,
+// so isBehaviorEligible() re-applies that gating here. Once eligible, the directive is
+// built through the SAME per-behavior transform (capture's confirm-mode substitution +
+// hints, research's source hint, settings/defer/spec-reference's raw inject) and
+// wrapped in the same CONFIRMED MATCH marker as the old lexical path
+// (buildConfirmedDirective) — so a gate that fires emits a byte-identical directive to
+// before. The five gates' own matching patterns and inject text are untouched.
+//
+// CUTOVER FLAG: agent_behaviors.intent_classifier.engine (.heyspex/config.yaml, read
+// from the VAULT root via the loader's default config root — this hook never joins a
+// config path itself; [[HS-4C76-9W86-DIAG-heyspex-config-yaml-has-no-single-home]]).
+// Defaults ON (isConfigKeyEnabled semantics — absent/anything but explicit `false` is
+// enabled). Set to `false` to fall back to the pre-HS-5ISS path in full — the unified
+// lexical-sweep-plus-Layer-2-self-check hook, unchanged (_intent-classifier-router.mjs's
+// runClassifierHook()).
+//
+// UNGATED by CLAUDE_AGENT — interactive human typing is the point. Per-behavior mutes
+// still work: HEYSPEX_CAPTURE_TRIGGER_OFF / HEYSPEX_RESEARCH_TRIGGER_OFF /
+// HEYSPEX_SETTINGS_INTENT_OFF / HEYSPEX_DEFER_INTENT_OFF / HEYSPEX_SPEC_REFERENCE_LOOKUP_OFF
+// = 1. HEYSPEX_INTENT_ENGINE_OFF=1 is the cutover's own env kill switch — same
+// contract as every other behavior here (a config_key AND an env var, never just
+// one) — and forces the old fallback path without touching the git-tracked config
+// file, which is what tests use to exercise the fallback safely. Decisions audited
+// to .heyspex/intent-classifier-history.jsonl.
+//
+// FAIL-SAFE: exits 0 on every path. A missing/corrupt config, a missing rule table, or
+// any thrown error degrades to "no injection" (engine path) or defers to the untouched
+// fallback (runClassifierHook never throws either).
+
+import { classifyPrompt } from '../../spexharness/src/intent-classifier.mjs';
+import { isConfigKeyEnabled, startsWithInjectedContent } from './_guardrail-loader.mjs';
+import {
+  appendClassifierEvent,
+  classifyIntent,
+  readIntentClassifierConfig,
+} from './_intent-classifier-semantic.mjs';
+import {
+  runClassifierHook,
+  readStdinJson,
+  behaviorKeyForRuleId,
+  isBehaviorEligible,
+  buildConfirmedDirective,
+  buildSelfCheckBlock,
+  CLASSIFIER_BEHAVIORS,
+  MIN_SELF_CHECK_CHARS,
+} from './_intent-classifier-router.mjs';
+
+const ENGINE_FLAG = 'agent_behaviors.intent_classifier.engine';
+
+// THE SEMANTIC NET ON THE ENGINE PATH ([[HS-3J57-7EDT-DIAG-intent-classifier-s-semantic-fallback]],
+// [[HS-8A3Y-LELB-DIAG-a-prose-feature-request-bypassed]]). The HS-5ISS cutover made a
+// lexical miss a silent no-op — the ~6.5 KB Layer 2 self-check block was dropped and
+// nothing took its place, so a paraphrased idea, or an owner's work-order-shaped
+// feature ask ("please also add this to heyspex-app … should we create our own …"),
+// reached the agent with no capture directive at all and was built straight from the
+// prompt. This is the replacement: on a miss, when the semantic layer is on
+// (agent_behaviors.intent_classifier.semantic_enabled, env HEYSPEX_INTENT_SEMANTIC_OFF=1
+// to mute), the hook's behavior depends on the resolved mode
+// (agent_behaviors.intent_classifier.mode, default self_check):
+//   - mode:self_check (DEFAULT) — the SAME deterministic SELF-CHECK block the legacy
+//     _intent-classifier-router.mjs path builds (buildSelfCheckBlock, reused verbatim
+//     — not a second copy of its prose) over whichever behaviors are still eligible on
+//     this prompt (env kill switch / config_key / injected-content guard, via
+//     isBehaviorEligible). This is a REAL directive, not an advisory: the agent judges
+//     the gates and, on a hit, fetches and follows the exact directive via
+//     `--directive <key>`, byte-identical to Layer 1. A prompt with zero eligible
+//     behaviors emits nothing (nothing to self-check).
+//   - mode:model (OPT-IN) — the local classifier is consulted first and a confident hit
+//     fires the full CONFIRMED MATCH directive, exactly as the legacy router's opt-in
+//     path did. When the model is silent, low-confidence, or unreachable, the hook
+//     falls back to the COMPACT_GATE_CHECK advisory below (under 400 bytes) rather than
+//     going fully silent again.
+// A sub-12-char prompt ("yes", "proceed") and a harness envelope (task-notification /
+// system-reminder as the prompt) never get either treatment.
+export const COMPACT_GATE_CHECK =
+  'HEYSPEX GATE CHECK (system note): no lexical rule matched. If this is a raw idea or a ' +
+  'feature ask (please add/build X, should we build our own X), run `node ' +
+  'scripts/claude-hooks/_intent-classifier-router.mjs --directive capture_on_idea` and ' +
+  'follow it. Other keys: research_before_decision, settings_intent, defer_intent, ' +
+  'spec_reference_lookup. Otherwise proceed silently.';
+
+/**
+ * The engine-miss fallback. Returns the additionalContext to emit, or null when the
+ * miss must stay silent (semantic layer off, prompt too short, harness envelope).
+ * Never throws.
+ */
+export async function engineMissFallback(prompt) {
+  try {
+    if (typeof prompt !== 'string' || prompt.trim().length < MIN_SELF_CHECK_CHARS) return null;
+    if (startsWithInjectedContent(prompt)) return null;
+    const cfg = readIntentClassifierConfig();
+    if (!cfg.semanticEnabled) return null;
+
+    if (cfg.semanticMode === 'model') {
+      const result = await classifyIntent(prompt);
+      if (
+        result?.behavior &&
+        result.confidence >= cfg.minConfidence &&
+        isBehaviorEligible(result.behavior, prompt)
+      ) {
+        const directive = buildConfirmedDirective(result.behavior, undefined, prompt);
+        if (directive) {
+          appendClassifierEvent({
+            surface: 'userpromptsubmit',
+            rule: result.behavior,
+            layer: 'semantic',
+            decision: 'fire',
+            engine: true,
+            confidence: result.confidence,
+            latency_ms: result.latencyMs,
+            prompt_chars: prompt.length,
+          });
+          return directive;
+        }
+      }
+      // model silent/low-confidence/unreachable/ineligible → fall through to the
+      // COMPACT_GATE_CHECK advisory below (unchanged from before this fix).
+    } else if (cfg.semanticMode === 'self_check') {
+      // THE FIX: reuse the legacy router's own self-check block builder
+      // (_intent-classifier-router.mjs's buildSelfCheckBlock) rather than the weak
+      // COMPACT_GATE_CHECK advisory — this is what closes the Layer 2 hole if
+      // `engine` is ever flipped back to true while mode stays self_check (the
+      // default and, on this machine, the only reachable mode: `model` needs an
+      // Ollama endpoint that is off the network here). Byte-identical to what the
+      // legacy path would emit for the SAME considered set, so a gate an agent
+      // judges to fire resolves to the exact same directive either way.
+      const considered = CLASSIFIER_BEHAVIORS.filter((behavior) =>
+        isBehaviorEligible(behavior.key, prompt),
+      ).map((behavior) => ({ behavior }));
+      if (considered.length) {
+        const additionalContext = buildSelfCheckBlock(considered, undefined, prompt);
+        if (additionalContext) {
+          appendClassifierEvent({
+            surface: 'userpromptsubmit',
+            rule: 'intent-classifier',
+            layer: 'semantic',
+            decision: 'self_check_injected',
+            engine: true,
+            offered: considered.map((entry) => entry.behavior.key),
+            prompt_chars: prompt.length,
+          });
+          return additionalContext;
+        }
+      }
+      // No behavior is currently eligible (every gate env/config-disabled) — mirror
+      // the legacy router's routePrompt(), which returns null before ever building a
+      // self-check block when its `eligible` set is empty. Nothing to self-check.
+      return null;
+    }
+
+    appendClassifierEvent({
+      surface: 'userpromptsubmit',
+      rule: null,
+      layer: 'semantic',
+      decision: 'compact_gate_check',
+      engine: true,
+      mode: cfg.semanticMode,
+      prompt_chars: prompt.length,
+    });
+    return COMPACT_GATE_CHECK;
+  } catch {
+    return null;
+  }
+}
+
+function emit(additionalContext) {
+  if (!additionalContext) return;
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext },
+    }),
+  );
+}
+
+/**
+ * The engine-cutover hook body: read the payload, classify via the engine module, and
+ * emit a directive ONLY when a gate both matches lexically AND is eligible (env/config/
+ * guard). Every other path — a full lexical miss, an unknown rule id, an ineligible
+ * behavior, a malformed payload — emits nothing at all, which is the point (AC3).
+ * Never throws (mirrors runClassifierHook's own contract).
+ */
+export async function runEngineClassifierHook() {
+  try {
+    const raw = await readStdinJson();
+    if (!raw) return;
+    let payload;
+    try {
+      payload = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (payload?.hook_event_name !== 'UserPromptSubmit') return;
+    const prompt = payload?.prompt;
+    if (typeof prompt !== 'string' || !prompt.trim()) return;
+
+    const hit = classifyPrompt(prompt);
+    if (!hit) {
+      // Lexical miss: the compact semantic net (see engineMissFallback) — never the
+      // old multi-KB self-check block, and nothing at all when the layer is off.
+      emit(await engineMissFallback(prompt));
+      return;
+    }
+
+    const behaviorKey = behaviorKeyForRuleId(hit.rule);
+    if (!behaviorKey) return; // an engine rule id this router doesn't know as a behavior
+
+    if (!isBehaviorEligible(behaviorKey, prompt)) return; // env-off / config-disabled / injected-content guard
+
+    const directive = buildConfirmedDirective(behaviorKey, undefined, prompt);
+    if (!directive) return;
+
+    appendClassifierEvent({
+      surface: 'userpromptsubmit',
+      rule: hit.rule,
+      layer: 'lexical',
+      decision: 'fire',
+      engine: true,
+      prompt_chars: prompt.length,
+    });
+
+    emit(directive);
+  } catch {
+    // Never break Claude Code on a hook failure.
+  }
+}
+
+const engineForcedOff = process.env.HEYSPEX_INTENT_ENGINE_OFF === '1';
+if (!engineForcedOff && isConfigKeyEnabled(ENGINE_FLAG)) {
+  runEngineClassifierHook();
+} else {
+  runClassifierHook();
+}

package/scripts/claude-hooks/log-session-activity.mjs

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+// log-session-activity.mjs — HS-6QEW-TASK (epic HS-JAAB-EPIC)
+// PreToolUse + PostToolUse hook (matcher .*): append one `agent.tool_called`
+// event row per tool call to the git-tracked .heyspex/sesslog-history.jsonl.
+//
+// Contract (see the task spec's Builder brief):
+// - Reuse the stdin-payload parse + resolveSessionId from claim-liveness-shared.mjs.
+// - Fail-open: any error, malformed payload, or missing field exits 0 — never
+//   break the host session.
+// - Privacy: args_hash (deterministic hash) by default; always redact keys
+//   matching /token|secret|password|api_key|auth/i; full args only behind the
+//   per-vault audit_log_full_args opt-in.
+// - Event fields: kind=agent.tool_called, source=hook, transport=local,
+//   tool_kind (edit|command|mcp|task|read|other), tool_name, session_id,
+//   session_short, spec_id, args_hash, latency_ms, success, error_kind, ts.
+// - `--self-test` entrypoint: exercises well-formed payload → one valid JSONL
+//   row (temp file), malformed payload → exit 0 no throw, api_key/token keys →
+//   redacted, identical args → identical args_hash. Exits 0 on pass.
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  normalizeHookEvent,
+  parseArgs,
+  readStdin,
+  resolveSessionId,
+} from "./claim-liveness-shared.mjs";
+
+const REPO_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+);
+
+function getLogPath() {
+  const env = process.env.HEYSPEX_SESSLOG_PATH?.trim();
+  return env || path.join(REPO_ROOT, ".heyspex", "sesslog-history.jsonl");
+}
+
+function getClaimsPath() {
+  const env = process.env.HEYSPEX_CLAIMS_PATH?.trim();
+  return env || path.join(REPO_ROOT, ".heyspex", "active-claims.json");
+}
+
+function getPendingDir() {
+  const env = process.env.HEYSPEX_SESSLOG_PENDING_DIR?.trim();
+  return env || path.join(REPO_ROOT, ".heyspex", "pending");
+}
+
+function getFocusPath() {
+  const env = process.env.HEYSPEX_FOCUS_PATH?.trim();
+  return env || path.join(REPO_ROOT, ".heyspex", "focus.yaml");
+}
+
+// Tool kind mapping
+function getToolKind(toolName) {
+  if (!toolName) return "other";
+  const toolMap = {
+    Edit: "edit",
+    Write: "edit",
+    NotebookEdit: "edit",
+    Bash: "command",
+    PowerShell: "command",
+    Read: "read",
+    Grep: "read",
+    Glob: "read",
+    Task: "task",
+    Agent: "task",
+  };
+  if (toolMap[toolName] !== undefined) return toolMap[toolName];
+  // Claude Code reports MCP tools as mcp__<server>__<tool>; Command Code's
+  // hooks engine reports the bare heyspex_<tool> name (seen in live rows).
+  if (
+    typeof toolName === "string" &&
+    (toolName.startsWith("mcp__") || toolName.startsWith("heyspex_"))
+  )
+    return "mcp";
+  return "other";
+}
+
+// Redact sensitive keys (shallow)
+function redactSensitiveKeys(obj) {
+  if (!obj || typeof obj !== "object") return obj;
+  const redacted = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (
+      typeof key === "string" &&
+      /token|secret|password|api_key|auth/i.test(key)
+    ) {
+      redacted[key] = "[REDACTED]";
+    } else {
+      redacted[key] = value;
+    }
+  }
+  return redacted;
+}
+
+// Generate deterministic hash from redacted args (sha256, first 16 hex chars)
+function generateArgsHash(args) {
+  if (!args || typeof args !== "object") return null;
+  const clean = redactSensitiveKeys(args);
+  return createHash("sha256")
+    .update(JSON.stringify(clean))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+// Write session log entry
+function writeSessionLogEntry(entry) {
+  try {
+    const logPath = getLogPath();
+    const dir = path.dirname(logPath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(logPath, JSON.stringify(entry) + "\n");
+  } catch {
+    // Fail-safe: silently ignore write errors
+  }
+}
+
+// Read active-claims.json and find claim for session
+function resolveClaim(sessionId) {
+  try {
+    const claimsPath = getClaimsPath();
+    if (!fs.existsSync(claimsPath)) return null;
+    const raw = fs.readFileSync(claimsPath, "utf8");
+    const data = JSON.parse(raw);
+    const claims = data?.claims;
+    if (!claims || typeof claims !== "object") return null;
+    // A session may hold several claims (e.g. an epic and its task) —
+    // attribute to the most recently active one.
+    const mine = Object.values(claims)
+      .filter((c) => c?.sessionId === sessionId)
+      .sort(
+        (a, b) =>
+          Date.parse(b.lastActivityAt ?? b.claimedAt ?? 0) -
+          Date.parse(a.lastActivityAt ?? a.claimedAt ?? 0),
+      );
+    if (mine.length > 0) {
+      return { specId: mine[0].specId, actor: mine[0].agent };
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+// Fallback attribution: the vault-wide focus pin (.heyspex/focus.yaml).
+// Coarser than a session claim — every unclaimed session inherits the pinned
+// spec — but it is the epic's named v1 mechanism for spec_id attribution.
+function resolveFocusSpecId() {
+  try {
+    const focusPath = getFocusPath();
+    if (!fs.existsSync(focusPath)) return null;
+    const raw = fs.readFileSync(focusPath, "utf8");
+    const m = /^spec_path:\s*(?:"([^"]+)"|'([^']+)'|(\S+))\s*$/m.exec(raw);
+    const specPath = m?.[1] ?? m?.[2] ?? m?.[3];
+    if (!specPath) return null;
+    // basename "HS-XXXX-KIND-slug.md" → id "HS-XXXX-KIND"
+    const base = path.basename(specPath, ".md");
+    const idMatch = /^(HS-[A-Za-z0-9]+-(?:MIL|EPIC|TASK|DIAG|RES|CAP|REV))/.exec(
+      base,
+    );
+    return idMatch?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// Sweep orphaned pending markers. A tool call that never gets a PostToolUse
+// (interrupt, denied permission, crashed session) leaks its marker forever, so
+// the dir accumulates. Anything older than 1 hour is dead — a stale marker only
+// costs one missing latency_ms, so deletion is always safe. Non-fatal.
+const STALE_MARKER_MS = 60 * 60 * 1000;
+function sweepStaleMarkers(dir) {
+  try {
+    const cutoff = Date.now() - STALE_MARKER_MS;
+    for (const name of fs.readdirSync(dir)) {
+      try {
+        const p = path.join(dir, name);
+        const st = fs.statSync(p);
+        if (st.isFile() && st.mtimeMs < cutoff) fs.unlinkSync(p);
+      } catch {
+        // fail-safe: skip entries we cannot stat/delete
+      }
+    }
+  } catch {
+    // fail-safe
+  }
+}
+
+// Write a pending marker file for PreToolUse
+function writePendingMarker(toolUseId) {
+  try {
+    const dir = getPendingDir();
+    if (!dir) return;
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    sweepStaleMarkers(dir);
+    const marker = { startTime: Date.now() };
+    fs.writeFileSync(path.join(dir, toolUseId), JSON.stringify(marker));
+  } catch {
+    // fail-safe
+  }
+}
+
+// Read and remove pending marker for PostToolUse; returns startTime or null
+function readPendingMarker(toolUseId) {
+  try {
+    const dir = getPendingDir();
+    if (!dir) return null;
+    const filePath = path.join(dir, toolUseId);
+    if (!fs.existsSync(filePath)) return null;
+    const raw = fs.readFileSync(filePath, "utf8");
+    fs.unlinkSync(filePath);
+    const data = JSON.parse(raw);
+    return typeof data?.startTime === "number" ? data.startTime : null;
+  } catch {
+    return null;
+  }
+}
+
+// Process hook event
+async function processHookEvent() {
+  try {
+    const payload = await readStdin();
+    if (!payload) return;
+
+    const parsedPayload = JSON.parse(payload);
+    const args = parsedPayload?.tool_input;
+    const toolName = parsedPayload?.tool_name;
+    // Claude Code sends hook_event_name in the payload (PascalCase); Cursor
+    // passes --event=camelCase on argv instead. Normalize both.
+    const cliArgs = parseArgs(process.argv);
+    const event = normalizeHookEvent(
+      parsedPayload?.hook_event_name ?? cliArgs.event,
+    );
+
+    // Skip if not a tool call event
+    if (event !== "PreToolUse" && event !== "PostToolUse") return;
+
+    const sessionId = resolveSessionId(parsedPayload);
+    if (!sessionId) return;
+
+    const fullArgsEnabled =
+      process.env.HEYSPEX_AUDIT_LOG_FULL_ARGS?.trim() === "1";
+    const argsHash = generateArgsHash(args);
+
+    // Determine tool kind
+    const toolKind = getToolKind(toolName);
+
+    // Resolve spec_id and actor: session claim first, focus pin as fallback
+    const claim = resolveClaim(sessionId);
+    const specId = claim?.specId ?? resolveFocusSpecId();
+    const actor = claim?.actor ?? "unknown";
+
+    const toolUseId = parsedPayload?.tool_use_id;
+
+    // PreToolUse: store pending marker, do NOT write session log row.
+    // (No claim-liveness emit here — that is the liveness hook's own job;
+    // calling it from this logger would double-emit heartbeats and add an
+    // HTTP round-trip to every tool call.)
+    if (event === "PreToolUse") {
+      if (toolUseId) writePendingMarker(toolUseId);
+      return;
+    }
+
+    // PostToolUse: compute latency (null = no matching marker), build entry, write row
+    let latencyMs = null;
+    if (toolUseId) {
+      const startTime = readPendingMarker(toolUseId);
+      if (startTime !== null) {
+        latencyMs = Math.max(0, Date.now() - startTime);
+      }
+    }
+
+    const response = parsedPayload?.tool_response;
+    let success = true;
+    let errorKind = null;
+
+    if (response && typeof response === "object") {
+      if (response.is_error === true) {
+        success = false;
+        errorKind = "tool_error";
+      } else if (typeof response.error === "string" && response.error.trim()) {
+        success = false;
+        errorKind = "tool_error";
+      }
+    }
+
+    // Build metadata
+    const metadata = {
+      tool_name: toolName,
+      tool_kind: toolKind,
+      session_id: sessionId,
+      session_short: sessionId.slice(0, 8),
+      source: "hook",
+      transport: "local",
+      args_hash: argsHash,
+      success,
+      latency_ms: latencyMs,
+    };
+
+    if (errorKind) {
+      metadata.error_kind = errorKind;
+    }
+
+    if (fullArgsEnabled && args && typeof args === "object") {
+      metadata.args = redactSensitiveKeys(args);
+    }
+
+    const entry = {
+      timestamp: new Date().toISOString(),
+      event_kind: "agent.tool_called",
+      actor,
+      spec_id: specId,
+      metadata,
+    };
+
+    writeSessionLogEntry(entry);
+  } catch {
+    // Fail-open: silently ignore all errors
+  }
+}
+
+// Self-test: DELEGATES to the sibling smoke file (the deterministic gate).
+// DO NOT replace this block with inline assertions — the gate contract requires
+// `node <this file> --self-test` to run log-session-activity.smoke.mjs verbatim.
+if (process.argv.includes("--self-test")) {
+  const { spawnSync } = await import("node:child_process");
+  const smoke = path.join(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "log-session-activity.smoke.mjs",
+  );
+  const proc = spawnSync(process.execPath, [smoke], { stdio: "inherit" });
+  process.exit(proc.status ?? 1);
+}
+
+// Main execution
+await processHookEvent();
+process.exit(0);

package/scripts/claude-hooks/naughty-list-gate.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// GENERATED by scripts/generate-hook-shells.mjs (HS-IQBF) — do not hand-edit.
+// This file only wires Claude Code's hook stdin/stdout contract to the
+// spexharness engine port of this gate. To change what this gate DECIDES,
+// edit spexharness/src/gates/naughty-list-gate.mjs. To change the SHAPE of this shell,
+// edit the generator, then rerun: node scripts/generate-hook-shells.mjs
+
+import { runGateAsHook } from '../../spexharness/src/adapters/claude-code.mjs';
+import gate from '../../spexharness/src/gates/naughty-list-gate.mjs';
+
+await runGateAsHook(gate);

package/scripts/claude-hooks/notify-status-flip.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// Claude Code hook → play tada.wav when a spec flips to `status: in_review`.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+import { isShipEvent, readStdin, repoRoot } from './terminal-close-shared.mjs';
+
+const SOUND_PATH = 'C:\\Windows\\Media\\tada.wav';
+
+function resolveSoundEnabledFromSettings() {
+  try {
+    const raw = fs.readFileSync(path.join(repoRoot(), 'spex-console', 'settings.json'), 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed?.soundEnabled === true;
+  } catch {
+    return false;
+  }
+}
+
+function playSound() {
+  try {
+    const child = spawn(
+      'powershell.exe',
+      [
+        '-NoProfile',
+        '-WindowStyle',
+        'Hidden',
+        '-Command',
+        `[System.Media.SoundPlayer]::new('${SOUND_PATH}').PlaySync()`,
+      ],
+      { detached: true, stdio: 'ignore', windowsHide: true },
+    );
+    child.unref();
+  } catch {
+    // Silent
+  }
+  try {
+    fs.writeFileSync(path.join(repoRoot(), '.heyspex', '.last-success-sound-at'), String(Date.now()));
+  } catch {
+    // never block
+  }
+}
+
+async function main() {
+  const stdinRaw = await readStdin();
+  if (!stdinRaw) return;
+
+  let payload;
+  try {
+    payload = JSON.parse(stdinRaw);
+  } catch {
+    return;
+  }
+
+  if (!isShipEvent(payload)) return;
+  if (!resolveSoundEnabledFromSettings()) return;
+
+  const filePath = payload?.file_path ?? payload?.tool_input?.file_path;
+  if (typeof filePath === 'string') {
+    try {
+      fs.accessSync(filePath, fs.constants.R_OK);
+    } catch {
+      return;
+    }
+  }
+
+  playSound();
+}
+
+main().catch(() => {});