heyspex 0.2.0 → 0.2.2

package/scripts/claude-hooks/_intent-classifier-router.mjs

@@ -1,410 +1,456 @@
-#!/usr/bin/env node
-// HeySpex Intent Classifier — the UNIFIED registry-driven router.
-//
-// One place that reads every `userpromptsubmit` / `prime` CLASSIFIER rule from the
-// compiled guardrail registry, runs ONE lexical sweep, and on a full lexical miss
-// resolves the harder-to-pattern-match cases WITHOUT a second, separate model.
-// Adding a future skill = adding a rule (+ a handler entry only if its inject needs
-// special logic).
-// Design home: [[HS-UJVA-EPIC-KKMO-autonomous-skill-routing-context]] "generalize the router".
-//
-// SEMANTIC LAYER (Layer 2) — TWO MODES ([[HS-M4PN-TASK]]):
-//   - self_check (DEFAULT): on a full lexical miss, build ONE deterministic SELF-CHECK
-//     block — for each eligible behavior, its classification gate paired with the exact
-//     resolved inject Layer 1 would have emitted — and hand it to the agent already
-//     running THIS session to judge as part of its own turn. No network, no fleet
-//     machine, no timeout/fail-safe path; works identically for the owner and any
-//     future customer, and needs zero HeySpex inference budget. The injection is
-//     DETERMINISTIC (same input → same block); the JUDGMENT is the agent's.
-//   - model (OPT-IN): the original mechanism — AT MOST ONE local-model call classifies
-//     the prompt and the winner fires above min_confidence. Demoted to opt-in; never
-//     on the default path, so no reachable endpoint is required.
-// The mode is resolved by readIntentClassifierConfig() (config `mode:` / env
-// HEYSPEX_INTENT_SEMANTIC_MODE). HEYSPEX_INTENT_SEMANTIC_OFF=1 disables Layer 2 wholly.
-//
-// PER-BEHAVIOR FIDELITY (byte-identical to the old separate hooks):
-//   - capture_on_idea: inject runs through applyConfirmMode() — the {{CONFIRM_MODE}}
-//     token is replaced with the forgiveness (auto) or permission (ask) directive,
-//     resolved by resolveConfirmMode('capture_on_idea'). Injected-content guard:
-//     startsWithInjectedContent (strict envelope-leads-with).
-//   - research_before_decision: rule.inject + appendResearchSourceHint() — a best-effort
-//     hint naming agent_behaviors.research.default_source/default_agent, appended (not
-//     replacing) so the original inject text stays byte-identical up to that point
-//     ([[HS-LFUH-DIAG-W1YE]] fix). Injected-content guard: containsInjectedContent
-//     (contains-anywhere — the research hook's original guard).
-//   - settings_intent: raw rule.inject. Injected-content guard: startsWithInjectedContent.
-//   Each behavior keeps its own config_key enable/disable and env kill switch. In the
-//   self_check mode the SAME per-behavior transform builds each directive inside the
-//   combined block, so the directive the agent follows stays byte-identical to Layer 1.
-//
-// PRECEDENCE: a lexical hit always wins over the semantic layer. Among lexical hits,
-// the FIRST behavior in BEHAVIOR_ORDER wins (deterministic). The behaviors are
-// mutually exclusive on their pattern sets today (verified by the cross-fire matrix in
-// the smoke suites) — the order only matters as a tiebreak that must never be reached.
-//
-// HARD FAIL-SAFE: every function degrades to "no injection". A corrupt/missing
-// registry, a disabled rule, an unreachable/slow model, or any thrown error → the
-// caller emits nothing and exits 0. Dependency-free (Node stdlib + global fetch).
-
-import {
-  loadGuardrails,
-  rulesForSurface,
-  compilePatterns,
-  isRuleEnabled,
-} from './_guardrail-loader.mjs';
-import {
-  classifyIntent,
-  readIntentClassifierConfig,
-  appendClassifierEvent,
-} from './_intent-classifier-semantic.mjs';
-// HS-N01T: the directive assembly MOVED to the engine (spexharness/src/intent-directive.mjs)
-// so the Claude Code hook and a SpexCode seat build the SAME text for the same prompt. This
-// router imports it from there and RE-EXPORTS every moved symbol under its old name, so the
-// trigger hook, the smokes and the `--directive` CLI keep their imports and their bytes.
-// Layering: the plugin scripts import DOWN into the engine, never the reverse.
-import {
-  CONFIRMED_MATCH_MARKER,
-  withConfirmedMatchMarker,
-  CAPTURE_MODE_DIRECTIVES,
-  CLASSIFIER_BEHAVIORS,
-  applyCaptureConfirmMode,
-  appendCaptureKindHint,
-  appendCaptureRoutingHint,
-  appendResearchSourceHint,
-  buildConfirmedDirective,
-  behaviorKeyForRuleId,
-  isBehaviorEligible,
-} from '../../spexharness/src/intent-directive.mjs';
-
-export {
-  CONFIRMED_MATCH_MARKER,
-  CAPTURE_MODE_DIRECTIVES,
-  CLASSIFIER_BEHAVIORS,
-  applyCaptureConfirmMode,
-  appendCaptureKindHint,
-  appendCaptureRoutingHint,
-  appendResearchSourceHint,
-  buildConfirmedDirective,
-  behaviorKeyForRuleId,
-  isBehaviorEligible,
-};
-
-const SURFACE = 'userpromptsubmit';
-
-// Human-readable heading per behavior for the self-check block. Falls back to the key.
-const SELF_CHECK_LABELS = {
-  capture_on_idea: 'Capture-on-idea',
-  research_before_decision: 'Research-before-decision',
-  settings_intent: 'Settings intent',
-  defer_intent: 'Defer / schedule intent',
-  spec_reference_lookup: 'Spec-reference lookup',
-};
-
-// Cheap deterministic emission floor (mirrors the old classifyIntent text.length<12
-// short-prompt skip): a sub-12-char message ("yes", "ok", "proceed") carries no
-// classifiable intent, so never spend the agent's attention self-checking it.
-export const MIN_SELF_CHECK_CHARS = 12;
-
-/**
- * Build the ONE deterministic self-check block emitted on a lexical miss (mode:
- * self_check). For each considered behavior it pairs the classification GATE (the same
- * description the model was given) with the exact resolved inject Layer 1 would have
- * emitted — so whichever ONE the agent judges to apply, it follows the byte-identical
- * directive. The wrapper's whole job is precision: it states loudly that the common
- * outcome is "none" and that the check must never leak into the visible response, so a
- * block injected on every substantive prompt does not turn into noise. Deterministic:
- * same considered set + repoRoot → same block.
- */
-export function buildSelfCheckBlock(considered, repoRoot, prompt) {
-  const sections = considered.map((entry) => {
-    const label = SELF_CHECK_LABELS[entry.behavior.key] || entry.behavior.key;
-    return (
-      `### ${label} (${entry.behavior.key})\n` +
-      `Applies ONLY when: ${entry.behavior.description}`
-    );
-  });
-  return (
-    'HEYSPEX SILENT SELF-CHECK — a deterministic system note (NOT written by the user). ' +
-    "Before you respond, silently judge the user's latest message against the gate(s) below.\n" +
-    'DEFAULT OUTCOME IS "NONE": ordinary work orders, questions about existing work, direct answers, ' +
-    'and small talk match NONE of these. When none clearly applies — the common case — do NOT mention ' +
-    "this note, do NOT change what you would otherwise do, and just carry out the user's request normally.\n" +
-    'If EXACTLY ONE gate clearly applies, run this to get its exact directive and follow that verbatim:\n' +
-    `  node scripts/claude-hooks/_intent-classifier-router.mjs --directive <key>\n` +
-    '(<key> is the parenthesised key on the heading, e.g. capture_on_idea. If two gates seem to apply, ' +
-    'pick the single best fit and fetch only that one.) Never announce, quote, or acknowledge that you ' +
-    'ran this check — the user must not see it.\n\n' +
-    sections.join('\n\n')
-  );
-}
-
-/**
- * Resolve ONE behavior's full directive on demand — the other half of the
- * gate-plus-pointer split above.
- *
- * The block used to paste all four directives into every substantive turn, about
- * 4,200 tokens, so the agent could judge which one applied. It usually applied to
- * none of them, which meant paying for four directives to use zero. Now the block
- * carries only the gates (what you need to JUDGE) and this resolves the directive
- * (what you need to ACT) for the one gate that fired.
- *
- * Returns the directive string, or null when the key is unknown / its rule is gone.
- */
-export function resolveDirective(behaviorKey, repoRoot, prompt = '') {
-  const resolved = resolveBehaviorRules();
-  const entry = resolved.find((e) => e.behavior.key === behaviorKey);
-  if (!entry) return null;
-  return entry.behavior.transform(entry.rule.inject, repoRoot, prompt);
-}
-
-/**
- * Resolve the compiled rule for each classifier behavior from the registry. Returns a
- * map behaviorKey → { behavior, rule, patterns } for behaviors whose rule exists and
- * carries an inject. FAIL-SAFE: a missing rule simply drops that behavior.
- */
-function resolveBehaviorRules() {
-  const guardrails = loadGuardrails();
-  const primeRules = rulesForSurface(guardrails, SURFACE, 'prime');
-  const byId = new Map(primeRules.map((r) => [r.rule, r]));
-  const resolved = [];
-  for (const behavior of CLASSIFIER_BEHAVIORS) {
-    const rule = byId.get(behavior.ruleId);
-    if (!rule || !rule.inject) continue;
-    resolved.push({ behavior, rule, patterns: compilePatterns(rule) });
-  }
-  return resolved;
-}
-
-/**
- * Is this behavior eligible to fire on this prompt at all? (env kill switch off,
- * config_key enabled, and the injected-content envelope guard passes). Behaviors that
- * are ineligible participate in neither the lexical sweep nor the semantic call —
- * matching the old per-hook early-returns exactly.
- */
-function isEligible(entry, prompt, repoRoot) {
-  const { behavior, rule } = entry;
-  if (process.env[behavior.envOff] === '1') return false;
-  if (rule.ignoreInjectedContent && behavior.guard(prompt)) return false;
-  if (!isRuleEnabled(rule, repoRoot)) return false;
-  return true;
-}
-
-/**
- * Classify a prompt and return the single inject to emit, or null.
- * `deps.classify` is injectable for tests (defaults to the real semantic classifier).
- * Guarantees AT MOST ONE call to `deps.classify` per invocation.
- *
- * @param {object} [opts]
- * @param {string} [opts.repoRoot]
- * @param {object} [opts.deps]
- * @param {string|null} [opts.onlyBehavior] Restrict firing to this one behavior key —
- *   originally used by the three thin per-behavior shim hooks (capture-trigger /
- *   research-trigger / settings-intent-trigger, retired HS-IYU1 after burn-in) so
- *   each stayed byte-identical to its old single-behavior self: it lexically tests
- *   ONLY its own patterns, and on a miss its self-check block offers ONLY its own
- *   behavior (mode: self_check) / classifies against all eligible but fires only its
- *   own winner (mode: model). Kept as a general single-behavior mode for callers that
- *   still need it (e.g. tests). Omit for the unified hook (all behaviors compete /
- *   are offered together).
- * @returns {Promise<{ additionalContext: string, behavior: string, layer: 'lexical'|'semantic', confidence?: number, offered?: string[] } | null>}
- *   In mode self_check the semantic result has behavior:'self_check' and `offered` lists
- *   the behavior keys the block presented; in mode model it is the single winning behavior.
- */
-export async function routePrompt(prompt, { repoRoot, deps = {}, onlyBehavior = null } = {}) {
-  try {
-    if (typeof prompt !== 'string' || !prompt.trim()) return null;
-    const entries = resolveBehaviorRules();
-    if (!entries.length) return null;
-
-    // Eligibility is computed once and reused for BOTH layers.
-    const eligible = entries.filter((e) => isEligible(e, prompt, repoRoot));
-    if (!eligible.length) return null;
-
-    // In onlyBehavior (single-behavior) mode, the lexical sweep and the final fire are
-    // restricted to that one behavior; if it is ineligible, do nothing at all (matching
-    // the retired per-hook shims' early-return). The semantic classification still runs
-    // against all eligible behaviors so the model picks among the same options as before.
-    const considered = onlyBehavior ? eligible.filter((e) => e.behavior.key === onlyBehavior) : eligible;
-    if (!considered.length) return null;
-
-    // ── Layer 1: lexical (fast path). First match in BEHAVIOR_ORDER wins. ──
-    for (const entry of considered) {
-      if (entry.patterns.some((re) => re.test(prompt))) {
-        const additionalContext = withConfirmedMatchMarker(entry.behavior.transform(entry.rule.inject, repoRoot, prompt));
-        appendClassifierEvent(
-          { surface: SURFACE, rule: entry.behavior.ruleId, layer: 'lexical', decision: 'fire', prompt_chars: prompt.length },
-          repoRoot,
-        );
-        return { additionalContext, behavior: entry.behavior.key, layer: 'lexical' };
-      }
-    }
-
-    // ── Layer 2: semantic (regex missed). ──
-    const cfg = readIntentClassifierConfig(repoRoot);
-    if (!cfg.semanticEnabled) return null;
-
-    // DEFAULT (mode: self_check): deterministically inject ONE self-check block and let
-    // THIS session's own agent judge intent — no second model, no network call.
-    if (cfg.semanticMode !== 'model') {
-      // Cheap deterministic floor: skip trivially short prompts (no classifiable
-      // intent). Anything longer gets the block; PRECISION is the agent's job (the
-      // wrapper tells it the default is "none, do nothing"), not a hook-side pre-verdict.
-      if (prompt.trim().length < MIN_SELF_CHECK_CHARS) return null;
-
-      const additionalContext = buildSelfCheckBlock(considered, repoRoot, prompt);
-      if (!additionalContext) return null;
-      appendClassifierEvent(
-        {
-          surface: SURFACE,
-          // Unified hook offers all eligible behaviors; a shim offers just its one.
-          rule: onlyBehavior ? considered[0].behavior.ruleId : 'intent-classifier',
-          layer: 'semantic',
-          decision: 'self_check_injected',
-          offered: considered.map((e) => e.behavior.ruleId),
-          prompt_chars: prompt.length,
-        },
-        repoRoot,
-      );
-      return {
-        additionalContext,
-        behavior: 'self_check',
-        layer: 'semantic',
-        offered: considered.map((e) => e.behavior.key),
-      };
-    }
-
-    // OPT-IN (mode: model): the original mechanism — AT MOST ONE local-model call.
-    const behaviorsForModel = eligible.map((e) => ({
-      key: e.behavior.key,
-      description: e.behavior.description,
-    }));
-    const classify = deps.classify || classifyIntent;
-    const result = await classify(prompt, behaviorsForModel, { ...cfg, repoRoot });
-
-    if (result.error) {
-      appendClassifierEvent(
-        { surface: SURFACE, rule: 'intent-classifier', layer: 'semantic', decision: 'error', error: result.error, prompt_chars: prompt.length },
-        repoRoot,
-      );
-      return null;
-    }
-
-    // In onlyBehavior mode the winner must be that behavior; otherwise any eligible.
-    const winner = considered.find((e) => e.behavior.key === result.behavior);
-    if (!winner) return null; // 'none', another behavior, or an unrecognized/ineligible key
-
-    const fire = result.confidence >= cfg.minConfidence;
-    appendClassifierEvent(
-      {
-        surface: SURFACE,
-        rule: winner.behavior.ruleId,
-        layer: 'semantic',
-        decision: fire ? 'fire' : 'below_threshold',
-        confidence: result.confidence,
-        min_confidence: cfg.minConfidence,
-        model: cfg.model,
-        latency_ms: result.latencyMs,
-        prompt_chars: prompt.length,
-      },
-      repoRoot,
-    );
-    if (!fire) return null;
-
-    const additionalContext = withConfirmedMatchMarker(winner.behavior.transform(winner.rule.inject, repoRoot, prompt));
-    return { additionalContext, behavior: winner.behavior.key, layer: 'semantic', confidence: result.confidence };
-  } catch {
-    return null; // any unexpected error → no injection (fail-safe)
-  }
-}
-
-// ── shared hook entry (stdin → route → emit) ────────────────────────────────
-// The unified hook calls this with `onlyBehavior` unset; the three per-behavior
-// shims (capture-trigger / research-trigger / settings-intent-trigger) called it
-// with `onlyBehavior` set until they were retired after burn-in (HS-IYU1). Fail-safe:
-// reads stdin defensively, never throws.
-
-export function readStdinJson() {
-  if (process.stdin.isTTY) return Promise.resolve(null);
-  return new Promise((resolve) => {
-    let buf = '';
-    let settled = false;
-    const finish = (value) => {
-      if (settled) return;
-      settled = true;
-      resolve(value);
-    };
-    const timer = setTimeout(() => finish(buf || ''), 200);
-    process.stdin.setEncoding('utf8');
-    process.stdin.on('data', (chunk) => {
-      buf += chunk;
-    });
-    process.stdin.on('end', () => {
-      clearTimeout(timer);
-      finish(buf);
-    });
-    process.stdin.on('error', () => {
-      clearTimeout(timer);
-      finish(buf);
-    });
-  });
-}
-
-function emit(additionalContext) {
-  if (!additionalContext) return;
-  process.stdout.write(
-    JSON.stringify({
-      hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext },
-    }),
-  );
-}
-
-/**
- * Full UserPromptSubmit hook body: read the payload, route the prompt, emit the winner.
- * @param {{ onlyBehavior?: string|null }} [options]
- */
-export async function runClassifierHook({ onlyBehavior = null } = {}) {
-  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 routed = await routePrompt(prompt, { onlyBehavior });
-    if (routed) emit(routed.additionalContext);
-  } catch {
-    // Never break Claude Code on a hook failure.
-  }
-}
-
-// ── CLI: resolve one directive on demand ────────────────────────────────────
-// The self-check block emits gates plus a pointer here, rather than pasting all
-// four directives into every turn. Invoked as:
-//   node scripts/claude-hooks/_intent-classifier-router.mjs --directive capture_on_idea
-// Prints the directive to stdout and exits 0, or an error to stderr and exits 1.
-if (process.argv[2] === '--directive') {
-  const key = process.argv[3];
-  if (!key) {
-    process.stderr.write(
-      'usage: _intent-classifier-router.mjs --directive <key>\n' +
-      `known keys: ${CLASSIFIER_BEHAVIORS.map((b) => b.key).join(', ')}\n`,
-    );
-    process.exit(1);
-  }
-  // repoRoot is optional throughout — the loader helpers fall back to their own
-  // env/cwd detection, the same as the hook path does.
-  const directive = resolveDirective(key, undefined, process.argv[4] ?? '');
-  if (!directive) {
-    process.stderr.write(
-      `unknown or unavailable behavior key: ${key}\n` +
-      `known keys: ${CLASSIFIER_BEHAVIORS.map((b) => b.key).join(', ')}\n`,
-    );
-    process.exit(1);
-  }
-  process.stdout.write(directive + '\n');
-}
+#!/usr/bin/env node
+// HeySpex Intent Classifier — the UNIFIED registry-driven router.
+//
+// One place that reads every `userpromptsubmit` / `prime` CLASSIFIER rule from the
+// compiled guardrail registry, runs ONE lexical sweep, and on a full lexical miss
+// resolves the harder-to-pattern-match cases WITHOUT a second, separate model.
+// Adding a future skill = adding a rule (+ a handler entry only if its inject needs
+// special logic).
+// Design home: [[HS-UJVA-EPIC-KKMO-autonomous-skill-routing-context]] "generalize the router".
+//
+// SEMANTIC LAYER (Layer 2) — TWO MODES ([[HS-M4PN-TASK]]):
+//   - self_check (DEFAULT): on a full lexical miss, build ONE deterministic SELF-CHECK
+//     block — for each eligible behavior, its classification gate paired with the exact
+//     resolved inject Layer 1 would have emitted — and hand it to the agent already
+//     running THIS session to judge as part of its own turn. No network, no fleet
+//     machine, no timeout/fail-safe path; works identically for the owner and any
+//     future customer, and needs zero HeySpex inference budget. The injection is
+//     DETERMINISTIC (same input → same block); the JUDGMENT is the agent's.
+//   - model (OPT-IN): the original mechanism — AT MOST ONE local-model call classifies
+//     the prompt and the winner fires above min_confidence. Demoted to opt-in; never
+//     on the default path, so no reachable endpoint is required.
+// The mode is resolved by readIntentClassifierConfig() (config `mode:` / env
+// HEYSPEX_INTENT_SEMANTIC_MODE). HEYSPEX_INTENT_SEMANTIC_OFF=1 disables Layer 2 wholly.
+//
+// PER-BEHAVIOR FIDELITY (byte-identical to the old separate hooks):
+//   - capture_on_idea: inject runs through applyConfirmMode() — the {{CONFIRM_MODE}}
+//     token is replaced with the forgiveness (auto) or permission (ask) directive,
+//     resolved by resolveConfirmMode('capture_on_idea'). Injected-content guard:
+//     startsWithInjectedContent (strict envelope-leads-with).
+//   - research_before_decision: rule.inject + appendResearchSourceHint() — a best-effort
+//     hint naming agent_behaviors.research.default_source/default_agent, appended (not
+//     replacing) so the original inject text stays byte-identical up to that point
+//     ([[HS-LFUH-DIAG-W1YE]] fix). Injected-content guard: containsInjectedContent
+//     (contains-anywhere — the research hook's original guard).
+//   - settings_intent: raw rule.inject. Injected-content guard: startsWithInjectedContent.
+//   Each behavior keeps its own config_key enable/disable and env kill switch. In the
+//   self_check mode the SAME per-behavior transform builds each directive inside the
+//   combined block, so the directive the agent follows stays byte-identical to Layer 1.
+//
+// PRECEDENCE: a lexical hit always wins over the semantic layer. Among lexical hits,
+// the FIRST behavior in BEHAVIOR_ORDER wins (deterministic). The behaviors are
+// mutually exclusive on their pattern sets today (verified by the cross-fire matrix in
+// the smoke suites) — the order only matters as a tiebreak that must never be reached.
+//
+// HARD FAIL-SAFE: every function degrades to "no injection". A corrupt/missing
+// registry, a disabled rule, an unreachable/slow model, or any thrown error → the
+// caller emits nothing and exits 0. Dependency-free (Node stdlib + global fetch).
+
+import {
+  loadGuardrails,
+  rulesForSurface,
+  compilePatterns,
+  isRuleEnabled,
+} from './_guardrail-loader.mjs';
+import {
+  classifyIntent,
+  readIntentClassifierConfig,
+  appendClassifierEvent,
+} from './_intent-classifier-semantic.mjs';
+// HS-N01T: the directive assembly MOVED to the engine (spexharness/src/intent-directive.mjs)
+// so the Claude Code hook and a SpexCode seat build the SAME text for the same prompt. This
+// router imports it from there and RE-EXPORTS every moved symbol under its old name, so the
+// trigger hook, the smokes and the `--directive` CLI keep their imports and their bytes.
+// Layering: the plugin scripts import DOWN into the engine, never the reverse.
+import {
+  CONFIRMED_MATCH_MARKER,
+  withConfirmedMatchMarker,
+  withMatchMarker,
+  ruleMatchesPrompt,
+  CAPTURE_MODE_DIRECTIVES,
+  CLASSIFIER_BEHAVIORS,
+  applyCaptureConfirmMode,
+  appendCaptureKindHint,
+  appendCaptureRoutingHint,
+  appendResearchSourceHint,
+  buildConfirmedDirective,
+  behaviorKeyForRuleId,
+  isBehaviorEligible,
+} from '../../spexharness/src/intent-directive.mjs';
+
+export {
+  CONFIRMED_MATCH_MARKER,
+  CAPTURE_MODE_DIRECTIVES,
+  CLASSIFIER_BEHAVIORS,
+  applyCaptureConfirmMode,
+  appendCaptureKindHint,
+  appendCaptureRoutingHint,
+  appendResearchSourceHint,
+  buildConfirmedDirective,
+  behaviorKeyForRuleId,
+  isBehaviorEligible,
+};
+
+const SURFACE = 'userpromptsubmit';
+
+// Human-readable heading per behavior for the self-check block. Falls back to the key.
+const SELF_CHECK_LABELS = {
+  capture_on_idea: 'Capture-on-idea',
+  research_before_decision: 'Research-before-decision',
+  settings_intent: 'Settings intent',
+  defer_intent: 'Defer / schedule intent',
+  handoff_intent: 'Hand-off request',
+  spec_reference_lookup: 'Spec-reference lookup',
+};
+
+// Cheap deterministic emission floor (mirrors the old classifyIntent text.length<12
+// short-prompt skip): a sub-12-char message ("yes", "ok", "proceed") carries no
+// classifiable intent, so never spend the agent's attention self-checking it.
+export const MIN_SELF_CHECK_CHARS = 12;
+
+/**
+ * Build the ONE deterministic self-check block emitted on a lexical miss (mode:
+ * self_check). For each considered behavior it pairs the classification GATE (the same
+ * description the model was given) with the exact resolved inject Layer 1 would have
+ * emitted — so whichever ONE the agent judges to apply, it follows the byte-identical
+ * directive. The wrapper's whole job is precision: it states loudly that the common
+ * outcome is "none" and that the check must never leak into the visible response, so a
+ * block injected on every substantive prompt does not turn into noise. Deterministic:
+ * same considered set + repoRoot → same block.
+ */
+export function buildSelfCheckBlock(considered, repoRoot, prompt) {
+  const sections = considered.map((entry) => {
+    const label = SELF_CHECK_LABELS[entry.behavior.key] || entry.behavior.key;
+    return (
+      `### ${label} (${entry.behavior.key})\n` +
+      `Applies ONLY when: ${entry.behavior.description}`
+    );
+  });
+  return (
+    'HEYSPEX SILENT SELF-CHECK — a deterministic system note (NOT written by the user). ' +
+    "Before you respond, silently judge the user's latest message against the gate(s) below.\n" +
+    'DEFAULT OUTCOME IS "NONE": ordinary work orders, questions about existing work, direct answers, ' +
+    'and small talk match NONE of these. When none clearly applies — the common case — do NOT mention ' +
+    "this note, do NOT change what you would otherwise do, and just carry out the user's request normally.\n" +
+    'If EXACTLY ONE gate clearly applies, run this to get its exact directive and follow that verbatim:\n' +
+    `  node scripts/claude-hooks/_intent-classifier-router.mjs --directive <key>\n` +
+    '(<key> is the parenthesised key on the heading, e.g. capture_on_idea. If two gates seem to apply, ' +
+    'pick the single best fit and fetch only that one.) Never announce, quote, or acknowledge that you ' +
+    'ran this check — the user must not see it.\n\n' +
+    sections.join('\n\n')
+  );
+}
+
+/**
+ * Resolve ONE behavior's full directive on demand — the other half of the
+ * gate-plus-pointer split above.
+ *
+ * The block used to paste all four directives into every substantive turn, about
+ * 4,200 tokens, so the agent could judge which one applied. It usually applied to
+ * none of them, which meant paying for four directives to use zero. Now the block
+ * carries only the gates (what you need to JUDGE) and this resolves the directive
+ * (what you need to ACT) for the one gate that fired.
+ *
+ * Returns the directive string, or null when the key is unknown / its rule is gone.
+ */
+export function resolveDirective(behaviorKey, repoRoot, prompt = '') {
+  const resolved = resolveBehaviorRules();
+  const entry = resolved.find((e) => e.behavior.key === behaviorKey);
+  if (!entry) return null;
+  return entry.behavior.transform(entry.rule.inject, repoRoot, prompt);
+}
+
+/**
+ * Resolve the compiled rule for each classifier behavior from the registry. Returns a
+ * map behaviorKey → { behavior, rule, patterns } for behaviors whose rule exists and
+ * carries an inject. FAIL-SAFE: a missing rule simply drops that behavior.
+ */
+function resolveBehaviorRules() {
+  const guardrails = loadGuardrails();
+  const primeRules = rulesForSurface(guardrails, SURFACE, 'prime');
+  const byId = new Map(primeRules.map((r) => [r.rule, r]));
+  const resolved = [];
+  for (const behavior of CLASSIFIER_BEHAVIORS) {
+    const rule = byId.get(behavior.ruleId);
+    if (!rule || !rule.inject) continue;
+    resolved.push({ behavior, rule, patterns: compilePatterns(rule) });
+  }
+  return resolved;
+}
+
+/**
+ * Is this behavior eligible to fire on this prompt at all? (env kill switch off,
+ * config_key enabled, and the injected-content envelope guard passes). Behaviors that
+ * are ineligible participate in neither the lexical sweep nor the semantic call —
+ * matching the old per-hook early-returns exactly.
+ */
+function isEligible(entry, prompt, repoRoot) {
+  const { behavior, rule } = entry;
+  if (process.env[behavior.envOff] === '1') return false;
+  if (rule.ignoreInjectedContent && behavior.guard(prompt)) return false;
+  if (!isRuleEnabled(rule, repoRoot)) return false;
+  return true;
+}
+
+/**
+ * Classify a prompt and return the single inject to emit, or null.
+ * `deps.classify` is injectable for tests (defaults to the real semantic classifier).
+ * Guarantees AT MOST ONE call to `deps.classify` per invocation.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.repoRoot]
+ * @param {object} [opts.deps]
+ * @param {string|null} [opts.onlyBehavior] Restrict firing to this one behavior key —
+ *   originally used by the three thin per-behavior shim hooks (capture-trigger /
+ *   research-trigger / settings-intent-trigger, retired HS-IYU1 after burn-in) so
+ *   each stayed byte-identical to its old single-behavior self: it lexically tests
+ *   ONLY its own patterns, and on a miss its self-check block offers ONLY its own
+ *   behavior (mode: self_check) / classifies against all eligible but fires only its
+ *   own winner (mode: model). Kept as a general single-behavior mode for callers that
+ *   still need it (e.g. tests). Omit for the unified hook (all behaviors compete /
+ *   are offered together).
+ * @returns {Promise<{ additionalContext: string, behavior: string, layer: 'lexical'|'semantic', confidence?: number, offered?: string[] } | null>}
+ *   In mode self_check the semantic result has behavior:'self_check' and `offered` lists
+ *   the behavior keys the block presented; in mode model it is the single winning behavior.
+ */
+export async function routePrompt(prompt, { repoRoot, deps = {}, onlyBehavior = null } = {}) {
+  try {
+    if (typeof prompt !== 'string' || !prompt.trim()) return null;
+    const entries = resolveBehaviorRules();
+    if (!entries.length) return null;
+
+    // Eligibility is computed once and reused for BOTH layers.
+    const eligible = entries.filter((e) => isEligible(e, prompt, repoRoot));
+    if (!eligible.length) return null;
+
+    // In onlyBehavior (single-behavior) mode, the lexical sweep and the final fire are
+    // restricted to that one behavior; if it is ineligible, do nothing at all (matching
+    // the retired per-hook shims' early-return). The semantic classification still runs
+    // against all eligible behaviors so the model picks among the same options as before.
+    const considered = onlyBehavior ? eligible.filter((e) => e.behavior.key === onlyBehavior) : eligible;
+    if (!considered.length) return null;
+
+    // ── Layer 1: lexical (fast path). First match in BEHAVIOR_ORDER wins. ──
+    for (const entry of considered) {
+      // HS-XDH8: negation-aware for guarded rules; per-behavior marker (defer/settings are precision-gated).
+      if (ruleMatchesPrompt(entry.rule, entry.patterns, prompt)) {
+        const additionalContext = withMatchMarker(entry.behavior.key, entry.behavior.transform(entry.rule.inject, repoRoot, prompt));
+        appendClassifierEvent(
+          { surface: SURFACE, rule: entry.behavior.ruleId, layer: 'lexical', decision: 'fire', prompt_chars: prompt.length },
+          repoRoot,
+        );
+        return { additionalContext, behavior: entry.behavior.key, layer: 'lexical' };
+      }
+    }
+
+    // ── Layer 2: semantic (regex missed). ──
+    const cfg = readIntentClassifierConfig(repoRoot);
+    if (!cfg.semanticEnabled) return null;
+
+    // DEFAULT (mode: self_check): deterministically inject ONE self-check block and let
+    // THIS session's own agent judge intent — no second model, no network call.
+    if (cfg.semanticMode !== 'model') {
+      // Cheap deterministic floor: skip trivially short prompts (no classifiable
+      // intent). Anything longer gets the block; PRECISION is the agent's job (the
+      // wrapper tells it the default is "none, do nothing"), not a hook-side pre-verdict.
+      if (prompt.trim().length < MIN_SELF_CHECK_CHARS) return null;
+
+      const additionalContext = buildSelfCheckBlock(considered, repoRoot, prompt);
+      if (!additionalContext) return null;
+      appendClassifierEvent(
+        {
+          surface: SURFACE,
+          // Unified hook offers all eligible behaviors; a shim offers just its one.
+          rule: onlyBehavior ? considered[0].behavior.ruleId : 'intent-classifier',
+          layer: 'semantic',
+          decision: 'self_check_injected',
+          offered: considered.map((e) => e.behavior.ruleId),
+          prompt_chars: prompt.length,
+        },
+        repoRoot,
+      );
+      return {
+        additionalContext,
+        behavior: 'self_check',
+        layer: 'semantic',
+        offered: considered.map((e) => e.behavior.key),
+      };
+    }
+
+    // OPT-IN (mode: model): the original mechanism — AT MOST ONE local-model call.
+    const behaviorsForModel = eligible.map((e) => ({
+      key: e.behavior.key,
+      description: e.behavior.description,
+    }));
+    const classify = deps.classify || classifyIntent;
+    const result = await classify(prompt, behaviorsForModel, { ...cfg, repoRoot });
+
+    // Model rung unreachable / errored / unsure: fall through to the deterministic self-check block
+    // instead of going silent (2026-10-10, diagnose HS-IK2D: a silent null here let ideas pass uncaptured).
+    const selfCheckFallback = (decision, extra = {}) => {
+      if (prompt.trim().length < MIN_SELF_CHECK_CHARS) return null;
+      const additionalContext = buildSelfCheckBlock(considered, repoRoot, prompt);
+      if (!additionalContext) return null;
+      appendClassifierEvent(
+        {
+          surface: SURFACE,
+          rule: onlyBehavior ? considered[0].behavior.ruleId : 'intent-classifier',
+          layer: 'semantic',
+          decision,
+          ...extra,
+          offered: considered.map((e) => e.behavior.ruleId),
+          prompt_chars: prompt.length,
+        },
+        repoRoot,
+      );
+      return { additionalContext, behavior: 'self_check', layer: 'semantic', offered: considered.map((e) => e.behavior.key) };
+    };
+
+    if (result.error) {
+      appendClassifierEvent(
+        { surface: SURFACE, rule: 'intent-classifier', layer: 'semantic', decision: 'error', error: result.error, prompt_chars: prompt.length },
+        repoRoot,
+      );
+      return selfCheckFallback('self_check_injected_after_model_error');
+    }
+
+    // In onlyBehavior mode the winner must be that behavior; otherwise any eligible.
+    const winner = considered.find((e) => e.behavior.key === result.behavior);
+    if (!winner) return null; // 'none', another behavior, or an unrecognized/ineligible key
+
+    const fire = result.confidence >= cfg.minConfidence;
+    appendClassifierEvent(
+      {
+        surface: SURFACE,
+        rule: winner.behavior.ruleId,
+        layer: 'semantic',
+        decision: fire ? 'fire' : 'below_threshold',
+        confidence: result.confidence,
+        min_confidence: cfg.minConfidence,
+        model: cfg.model,
+        latency_ms: result.latencyMs,
+        prompt_chars: prompt.length,
+      },
+      repoRoot,
+    );
+    if (!fire) return selfCheckFallback('self_check_injected_after_low_confidence', { confidence: result.confidence });
+
+    const additionalContext = withMatchMarker(winner.behavior.key, winner.behavior.transform(winner.rule.inject, repoRoot, prompt));
+    return { additionalContext, behavior: winner.behavior.key, layer: 'semantic', confidence: result.confidence };
+  } catch {
+    return null; // any unexpected error → no injection (fail-safe)
+  }
+}
+
+// ── shared hook entry (stdin → route → emit) ────────────────────────────────
+// The unified hook calls this with `onlyBehavior` unset; the three per-behavior
+// shims (capture-trigger / research-trigger / settings-intent-trigger) called it
+// with `onlyBehavior` set until they were retired after burn-in (HS-IYU1). Fail-safe:
+// reads stdin defensively, never throws.
+
+export function readStdinJson() {
+  if (process.stdin.isTTY) return Promise.resolve(null);
+  return new Promise((resolve) => {
+    let buf = '';
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    const timer = setTimeout(() => finish(buf || ''), 200);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      buf += chunk;
+    });
+    process.stdin.on('end', () => {
+      clearTimeout(timer);
+      finish(buf);
+    });
+    process.stdin.on('error', () => {
+      clearTimeout(timer);
+      finish(buf);
+    });
+  });
+}
+
+function emit(additionalContext) {
+  if (!additionalContext) return;
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext },
+    }),
+  );
+}
+
+/**
+ * Full UserPromptSubmit hook body: read the payload, route the prompt, emit the winner.
+ * @param {{ onlyBehavior?: string|null }} [options]
+ */
+export async function runClassifierHook({ onlyBehavior = null } = {}) {
+  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 routed = await routePrompt(prompt, { onlyBehavior });
+    // HS-KNJ8 deterministic verbatim stage, also on the legacy path (engine: false): an idea-bearing
+    // prompt (capture/research lexical hit, or the self-check rung) is appended VERBATIM to the capture on
+    // deck for this session. A self-check prompt with NOTHING on deck gets the hard capture directive.
+    const append =
+      routed?.behavior === 'capture_on_idea' ||
+      routed?.behavior === 'research_before_decision' ||
+      routed?.behavior === 'self_check';
+    let note = null;
+    if (append) {
+      try {
+        // Variable specifier on purpose: platform-only module, absent from the published npm closure.
+        const mod = '../lib/capture-verbatim-append.mjs';
+        const { runVerbatimStageForHook } = await import(mod);
+        note = await runVerbatimStageForHook(payload, prompt, append, {
+          directiveIfNoCapture: routed.behavior === 'self_check',
+          armObligation: routed.behavior === 'self_check' || routed.behavior === 'capture_on_idea',
+        });
+      } catch {
+        note = null;
+      }
+    }
+    if (routed) emit([routed.additionalContext, note].filter(Boolean).join(String.fromCharCode(10,10)));
+  } catch {
+    // Never break Claude Code on a hook failure.
+  }
+}
+
+// ── CLI: resolve one directive on demand ────────────────────────────────────
+// The self-check block emits gates plus a pointer here, rather than pasting all
+// four directives into every turn. Invoked as:
+//   node scripts/claude-hooks/_intent-classifier-router.mjs --directive capture_on_idea
+// Prints the directive to stdout and exits 0, or an error to stderr and exits 1.
+if (process.argv[2] === '--directive') {
+  const key = process.argv[3];
+  if (!key) {
+    process.stderr.write(
+      'usage: _intent-classifier-router.mjs --directive <key>\n' +
+      `known keys: ${CLASSIFIER_BEHAVIORS.map((b) => b.key).join(', ')}\n`,
+    );
+    process.exit(1);
+  }
+  // repoRoot is optional throughout — the loader helpers fall back to their own
+  // env/cwd detection, the same as the hook path does.
+  const directive = resolveDirective(key, undefined, process.argv[4] ?? '');
+  if (!directive) {
+    process.stderr.write(
+      `unknown or unavailable behavior key: ${key}\n` +
+      `known keys: ${CLASSIFIER_BEHAVIORS.map((b) => b.key).join(', ')}\n`,
+    );
+    process.exit(1);
+  }
+  process.stdout.write(directive + '\n');
+}