heyspex 0.2.2 → 0.2.3

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

@@ -1,279 +1,305 @@
-#!/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';
-
-// HS-KNJ8: deterministic verbatim capture. After the classifier has run, an idea-bearing prompt
-// (a capture_on_idea / research_before_decision match, or the semantic-miss rung firing) is appended
-// VERBATIM to the capture on deck for THIS session, and the model is told it was done. Also refreshes
-// the PreToolUse capture-execution-gate's state file. Returns the note to append to the emitted context.
-// Body moved to scripts/lib/capture-verbatim-append.mjs (runVerbatimStageForHook) so the legacy router shares it.
-// Dynamic + variable specifier on purpose: platform-only module (customer-kit scope 'platform'), NOT in the
-// published npm closure; a customer install simply has no verbatim stage (caught -> null).
-//
-// HS-20SW: BOTH UserPromptSubmit entry points (this engine path AND the legacy router) now pass the same
-// options, so engine:true and engine:false behave identically ([[HS-LES-a-safety-net-wired-into-only-one-of-two]]):
-// `directiveIfNoCapture` on the semantic-miss rung (the hard directive when nothing is on deck, exactly what the
-// legacy self_check rung does) and `armObligation` on every capture-bearing path, which records the outstanding
-// capture obligation the directive-obligation-gate enforces.
-async function verbatimStage(payload, prompt, append, options = {}) {
-  try {
-    const mod = '../lib/capture-verbatim-append.mjs';
-    const { runVerbatimStageForHook } = await import(mod);
-    return await runVerbatimStageForHook(payload, prompt, append, options);
-  } catch {
-    return null;
-  }
-}
-
-const NOTE_SEP = '\n\n';
-const IDEA_BEARING_BEHAVIORS =new Set(['capture_on_idea', 'research_before_decision']);
-
-// 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.
-      const missContext = await engineMissFallback(prompt);
-      // The semantic-miss rung fired (substantive, non-envelope prompt, layer on) = idea-bearing.
-      const missNote = await verbatimStage(payload, prompt, Boolean(missContext), { directiveIfNoCapture: Boolean(missContext), armObligation: Boolean(missContext) });
-      emit([missContext, missNote].filter(Boolean).join(NOTE_SEP));
-      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,
-    });
-
-    const hitNote = await verbatimStage(payload, prompt, IDEA_BEARING_BEHAVIORS.has(behaviorKey), {
-      armObligation: behaviorKey === 'capture_on_idea',
-    });
-    emit([directive, hitNote].filter(Boolean).join(NOTE_SEP));
-  } 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();
-}
+#!/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,
+  nonIdeaExclusion,
+  CLASSIFIER_BEHAVIORS,
+  MIN_SELF_CHECK_CHARS,
+  directiveCommand,
+} from './_intent-classifier-router.mjs';
+
+const ENGINE_FLAG = 'agent_behaviors.intent_classifier.engine';
+
+// HS-KNJ8: deterministic verbatim capture. After the classifier has run, an idea-bearing prompt
+// (a capture_on_idea / research_before_decision match, or the semantic-miss rung firing) is appended
+// VERBATIM to the capture on deck for THIS session, and the model is told it was done. Also refreshes
+// the PreToolUse capture-execution-gate's state file. Returns the note to append to the emitted context.
+// Body moved to scripts/lib/capture-verbatim-append.mjs (runVerbatimStageForHook) so the legacy router shares it.
+// Dynamic + variable specifier on purpose: platform-only module (customer-kit scope 'platform'), NOT in the
+// published npm closure; a customer install simply has no verbatim stage (caught -> null).
+//
+// HS-20SW: BOTH UserPromptSubmit entry points (this engine path AND the legacy router) now pass the same
+// options, so engine:true and engine:false behave identically ([[HS-LES-a-safety-net-wired-into-only-one-of-two]]):
+// `directiveIfNoCapture` on the semantic-miss rung (the hard directive when nothing is on deck, exactly what the
+// legacy self_check rung does) and `armObligation` on every capture-bearing path, which records the outstanding
+// capture obligation the directive-obligation-gate enforces.
+async function verbatimStage(payload, prompt, append, options = {}) {
+  try {
+    const mod = '../lib/capture-verbatim-append.mjs';
+    const { runVerbatimStageForHook } = await import(mod);
+    return await runVerbatimStageForHook(payload, prompt, append, options);
+  } catch {
+    return null;
+  }
+}
+
+const NOTE_SEP = '\n\n';
+const IDEA_BEARING_BEHAVIORS =new Set(['capture_on_idea', 'research_before_decision']);
+
+// 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.
+// The fetch command comes from directiveCommand() so it resolves in the session's project —
+// the repo-relative form in the platform checkout (byte-identical to before), the committed
+// hook launcher or the router's absolute path in a satellite repo (no scripts/ there).
+export function compactGateCheck(opts = {}) {
+  return (
+    '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 \`${directiveCommand('capture_on_idea', opts)}\` and ` +
+    'follow it. Other keys: research_before_decision, settings_intent, defer_intent, ' +
+    'spec_reference_lookup. Otherwise proceed silently.'
+  );
+}
+export const COMPACT_GATE_CHECK = compactGateCheck();
+
+/**
+ * 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) &&
+        // HS-BCCN: a model vote for capture_on_idea on a non-idea shape is not a confirmed match.
+        !(result.behavior === 'capture_on_idea' && nonIdeaExclusion(prompt).excluded)
+      ) {
+        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.
+      const missContext = await engineMissFallback(prompt);
+      // The semantic-miss rung fired (substantive, non-envelope prompt, layer on) = idea-bearing —
+      // unless HS-BCCN's exclusion class says the shape carries no idea (a shell paste, a mechanical
+      // git/npm/agent order, a plain question). Decided BEFORE the verbatim stage can issue the hard
+      // capture directive or arm an obligation; the self-check block itself still goes out.
+      const exclusion = missContext ? nonIdeaExclusion(prompt) : { excluded: false, reason: null };
+      if (exclusion.excluded) {
+        appendClassifierEvent({
+          surface: 'userpromptsubmit',
+          rule: 'capture-on-idea',
+          layer: 'semantic',
+          decision: 'non_idea_excluded',
+          engine: true,
+          non_idea: exclusion.reason,
+          prompt_chars: prompt.length,
+        });
+      }
+      const ideaBearing = Boolean(missContext) && !exclusion.excluded;
+      const missNote = await verbatimStage(payload, prompt, ideaBearing, { directiveIfNoCapture: ideaBearing, armObligation: ideaBearing });
+      emit([missContext, missNote].filter(Boolean).join(NOTE_SEP));
+      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,
+    });
+
+    const hitNote = await verbatimStage(payload, prompt, IDEA_BEARING_BEHAVIORS.has(behaviorKey), {
+      armObligation: behaviorKey === 'capture_on_idea',
+    });
+    emit([directive, hitNote].filter(Boolean).join(NOTE_SEP));
+  } 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/research-method-guard.mjs

@@ -51,7 +51,7 @@
 //
 // Self-test: `node scripts/claude-hooks/research-method-guard.mjs --self-test`
 
-import { pathToFileURL } from "node:url";
+import { isMainModule } from "../lib/shared-path-helpers.mjs";
 
 // Order matters for the scriptPath substring scan below (first match wins) —
 // the three specific profiles are listed before the bare "deep-research" so a
@@ -388,7 +388,7 @@ async function main() {
 // executed directly — mirrors env-vault-guard.mjs's guard so importing this
 // module (e.g. from a future regression test) never blocks on stdin.
 const isDirectExecution =
-  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+  isMainModule(import.meta.url);
 
 if (isDirectExecution) {
   main().catch(() => {