heyspex 0.1.0 → 0.2.1

package/spexharness/src/intent-classifier.mjs

@@ -0,0 +1,196 @@
+// spexharness/src/intent-classifier.mjs
+//
+// Intent classification as an engine module on the prompt_submit event (HS-5ISS, epic
+// HS-1YDJ), replacing scripts/claude-hooks/_intent-classifier-router.mjs's per-prompt prose
+// injection with a mechanical lexical check against the engine's own compiled rule table
+// (./rule-table.mjs's loadRuleTable — the same registry _guardrail-loader.mjs reads, so this
+// module and the Claude Code hook agree about what a rule's pattern set and inject text are;
+// neither re-derives the other's regex).
+//
+// THE COST FIX (why this task exists): the original hook's Layer 2 ("self_check" semantic
+// mode) injects a multi-behavior "gate" block — one section per classifier behavior, several
+// KB of behavior descriptions — on every prompt that MISSES every lexical pattern and is at
+// least 12 characters long. That fires on almost every substantive prompt (an ordinary work
+// order matches none of the five behaviors' regex), which is the ~6.5 KB/prompt the epic
+// measured. This module drops that speculative layer entirely: classification here is
+// LEXICAL ONLY. A rule's `inject` text is resolved and returned only when one of its own
+// compiled patterns actually matches the prompt (AC2, "the directive is fetched only when a
+// gate fires") — a prompt that matches nothing produces `{ decision: 'allow' }` with no
+// injected text at all, which is the <500-byte target on a plain prompt (AC3).
+//
+// SCOPE NOTE: `classifyPrompt` is the LEXICAL core and stays pure — it returns the matched
+// rule's raw inject, nothing more. The per-behavior enrichment the plugin applies on top —
+// capture-on-idea's {{CONFIRM_MODE}} substitution, the capture-kind and thread-split-mode
+// hints, research-before-decision's appended source hint, the env/config kill switches, the
+// injected-content guard and the CONFIRMED MATCH marker — used to live only in
+// scripts/claude-hooks/_intent-classifier-router.mjs, so a SpexCode seat saw a different
+// (and, with the literal `{{CONFIRM_MODE}}` token, visibly unfinished) directive from the
+// one Claude Code injects for the same prompt. HS-N01T moved that assembly into
+// ./intent-directive.mjs, which BOTH the router and this gate's `run()` call — so the inject
+// this gate returns is now byte-identical to the plugin's. The semantic (Layer 2 self-check /
+// opt-in model-classify) layer stays in the router, unported.
+//
+// Pure: no I/O of its own beyond loadRuleTable's fs.readFileSync (itself fail-safe — see
+// rule-table.mjs's header). No process.stdin/stdout/exit.
+
+import { loadRuleTable } from './rule-table.mjs';
+import { buildIntentDirective, ruleMatchesPrompt } from './intent-directive.mjs';
+
+/** This gate's id, for a registry or an audit row. */
+export const GATE_ID = 'intent-classifier';
+/** Runs on the prompt-submit event, mirroring the retired hook's UserPromptSubmit wiring. */
+export const EVENT = 'prompt_submit';
+
+/**
+ * The rule table carries every `userpromptsubmit` rule, including
+ * `communication-style-prime` (HS-XIYJ's rule — an unconditional `[\s\S]` pattern that would
+ * "match" every prompt) and severity `prime` rules with no patterns at all. Intent
+ * classification is specifically the five mutually-exclusive INTENT rules the original
+ * router's `CLASSIFIER_BEHAVIORS` catalog named — restricting to these ids is what keeps
+ * this module from reinventing the always-on communication-style injection XIYJ retires
+ * separately.
+ * @type {ReadonlyArray<string>}
+ */
+export const CLASSIFIER_RULE_IDS = Object.freeze([
+  'capture-on-idea',
+  'research-before-decision',
+  'settings-intent',
+  'defer-intent',
+  'handoff-intent',
+  'spec-reference-lookup',
+]);
+
+/** Compile a rule's string patterns into case-insensitive RegExps, skipping any that fail
+ *  to compile (a corrupt pattern degrades to "never matches", never a throw). */
+function compilePatterns(rule) {
+  const patterns = Array.isArray(rule?.patterns) ? rule.patterns : [];
+  const compiled = [];
+  for (const source of patterns) {
+    try {
+      compiled.push(new RegExp(source, 'i'));
+    } catch {
+      // corrupt pattern in the table — skip it, fail-safe.
+    }
+  }
+  return compiled;
+}
+
+/** The classifier rules eligible to fire, in {@link CLASSIFIER_RULE_IDS} order (the
+ *  deterministic lexical tiebreak, mirroring the original router's BEHAVIOR_ORDER). */
+function classifierRules(table) {
+  const byId = new Map((table?.rules ?? []).map((r) => [r?.rule, r]));
+  const rules = [];
+  for (const id of CLASSIFIER_RULE_IDS) {
+    const rule = byId.get(id);
+    if (rule && typeof rule.inject === 'string' && rule.inject.trim() && rule.surfaces?.includes('userpromptsubmit')) {
+      rules.push(rule);
+    }
+  }
+  return rules;
+}
+
+/**
+ * @typedef {object} IntentClassification
+ * @property {string} rule            the matched rule's id (e.g. 'capture-on-idea').
+ * @property {string} sourceProtocol  the protocol that authored the rule.
+ * @property {string} inject          the rule's raw inject text (unmodified — see the
+ *   SCOPE NOTE above; per-behavior enrichment/substitution is not applied here).
+ */
+
+/**
+ * Classify a prompt against the engine's compiled rule table. First matching rule (in
+ * {@link CLASSIFIER_RULE_IDS} order) wins; a full miss returns null — no directive is
+ * resolved, matching AC2/AC3.
+ *
+ * @param {string} prompt
+ * @param {{ vaultRoot?: string, ruleTable?: { rules: object[] } }} [opts]
+ *   `ruleTable` is injectable so a test never depends on the live
+ *   `.heyspex/guardrails.json`/built-in table; omitted, it loads the real one via
+ *   {@link loadRuleTable}.
+ * @returns {IntentClassification|null}
+ */
+export function classifyPrompt(prompt, { vaultRoot, ruleTable } = {}) {
+  if (typeof prompt !== 'string' || !prompt.trim()) return null;
+  const table = ruleTable ?? loadRuleTable({ vaultRoot });
+  for (const rule of classifierRules(table)) {
+    const patterns = compilePatterns(rule);
+    // HS-XDH8: a negation-guarded rule (defer-intent) needs an un-negated occurrence.
+    if (ruleMatchesPrompt(rule, patterns, prompt)) {
+      return { rule: rule.rule, sourceProtocol: rule.sourceProtocol ?? null, inject: rule.inject };
+    }
+  }
+  return null;
+}
+
+/**
+ * The engine gate: runs on `prompt_submit`, classifies the prompt, and only when a rule
+ * actually fires does it return an `inject` decision carrying that rule's directive. A miss
+ * — including the common "plain prompt, matches nothing" case — is a plain `allow` with no
+ * injected text, satisfying AC3's <500-byte-on-a-plain-prompt target by construction (an
+ * `allow` decision carries no `inject` field at all).
+ *
+ * HS-N01T: a hit is then run through ./intent-directive.mjs's `buildIntentDirective` — the
+ * SAME eligibility check (env kill switch, config toggle, injected-content guard) and the
+ * SAME directive assembly (confirm-mode substitution, kind/routing hints, CONFIRMED MATCH
+ * marker) the Claude Code hook applies — so `inject.additionalContext` is what the plugin
+ * would have injected, never the raw inject with a literal `{{CONFIRM_MODE}}`. An
+ * ineligible behavior is an `allow`. A rule the behavior catalog does not know (or a row
+ * the plugin router would never fire) keeps the pre-N01T raw passthrough.
+ *
+ * `ctx` (all optional): `vaultRoot`/`repoRoot` — the app root holding `.heyspex/`;
+ * `ruleTable` — an injected table (tests); `env` — env overrides instead of `process.env`;
+ * `getSetting(repoRoot, key)` — an injected settings reader so a test never reads the real
+ * config (see ./intent-directive.mjs's header for the accepted shapes).
+ *
+ * @param {{ point: string, prompt?: string }} evt
+ * @param {{ vaultRoot?: string, repoRoot?: string, ruleTable?: object, env?: object, getSetting?: Function }} [ctx]
+ * @returns {{ decision: 'allow' }|{ decision: 'inject', reason: string, inject: { additionalContext: string, rule: string, behavior: string|null } }}
+ */
+export function run(evt, ctx = {}) {
+  const repoRoot = ctx.repoRoot ?? ctx.vaultRoot;
+  // One table load for both the lexical match and the directive resolution.
+  const ruleTable = ctx.ruleTable ?? loadRuleTable({ vaultRoot: repoRoot });
+  const hit = classifyPrompt(evt?.prompt, { ruleTable });
+  if (!hit) return { decision: 'allow' };
+  let built;
+  try {
+    built = buildIntentDirective(hit.rule, evt.prompt, {
+      repoRoot,
+      ruleTable,
+      env: ctx.env,
+      getSetting: ctx.getSetting,
+    });
+  } catch {
+    // The directive assembly is best-effort enrichment; a crash in it must never turn a
+    // confirmed lexical fire into silence. Degrade to the raw inject.
+    built = { behavior: null, additionalContext: null };
+  }
+  if (built === null) return { decision: 'allow' }; // killed by env/config/injected-content guard
+  return {
+    decision: 'inject',
+    reason: `intent-classifier: ${hit.rule} fired`,
+    inject: {
+      additionalContext: built.additionalContext ?? hit.inject,
+      rule: hit.rule,
+      behavior: built.behavior,
+    },
+  };
+}
+
+/**
+ * Caller-defined severity label. `prime` is the severity every rule in
+ * {@link CLASSIFIER_RULE_IDS} carries in the compiled registry — this gate never
+ * denies, it only primes a turn with the matched rule's directive.
+ *
+ * Added in wave 6 of [[HS-AZ61-NYPR]]: the module was written as a gate but was
+ * registered by nothing, so the classification it owns ran on no front at all.
+ * spexharness/src/gates/index.mjs now registers it (a registry row needs a
+ * severity for `hs harness gates` to print, hence this export), and
+ * spexharness/src/plugin-hook-coverage.test.mjs pins that registration so the
+ * Claude Code `intent-classifier-trigger` hook's coverage cannot silently lapse
+ * again.
+ */
+export const SEVERITY = 'prime';
+
+const gate = { id: GATE_ID, event: EVENT, severity: SEVERITY, run };
+export default gate;