heyspex 0.2.0 → 0.2.2

package/spexharness/src/intent-directive.mjs

@@ -1,541 +1,626 @@
-// spexharness/src/intent-directive.mjs
-//
-// The intent classifier's DIRECTIVE ASSEMBLY — the per-behavior enrichment that turns a rule's
-// raw `inject` text into the exact directive Claude Code's plugin injects for the same prompt
-// ([[HS-N01T-8CMW-TASK-prompt-submit-injects-reach-the-model]], epic
-// [[HS-LS51-8CMW-EPIC-spexcode-plugin-parity-the-prompt]]).
-//
-// MOVED, not copied, from scripts/claude-hooks/_intent-classifier-router.mjs: the confirmed-
-// match marker, the classifier behavior catalog, the capture confirm-mode substitution, the
-// capture kind/routing hints, the research source hint, the eligibility check and the
-// confirmed-directive builder. The router now imports every one of these from here and
-// re-exports them, so its own Layer 1/Layer 2 paths and the Claude Code hook emit the SAME
-// bytes they always did — and ../intent-classifier.mjs's engine gate builds the SAME text for
-// a SpexCode seat. One implementation, two callers; neither can drift from the other.
-//
-// LAYERING: this is a harness module. It imports from ./rule-table.mjs and from
-// vendor/heyspex-mcp (the same vendor modules ./chat/chat-loop.mjs and ./gates/*.mjs already
-// import) and NEVER from scripts/claude-hooks — the plugin's hook scripts sit above the
-// engine and import downward, not the other way round. The two small helpers the router
-// used to take from scripts/claude-hooks/_guardrail-loader.mjs (the injected-content
-// sentinel guards and the config-leaf reads) are therefore implemented here against the same
-// contracts; ./intent-directive.test.mjs pins the sentinel list to the loader's copy so the
-// two lists cannot diverge silently.
-//
-// INJECTED READS (so a test never touches the real config): every function that consults
-// `.heyspex/config.yaml` takes a trailing `opts` carrying
-//   opts.getSetting(repoRoot, key) — returns a leaf shaped like
-//     vendor/heyspex-mcp/config-settings.mjs's `getConfigLeaf` (`{ found, raw, value }`) or
-//     `getEffectiveSetting` (`{ found, value }`); a plain string is also accepted. Defaults to
-//     `getConfigLeaf` against `repoRoot`.
-//   repoRoot — the directory holding `.heyspex/config.yaml`. When absent it is the VAULT
-//     root (./config-root.mjs `defaultConfigRoot()`), NOT DEFAULT_APP_ROOT: since the
-//     2026-08-31 repo split the settings file lives in the vault checkout
-//     ([[HS-4C76-9W86-DIAG-heyspex-config-yaml-has-no-single-home]]). The rule table
-//     (`.heyspex/guardrails.json`) is a code-repo artifact and still loads from
-//     DEFAULT_APP_ROOT when `repoRoot` is absent.
-//   opts.env — the environment the per-behavior kill switches are read from. Defaults to
-//     `process.env`.
-//   opts.ruleTable — a ./rule-table.mjs table (`{ rules }`) to resolve behaviors against
-//     instead of loading the real one.
-// The value semantics mirror the loader's `readConfigLeafRaw` (the trimmed raw scalar after
-// the colon; `undefined` when the leaf is absent) so every substitution below stays
-// byte-identical to what the plugin hook produced before the move.
-//
-// Pure: no I/O of its own beyond loadRuleTable's / getConfigLeaf's fail-safe file reads. No
-// process.stdin/stdout/exit.
-
-import { loadRuleTable, DEFAULT_APP_ROOT } from './rule-table.mjs';
-import { defaultConfigRoot } from './config-root.mjs';
-import { getConfigLeaf } from '../../vendor/heyspex-mcp/config-settings.mjs';
-// HS-QOBQ: cheapest-possible-rung kind classification at capture time — the
-// same lexical guess promote-capture.mjs re-checks at promote time, so both
-// call sites the diagnose named agree on what "reads like a bug" means.
-import { guessCaptureKindFromText } from '../../vendor/heyspex-mcp/capture-kind-suggest.mjs';
-
-/** The registry surface every classifier behavior's rule is authored on. */
-export const SURFACE = 'userpromptsubmit';
-/** The severity the plugin router requires of a rule before it will fire it (its
- *  `rulesForSurface(guardrails, SURFACE, 'prime')` filter) — the same filter applies here. */
-export const DIRECTIVE_SEVERITY = 'prime';
-/** The token capture-on-idea's authored inject carries where the confirm mode goes. */
-export const MODE_TOKEN = '{{CONFIRM_MODE}}';
-
-// [[HS-BIDR-DTOP-DIAG]] fix: the bare/unconditional directive (a Layer 1 lexical fire,
-// or a Layer 2 mode:'model' fire) and the Layer 2 self_check "still undecided" block are
-// textually distinct but nothing marked WHICH one an agent was reading — it had to infer
-// from wording alone that discretion applies to the self-check and never to a confirmed
-// fire. That inference is easy to drop under load, and an agent that drops it treats a
-// confirmed match as if it were a self-check and silently skips it (the production miss
-// this diagnose captures). This marker is prepended to every CONFIRMED-FIRE directive —
-// loud and explicit as the mirror image of the self-check wrapper's own "silently
-// judge... DEFAULT OUTCOME IS NONE" framing — so the two shapes are unmistakable at a
-// glance, not just by prose wording.
-export const CONFIRMED_MATCH_MARKER =
-  'HEYSPEX CONFIRMED MATCH — NOT A SELF-CHECK. A deterministic rule has ALREADY matched ' +
-  "this message. There is no judgment step and nothing left to evaluate — do NOT silently " +
-  'second-guess it, and "this is also a work order / bug report" is explicitly NOT a valid ' +
-  'reason to skip it. Execute the directive below IMMEDIATELY, exactly as written.';
-
-/** Prepend the confirmed-match marker to a resolved directive. */
-export function withConfirmedMatchMarker(directive) {
-  return `${CONFIRMED_MATCH_MARKER}\n\n${directive}`;
-}
-
-// ── injected-content guards ──────────────────────────────────────────────────
-// Sentinels that mark harness-injected content arriving through the UserPromptSubmit
-// channel (background-task notifications, system reminders, slash-command envelopes). They
-// can contain a rule's trigger phrase verbatim but are NOT a genuine human prompt, so a rule
-// with `ignoreInjectedContent` must not fire on them. scripts/claude-hooks/_guardrail-loader.mjs
-// carries the plugin-side copy of this list; ./intent-directive.test.mjs asserts the two are
-// equal so an edit to one cannot silently leave the other behind.
-export const INJECTED_CONTENT_SENTINELS = [
-  '<task-notification>',
-  '<system-reminder>',
-  '[SYSTEM NOTIFICATION',
-  '<command-message>',
-  '<command-name>',
-  '<local-command-stdout>',
-];
-
-/** Contains-anywhere guard — the research hook's original (broad) check. */
-export function containsInjectedContent(text) {
-  if (typeof text !== 'string') return false;
-  return INJECTED_CONTENT_SENTINELS.some((s) => text.includes(s));
-}
-
-/**
- * Stricter, false-positive-safe variant: is the message a genuine harness ENVELOPE (a
- * task-notification / system-reminder / slash-command envelope delivered AS the prompt),
- * rather than user text that merely QUOTES a sentinel? A real envelope leads with its tag;
- * a user pasting a transcript or terminal logs leads with their own words.
- */
-export function startsWithInjectedContent(text) {
-  if (typeof text !== 'string') return false;
-  const head = text.trimStart();
-  return INJECTED_CONTENT_SENTINELS.some((s) => head.startsWith(s));
-}
-
-// ── config reads (injectable) ────────────────────────────────────────────────
-
-/**
- * The default settings reader: vendor/heyspex-mcp/config-settings.mjs's `getConfigLeaf`
- * against `<repoRoot>/.heyspex/config.yaml` — the same indent-scoped `key:` scan the plugin
- * loader's `readConfigLeafRaw` performs, returning `{ found, raw, value }`. With no
- * `repoRoot` the file is read from the vault root (`defaultConfigRoot()`).
- */
-export function defaultGetSetting(repoRoot, key) {
-  return getConfigLeaf(repoRoot ?? defaultConfigRoot(), key);
-}
-
-/**
- * Read one config leaf as the loader's `readConfigLeafRaw` would: the trimmed raw scalar,
- * or `undefined` when absent/unreadable. Accepts every reader shape the header documents.
- * FAIL-SAFE: a throwing reader reads as "absent".
- */
-export function readConfigLeafRaw(configKey, repoRoot, opts = {}) {
-  if (!configKey || typeof configKey !== 'string') return undefined;
-  const getSetting = typeof opts.getSetting === 'function' ? opts.getSetting : defaultGetSetting;
-  let leaf;
-  try {
-    leaf = getSetting(repoRoot ?? defaultConfigRoot(), configKey);
-  } catch {
-    return undefined;
-  }
-  if (leaf == null) return undefined;
-  if (typeof leaf === 'string') return leaf.trim();
-  if (typeof leaf === 'object') {
-    if (leaf.found === false) return undefined;
-    if (typeof leaf.raw === 'string') return leaf.raw.trim();
-    if (leaf.value === undefined || leaf.value === null) return undefined;
-    return String(leaf.value).trim();
-  }
-  return String(leaf).trim();
-}
-
-/**
- * Is a dotted `config_key` ON? Semantics match the loader's `isConfigKeyEnabled`: ON unless
- * the leaf is explicitly `false`; absent / unreadable / no key at all default to ON.
- */
-export function isConfigKeyEnabled(configKey, repoRoot, opts = {}) {
-  if (!configKey || typeof configKey !== 'string') return true;
-  const raw = readConfigLeafRaw(configKey, repoRoot, opts);
-  if (raw === undefined) return true;
-  return raw.toLowerCase() !== 'false';
-}
-
-/** Enabled-check straight off a rule row (its `configKey`). */
-export function isRuleEnabled(rule, repoRoot, opts = {}) {
-  return isConfigKeyEnabled(rule && rule.configKey, repoRoot, opts);
-}
-
-/**
- * Resolve the CONFIRM MODE for an autonomous agent behavior — the two-layer permission
- * model the owner specified (2026-07-11):
- *   'auto' = act immediately, user can undo/discard afterward   (forgiveness)
- *   'ask'  = ask the user for confirmation before acting        (permission)
- *
- * Resolution order (per-behavior override wins over the global default):
- *   1. agent_behaviors.<behaviorKey>.ask_first
- *        true|yes|ask  → 'ask'   ·  false|no|auto → 'auto'  ·  null/absent → inherit
- *   2. (inherit) global agent_behaviors.ask_forgiveness_not_permission
- *        true|yes|absent → 'auto' (forgiveness — the owner's default)
- *        false|no        → 'ask'
- * FAIL-SAFE: any unreadable config → 'auto' (the stated default).
- */
-export function resolveConfirmMode(behaviorKey, repoRoot, opts = {}) {
-  if (behaviorKey && typeof behaviorKey === 'string') {
-    const per = readConfigLeafRaw(`agent_behaviors.${behaviorKey}.ask_first`, repoRoot, opts);
-    if (per !== undefined) {
-      const v = per.toLowerCase();
-      if (v === 'true' || v === 'yes' || v === 'ask') return 'ask';
-      if (v === 'false' || v === 'no' || v === 'auto') return 'auto';
-      // 'null' / '' / anything else → fall through to the global default (inherit)
-    }
-  }
-  const global = readConfigLeafRaw('agent_behaviors.ask_forgiveness_not_permission', repoRoot, opts);
-  if (global !== undefined) {
-    const g = global.toLowerCase();
-    if (g === 'false' || g === 'no') return 'ask'; // forgiveness OFF → ask first
-  }
-  return 'auto'; // forgiveness ON / absent → act, don't ask
-}
-
-// ── capture-on-idea enrichment ───────────────────────────────────────────────
-
-// Capture's forgiveness/permission directives — carried over verbatim from the retired
-// capture-trigger.mjs shim (HS-IYU1, deleted after burn-in) so the emitted inject stays
-// byte-identical.
-export const CAPTURE_MODE_DIRECTIVES = {
-  auto:
-    "FORGIVENESS MODE (the owner's default — act, don't ask): START THE CAPTURE FLOW " +
-    'IMMEDIATELY. In ONE short line, tell the user you are capturing this as an idea ' +
-    'and they can say "discard" (or "no, just do it") to skip — then begin. Do NOT ask ' +
-    'permission first.',
-  ask:
-    'PERMISSION MODE: ASK FIRST. Reply with ONE line — "Want me to capture this as an ' +
-    'idea? (yes / no, just do it)" — and run the capture steps below ONLY if the user ' +
-    'says yes. If they decline, just do the task.',
-};
-
-/**
- * capture-on-idea's full transform: substitute `{{CONFIRM_MODE}}` (or prepend the mode
- * directive when the token is absent), then append the routing and kind hints.
- */
-export function applyCaptureConfirmMode(inject, repoRoot, prompt, opts = {}) {
-  const mode = resolveConfirmMode('capture_on_idea', repoRoot, opts);
-  const directive = CAPTURE_MODE_DIRECTIVES[mode] || CAPTURE_MODE_DIRECTIVES.auto;
-  const base = inject.includes(MODE_TOKEN) ? inject.split(MODE_TOKEN).join(directive) : `${directive}\n\n${inject}`;
-  return appendCaptureKindHint(appendCaptureRoutingHint(base, repoRoot, opts), prompt);
-}
-
-// Capture kind hint ([[HS-QOBQ-S4JZ-DIAG-capture-kind-is-never-classified-every]]):
-// every capture materializes at `kind: idea` and nothing ever inspected the
-// triggering message to check whether that default is right. This is the
-// cheapest rung (lexical, no model call) — a strong bug-language match in the
-// SAME message the capture-on-idea rule already fired on. Suggest-only: the
-// agent still must offer it and get a yes before calling heyspex_update_capture
-// with kind ([[HS-5HYS]] elicitation — suggest, never auto-apply), matching the
-// existing heyspex_update_capture `kind` arg description verbatim.
-export function appendCaptureKindHint(inject, prompt) {
-  const guess = guessCaptureKindFromText(prompt);
-  if (!guess.kind) return inject;
-  const hint =
-    `CAPTURE KIND HINT (lexical, suggest-only): this message reads like kind: ${guess.kind} ` +
-    `(matched "${guess.matched}"), not the default idea. After capturing, offer the ` +
-    `reclassification in your reply (e.g. "this reads like a bug-fix capture — reclassify?") ` +
-    `and call heyspex_update_capture with kind: "${guess.kind}" ONLY on the user's yes — never ` +
-    `auto-apply it.`;
-  return `${inject}\n\n${hint}`;
-}
-
-// Capture model-routing + thread-split hint ([[HS-6YOA-HPR6-RES-capture-to-research-auto-model-routing]],
-// owner ruling 2026-08-11). A best-effort HINT appended to the capture inject, same shape as
-// appendResearchSourceHint below — the hook cannot know the running session's actual current
-// model (that's not in the UserPromptSubmit payload), so it can only tell the agent what's
-// CONFIGURED and trust the agent (which does know its own model, per its own system prompt) to
-// judge whether a switch/delegate/ask actually applies. Neither mode is ever a silent, live
-// model switch — that is not possible from a hook or from the agent itself (research doc's
-// Platform capability check: `/model` is a user-issued local command; no MCP tool flips it).
-export function appendCaptureRoutingHint(inject, repoRoot, opts = {}) {
-  const defaultModel = readConfigLeafRaw('agent_behaviors.capture_on_idea.default_model', repoRoot, opts);
-  const switchMode = readConfigLeafRaw('agent_behaviors.capture_on_idea.model_switch_mode', repoRoot, opts) || 'ask';
-  const splitMode = readConfigLeafRaw('agent_behaviors.capture_on_idea.thread_split_mode', repoRoot, opts) || 'ask';
-
-  const parts = [inject];
-
-  if (defaultModel && switchMode !== 'off') {
-    const modeInstruction =
-      switchMode === 'silent_delegate'
-        ? 'CONFIGURED MODE: silent_delegate — do NOT interrupt the user with a model question. ' +
-          `If this is the FIRST/ONLY capture turn in this thread (not a continuation of an ` +
-          `already-open capture) and you are not already running as ${defaultModel}, hand the ` +
-          'mechanical capture steps (verbatim quote, core idea, summary, ground=expand) to a ' +
-          `one-shot Agent(prompt: <the capture instructions>, model: "${defaultModel}") subagent ` +
-          'instead of running them on this session — then relay its result. Never switch this ' +
-          "running session's own model; that is not possible and is not what this mode means."
-        : 'CONFIGURED MODE: ask — if this is the FIRST/ONLY capture turn in this thread (not a ' +
-          `continuation of an already-open capture) and you are not already running as ` +
-          `${defaultModel}, add ONE short line to your capture-start message offering a switch — ` +
-          `e.g. "(captures default to ${defaultModel} — say switch to run /model ${defaultModel} ` +
-          'first)" — then proceed with the capture flow regardless of the answer; never block on ' +
-          'it. A mid-thread continuation never gets this offer — it stays on the thread\'s model.';
-    parts.push(
-      `CAPTURE MODEL ROUTING (default_model=${defaultModel}, model_switch_mode=${switchMode}): ${modeInstruction}`,
-    );
-  }
-
-  const splitInstruction =
-    splitMode === 'auto'
-      ? 'CONFIGURED thread_split_mode=auto: when new mid-thread prose is judged NOT a continuation ' +
-        'of the on-deck capture, decide on your own judgment — no AskUserQuestion — whether it ' +
-        'SPLITS (a new HS-CAP-* that still benefits from this thread\'s context: continue it via ' +
-        'Agent(subagent_type:"fork") so full context carries over) or SPAWNS (unrelated enough that ' +
-        'a fresh Agent() with no inherited context is cleaner). State which you picked and why in ' +
-        'one line.'
-      : 'CONFIGURED thread_split_mode=ask: when new mid-thread prose is judged NOT a continuation of ' +
-        'the on-deck capture, and you are NOT confident whether it benefits from this thread\'s ' +
-        'existing context, use AskUserQuestion with exactly two options — split (new capture id, ' +
-        'keep this thread\'s context via Agent(subagent_type:"fork")) vs. spawn (new capture id, ' +
-        'fresh context via a plain Agent() call) — rather than guessing. Skip the ask only when ' +
-        'you ARE confident: a clearly-related new idea still splits, a clearly-unrelated one still ' +
-        'spawns, with no prompt.';
-  parts.push(`CAPTURE THREAD SPLIT/SPAWN: ${splitInstruction}`);
-
-  return parts.join('\n\n');
-}
-
-// Research-source hint — fix for [[HS-LFUH-DIAG-W1YE]] root-cause part 1 ("not injected").
-// The research inject above tells the agent WHICH RUNGS to climb and WHICH MODEL to spawn
-// (default_agent), but never named the configured search/scrape BACKEND
-// (agent_behaviors.research.default_source) — so a configured `firecrawl-self-hosted` default
-// was silently unreachable on the interactive path; the agent had no way to even know it existed.
-// This is deliberately a best-effort HINT appended to the existing inject text, not a
-// replacement: it is a snapshot taken at prompt-submit time, so it can go stale mid-session
-// (a lease can be granted/refused, a box can go up/down). The authoritative, can't-go-stale
-// source of truth is the on-demand `heyspex_resolve_research_plan` MCP tool this hint points the
-// agent at — per the research doc's recommendation, "hook injection is a best-effort hint; the
-// on-demand tool is the source of truth", not either/or.
-export function appendResearchSourceHint(inject, repoRoot, opts = {}) {
-  const defaultSource = readConfigLeafRaw('agent_behaviors.research.default_source', repoRoot, opts);
-  const defaultAgent = readConfigLeafRaw('agent_behaviors.research.default_agent', repoRoot, opts);
-  if (!defaultSource && !defaultAgent) return inject; // nothing configured — nothing to hint at
-  const hint =
-    'CONFIGURED RESEARCH RESOURCE (best-effort hint, a snapshot — re-confirm live via ' +
-    'heyspex_resolve_research_plan() before RUNG 0 `sequential` search/scrape, since availability ' +
-    `can change mid-session): default_source=${defaultSource ?? '(unset)'}, ` +
-    `default_agent=${defaultAgent ?? '(unset)'}. If default_source names a Firecrawl backend ` +
-    '(firecrawl-self-hosted | firecrawl-hosted), call heyspex_firecrawl_research({ mode: "search"|"scrape", ' +
-    'query|url }) for rung 0 instead of native WebSearch/WebFetch — it wraps that SAME configured ' +
-    'backend and honors its existing availability gates (the Ollama-XOR-Firecrawl lease / hosted credit ' +
-    'gate). If its result reports downgraded:true, tell the user plainly that the configured backend was ' +
-    'unavailable and you fell back to web-native — NEVER substitute silently.';
-  return `${inject}\n\n${hint}`;
-}
-
-// ── the behavior catalog ─────────────────────────────────────────────────────
-
-// The classifier behavior catalog. `ruleId` ties a behavior to its registry rule;
-// `description` is the semantic-classification instruction (the router's self-check block
-// and opt-in model mode read it from here — this catalog is the single source of behavior
-// descriptions); `envOff` is the per-behavior kill switch; `guard` is the injected-content
-// check that behavior used historically; `transform(inject, repoRoot, prompt, opts)` builds
-// the final inject from the rule's inject text (`opts` carries the injected reads — see the
-// header). BEHAVIOR_ORDER (array order) is the deterministic lexical tiebreak.
-export const CLASSIFIER_BEHAVIORS = [
-  {
-    key: 'capture_on_idea',
-    ruleId: 'capture-on-idea',
-    envOff: 'HEYSPEX_CAPTURE_TRIGGER_OFF',
-    guard: startsWithInjectedContent,
-    transform: (inject, repoRoot, prompt, opts) => applyCaptureConfirmMode(inject, repoRoot, prompt, opts),
-    description:
-      'The user\'s message contains a raw idea, suggestion, observation, or improvement thought — something that could exist or be better. Fires even when the message is ALSO a work order or bug report, as long as it carries new idea/capability content worth remembering. Does NOT fire on purely mechanical commands with no new idea (e.g. "run the tests", "fix the typo"), plain questions about existing work, or bare continuations of work already in progress.',
-  },
-  {
-    key: 'research_before_decision',
-    ruleId: 'research-before-decision',
-    envOff: 'HEYSPEX_RESEARCH_TRIGGER_OFF',
-    guard: containsInjectedContent,
-    transform: (inject, repoRoot, _prompt, opts) => appendResearchSourceHint(inject, repoRoot, opts),
-    description:
-      'The user is declining to make a design or architecture decision themselves and is asking for research, best practices, or an expert recommendation instead (e.g. "not a decision I should have to make", "don\'t reinvent the wheel").',
-  },
-  {
-    key: 'settings_intent',
-    ruleId: 'settings-intent',
-    envOff: 'HEYSPEX_SETTINGS_INTENT_OFF',
-    guard: startsWithInjectedContent,
-    transform: (inject) => inject,
-    description:
-      'The user wants to READ or CHANGE a HeySpex workflow setting / agent behavior — enable or disable a behavior (auto-capture, the research trigger, the intent classifier), turn something on or off, set/lower/raise a threshold or value (confidence, timeout), or ask what a setting is currently. About the configuration itself, NOT a request to do the underlying work.',
-  },
-  {
-    key: 'defer_intent',
-    ruleId: 'defer-intent',
-    envOff: 'HEYSPEX_DEFER_INTENT_OFF',
-    guard: startsWithInjectedContent,
-    transform: (inject) => inject,
-    description:
-      'The user wants to DEFER, POSTPONE, or SCHEDULE a follow-up to a later time — "come back to this later", "remind me in a week", "park/table this until X is done", "schedule this for next week", "not now — later, after the migration". About WHEN to revisit something, not a request to do it now.',
-  },
-  {
-    key: 'spec_reference_lookup',
-    ruleId: 'spec-reference-lookup',
-    envOff: 'HEYSPEX_SPEC_REFERENCE_LOOKUP_OFF',
-    guard: startsWithInjectedContent,
-    transform: (inject) => inject,
-    description:
-      'The user\'s message is little more than a pointer at an existing spec by id (a bare "HS-XXXX-YYYY", or "Reference: HS-...", "re: HS-...", "see HS-..." with nothing else actionable). Fires whether or not the spec turns out to matter. Does NOT fire on an ordinary work order that happens to name a spec id alongside real instructions ("update HS-XXXX\'s tests and rerun them") — there the id is already load-bearing context, not an unresolved pointer.',
-  },
-];
-
-/**
- * Map an engine rule id (hyphenated, e.g. 'capture-on-idea') back to the router's
- * behavior key (underscored, e.g. 'capture_on_idea'). Returns null for an id no
- * behavior claims (fail-safe: the engine cutover treats that as no match).
- */
-export function behaviorKeyForRuleId(ruleId) {
-  const found = CLASSIFIER_BEHAVIORS.find((b) => b.ruleId === ruleId);
-  return found ? found.key : null;
-}
-
-/** The catalog entry for a behavior key, or null. */
-export function behaviorForKey(behaviorKey) {
-  return CLASSIFIER_BEHAVIORS.find((b) => b.key === behaviorKey) ?? null;
-}
-
-/**
- * Resolve the compiled rule for each classifier behavior from the rule table. Returns
- * `[{ behavior, rule }]` for behaviors whose rule exists on the userpromptsubmit surface at
- * {@link DIRECTIVE_SEVERITY} and carries an inject — the same filter the plugin router's
- * `rulesForSurface(guardrails, SURFACE, 'prime')` applies. FAIL-SAFE: a missing rule
- * simply drops that behavior.
- *
- * @param {{ repoRoot?: string, ruleTable?: { rules?: object[] } }} [opts]
- */
-export function resolveBehaviorRules(opts = {}) {
-  const table = opts.ruleTable ?? loadRuleTable({ vaultRoot: opts.repoRoot ?? DEFAULT_APP_ROOT });
-  const rules = Array.isArray(table?.rules) ? table.rules : [];
-  const byId = new Map();
-  for (const r of rules) {
-    if (!r || !Array.isArray(r.surfaces) || !r.surfaces.includes(SURFACE)) continue;
-    if (r.severity !== DIRECTIVE_SEVERITY) continue;
-    byId.set(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 });
-  }
-  return resolved;
-}
-
-/**
- * Is this resolved `{ behavior, rule }` entry eligible to fire on this prompt right now?
- * (env kill switch off, injected-content guard passes, config_key enabled.) Behaviors
- * that are ineligible fire on no path — matching the old per-hook early-returns exactly.
- *
- * @param {{ behavior: object, rule: object }} entry
- * @param {string} prompt
- * @param {string} [repoRoot]
- * @param {{ env?: object, getSetting?: Function }} [opts]
- */
-export function isEntryEligible(entry, prompt, repoRoot, opts = {}) {
-  const { behavior, rule } = entry;
-  const env = opts.env ?? process.env;
-  if (String(env?.[behavior.envOff] ?? '') === '1') return false;
-  if (rule.ignoreInjectedContent && behavior.guard(prompt)) return false;
-  if (!isRuleEnabled(rule, repoRoot, opts)) return false;
-  return true;
-}
-
-/**
- * Is this ONE behavior eligible to fire on this prompt right now? (env kill switch off,
- * config_key enabled, injected-content guard passes). The engine gate uses this to re-apply
- * the same gating the plugin's lexical sweep applied per-entry, since
- * ../intent-classifier.mjs's `classifyPrompt()` is lexical-pattern-only and knows nothing
- * about env switches, config toggles, or the injected-content guard. Returns false for an
- * unknown behavior key.
- *
- * @param {string} behaviorKey
- * @param {string} prompt
- * @param {string} [repoRoot]
- * @param {{ env?: object, getSetting?: Function, ruleTable?: object }} [opts]
- */
-export function isBehaviorEligible(behaviorKey, prompt, repoRoot, opts = {}) {
-  const entry = resolveBehaviorRules({ repoRoot, ruleTable: opts.ruleTable }).find((e) => e.behavior.key === behaviorKey);
-  if (!entry) return false;
-  return isEntryEligible(entry, prompt, repoRoot, opts);
-}
-
-/**
- * Resolve ONE behavior's full directive (the rule's inject run through the behavior's
- * transform), WITHOUT the marker. Returns null when the key is unknown / its rule is gone.
- *
- * @param {string} behaviorKey
- * @param {string} [repoRoot]
- * @param {string} [prompt]
- * @param {{ env?: object, getSetting?: Function, ruleTable?: object }} [opts]
- */
-export function resolveDirective(behaviorKey, repoRoot, prompt = '', opts = {}) {
-  const entry = resolveBehaviorRules({ repoRoot, ruleTable: opts.ruleTable }).find((e) => e.behavior.key === behaviorKey);
-  if (!entry) return null;
-  return entry.behavior.transform(entry.rule.inject, repoRoot, prompt, opts);
-}
-
-/**
- * The confirmed-fire seam (HS-5ISS): {@link resolveDirective} plus the SAME loud marker
- * the plugin's Layer 1 lexical fire prepends — so a behavior the engine module
- * (../intent-classifier.mjs) matched, once confirmed eligible, emits a byte-identical
- * directive to the plugin's lexical path. Returns null on an unknown/gone behavior
- * (fail-safe: no injection).
- *
- * @param {string} behaviorKey
- * @param {string} [repoRoot]
- * @param {string} [prompt]
- * @param {{ env?: object, getSetting?: Function, ruleTable?: object }} [opts]
- */
-export function buildConfirmedDirective(behaviorKey, repoRoot, prompt = '', opts = {}) {
-  const directive = resolveDirective(behaviorKey, repoRoot, prompt, opts);
-  if (!directive) return null;
-  return withConfirmedMatchMarker(directive);
-}
-
-/**
- * The engine gate's one-shot: from a rule id the classifier matched, decide whether the
- * behavior may fire and, if so, build the plugin's confirmed directive for it.
- *
- * Outcomes:
- *   - `null` — the behavior is known but NOT eligible right now (env kill switch, config
- *     toggle, or the injected-content guard). The gate must inject nothing.
- *   - `{ behavior: null, additionalContext: null }` — no catalog behavior claims this rule
- *     id, or its rule is not a userpromptsubmit `prime` row the plugin router would have
- *     fired. The gate falls back to the rule's raw inject (the pre-HS-N01T behavior).
- *   - `{ behavior, additionalContext }` — marker + directive, byte-identical to the plugin.
- *
- * @param {string} ruleId
- * @param {string} prompt
- * @param {{ repoRoot?: string, env?: object, getSetting?: Function, ruleTable?: object }} [opts]
- * @returns {{ behavior: string|null, additionalContext: string|null }|null}
- */
-export function buildIntentDirective(ruleId, prompt, opts = {}) {
-  const behaviorKey = behaviorKeyForRuleId(ruleId);
-  if (!behaviorKey) return { behavior: null, additionalContext: null };
-  const behavior = behaviorForKey(behaviorKey);
-  const table = opts.ruleTable ?? loadRuleTable({ vaultRoot: opts.repoRoot ?? DEFAULT_APP_ROOT });
-  const entry = resolveBehaviorRules({ ruleTable: table }).find((e) => e.behavior.key === behaviorKey);
-  if (!entry) {
-    // The classifier matched a row this catalog knows but the plugin router would never
-    // have fired (not a userpromptsubmit `prime` row). The kill switches still apply to the
-    // BEHAVIOR; the directive does not — the gate falls back to the row's raw inject.
-    const row = (Array.isArray(table?.rules) ? table.rules : []).find((r) => r?.rule === ruleId);
-    if (row && !isEntryEligible({ behavior, rule: row }, prompt, opts.repoRoot, opts)) return null;
-    return { behavior: behaviorKey, additionalContext: null };
-  }
-  if (!isEntryEligible(entry, prompt, opts.repoRoot, opts)) return null;
-  const directive = entry.behavior.transform(entry.rule.inject, opts.repoRoot, prompt, opts);
-  if (!directive) return null;
-  return { behavior: behaviorKey, additionalContext: withConfirmedMatchMarker(directive) };
-}
+// spexharness/src/intent-directive.mjs
+//
+// The intent classifier's DIRECTIVE ASSEMBLY — the per-behavior enrichment that turns a rule's
+// raw `inject` text into the exact directive Claude Code's plugin injects for the same prompt
+// ([[HS-N01T-8CMW-TASK-prompt-submit-injects-reach-the-model]], epic
+// [[HS-LS51-8CMW-EPIC-spexcode-plugin-parity-the-prompt]]).
+//
+// MOVED, not copied, from scripts/claude-hooks/_intent-classifier-router.mjs: the confirmed-
+// match marker, the classifier behavior catalog, the capture confirm-mode substitution, the
+// capture kind/routing hints, the research source hint, the eligibility check and the
+// confirmed-directive builder. The router now imports every one of these from here and
+// re-exports them, so its own Layer 1/Layer 2 paths and the Claude Code hook emit the SAME
+// bytes they always did — and ../intent-classifier.mjs's engine gate builds the SAME text for
+// a SpexCode seat. One implementation, two callers; neither can drift from the other.
+//
+// LAYERING: this is a harness module. It imports from ./rule-table.mjs and from
+// vendor/heyspex-mcp (the same vendor modules ./chat/chat-loop.mjs and ./gates/*.mjs already
+// import) and NEVER from scripts/claude-hooks — the plugin's hook scripts sit above the
+// engine and import downward, not the other way round. The two small helpers the router
+// used to take from scripts/claude-hooks/_guardrail-loader.mjs (the injected-content
+// sentinel guards and the config-leaf reads) are therefore implemented here against the same
+// contracts; ./intent-directive.test.mjs pins the sentinel list to the loader's copy so the
+// two lists cannot diverge silently.
+//
+// INJECTED READS (so a test never touches the real config): every function that consults
+// `.heyspex/config.yaml` takes a trailing `opts` carrying
+//   opts.getSetting(repoRoot, key) — returns a leaf shaped like
+//     vendor/heyspex-mcp/config-settings.mjs's `getConfigLeaf` (`{ found, raw, value }`) or
+//     `getEffectiveSetting` (`{ found, value }`); a plain string is also accepted. Defaults to
+//     `getConfigLeaf` against `repoRoot`.
+//   repoRoot — the directory holding `.heyspex/config.yaml`. When absent it is the VAULT
+//     root (./config-root.mjs `defaultConfigRoot()`), NOT DEFAULT_APP_ROOT: since the
+//     2026-08-31 repo split the settings file lives in the vault checkout
+//     ([[HS-4C76-9W86-DIAG-heyspex-config-yaml-has-no-single-home]]). The rule table
+//     (`.heyspex/guardrails.json`) is a code-repo artifact and still loads from
+//     DEFAULT_APP_ROOT when `repoRoot` is absent.
+//   opts.env — the environment the per-behavior kill switches are read from. Defaults to
+//     `process.env`.
+//   opts.ruleTable — a ./rule-table.mjs table (`{ rules }`) to resolve behaviors against
+//     instead of loading the real one.
+// The value semantics mirror the loader's `readConfigLeafRaw` (the trimmed raw scalar after
+// the colon; `undefined` when the leaf is absent) so every substitution below stays
+// byte-identical to what the plugin hook produced before the move.
+//
+// Pure: no I/O of its own beyond loadRuleTable's / getConfigLeaf's fail-safe file reads. No
+// process.stdin/stdout/exit.
+
+import { loadRuleTable, DEFAULT_APP_ROOT } from './rule-table.mjs';
+import { defaultConfigRoot } from './config-root.mjs';
+import { getConfigLeaf } from '../../vendor/heyspex-mcp/config-settings.mjs';
+// HS-QOBQ: cheapest-possible-rung kind classification at capture time — the
+// same lexical guess promote-capture.mjs re-checks at promote time, so both
+// call sites the diagnose named agree on what "reads like a bug" means.
+import { guessCaptureKindFromText } from '../../vendor/heyspex-mcp/capture-kind-suggest.mjs';
+
+/** The registry surface every classifier behavior's rule is authored on. */
+export const SURFACE = 'userpromptsubmit';
+/** The severity the plugin router requires of a rule before it will fire it (its
+ *  `rulesForSurface(guardrails, SURFACE, 'prime')` filter) — the same filter applies here. */
+export const DIRECTIVE_SEVERITY = 'prime';
+/** The token capture-on-idea's authored inject carries where the confirm mode goes. */
+export const MODE_TOKEN = '{{CONFIRM_MODE}}';
+
+// [[HS-BIDR-DTOP-DIAG]] fix: the bare/unconditional directive (a Layer 1 lexical fire,
+// or a Layer 2 mode:'model' fire) and the Layer 2 self_check "still undecided" block are
+// textually distinct but nothing marked WHICH one an agent was reading — it had to infer
+// from wording alone that discretion applies to the self-check and never to a confirmed
+// fire. That inference is easy to drop under load, and an agent that drops it treats a
+// confirmed match as if it were a self-check and silently skips it (the production miss
+// this diagnose captures). This marker is prepended to every CONFIRMED-FIRE directive —
+// loud and explicit as the mirror image of the self-check wrapper's own "silently
+// judge... DEFAULT OUTCOME IS NONE" framing — so the two shapes are unmistakable at a
+// glance, not just by prose wording.
+export const CONFIRMED_MATCH_MARKER =
+  'HEYSPEX CONFIRMED MATCH — NOT A SELF-CHECK. A deterministic rule has ALREADY matched ' +
+  "this message. There is no judgment step and nothing left to evaluate — do NOT silently " +
+  'second-guess it, and "this is also a work order / bug report" is explicitly NOT a valid ' +
+  'reason to skip it. Execute the directive below IMMEDIATELY, exactly as written.';
+
+/** Prepend the confirmed-match marker to a resolved directive. */
+export function withConfirmedMatchMarker(directive) {
+  return `${CONFIRMED_MATCH_MARKER}\n\n${directive}`;
+}
+
+// ── [[HS-XDH8-9Y92-DIAG-defer-intent-hook-fires-on-negated]] Fix §2: per-behavior marker ──
+// The unconditional CONFIRMED MATCH marker is right for capture_on_idea (HS-BIDR: a false
+// positive only costs an extra capture, a skipped fire loses an idea). For behaviors whose
+// false positive CHANGES WHAT GETS DONE — defer_intent (schedules the work a week out instead
+// of doing it) and settings_intent (writes a setting) — the marker must not override the
+// inject's own "FIRST, gate for precision" step. On 2026-10-10 "No do not defer the vault
+// right to closeout. Do it, right, please." fired defer, and the "do NOT second-guess" marker
+// ordered the agent to invert the owner's explicit instruction. These behaviors get a softer
+// marker that still says a deterministic rule matched (so it is never confused with the
+// self-check block) but keeps the precision gate authoritative.
+export const PRECISION_GATED_MATCH_MARKER =
+  'HEYSPEX LEXICAL MATCH — PRECISION-GATED, NOT A SELF-CHECK. A deterministic rule matched a ' +
+  'phrase in this message, but a phrase match can misread what the user asked (for example a ' +
+  'negated request such as "do not defer this"). The directive\'s own FIRST precision gate is ' +
+  'AUTHORITATIVE: if the user\'s words do not actually ask for this, IGNORE the directive and do ' +
+  'what they asked. Never act against an explicit instruction in the message.';
+
+/** Behavior keys whose fire is precision-gated (soft marker), not unconditional. */
+export const PRECISION_GATED_BEHAVIORS = Object.freeze(new Set(['defer_intent', 'settings_intent']));
+
+/** The marker a confirmed lexical/model fire of this behavior carries. */
+export function matchMarkerFor(behaviorKey) {
+  return PRECISION_GATED_BEHAVIORS.has(behaviorKey) ? PRECISION_GATED_MATCH_MARKER : CONFIRMED_MATCH_MARKER;
+}
+
+/** Prepend the behavior-appropriate match marker to a resolved directive. */
+export function withMatchMarker(behaviorKey, directive) {
+  return `${matchMarkerFor(behaviorKey)}\n\n${directive}`;
+}
+
+// ── HS-XDH8 Fix §1: negation-aware lexical matching ─────────────────────────
+// A rule's patterns are a bag of positive regexes; "defer the vault" matched inside "do not
+// defer the vault". For a negation-guarded rule, a pattern hit only counts when its CLAUSE
+// does not negate it: the text before the match, back to the nearest clause boundary
+// (punctuation, a dash, or a joining conjunction such as "so"/"but"), has its last few words
+// scanned for a negation cue. Every occurrence of every pattern is checked; the rule fires if
+// ANY occurrence is un-negated ("don't defer the docs, but park this until Friday" fires).
+// Opt-in per rule: the ids below, or `negationGuard: true` on a rule row.
+export const NEGATION_GUARDED_RULE_IDS = Object.freeze(new Set(['defer-intent', 'capture-on-idea']));
+const NEGATION_WINDOW_WORDS = 5;
+const NEGATION_CUE_RE =
+  /\b(?:no|not|never|dont|don't|doesn't|didn't|won't|wont|shouldn't|mustn't|can't|cannot|stop|quit|without|nor|neither|instead\s+of|rather\s+than)\b/i;
+const CLAUSE_BOUNDARY_RE = /[.!?;:,\n\r—–]|\s-\s|\b(?:so|but|and|then|because|though|although)\b/gi;
+
+/** Does the clause leading up to `index` in `text` negate what starts at `index`? */
+export function isNegatedAt(text, index) {
+  let before = String(text).slice(0, index).replace(/’/g, "'");
+  let cut = -1;
+  for (const m of before.matchAll(CLAUSE_BOUNDARY_RE)) cut = m.index + m[0].length;
+  if (cut >= 0) before = before.slice(cut);
+  const words = before.match(/[a-z]+(?:'[a-z]+)?/gi) ?? [];
+  return NEGATION_CUE_RE.test(words.slice(-NEGATION_WINDOW_WORDS).join(' '));
+}
+
+/** Is this rule row negation-guarded? */
+export function isNegationGuarded(rule) {
+  return rule?.negationGuard === true || NEGATION_GUARDED_RULE_IDS.has(rule?.rule);
+}
+
+/**
+ * Does `prompt` match `rule` through its compiled `patterns` (case-insensitive RegExps)?
+ * Unguarded rules keep the plain `patterns.some(re.test)` semantics byte-for-byte; a
+ * negation-guarded rule needs at least one un-negated occurrence.
+ */
+export function ruleMatchesPrompt(rule, patterns, prompt) {
+  if (typeof prompt !== 'string' || !Array.isArray(patterns)) return false;
+  if (!isNegationGuarded(rule)) return patterns.some((re) => re.test(prompt));
+  for (const re of patterns) {
+    const global = new RegExp(re.source, re.flags.includes('g') ? re.flags : `${re.flags}g`);
+    for (const m of prompt.matchAll(global)) {
+      if (!isNegatedAt(prompt, m.index)) return true;
+    }
+  }
+  return false;
+}
+
+// ── injected-content guards ──────────────────────────────────────────────────
+// Sentinels that mark harness-injected content arriving through the UserPromptSubmit
+// channel (background-task notifications, system reminders, slash-command envelopes). They
+// can contain a rule's trigger phrase verbatim but are NOT a genuine human prompt, so a rule
+// with `ignoreInjectedContent` must not fire on them. scripts/claude-hooks/_guardrail-loader.mjs
+// carries the plugin-side copy of this list; ./intent-directive.test.mjs asserts the two are
+// equal so an edit to one cannot silently leave the other behind.
+export const INJECTED_CONTENT_SENTINELS = [
+  '<task-notification>',
+  '<system-reminder>',
+  '[SYSTEM NOTIFICATION',
+  '<command-message>',
+  '<command-name>',
+  '<local-command-stdout>',
+];
+
+/** Contains-anywhere guard — the research hook's original (broad) check. */
+export function containsInjectedContent(text) {
+  if (typeof text !== 'string') return false;
+  return INJECTED_CONTENT_SENTINELS.some((s) => text.includes(s));
+}
+
+/**
+ * Stricter, false-positive-safe variant: is the message a genuine harness ENVELOPE (a
+ * task-notification / system-reminder / slash-command envelope delivered AS the prompt),
+ * rather than user text that merely QUOTES a sentinel? A real envelope leads with its tag;
+ * a user pasting a transcript or terminal logs leads with their own words.
+ */
+export function startsWithInjectedContent(text) {
+  if (typeof text !== 'string') return false;
+  const head = text.trimStart();
+  return INJECTED_CONTENT_SENTINELS.some((s) => head.startsWith(s));
+}
+
+// ── config reads (injectable) ────────────────────────────────────────────────
+
+/**
+ * The default settings reader: vendor/heyspex-mcp/config-settings.mjs's `getConfigLeaf`
+ * against `<repoRoot>/.heyspex/config.yaml` — the same indent-scoped `key:` scan the plugin
+ * loader's `readConfigLeafRaw` performs, returning `{ found, raw, value }`. With no
+ * `repoRoot` the file is read from the vault root (`defaultConfigRoot()`).
+ */
+export function defaultGetSetting(repoRoot, key) {
+  return getConfigLeaf(repoRoot ?? defaultConfigRoot(), key);
+}
+
+/**
+ * Read one config leaf as the loader's `readConfigLeafRaw` would: the trimmed raw scalar,
+ * or `undefined` when absent/unreadable. Accepts every reader shape the header documents.
+ * FAIL-SAFE: a throwing reader reads as "absent".
+ */
+export function readConfigLeafRaw(configKey, repoRoot, opts = {}) {
+  if (!configKey || typeof configKey !== 'string') return undefined;
+  const getSetting = typeof opts.getSetting === 'function' ? opts.getSetting : defaultGetSetting;
+  let leaf;
+  try {
+    leaf = getSetting(repoRoot ?? defaultConfigRoot(), configKey);
+  } catch {
+    return undefined;
+  }
+  if (leaf == null) return undefined;
+  if (typeof leaf === 'string') return leaf.trim();
+  if (typeof leaf === 'object') {
+    if (leaf.found === false) return undefined;
+    if (typeof leaf.raw === 'string') return leaf.raw.trim();
+    if (leaf.value === undefined || leaf.value === null) return undefined;
+    return String(leaf.value).trim();
+  }
+  return String(leaf).trim();
+}
+
+/**
+ * Is a dotted `config_key` ON? Semantics match the loader's `isConfigKeyEnabled`: ON unless
+ * the leaf is explicitly `false`; absent / unreadable / no key at all default to ON.
+ */
+export function isConfigKeyEnabled(configKey, repoRoot, opts = {}) {
+  if (!configKey || typeof configKey !== 'string') return true;
+  const raw = readConfigLeafRaw(configKey, repoRoot, opts);
+  if (raw === undefined) return true;
+  return raw.toLowerCase() !== 'false';
+}
+
+/** Enabled-check straight off a rule row (its `configKey`). */
+export function isRuleEnabled(rule, repoRoot, opts = {}) {
+  return isConfigKeyEnabled(rule && rule.configKey, repoRoot, opts);
+}
+
+/**
+ * Resolve the CONFIRM MODE for an autonomous agent behavior — the two-layer permission
+ * model the owner specified (2026-07-11):
+ *   'auto' = act immediately, user can undo/discard afterward   (forgiveness)
+ *   'ask'  = ask the user for confirmation before acting        (permission)
+ *
+ * Resolution order (per-behavior override wins over the global default):
+ *   1. agent_behaviors.<behaviorKey>.ask_first
+ *        true|yes|ask  → 'ask'   ·  false|no|auto → 'auto'  ·  null/absent → inherit
+ *   2. (inherit) global agent_behaviors.ask_forgiveness_not_permission
+ *        true|yes|absent → 'auto' (forgiveness — the owner's default)
+ *        false|no        → 'ask'
+ * FAIL-SAFE: any unreadable config → 'auto' (the stated default).
+ */
+export function resolveConfirmMode(behaviorKey, repoRoot, opts = {}) {
+  if (behaviorKey && typeof behaviorKey === 'string') {
+    const per = readConfigLeafRaw(`agent_behaviors.${behaviorKey}.ask_first`, repoRoot, opts);
+    if (per !== undefined) {
+      const v = per.toLowerCase();
+      if (v === 'true' || v === 'yes' || v === 'ask') return 'ask';
+      if (v === 'false' || v === 'no' || v === 'auto') return 'auto';
+      // 'null' / '' / anything else → fall through to the global default (inherit)
+    }
+  }
+  const global = readConfigLeafRaw('agent_behaviors.ask_forgiveness_not_permission', repoRoot, opts);
+  if (global !== undefined) {
+    const g = global.toLowerCase();
+    if (g === 'false' || g === 'no') return 'ask'; // forgiveness OFF → ask first
+  }
+  return 'auto'; // forgiveness ON / absent → act, don't ask
+}
+
+// ── capture-on-idea enrichment ───────────────────────────────────────────────
+
+// Capture's forgiveness/permission directives — carried over verbatim from the retired
+// capture-trigger.mjs shim (HS-IYU1, deleted after burn-in) so the emitted inject stays
+// byte-identical.
+export const CAPTURE_MODE_DIRECTIVES = {
+  auto:
+    "FORGIVENESS MODE (the owner's default — act, don't ask): START THE CAPTURE FLOW " +
+    'IMMEDIATELY. In ONE short line, tell the user you are capturing this as an idea ' +
+    'and they can say "discard" (or "no, just do it") to skip — then begin. Do NOT ask ' +
+    'permission first.',
+  ask:
+    'PERMISSION MODE: ASK FIRST. Reply with ONE line — "Want me to capture this as an ' +
+    'idea? (yes / no, just do it)" — and run the capture steps below ONLY if the user ' +
+    'says yes. If they decline, just do the task.',
+};
+
+/**
+ * capture-on-idea's full transform: substitute `{{CONFIRM_MODE}}` (or prepend the mode
+ * directive when the token is absent), then append the routing and kind hints.
+ */
+export function applyCaptureConfirmMode(inject, repoRoot, prompt, opts = {}) {
+  const mode = resolveConfirmMode('capture_on_idea', repoRoot, opts);
+  const directive = CAPTURE_MODE_DIRECTIVES[mode] || CAPTURE_MODE_DIRECTIVES.auto;
+  const base = inject.includes(MODE_TOKEN) ? inject.split(MODE_TOKEN).join(directive) : `${directive}\n\n${inject}`;
+  return appendCaptureKindHint(appendCaptureRoutingHint(base, repoRoot, opts), prompt);
+}
+
+// Capture kind hint ([[HS-QOBQ-S4JZ-DIAG-capture-kind-is-never-classified-every]]):
+// every capture materializes at `kind: idea` and nothing ever inspected the
+// triggering message to check whether that default is right. This is the
+// cheapest rung (lexical, no model call) — a strong bug-language match in the
+// SAME message the capture-on-idea rule already fired on. Suggest-only: the
+// agent still must offer it and get a yes before calling heyspex_update_capture
+// with kind ([[HS-5HYS]] elicitation — suggest, never auto-apply), matching the
+// existing heyspex_update_capture `kind` arg description verbatim.
+export function appendCaptureKindHint(inject, prompt) {
+  const guess = guessCaptureKindFromText(prompt);
+  if (!guess.kind) return inject;
+  const hint =
+    `CAPTURE KIND HINT (lexical, suggest-only): this message reads like kind: ${guess.kind} ` +
+    `(matched "${guess.matched}"), not the default idea. After capturing, offer the ` +
+    `reclassification in your reply (e.g. "this reads like a bug-fix capture — reclassify?") ` +
+    `and call heyspex_update_capture with kind: "${guess.kind}" ONLY on the user's yes — never ` +
+    `auto-apply it.`;
+  return `${inject}\n\n${hint}`;
+}
+
+// Capture model-routing + thread-split hint ([[HS-6YOA-HPR6-RES-capture-to-research-auto-model-routing]],
+// owner ruling 2026-08-11). A best-effort HINT appended to the capture inject, same shape as
+// appendResearchSourceHint below — the hook cannot know the running session's actual current
+// model (that's not in the UserPromptSubmit payload), so it can only tell the agent what's
+// CONFIGURED and trust the agent (which does know its own model, per its own system prompt) to
+// judge whether a switch/delegate/ask actually applies. Neither mode is ever a silent, live
+// model switch — that is not possible from a hook or from the agent itself (research doc's
+// Platform capability check: `/model` is a user-issued local command; no MCP tool flips it).
+export function appendCaptureRoutingHint(inject, repoRoot, opts = {}) {
+  const defaultModel = readConfigLeafRaw('agent_behaviors.capture_on_idea.default_model', repoRoot, opts);
+  const switchMode = readConfigLeafRaw('agent_behaviors.capture_on_idea.model_switch_mode', repoRoot, opts) || 'ask';
+  const splitMode = readConfigLeafRaw('agent_behaviors.capture_on_idea.thread_split_mode', repoRoot, opts) || 'ask';
+
+  const parts = [inject];
+
+  if (defaultModel && switchMode !== 'off') {
+    const modeInstruction =
+      switchMode === 'silent_delegate'
+        ? 'CONFIGURED MODE: silent_delegate — do NOT interrupt the user with a model question. ' +
+          `If this is the FIRST/ONLY capture turn in this thread (not a continuation of an ` +
+          `already-open capture) and you are not already running as ${defaultModel}, hand the ` +
+          'mechanical capture steps (verbatim quote, core idea, summary, ground=expand) to a ' +
+          `one-shot Agent(prompt: <the capture instructions>, model: "${defaultModel}") subagent ` +
+          'instead of running them on this session — then relay its result. Never switch this ' +
+          "running session's own model; that is not possible and is not what this mode means."
+        : 'CONFIGURED MODE: ask — if this is the FIRST/ONLY capture turn in this thread (not a ' +
+          `continuation of an already-open capture) and you are not already running as ` +
+          `${defaultModel}, add ONE short line to your capture-start message offering a switch — ` +
+          `e.g. "(captures default to ${defaultModel} — say switch to run /model ${defaultModel} ` +
+          'first)" — then proceed with the capture flow regardless of the answer; never block on ' +
+          'it. A mid-thread continuation never gets this offer — it stays on the thread\'s model.';
+    parts.push(
+      `CAPTURE MODEL ROUTING (default_model=${defaultModel}, model_switch_mode=${switchMode}): ${modeInstruction}`,
+    );
+  }
+
+  const splitInstruction =
+    splitMode === 'auto'
+      ? 'CONFIGURED thread_split_mode=auto: when new mid-thread prose is judged NOT a continuation ' +
+        'of the on-deck capture, decide on your own judgment — no AskUserQuestion — whether it ' +
+        'SPLITS (a new HS-CAP-* that still benefits from this thread\'s context: continue it via ' +
+        'Agent(subagent_type:"fork") so full context carries over) or SPAWNS (unrelated enough that ' +
+        'a fresh Agent() with no inherited context is cleaner). State which you picked and why in ' +
+        'one line.'
+      : 'CONFIGURED thread_split_mode=ask: when new mid-thread prose is judged NOT a continuation of ' +
+        'the on-deck capture, and you are NOT confident whether it benefits from this thread\'s ' +
+        'existing context, use AskUserQuestion with exactly two options — split (new capture id, ' +
+        'keep this thread\'s context via Agent(subagent_type:"fork")) vs. spawn (new capture id, ' +
+        'fresh context via a plain Agent() call) — rather than guessing. Skip the ask only when ' +
+        'you ARE confident: a clearly-related new idea still splits, a clearly-unrelated one still ' +
+        'spawns, with no prompt.';
+  parts.push(`CAPTURE THREAD SPLIT/SPAWN: ${splitInstruction}`);
+
+  return parts.join('\n\n');
+}
+
+// Research-source hint — fix for [[HS-LFUH-DIAG-W1YE]] root-cause part 1 ("not injected").
+// The research inject above tells the agent WHICH RUNGS to climb and WHICH MODEL to spawn
+// (default_agent), but never named the configured search/scrape BACKEND
+// (agent_behaviors.research.default_source) — so a configured `firecrawl-self-hosted` default
+// was silently unreachable on the interactive path; the agent had no way to even know it existed.
+// This is deliberately a best-effort HINT appended to the existing inject text, not a
+// replacement: it is a snapshot taken at prompt-submit time, so it can go stale mid-session
+// (a lease can be granted/refused, a box can go up/down). The authoritative, can't-go-stale
+// source of truth is the on-demand `heyspex_resolve_research_plan` MCP tool this hint points the
+// agent at — per the research doc's recommendation, "hook injection is a best-effort hint; the
+// on-demand tool is the source of truth", not either/or.
+export function appendResearchSourceHint(inject, repoRoot, opts = {}) {
+  const defaultSource = readConfigLeafRaw('agent_behaviors.research.default_source', repoRoot, opts);
+  const defaultAgent = readConfigLeafRaw('agent_behaviors.research.default_agent', repoRoot, opts);
+  if (!defaultSource && !defaultAgent) return inject; // nothing configured — nothing to hint at
+  const hint =
+    'CONFIGURED RESEARCH RESOURCE (best-effort hint, a snapshot — re-confirm live via ' +
+    'heyspex_resolve_research_plan() before RUNG 0 `sequential` search/scrape, since availability ' +
+    `can change mid-session): default_source=${defaultSource ?? '(unset)'}, ` +
+    `default_agent=${defaultAgent ?? '(unset)'}. If default_source names a Firecrawl backend ` +
+    '(firecrawl-self-hosted | firecrawl-hosted), call heyspex_firecrawl_research({ mode: "search"|"scrape", ' +
+    'query|url }) for rung 0 instead of native WebSearch/WebFetch — it wraps that SAME configured ' +
+    'backend and honors its existing availability gates (the Ollama-XOR-Firecrawl lease / hosted credit ' +
+    'gate). If its result reports downgraded:true, tell the user plainly that the configured backend was ' +
+    'unavailable and you fell back to web-native — NEVER substitute silently.';
+  return `${inject}\n\n${hint}`;
+}
+
+// ── the behavior catalog ─────────────────────────────────────────────────────
+
+// The classifier behavior catalog. `ruleId` ties a behavior to its registry rule;
+// `description` is the semantic-classification instruction (the router's self-check block
+// and opt-in model mode read it from here — this catalog is the single source of behavior
+// descriptions); `envOff` is the per-behavior kill switch; `guard` is the injected-content
+// check that behavior used historically; `transform(inject, repoRoot, prompt, opts)` builds
+// the final inject from the rule's inject text (`opts` carries the injected reads — see the
+// header). BEHAVIOR_ORDER (array order) is the deterministic lexical tiebreak.
+export const CLASSIFIER_BEHAVIORS = [
+  {
+    key: 'capture_on_idea',
+    ruleId: 'capture-on-idea',
+    envOff: 'HEYSPEX_CAPTURE_TRIGGER_OFF',
+    guard: startsWithInjectedContent,
+    transform: (inject, repoRoot, prompt, opts) => applyCaptureConfirmMode(inject, repoRoot, prompt, opts),
+    description:
+      'The user\'s message contains a raw idea, suggestion, observation, or improvement thought — something that could exist or be better. Fires even when the message is ALSO a work order or bug report, as long as it carries new idea/capability content worth remembering. Does NOT fire on purely mechanical commands with no new idea (e.g. "run the tests", "fix the typo"), plain questions about existing work, or bare continuations of work already in progress.',
+  },
+  {
+    key: 'research_before_decision',
+    ruleId: 'research-before-decision',
+    envOff: 'HEYSPEX_RESEARCH_TRIGGER_OFF',
+    guard: containsInjectedContent,
+    transform: (inject, repoRoot, _prompt, opts) => appendResearchSourceHint(inject, repoRoot, opts),
+    description:
+      'The user is declining to make a design or architecture decision themselves and is asking for research, best practices, or an expert recommendation instead (e.g. "not a decision I should have to make", "don\'t reinvent the wheel").',
+  },
+  {
+    key: 'settings_intent',
+    ruleId: 'settings-intent',
+    envOff: 'HEYSPEX_SETTINGS_INTENT_OFF',
+    guard: startsWithInjectedContent,
+    transform: (inject) => inject,
+    description:
+      'The user wants to READ or CHANGE a HeySpex workflow setting / agent behavior — enable or disable a behavior (auto-capture, the research trigger, the intent classifier), turn something on or off, set/lower/raise a threshold or value (confidence, timeout), or ask what a setting is currently. About the configuration itself, NOT a request to do the underlying work.',
+  },
+  {
+    key: 'defer_intent',
+    ruleId: 'defer-intent',
+    envOff: 'HEYSPEX_DEFER_INTENT_OFF',
+    guard: startsWithInjectedContent,
+    transform: (inject) => inject,
+    description:
+      'The user wants to DEFER, POSTPONE, or SCHEDULE a follow-up to a later time — "come back to this later", "remind me in a week", "park/table this until X is done", "schedule this for next week", "not now — later, after the migration". About WHEN to revisit something, not a request to do it now.',
+  },
+  {
+    key: 'handoff_intent',
+    ruleId: 'handoff-intent',
+    envOff: 'HEYSPEX_HANDOFF_INTENT_OFF',
+    guard: startsWithInjectedContent,
+    transform: (inject) => inject,
+    description:
+      'The user asks for a hand-off prompt, doc, notes or resume context for the NEXT agent or session ("give me a handoff prompt for the next agent", "hand this off", "what should the next session know"). About producing the hand-off artifact, NOT about loading one (a lane code like GQ5R or `hs handoff load`) and not ordinary work.',
+  },
+  {
+    key: 'spec_reference_lookup',
+    ruleId: 'spec-reference-lookup',
+    envOff: 'HEYSPEX_SPEC_REFERENCE_LOOKUP_OFF',
+    guard: startsWithInjectedContent,
+    transform: (inject) => inject,
+    description:
+      'The user\'s message is little more than a pointer at an existing spec by id (a bare "HS-XXXX-YYYY", or "Reference: HS-...", "re: HS-...", "see HS-..." with nothing else actionable). Fires whether or not the spec turns out to matter. Does NOT fire on an ordinary work order that happens to name a spec id alongside real instructions ("update HS-XXXX\'s tests and rerun them") — there the id is already load-bearing context, not an unresolved pointer.',
+  },
+];
+
+/**
+ * Map an engine rule id (hyphenated, e.g. 'capture-on-idea') back to the router's
+ * behavior key (underscored, e.g. 'capture_on_idea'). Returns null for an id no
+ * behavior claims (fail-safe: the engine cutover treats that as no match).
+ */
+export function behaviorKeyForRuleId(ruleId) {
+  const found = CLASSIFIER_BEHAVIORS.find((b) => b.ruleId === ruleId);
+  return found ? found.key : null;
+}
+
+/** The catalog entry for a behavior key, or null. */
+export function behaviorForKey(behaviorKey) {
+  return CLASSIFIER_BEHAVIORS.find((b) => b.key === behaviorKey) ?? null;
+}
+
+/**
+ * Resolve the compiled rule for each classifier behavior from the rule table. Returns
+ * `[{ behavior, rule }]` for behaviors whose rule exists on the userpromptsubmit surface at
+ * {@link DIRECTIVE_SEVERITY} and carries an inject — the same filter the plugin router's
+ * `rulesForSurface(guardrails, SURFACE, 'prime')` applies. FAIL-SAFE: a missing rule
+ * simply drops that behavior.
+ *
+ * @param {{ repoRoot?: string, ruleTable?: { rules?: object[] } }} [opts]
+ */
+export function resolveBehaviorRules(opts = {}) {
+  const table = opts.ruleTable ?? loadRuleTable({ vaultRoot: opts.repoRoot ?? DEFAULT_APP_ROOT });
+  const rules = Array.isArray(table?.rules) ? table.rules : [];
+  const byId = new Map();
+  for (const r of rules) {
+    if (!r || !Array.isArray(r.surfaces) || !r.surfaces.includes(SURFACE)) continue;
+    if (r.severity !== DIRECTIVE_SEVERITY) continue;
+    byId.set(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 });
+  }
+  return resolved;
+}
+
+/**
+ * Is this resolved `{ behavior, rule }` entry eligible to fire on this prompt right now?
+ * (env kill switch off, injected-content guard passes, config_key enabled.) Behaviors
+ * that are ineligible fire on no path — matching the old per-hook early-returns exactly.
+ *
+ * @param {{ behavior: object, rule: object }} entry
+ * @param {string} prompt
+ * @param {string} [repoRoot]
+ * @param {{ env?: object, getSetting?: Function }} [opts]
+ */
+export function isEntryEligible(entry, prompt, repoRoot, opts = {}) {
+  const { behavior, rule } = entry;
+  const env = opts.env ?? process.env;
+  if (String(env?.[behavior.envOff] ?? '') === '1') return false;
+  if (rule.ignoreInjectedContent && behavior.guard(prompt)) return false;
+  if (!isRuleEnabled(rule, repoRoot, opts)) return false;
+  return true;
+}
+
+/**
+ * Is this ONE behavior eligible to fire on this prompt right now? (env kill switch off,
+ * config_key enabled, injected-content guard passes). The engine gate uses this to re-apply
+ * the same gating the plugin's lexical sweep applied per-entry, since
+ * ../intent-classifier.mjs's `classifyPrompt()` is lexical-pattern-only and knows nothing
+ * about env switches, config toggles, or the injected-content guard. Returns false for an
+ * unknown behavior key.
+ *
+ * @param {string} behaviorKey
+ * @param {string} prompt
+ * @param {string} [repoRoot]
+ * @param {{ env?: object, getSetting?: Function, ruleTable?: object }} [opts]
+ */
+export function isBehaviorEligible(behaviorKey, prompt, repoRoot, opts = {}) {
+  const entry = resolveBehaviorRules({ repoRoot, ruleTable: opts.ruleTable }).find((e) => e.behavior.key === behaviorKey);
+  if (!entry) return false;
+  return isEntryEligible(entry, prompt, repoRoot, opts);
+}
+
+/**
+ * Resolve ONE behavior's full directive (the rule's inject run through the behavior's
+ * transform), WITHOUT the marker. Returns null when the key is unknown / its rule is gone.
+ *
+ * @param {string} behaviorKey
+ * @param {string} [repoRoot]
+ * @param {string} [prompt]
+ * @param {{ env?: object, getSetting?: Function, ruleTable?: object }} [opts]
+ */
+export function resolveDirective(behaviorKey, repoRoot, prompt = '', opts = {}) {
+  const entry = resolveBehaviorRules({ repoRoot, ruleTable: opts.ruleTable }).find((e) => e.behavior.key === behaviorKey);
+  if (!entry) return null;
+  return entry.behavior.transform(entry.rule.inject, repoRoot, prompt, opts);
+}
+
+/**
+ * The confirmed-fire seam (HS-5ISS): {@link resolveDirective} plus the SAME loud marker
+ * the plugin's Layer 1 lexical fire prepends — so a behavior the engine module
+ * (../intent-classifier.mjs) matched, once confirmed eligible, emits a byte-identical
+ * directive to the plugin's lexical path. Returns null on an unknown/gone behavior
+ * (fail-safe: no injection).
+ *
+ * @param {string} behaviorKey
+ * @param {string} [repoRoot]
+ * @param {string} [prompt]
+ * @param {{ env?: object, getSetting?: Function, ruleTable?: object }} [opts]
+ */
+export function buildConfirmedDirective(behaviorKey, repoRoot, prompt = '', opts = {}) {
+  const directive = resolveDirective(behaviorKey, repoRoot, prompt, opts);
+  if (!directive) return null;
+  return withMatchMarker(behaviorKey, directive);
+}
+
+/**
+ * The engine gate's one-shot: from a rule id the classifier matched, decide whether the
+ * behavior may fire and, if so, build the plugin's confirmed directive for it.
+ *
+ * Outcomes:
+ *   - `null` — the behavior is known but NOT eligible right now (env kill switch, config
+ *     toggle, or the injected-content guard). The gate must inject nothing.
+ *   - `{ behavior: null, additionalContext: null }` — no catalog behavior claims this rule
+ *     id, or its rule is not a userpromptsubmit `prime` row the plugin router would have
+ *     fired. The gate falls back to the rule's raw inject (the pre-HS-N01T behavior).
+ *   - `{ behavior, additionalContext }` — marker + directive, byte-identical to the plugin.
+ *
+ * @param {string} ruleId
+ * @param {string} prompt
+ * @param {{ repoRoot?: string, env?: object, getSetting?: Function, ruleTable?: object }} [opts]
+ * @returns {{ behavior: string|null, additionalContext: string|null }|null}
+ */
+export function buildIntentDirective(ruleId, prompt, opts = {}) {
+  const behaviorKey = behaviorKeyForRuleId(ruleId);
+  if (!behaviorKey) return { behavior: null, additionalContext: null };
+  const behavior = behaviorForKey(behaviorKey);
+  const table = opts.ruleTable ?? loadRuleTable({ vaultRoot: opts.repoRoot ?? DEFAULT_APP_ROOT });
+  const entry = resolveBehaviorRules({ ruleTable: table }).find((e) => e.behavior.key === behaviorKey);
+  if (!entry) {
+    // The classifier matched a row this catalog knows but the plugin router would never
+    // have fired (not a userpromptsubmit `prime` row). The kill switches still apply to the
+    // BEHAVIOR; the directive does not — the gate falls back to the row's raw inject.
+    const row = (Array.isArray(table?.rules) ? table.rules : []).find((r) => r?.rule === ruleId);
+    if (row && !isEntryEligible({ behavior, rule: row }, prompt, opts.repoRoot, opts)) return null;
+    return { behavior: behaviorKey, additionalContext: null };
+  }
+  if (!isEntryEligible(entry, prompt, opts.repoRoot, opts)) return null;
+  const directive = entry.behavior.transform(entry.rule.inject, opts.repoRoot, prompt, opts);
+  if (!directive) return null;
+  return { behavior: behaviorKey, additionalContext: withMatchMarker(behaviorKey, directive) };
+}