heyspex 0.1.0 → 0.2.1

package/spexharness/src/gates/preflight-reminder-gate.mjs

@@ -0,0 +1,265 @@
+// spexharness/src/gates/preflight-reminder-gate.mjs
+//
+// Engine port of scripts/claude-hooks/preflight-reminder.mjs's UserPromptSubmit half — the
+// registry-driven filing-intent prime ([[HS-EPIC-ZGWR]] AC#6: "file a milestone" / "create
+// an epic" → the spec-creation-via-minter rule's inject) and the grounding-before-proposing
+// nudge ([[HS-RES-2QX6]] / [[HS-EPIC-PLRV]]: a design/planning request → "run /hs-ground
+// first"). Task [[HS-N01T-8CMW-TASK-prompt-submit-injects-reach-the-model]], epic
+// [[HS-LS51-8CMW-EPIC-spexcode-plugin-parity-the-prompt]]. See ./PORTING.md for the recipe.
+//
+// The hook's PreToolUse half (protocol-edit, CLAUDE.md-edit and destructive-command
+// reminders) is NOT ported here — it is a `before_tool` concern with its own shape, and
+// this task's scope is the prompt_submit event only.
+//
+// PORTING.md step 1 says "import the pure decision function; never a second copy". That
+// rule bends here for a documented reason: the hook's `detectRegistryPrimeReminder` was
+// written against scripts/claude-hooks/_guardrail-loader.mjs (its file-scanning config
+// helpers and stderr-writing loader), and the engine must not import upward into the
+// plugin's scripts. So the decision function LIVES HERE, against ../rule-table.mjs and the
+// injected config reader ../intent-directive.mjs provides, and the hook script imports it
+// from this module — one implementation, the plugin as the thin caller, which is the same
+// relationship every other ported gate ends up in. The hook's own smoke keeps exercising it
+// through the hook's re-export.
+//
+// Event mapping: UserPromptSubmit → `prompt_submit` (../events.mjs).
+//
+// Decision mapping: the hook's only outcomes are "say nothing" and "emit additionalContext",
+// so: `allow` and `inject` — a PRIME injection, never a deny, never a rewrite.
+//
+// NOT GATED ON CLAUDE_AGENT. The hook exits silently unless `CLAUDE_AGENT=true` (so a human
+// typing in an interactive Claude Code session is not nudged) and keeps that gate in its
+// own `main()`. A SpexCode seat IS the agent, so the engine gate runs unconditionally; the
+// two kill switches port unchanged through `ctx.env`:
+//   HEYSPEX_PREFLIGHT_REMINDER_OFF=1 — the whole gate is silent.
+//   HEYSPEX_GROUNDING_NUDGE_OFF=1    — the grounding nudge alone is silent.
+//
+// OWNED ELSEWHERE — the one deliberate difference from the hook's sweep. The hook excludes
+// only `research-before-decision` from the userpromptsubmit `prime` rules it will fire,
+// because on the plugin every OTHER intent rule is ALSO fired by the (CLAUDE_AGENT-gated)
+// hook — a latent double-injection that never shows because the gate is unset
+// interactively. Ungated in the engine that would fire capture-on-idea's raw inject (with
+// a literal `{{CONFIRM_MODE}}`) next to ../intent-classifier.mjs's finished directive, and
+// would fire `communication-style-prime` (an unconditional `[\s\S]` rule, 3.7 KB) on every
+// prompt. So the ENGINE default excludes every rule ../intent-classifier.mjs owns on this
+// same event plus communication-style-prime (its own always-on injection is a separate
+// concern — see intent-classifier.mjs's CLASSIFIER_RULE_IDS note). The hook passes its own
+// narrower set explicitly (`PRIME_RULES_OWNED_ELSEWHERE`), so its emitted bytes are
+// unchanged.
+//
+// `ctx` contract (all optional; every field defaults to a real read):
+//   ctx.repoRoot / ctx.vaultRoot - the app root holding `.heyspex/guardrails.json`. Defaults
+//                       to the event's `cwd`, then CLAUDE_PROJECT_DIR, then this repo's root.
+//                       When given it is a self-contained fixture root and each rule's
+//                       config toggle is read from it too.
+//   ctx.configRoot    - the directory holding `.heyspex/config.yaml` (the rules' configKey
+//                       toggles); wins over ctx.repoRoot/ctx.vaultRoot for that read. With
+//                       none of the three, the VAULT root (../config-root.mjs
+//                       `defaultConfigRoot()`) — never the event's cwd or CLAUDE_PROJECT_DIR,
+//                       which under Claude Code is the app checkout, not where the settings
+//                       file lives ([[HS-4C76-9W86-DIAG-heyspex-config-yaml-has-no-single-home]]).
+//   ctx.ruleTable     - an injected ../rule-table.mjs table (tests).
+//   ctx.getSetting    - an injected settings reader (see ../intent-directive.mjs's header).
+//   ctx.env           - env var overrides (tests use this instead of mutating process.env).
+//   ctx.ownedElsewhere - override the excluded rule-id set (the hook passes its own).
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { loadRuleTable } from '../rule-table.mjs';
+import { CLASSIFIER_RULE_IDS } from '../intent-classifier.mjs';
+import { containsInjectedContent, isRuleEnabled } from '../intent-directive.mjs';
+import { defaultConfigRoot } from '../config-root.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, '..', '..', '..');
+
+/** This gate's id — unique across the registry. */
+export const GATE_ID = 'preflight-reminder';
+/** Runs at prompt submit, same as its UserPromptSubmit hook registration. */
+export const EVENT = 'prompt_submit';
+/** Caller-defined severity label; a prime injection, never a block. */
+export const SEVERITY = 'prime';
+
+/** The whole-gate kill switch (ported unchanged from the hook). */
+export const OFF_ENV = 'HEYSPEX_PREFLIGHT_REMINDER_OFF';
+/** The grounding-nudge-only kill switch (ported unchanged from the hook). */
+export const GROUNDING_OFF_ENV = 'HEYSPEX_GROUNDING_NUDGE_OFF';
+
+/** The registry surface the filing-intent prime rules are authored on. */
+export const USERPROMPT_PRIME_SURFACE = 'userpromptsubmit';
+
+/**
+ * The hook's OWN exclusion set: research-before-decision has its own dedicated dispatch
+ * (the unified intent-classifier-trigger.mjs router) that does extra workflow
+ * orchestration — exclude it so it never double-injects. The hook passes this set.
+ */
+export const PRIME_RULES_OWNED_ELSEWHERE = new Set(['research-before-decision']);
+
+/**
+ * The ENGINE's exclusion set (the default here): the hook's set, plus every intent rule
+ * ../intent-classifier.mjs fires on this same event, plus the always-on
+ * communication-style prime. See the header for why.
+ */
+export const ENGINE_PRIME_RULES_OWNED_ELSEWHERE = new Set([
+  ...PRIME_RULES_OWNED_ELSEWHERE,
+  ...CLASSIFIER_RULE_IDS,
+  'communication-style-prime',
+]);
+
+// Grounding-before-proposing nudge ([[HS-RES-2QX6]] / [[HS-EPIC-PLRV]]).
+// Deterministic context injection — the research's PRIMARY lever (F1): surface
+// prior decisions at the moment a design/planning request arrives, BEFORE the
+// agent proposes an approach or runs an AskUserQuestion menu around its own
+// abstraction (the HS-CAP-UIBF "three modes" failure). This is injected context,
+// not a block; it only points the agent at /hs-ground (which now searches
+// captures). Tuned for PRECISION over recall (a noisy nudge is worse than none —
+// F12): fires on imperative design/build/plan requests, NOT on questions about
+// existing work or on filing verbs (covered by the intent reminders above).
+export const DESIGN_INTENT_PATTERNS = [
+  // A — design/architecture verb acting directly on a thing (verb + determiner).
+  /\b(?:design|architect|re-?design|re-?architect|rework|reimplement|propose|structure|plan|model)\s+(?:a|an|the|our|this|how|out)\b/i,
+  // B — build/finish a design-noun, EXCLUDING the filing nouns (epic/task/
+  //     milestone) the intent reminders already handle.
+  /\b(?:build|implement|finish|create|introduce|spec|wire)\b[^.?!\n]{0,40}\b(?:feature|flow|system|capability|workflow|mechanism|surface|component|schema|gate|pipeline|integration|architecture|approach|modes?)\b/i,
+  // C — explicit approach-choosing questions.
+  /\b(?:how should (?:we|i)|what(?:'s| is) the best way to|which approach|what approach should)\b/i,
+];
+
+export const GROUNDING_REMINDER =
+  'Detected a design/planning request. Before you propose an approach or run an ' +
+  'AskUserQuestion menu to choose between options, run `/hs-ground` (it now ' +
+  'searches captures, epics, and research) to surface prior decisions and ' +
+  'existing vocabulary — the user is NOT the memory of record. If a related ' +
+  'capture/epic exists, reconcile with its terms instead of inventing your own. ' +
+  'Skip only for a trivial/mechanical change with no design choice. ' +
+  '(Mute: HEYSPEX_GROUNDING_NUDGE_OFF=1.)';
+
+/** Compile a rule's string patterns to case-insensitive RegExps; an uncompilable
+ *  pattern is skipped (fail-safe), never a throw. */
+function compilePatterns(rule) {
+  const patterns = rule && Array.isArray(rule.patterns) ? rule.patterns : [];
+  const compiled = [];
+  for (const p of patterns) {
+    try {
+      compiled.push(new RegExp(p, 'i'));
+    } catch {
+      // corrupt pattern — skip it.
+    }
+  }
+  return compiled;
+}
+
+/**
+ * Registry-driven filing-intent prime ([[HS-EPIC-ZGWR]] AC#6). Reads the userpromptsubmit
+ * `prime` rules from the engine rule table, matches the prompt against each rule's
+ * authored patterns, and returns the matched rules' inject text joined by a blank line.
+ * Honors each rule's config_key gate + ignore_injected_content, and skips rules owned by
+ * another gate/hook. Fail-safe: any error → null (no reminder, never throws).
+ *
+ * @param {string} prompt
+ * @param {string} [repoRoot] - where `.heyspex/guardrails.json` (the rule table) is read from.
+ * @param {{ ruleTable?: object, getSetting?: Function, ownedElsewhere?: Set<string>|string[],
+ *   configRoot?: string }} [opts] - `configRoot` is where `.heyspex/config.yaml` (each rule's
+ *   toggle) is read from; defaults to `repoRoot` so a self-contained fixture root — and the
+ *   hook-parity call that passes neither — keeps working as one unit. `run()` passes the
+ *   vault root explicitly.
+ * @returns {string|null}
+ */
+export function detectRegistryPrimeReminder(prompt, repoRoot = REPO_ROOT, opts = {}) {
+  if (typeof prompt !== 'string' || !prompt.trim()) return null;
+  const configRoot =
+    typeof opts.configRoot === 'string' && opts.configRoot.trim() ? opts.configRoot : repoRoot;
+  const owned = opts.ownedElsewhere instanceof Set
+    ? opts.ownedElsewhere
+    : new Set(Array.isArray(opts.ownedElsewhere) ? opts.ownedElsewhere : ENGINE_PRIME_RULES_OWNED_ELSEWHERE);
+  let rules;
+  try {
+    const table = opts.ruleTable ?? loadRuleTable({ vaultRoot: repoRoot });
+    rules = (Array.isArray(table?.rules) ? table.rules : []).filter(
+      (r) => r && Array.isArray(r.surfaces) && r.surfaces.includes(USERPROMPT_PRIME_SURFACE) && r.severity === 'prime',
+    );
+  } catch {
+    return null;
+  }
+  const parts = [];
+  for (const rule of rules) {
+    if (!rule.inject || owned.has(rule.rule)) continue;
+    if (!isRuleEnabled(rule, configRoot, opts)) continue;
+    if (rule.ignoreInjectedContent && containsInjectedContent(prompt)) continue;
+    const patterns = compilePatterns(rule);
+    if (patterns.length && patterns.some((re) => re.test(prompt))) {
+      parts.push(rule.inject);
+    }
+  }
+  return parts.length ? parts.join('\n\n') : null;
+}
+
+/** The grounding nudge: GROUNDING_REMINDER on a design/planning prompt, else null. */
+export function detectDesignIntent(prompt) {
+  if (typeof prompt !== 'string' || !prompt.trim()) return null;
+  return DESIGN_INTENT_PATTERNS.some((re) => re.test(prompt)) ? GROUNDING_REMINDER : null;
+}
+
+function resolveRoot(evt, ctx) {
+  for (const candidate of [ctx.repoRoot, ctx.vaultRoot, evt?.cwd]) {
+    if (typeof candidate === 'string' && candidate.trim()) return candidate.trim().replace(/[\\/]+$/, '');
+  }
+  const env = ctx.env ?? process.env;
+  const fromEnv = env.CLAUDE_PROJECT_DIR?.trim();
+  if (fromEnv) return fromEnv.replace(/[\\/]+$/, '');
+  return REPO_ROOT;
+}
+
+/**
+ * @param {{ point: string, prompt?: string, cwd?: string }} evt
+ * @param {{ repoRoot?: string, vaultRoot?: string, configRoot?: string, ruleTable?: object,
+ *   getSetting?: Function, env?: Record<string, string | undefined>,
+ *   ownedElsewhere?: Set<string>|string[] }} [ctx]
+ * @returns {{ decision: 'allow' }|{ decision: 'inject', reason: string,
+ *   inject: { additionalContext: string, severity: string } }}
+ */
+export function run(evt, ctx = {}) {
+  const env = ctx.env ?? process.env;
+  if (String(env[OFF_ENV] ?? '') === '1') return { decision: 'allow' };
+
+  const prompt = evt?.prompt;
+  if (typeof prompt !== 'string' || !prompt.trim()) return { decision: 'allow' };
+
+  const root = resolveRoot(evt, ctx);
+  // Only a ctx-supplied root is a fixture; the event's cwd / CLAUDE_PROJECT_DIR are the live
+  // app checkout and never decide where the settings file is read from.
+  const fixtureRoot = [ctx.repoRoot, ctx.vaultRoot].some((c) => typeof c === 'string' && c.trim());
+  const configRoot = ctx.configRoot ?? (fixtureRoot ? root : defaultConfigRoot());
+
+  // Combined into ONE injection — the filing-intent reminder and the grounding nudge are
+  // independent and can co-fire, exactly as the hook joins them into one emit.
+  const parts = [];
+  const reasons = [];
+  const intentReminder = detectRegistryPrimeReminder(prompt, root, {
+    ruleTable: ctx.ruleTable,
+    getSetting: ctx.getSetting,
+    ownedElsewhere: ctx.ownedElsewhere,
+    configRoot,
+  });
+  if (intentReminder) {
+    parts.push(intentReminder);
+    reasons.push('filing intent');
+  }
+  if (String(env[GROUNDING_OFF_ENV] ?? '') !== '1') {
+    const grounding = detectDesignIntent(prompt);
+    if (grounding) {
+      parts.push(grounding);
+      reasons.push('design/planning request');
+    }
+  }
+  if (!parts.length) return { decision: 'allow' };
+
+  return {
+    decision: 'inject',
+    reason: `preflight-reminder: ${reasons.join(' + ')}`,
+    inject: { additionalContext: parts.join('\n\n'), severity: SEVERITY },
+  };
+}
+
+const gate = { id: GATE_ID, event: EVENT, severity: SEVERITY, run };
+export default gate;

package/spexharness/src/gates/research-protocol-gate.mjs

@@ -0,0 +1,175 @@
+// spexharness/src/gates/research-protocol-gate.mjs
+//
+// [[HS-K0ZP]] — the research-capture-protocol proof-of-use gate.
+//
+// THE HOLE THIS CLOSES: research-capture-protocol was enforced as prose. The
+// only machine on the research path was ./deep-research-cost-gate.mjs, which
+// sees Workflow/Skill launches and nothing else — its own protocol text named
+// the bare WebSearch/WebFetch path as "out of reach". On 2026-09-11 an agent
+// asked to verify one claim ran native WebSearch + WebFetch and then filed a
+// full research doc through heyspex_save_research: no method triage (this was
+// a known-target retrieval that should never have entered the research-doc
+// pipeline), no ground-first, no offer-before-save. Nothing refused any of
+// the three calls because nothing was looking at them.
+//
+// WHAT IT DECIDES: a `before_tool` event for WebSearch, WebFetch or
+// heyspex_save_research (bare or MCP-prefixed) is DENIED unless the session
+// holds a current preflight proof-of-use marker for one of
+// RESEARCH_PROTOCOL_INTENTS (`research`, `file_research`, `promote_research`
+// — vendor/heyspex-mcp/preflight-gate.mjs, the same store the MCP server's
+// own PREFLIGHT_NOT_RUN refusals read). heyspex_preflight({ intent:
+// "research" }) writes that marker; so does heyspex_get_procedure on the
+// protocol itself (procedure-handlers.mjs). Every other tool is allowed —
+// this gate never speaks for anything but those three names.
+//
+// WHY A DENY, NOT A PRIME: the owner's ruling on the incident, verbatim —
+// "HeySpex plugin needs to make it impossible for you to break the rule.
+// User permissions is the only way to break the rule." A prime is text the
+// model can read and skip, which is exactly what failed. So: deny by default,
+// the reason names the one call that unlocks it, and the ONLY bypass is the
+// owner setting HEYSPEX_RESEARCH_PROTOCOL_GATE_OFF=1 in their own environment
+// — an env var, never a file (.heyspex/mode.json and config.yaml are
+// agent-writable; scripts/claude-hooks/_run.mjs lists this gate ALWAYS_ON so
+// the mode file cannot silence it either). The agent has no lever here.
+//
+// WHERE IT RUNS: registered in ./index.mjs's PORTED_GATES (every engine front
+// — SpexCode seats, hs chat, overnight runs) and shelled to Claude Code by
+// scripts/claude-hooks/research-protocol-gate.mjs (generated) on the matcher
+// `WebSearch|WebFetch|mcp__heyspex__heyspex_save_research|
+// mcp__plugin_heyspex_heyspex__heyspex_save_research`, and to Cursor through
+// scripts/cursor-hooks/_run.mjs's --hs-tool matcher.
+//
+// MARKER ROOTS: preflight markers live under the VAULT root
+// (`<vault>/.heyspex/preflight/`). A hook process only knows
+// CLAUDE_PROJECT_DIR (the code checkout), so the gate looks in BOTH the
+// project root and the vault the MCP resolver names (vault-resolve.mjs —
+// the same 5-tier resolver the server used when it wrote the marker). On a
+// single-checkout install the two are one directory.
+//
+// `ctx` contract (all optional):
+//   ctx.env          - env var overrides (falls back to process.env).
+//   ctx.cwd          - project root (defaults to CLAUDE_PROJECT_DIR, else
+//                      this repo's root).
+//   ctx.vaultRoot    - when given, the ONLY marker root searched (tests).
+//   ctx.readMarkers  - (root, intent, sessionId) => marker[] override
+//                      (defaults to preflight-gate.mjs's readPreflightMarkers).
+//   ctx.now          - clock for the session-less TTL fallback (tests).
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  RESEARCH_PROTOCOL_GATE_OFF_ENV,
+  RESEARCH_PROTOCOL_INTENTS,
+  isMarkerCurrent,
+  readPreflightMarkers,
+} from '../../../vendor/heyspex-mcp/preflight-gate.mjs';
+import { getActiveConfig } from '../../../vendor/heyspex-mcp/vault-resolve.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, '..', '..', '..');
+
+/** The gate's id — unique across the registry; also its Claude Code hook name. */
+export const id = 'research-protocol-gate';
+/** Runs pre-tool: a PreToolUse hook in Claude Code, before_tool in the engine. */
+export const event = 'before_tool';
+/** Denies, so "block". */
+export const severity = 'block';
+
+/** The exact env var the deny reason names — exported so tests and docs cannot drift from it. */
+export const OFF_ENV = RESEARCH_PROTOCOL_GATE_OFF_ENV;
+
+/** The call the deny reason names as the unlock — one string, quoted everywhere it appears. */
+export const UNLOCK_CALL = 'heyspex_preflight({ intent: "research" })';
+
+/**
+ * Is this tool one of the three the protocol governs? Bare names are what the
+ * engine and Claude Code's native tools use; the two MCP prefixes are the
+ * project-scoped and plugin-scoped spellings of the same HeySpex tool.
+ *
+ * @param {unknown} toolName
+ * @returns {boolean}
+ */
+export function isResearchTool(toolName) {
+  if (typeof toolName !== 'string') return false;
+  const name = toolName.trim();
+  if (name === 'WebSearch' || name === 'WebFetch') return true;
+  return /(^|__)heyspex_save_research$/.test(name);
+}
+
+/**
+ * The deny reason. Kept as a function of the tool name only, so the golden
+ * fixtures pin its exact text and a reworded reason is a deliberate edit here.
+ *
+ * @param {string} toolName
+ * @returns {string}
+ */
+export function denyReason(toolName) {
+  return (
+    `Research blocked: ${toolName} was called before research-capture-protocol was consulted this session. ` +
+    `Call ${UNLOCK_CALL} first — it returns the protocol's method triage (known-target-retrieval vs the confidence ladder), ` +
+    `the ground-first rule (heyspex_recall_memories + /hs-ground) and the offer-before-save step — read it, then retry this exact call. ` +
+    `Reading the protocol directly with heyspex_get_procedure({ name: "research-capture-protocol" }) also counts. ` +
+    `This gate is deterministic and is not the agent's to bypass: only the owner can lift it, by setting ${OFF_ENV}=1 in their own environment.`
+  );
+}
+
+function resolvedVaultRoot() {
+  try {
+    const { repoRootAbs } = getActiveConfig();
+    return typeof repoRootAbs === 'string' && repoRootAbs ? repoRootAbs : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The marker roots to search, in order, de-duplicated. `ctx.vaultRoot` pins a
+ * single root (tests, and any front that already knows its vault); otherwise
+ * the project root first, then the resolver's vault.
+ */
+function markerRoots(ctx) {
+  if (typeof ctx.vaultRoot === 'string' && ctx.vaultRoot) return [ctx.vaultRoot];
+  const roots = [ctx.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? REPO_ROOT, resolvedVaultRoot()];
+  const seen = new Set();
+  return roots.filter((r) => {
+    if (typeof r !== 'string' || !r) return false;
+    const key = path.resolve(r);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+/**
+ * @param {{ point: string, sessionId?: string, toolName?: string, toolInput?: Record<string, unknown> }} evt
+ * @param {{ env?: Record<string, string|undefined>, cwd?: string, vaultRoot?: string,
+ *            readMarkers?: (root: string, intent: string, sessionId?: string) => object[],
+ *            now?: number }} [ctx]
+ * @returns {{ decision: 'allow'|'deny', reason?: string }}
+ */
+export function run(evt, ctx = {}) {
+  const env = ctx.env ?? process.env;
+  if (String(env[OFF_ENV] ?? '') === '1') return { decision: 'allow' };
+
+  const toolName = evt?.toolName;
+  if (!isResearchTool(toolName)) return { decision: 'allow' };
+
+  const read = ctx.readMarkers ?? readPreflightMarkers;
+  const now = ctx.now ?? Date.now();
+  const sessionId = evt?.sessionId;
+  for (const root of markerRoots(ctx)) {
+    for (const intent of RESEARCH_PROTOCOL_INTENTS) {
+      let markers = [];
+      try {
+        markers = read(root, intent, sessionId) ?? [];
+      } catch {
+        markers = []; // an unreadable root proves nothing either way
+      }
+      if (markers.some((m) => isMarkerCurrent(m, sessionId, now))) return { decision: 'allow' };
+    }
+  }
+  return { decision: 'deny', reason: denyReason(String(toolName).trim()) };
+}
+
+export default { id, event, severity, run };

package/spexharness/src/gates/settings-write-gate.decide.mjs

@@ -0,0 +1,96 @@
+// spexharness/src/gates/settings-write-gate.decide.mjs
+//
+// Pure decision logic relocated from scripts/claude-hooks/settings-write-gate.mjs
+// (HS-IQBF, per PORTING.md's "move the pure decision logic into the gate
+// module itself or a sibling pure module"). The original hook's `decide()`
+// had NO isDirectExecution guard around its own module-level `main()`, which
+// is why ./settings-write-gate.mjs (the gate) used to import it lazily with
+// an env-var dance to dodge a stdin hang on static import (see that gate
+// module's git history / PORTING.md for the story). Relocating the pure
+// function here removes the hazard entirely: this file has no main() at all,
+// so a plain static top-level import is always safe. No stdin/stdout/
+// process.exit anywhere in this file.
+
+const CONFIG_FILE_RE = /(?:^|[\\/])\.heyspex[\\/]config\.ya?ml$/i;
+
+/** Conservative shell write-target scanner (same approach as env-vault-guard.mjs). */
+function extractShellTargets(command) {
+  if (!command || typeof command !== 'string') return [];
+  const targets = new Set();
+  const redirectRe = /(?:>>?|\|\s*tee(?:\s+-a)?)\s+("([^"]+)"|'([^']+)'|(\S+))/g;
+  for (const m of command.matchAll(redirectRe)) targets.add(m[2] ?? m[3] ?? m[4]);
+  const cmdRe =
+    /\b(?:mv|cp|touch|install|rename|tee|rm|del|Remove-Item|Move-Item|Copy-Item|New-Item|Set-Content|Out-File|Add-Content|Clear-Content|sed)\s+([^|;&\n]+)/g;
+  for (const m of command.matchAll(cmdRe)) {
+    const head = m[0].split(/\s/)[0];
+    const args = m[1]
+      .trim()
+      .split(/\s+/)
+      .filter((a) => a && !a.startsWith('-'));
+    if (args.length === 0) continue;
+    if (/^(?:mv|cp|install|rename|Move-Item|Copy-Item)$/.test(head)) {
+      targets.add(args[args.length - 1]);
+    } else {
+      for (const a of args) targets.add(a);
+    }
+  }
+  return [...targets]
+    .map((t) => t.replace(/^['"]|['"]$/g, ''))
+    .filter(Boolean)
+    .filter((t) => !/[$`(){}]/.test(t));
+}
+
+/**
+ * Pure gate decision. Returns null (pass through) or
+ * { ask: true, reason } — the harness then asks the USER for permission.
+ */
+export function decide(toolName, toolInput) {
+  // The MCP settings-write tool: gate ONLY the applying call (confirm_token given).
+  if (toolName === 'mcp__heyspex__heyspex_settings_set') {
+    const token = toolInput?.confirm_token;
+    if (typeof token === 'string' && token.trim()) {
+      return {
+        ask: true,
+        reason:
+          'Applying a HeySpex settings change (heyspex_settings_set with confirm_token). Settings writes ' +
+          'always require explicit user permission (agent-settings-protocol) — approve only if you asked for ' +
+          'this exact change.',
+      };
+    }
+    return null; // request step writes nothing
+  }
+
+  // Direct file writes to .heyspex/config.yaml.
+  if (toolName === 'Write' || toolName === 'Edit' || toolName === 'NotebookEdit') {
+    const filePath = String(toolInput?.file_path ?? toolInput?.notebook_path ?? '');
+    if (filePath && CONFIG_FILE_RE.test(filePath)) {
+      return {
+        ask: true,
+        reason:
+          `.heyspex/config.yaml is the settings control surface — agent writes require explicit user ` +
+          `permission (agent-settings-protocol), regardless of ask_forgiveness_not_permission. Approve only ` +
+          `if you asked for this change; the sanctioned agent path is heyspex_settings_set (two-step confirm) ` +
+          `or \`hs settings set ... --confirmed-by-user\`.`,
+      };
+    }
+    return null;
+  }
+
+  // Shell writes targeting the config file.
+  if (toolName === 'Bash' || toolName === 'PowerShell') {
+    for (const target of extractShellTargets(String(toolInput?.command ?? ''))) {
+      if (CONFIG_FILE_RE.test(target)) {
+        return {
+          ask: true,
+          reason:
+            'This shell command writes to .heyspex/config.yaml — the settings control surface. Settings ' +
+            'writes require explicit user permission (agent-settings-protocol). Approve only if you asked ' +
+            'for this change; prefer `hs settings set` or heyspex_settings_set.',
+        };
+      }
+    }
+    return null;
+  }
+
+  return null;
+}

package/spexharness/src/gates/settings-write-gate.mjs

@@ -0,0 +1,104 @@
+// spexharness/src/gates/settings-write-gate.mjs
+//
+// Engine port of scripts/claude-hooks/settings-write-gate.mjs — the
+// PreToolUse gate that asks the user's explicit permission before any agent
+// path writes .heyspex/config.yaml (the settings control surface;
+// agent-settings-protocol). See ./PORTING.md for the recipe this follows and
+// ./env-vault-guard.mjs for the reference port.
+//
+// This module does NOT reimplement the guard's decision logic. It imports
+// `decide(toolName, toolInput)` from ./settings-write-gate.decide.mjs — the
+// pure function relocated out of the original hook script (HS-IQBF; see
+// PORTING.md and that sibling module's own header for why) — and adapts it
+// to the engine's `{ id, event, severity, run(event, ctx) }` gate shape:
+//   - `event` (spexharness/src/events.mjs `before_tool`) → the legacy
+//     `(toolName, toolInput)` args `decide()` already expects.
+//   - the legacy `null | { ask: true, reason }` verdict → the engine's
+//     `{ decision: 'allow' | 'rewrite', reason?, rewrite? }` shape.
+//
+// The relocation also retires an old IMPORT HAZARD: the ORIGINAL hook
+// script's `main()` used to run unconditionally at module-evaluation time
+// (no isDirectExecution guard), so a plain static `import` of it hung any
+// process that imported it with an open, not-yet-closed stdin. This module
+// used to work around that with a lazily-imported, env-var-gated dynamic
+// import. Now that the pure `decide()` lives in a sibling module with no
+// main() of its own, that hazard no longer exists — a plain static
+// top-level import is always safe, same as every other gate in this set.
+//
+// Decision mapping (a documented judgment call, the same shape as
+// env-vault-guard.mjs's "ask" → rewrite mapping): the legacy verdict is
+// either `null` (no opinion → allow) or `{ ask: true, reason }` (the harness
+// should show the user a synchronous permission prompt). The engine's
+// decide.mjs has no synchronous-approval primitive, so `ask` is carried
+// forward as a `rewrite` envelope tagging `ask: true` — never silently
+// downgraded to an auto-allow (unsafe: skips the required permission
+// prompt) or upgraded to an auto-deny (a real behavior change; the original
+// never hard-denies a settings write, it only asks). A calling front decides
+// what `rewrite.ask` means for it.
+//
+// This gate never hard-denies (matching the original) — "deny" coverage for
+// AC3 ("allow, deny and rewrite each covered by at least one test per gate",
+// checked as one combined `node --test` run across all three ported gates in
+// this task) comes from the sibling enforce-session-sequence gate, which is
+// the only one of the three that can actually block a turn. See
+// ./enforce-session-sequence.test.mjs.
+//
+// Env hatch (unchanged): HEYSPEX_SETTINGS_GATE_OFF=1.
+// Config toggle (unchanged, full parity with the original's own opt-out, in
+// addition to the env hatch): agent_behaviors.settings_write_guard.enabled
+// (default ON; an explicit `false` in .heyspex/config.yaml silences the
+// gate) — read via the same dependency-free `_guardrail-loader.mjs` the
+// original imports.
+//
+// `ctx` contract (all optional):
+//   ctx.cwd        - a self-contained fixture root: when given, the config-toggle
+//                    read resolves from it (tests build a temp root carrying its
+//                    own .heyspex/config.yaml and pass it here).
+//   ctx.configRoot - the directory holding `.heyspex/config.yaml`; wins over
+//                    ctx.cwd for the toggle read. With neither, the VAULT root
+//                    (../config-root.mjs `defaultConfigRoot()`) — never
+//                    CLAUDE_PROJECT_DIR, which under Claude Code is the app
+//                    checkout, not where the settings file lives
+//                    ([[HS-4C76-9W86-DIAG-heyspex-config-yaml-has-no-single-home]]).
+//   ctx.env        - env var overrides (tests use this instead of mutating
+//                    process.env).
+
+import { isConfigKeyEnabled } from '../../../scripts/claude-hooks/_guardrail-loader.mjs';
+import { defaultConfigRoot } from '../config-root.mjs';
+import { decide as legacyDecide } from './settings-write-gate.decide.mjs';
+
+const TOGGLE_KEY = 'agent_behaviors.settings_write_guard.enabled';
+const OFF_ENV = 'HEYSPEX_SETTINGS_GATE_OFF';
+
+/** The settings-write gate's id — unique across the built-in registry. */
+export const id = 'settings-write-gate';
+/** Runs pre-tool, same as its PreToolUse Claude Code hook registration. */
+export const event = 'before_tool';
+/** Caller-defined severity label; this gate only ever asks (rewrites) or allows. */
+export const severity = 'ask';
+
+/**
+ * @param {{ point: string, toolName?: string, toolInput?: Record<string, unknown> }} evt
+ * @param {{ cwd?: string, configRoot?: string, env?: Record<string, string | undefined> }} [ctx]
+ * @returns {{ decision: 'allow'|'rewrite', reason?: string, rewrite?: object }}
+ */
+export function run(evt, ctx = {}) {
+  const env = ctx.env ?? process.env;
+  if (String(env[OFF_ENV] ?? '') === '1') return { decision: 'allow' };
+
+  // The ONLY root this gate reads is the config root — see the ctx contract above.
+  const configRoot = ctx.configRoot ?? (ctx.cwd ? ctx.cwd : defaultConfigRoot());
+  if (!isConfigKeyEnabled(TOGGLE_KEY, configRoot)) return { decision: 'allow' };
+
+  const verdict = legacyDecide(evt?.toolName, evt?.toolInput ?? {});
+
+  if (!verdict || !verdict.ask) return { decision: 'allow' };
+
+  return {
+    decision: 'rewrite',
+    reason: verdict.reason,
+    rewrite: { ask: true, reason: verdict.reason },
+  };
+}
+
+export default { id, event, severity, run };