heyspex 0.2.0 → 0.2.2

package/spexharness/src/gates/directive-obligation-gate.decide.mjs

@@ -0,0 +1,132 @@
+// spexharness/src/gates/directive-obligation-gate.decide.mjs
+//
+// Pure decision logic for the directive-obligation-gate ([[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]]).
+// No stdin/stdout/process.exit and no fs: every input arrives as an argument, so the gate module
+// (./directive-obligation-gate.mjs) owns all I/O and a test drives these functions directly.
+
+import { extractShellTargets } from './_shell-write-targets.mjs';
+import { isProductCodePath } from '../../../scripts/lib/directive-obligations.mjs';
+
+const WRITE_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'write_file', 'edit_file']);
+const SHELL_TOOLS = new Set(['Bash', 'PowerShell', 'Shell']);
+const SPAWN_TOOLS = new Set(['Agent', 'Task']);
+
+/** Sub-agent types that only read / plan / triage: spawning one never builds anything. */
+export const READ_ONLY_AGENT_TYPES = new Set([
+  'explore',
+  'plan',
+  'claude-code-guide',
+  'capture-triager',
+  'plan-grounder',
+  'research-synthesizer',
+  'resolution-triager',
+  'statusline-setup',
+]);
+
+// Commands that build, install, serve or publish product code. Test runners are deliberately absent.
+const BUILD_CMD_RE = new RegExp(
+  '(?:^|[\\s;&|(])(?:' +
+    '(?:npm|pnpm|yarn|bun)\\s+(?:run\\s+)?(?:build|dev|start|install|i|add|ci|publish|deploy)\\b' +
+    '|(?:npx\\s+)?(?:next|vite|webpack|turbo|esbuild)\\s+(?:build|dev)\\b' +
+    '|dotnet\\s+(?:build|publish|run)\\b' +
+    '|cargo\\s+(?:build|run|install)\\b' +
+    '|make\\b' +
+    '|vercel\\s+(?:deploy|--prod)\\b' +
+    '|(?:claude|spexcode)\\s+(?:-p|--print)\\b' +
+    ')',
+  'i',
+);
+
+/** Is this a heyspex_* MCP call (any spelling)? Those are never gated. */
+export function isHeyspexMcpTool(name) {
+  return /(?:^|__)heyspex_/.test(String(name ?? ''));
+}
+
+function pathOf(toolInput) {
+  return toolInput?.file_path ?? toolInput?.notebook_path ?? toolInput?.path ?? toolInput?.filePath ?? '';
+}
+
+/**
+ * Classify one tool call into the surface this gate cares about.
+ * @returns {{ kind: 'exempt'|'spawn'|'code_write'|'shell_build'|'shell_write', detail?: string }}
+ */
+export function classifyToolCall({ toolName, toolInput }, { cwd, vaultRoot } = {}) {
+  const name = String(toolName ?? '');
+  if (!name || isHeyspexMcpTool(name)) return { kind: 'exempt' };
+  const input = toolInput ?? {};
+
+  if (SPAWN_TOOLS.has(name)) {
+    const type = String(input.subagent_type ?? '').trim().toLowerCase();
+    if (type && READ_ONLY_AGENT_TYPES.has(type)) return { kind: 'exempt' };
+    return { kind: 'spawn', detail: type || 'general-purpose' };
+  }
+
+  if (WRITE_TOOLS.has(name)) {
+    const target = pathOf(input);
+    return isProductCodePath(target, { cwd, vaultRoot }) ? { kind: 'code_write', detail: String(target) } : { kind: 'exempt' };
+  }
+
+  if (SHELL_TOOLS.has(name)) {
+    const command = String(input.command ?? '');
+    const product = extractShellTargets(command).find((t) => isProductCodePath(t, { cwd, vaultRoot }));
+    if (product) return { kind: 'shell_write', detail: product };
+    if (BUILD_CMD_RE.test(command)) return { kind: 'shell_build', detail: command.trim().slice(0, 80) };
+    return { kind: 'exempt' };
+  }
+
+  return { kind: 'exempt' };
+}
+
+const HOW_TO_DISCHARGE =
+  'Capture the owner\'s words first: call heyspex_update_capture (or heyspex_file_spec / the /hs-capture skill) with their exact ' +
+  'message, then retry. Reads, greps, git, test runs, vault and .heyspex writes and every heyspex_* tool stay open meanwhile.';
+
+/**
+ * Rule 1: while a capture obligation is outstanding for this session, deny a sub-agent spawn, a
+ * product-code write and a build/product-write shell command.
+ * @returns {{ deny: boolean, reason?: string, rule?: string }}
+ */
+export function decideObligation(call, { outstandingCount, cwd, vaultRoot }) {
+  if (!outstandingCount) return { deny: false };
+  const c = classifyToolCall(call, { cwd, vaultRoot });
+  if (c.kind === 'exempt') return { deny: false };
+  const what =
+    c.kind === 'spawn' ? `spawn a ${c.detail} sub-agent`
+    : c.kind === 'code_write' ? `write product code (${c.detail})`
+    : c.kind === 'shell_write' ? `write product code from the shell (${c.detail})`
+    : `run a build command (${c.detail})`;
+  return {
+    deny: true,
+    rule: 'directive-obligation',
+    reason:
+      `HEYSPEX directive-obligation-gate: the capture_on_idea directive was issued for this session and the capture has not happened, so you may not ${what}. ` +
+      `${HOW_TO_DISCHARGE} (Break-glass, owner only: HEYSPEX_DIRECTIVE_OBLIGATION_GATE_OFF=1. [[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]])`,
+  };
+}
+
+/**
+ * Rule 2 (claim-before-build): deny a build sub-agent spawn or a product-code write when the session
+ * has no claimed spec, no on-deck capture and no waiver. Independent of the plan-exit marker and CLAUDE_AGENT.
+ */
+export function decideClaimBeforeBuild(call, { hasRoadToCode, cwd, vaultRoot }) {
+  if (hasRoadToCode) return { deny: false };
+  const c = classifyToolCall(call, { cwd, vaultRoot });
+  if (c.kind !== 'spawn' && c.kind !== 'code_write') return { deny: false };
+  const what = c.kind === 'spawn' ? `spawn a ${c.detail} sub-agent` : `edit product code (${c.detail})`;
+  return {
+    deny: true,
+    rule: 'claim-before-build',
+    reason:
+      `HEYSPEX claim-before-build: this session holds no claimed spec (claim heartbeat confirmed), has no capture on deck and no waiver, so you may not ${what}. ` +
+      'Claim the spec you are building (heyspex_claim_spec) or capture the idea (heyspex_update_capture / /hs-capture), then retry. ' +
+      '(Break-glass, owner only: HEYSPEX_DIRECTIVE_OBLIGATION_GATE_OFF=1. [[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]])',
+  };
+}
+
+export function stopReason(count) {
+  return (
+    `HEYSPEX directive-obligation-gate: you are about to stop with ${count} capture obligation(s) unmet - the capture_on_idea directive ` +
+    'was issued this session and no capture write was seen. Capture the owner\'s words now (heyspex_update_capture with their exact message, ' +
+    'or /hs-capture), then finish. This re-drive fires once; it will not block again. [[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]]'
+  );
+}

package/spexharness/src/gates/directive-obligation-gate.mjs

@@ -0,0 +1,183 @@
+// spexharness/src/gates/directive-obligation-gate.mjs
+//
+// [[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]]. The capture_on_idea directive is advisory
+// text; nothing recorded "a directive was issued and still owes a capture", so a model that skipped the
+// capture met no gate (every capture gate keys on a capture that exists). This gate turns that unmet
+// obligation into a deny. State: `.heyspex/directive-obligations.json` (../../../scripts/lib/directive-obligations.mjs),
+// ARMED by the UserPromptSubmit verbatim stage (scripts/lib/capture-verbatim-append.mjs).
+//
+// ONE hook script, THREE Claude Code events (the coo-guard-gate / git-reflog-audit multi-event form):
+//   PreToolUse  (before_tool)  Agent|Task|Edit|Write|MultiEdit|NotebookEdit|Bash|PowerShell
+//     rule 1 `directive-obligation`: deny a sub-agent spawn, a product-code write and a build / product-write
+//            shell command while THIS session has an unsatisfied, unwaived, unexpired capture obligation.
+//     rule 2 `claim-before-build`: deny a build sub-agent spawn or a product-code Edit/Write when the session
+//            has no claimed spec, no on-deck capture and no waiver - independent of the plan-exit marker
+//            (claim-before-code-gate) and of CLAUDE_AGENT.
+//   PostToolUse (after_tool)   discharges the obligation on heyspex_update_capture / heyspex_promote_capture* /
+//            heyspex_file_spec / the hs-capture Skill (suffix match: bare and mcp__*__ spellings), and tracks
+//            heyspex_claim_spec / release_spec for rule 2. Never denies.
+//   Stop        (stop)         blocks ONCE with a re-drive reason while the obligation is unmet, stamps
+//            `stop_blocked_at`, then never loops (and honours stop_hook_active).
+//
+// Always allowed: Read / Grep / Glob, git, test runs, writes under the vault container / vault root / .heyspex /
+// .claude, and every heyspex_* MCP call.
+//
+// Event mapping: PreToolUse -> before_tool (tool_name -> toolName, tool_input -> toolInput); PostToolUse ->
+// after_tool (+ tool_response -> toolResult); Stop -> stop. Decision mapping: deny -> permissionDecision deny
+// (before_tool) or { decision: "block", reason } (stop); everything else allow. No `rewrite`/`ask` rung: a
+// directive that can be ignored is exactly the failure this gate exists to remove.
+//
+// FAIL OPEN: no session id, an unreadable / foreign-session state file, any thrown error -> allow.
+// Kill switches: env HEYSPEX_DIRECTIVE_OBLIGATION_GATE_OFF=1; config agent_behaviors.directive_obligation_gate.enabled
+// (false = off; read from the VAULT root, PORTING.md section 3); config agent_behaviors.directive_obligation_gate.claim_before_build.enabled: false
+// turns off rule 2 only. HEYSPEX_MODE=off mutes it (this gate is NOT always-on; scripts/claude-hooks/_run.mjs also skips it).
+//
+// GitHub Copilot (owner scope change 2026-10-16: must be Copilot-compatible, [[HS-0GBS-CTF8-RES-copilot-plugin-parity-with-the-spexcode]]):
+// every decision lives in ./directive-obligation-gate.decide.mjs over a harness-agnostic shape (toolName, toolInput,
+// sessionId, cwd); this module never builds a Claude `hookSpecificOutput` (the adapter shapes output); ANY missing or
+// malformed field fails OPEN. The Copilot adapter + hook rows follow once the Copilot hook contract is pinned.
+// Cursor: scripts/cursor-hooks/manifest.mjs.
+//
+// `ctx` (all optional): env, cwd (project root for the state files; default CLAUDE_PROJECT_DIR, else this checkout),
+// configRoot, vaultRoot, sessionId, now, configEnabled (false = off), claimRuleEnabled (false = rule 2 off).
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { defaultConfigRoot } from '../config-root.mjs';
+import { hasFreshNoClaimSignal } from '../../../scripts/claude-hooks/claim-liveness-shared.mjs';
+import { isConfigKeyEnabled } from '../../../scripts/claude-hooks/_guardrail-loader.mjs';
+import {
+  CLAIM_RULE_CONFIG_KEY,
+  GATE_CONFIG_KEY,
+  GATE_OFF_ENV,
+  hasRoadToCode,
+  sessionHoldsClaimOnDisk,
+  isClaimAcquireTool,
+  isClaimReleaseTool,
+  isSatisfyingTool,
+  markStopBlocked,
+  outstanding,
+  readObligations,
+  satisfyAll,
+  toolResultFailed,
+  trackClaim,
+} from '../../../scripts/lib/directive-obligations.mjs';
+import { classifyToolCall, decideClaimBeforeBuild, decideObligation, stopReason } from './directive-obligation-gate.decide.mjs';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+
+export const id = 'directive-obligation-gate';
+export const event = 'before_tool';
+export const severity = 'block';
+
+function projectRoot(ctx) {
+  if (ctx.cwd) return ctx.cwd;
+  const fromEnv = process.env.CLAUDE_PROJECT_DIR?.trim();
+  if (fromEnv) return fromEnv.replace(/[\\/]+$/, '');
+  // Installed from npm (node_modules/heyspex) with no CLAUDE_PROJECT_DIR (GitHub Copilot sets none): this
+  // checkout is the PACKAGE, not the project. The hook process runs with cwd = the repo.
+  if (/[\\/]node_modules[\\/]/.test(REPO_ROOT + path.sep)) return process.cwd();
+  return REPO_ROOT;
+}
+
+function enabled(ctx, key, override) {
+  if (override === false) return false;
+  try {
+    const configRoot = ctx.configRoot ?? (ctx.cwd ? ctx.cwd : defaultConfigRoot());
+    return isConfigKeyEnabled(key, configRoot);
+  } catch {
+    return true;
+  }
+}
+
+function claimedSpecId(toolInput) {
+  const v = toolInput?.spec_id ?? toolInput?.specId ?? toolInput?.id;
+  return typeof v === 'string' && v.trim() ? v.trim() : '*';
+}
+
+/**
+ * Rule 2 denies only on POSITIVE evidence of no claim (a fresh `noClaimUntil` heartbeat for this session).
+ * When a gated call is let through only because that evidence is absent (missing / stale cache, cloud claims),
+ * say so on stderr so the fail-open is visible. Never throws.
+ */
+function noteFailOpen(call, { root, sessionId, vaultRoot, env, stderr }) {
+  try {
+    const kind = classifyToolCall(call, { cwd: root, vaultRoot }).kind;
+    if (kind !== 'spawn' && kind !== 'code_write') return;
+    if (hasFreshNoClaimSignal(sessionId, root) || sessionHoldsClaimOnDisk(root, sessionId, env)) return;
+    (stderr ?? ((m) => process.stderr.write(m)))('HEYSPEX claim-before-build: claim liveness unconfirmed for this session; failing open (allow).\n');
+  } catch {
+    /* never throw */
+  }
+}
+
+/**
+ * @param {{ point?: string, toolName?: string, toolInput?: object, toolResult?: object, sessionId?: string, stopHookActive?: boolean }} evt
+ * @param {object} [ctx]
+ * @returns {{ decision: 'allow'|'deny', reason?: string, rule?: string }}
+ */
+export function run(evt, ctx = {}) {
+  try {
+    const env = ctx.env ?? process.env;
+    if (String(env[GATE_OFF_ENV] ?? '') === '1') return { decision: 'allow' };
+    if (String(env.HEYSPEX_MODE ?? '').trim().toLowerCase() === 'off') return { decision: 'allow' };
+    const sessionId = String(evt?.sessionId ?? ctx.sessionId ?? '').trim();
+    if (!sessionId) return { decision: 'allow' };
+    if (!enabled(ctx, GATE_CONFIG_KEY, ctx.configEnabled)) return { decision: 'allow' };
+
+    const root = projectRoot(ctx);
+    const now = ctx.now ?? Date.now();
+    const point = evt?.point;
+
+    if (point === 'after_tool') {
+      const name = String(evt?.toolName ?? '');
+      if (isSatisfyingTool(name, evt?.toolInput) && !toolResultFailed(evt?.toolResult)) {
+        satisfyAll({ root, sessionId, now });
+      } else if (isClaimAcquireTool(name) && !toolResultFailed(evt?.toolResult)) {
+        trackClaim({ root, sessionId, specId: claimedSpecId(evt?.toolInput) });
+      } else if (isClaimReleaseTool(name) && !toolResultFailed(evt?.toolResult)) {
+        trackClaim({ root, sessionId, specId: claimedSpecId(evt?.toolInput), release: true });
+      }
+      return { decision: 'allow' };
+    }
+
+    const state = readObligations(root, sessionId);
+    const open = outstanding(state, sessionId, now);
+
+    if (point === 'stop') {
+      if (evt?.stopHookActive === true) return { decision: 'allow' };
+      const unspent = open.filter((o) => !o.stop_blocked_at);
+      if (!unspent.length) return { decision: 'allow' };
+      markStopBlocked({ root, sessionId, now });
+      return { decision: 'deny', rule: 'directive-obligation', reason: stopReason(unspent.length) };
+    }
+
+    if (point !== 'before_tool') return { decision: 'allow' };
+
+    const call = { toolName: evt?.toolName, toolInput: evt?.toolInput ?? {} };
+    const vaultRoot = ctx.vaultRoot ?? defaultConfigRoot();
+
+    const v1 = decideObligation(call, { outstandingCount: open.length, cwd: root, vaultRoot });
+    if (v1.deny) return { decision: 'deny', reason: v1.reason, rule: v1.rule };
+
+    if (enabled(ctx, CLAIM_RULE_CONFIG_KEY, ctx.claimRuleEnabled)) {
+      const road = hasRoadToCode({ root, sessionId, state, now, env });
+      const v2 = decideClaimBeforeBuild(call, { hasRoadToCode: road, cwd: root, vaultRoot });
+      if (v2.deny) return { decision: 'deny', reason: v2.reason, rule: v2.rule };
+      if (road && !state?.claims?.length && !state?.captured_at) noteFailOpen(call, { root, sessionId, vaultRoot, env, stderr: ctx.stderr });
+    }
+    return { decision: 'allow' };
+  } catch {
+    return { decision: 'allow' }; // fail open
+  }
+}
+
+export const beforeToolGate = { id: 'directive-obligation-before-tool', event: 'before_tool', severity: 'block', run };
+export const afterToolGate = { id: 'directive-obligation-after-tool', event: 'after_tool', severity: 'warn', run };
+export const stopGate = { id: 'directive-obligation-stop', event: 'stop', severity: 'block', run };
+
+/** The multi-event form the Claude Code shell hands the adapter (registry.mjs registers the three rungs above). */
+export const hookGate = { id, event: ['before_tool', 'after_tool', 'stop'], severity, run };
+
+export default { id, event, severity, run, beforeToolGate, afterToolGate, stopGate, hookGate };

package/spexharness/src/gates/vault-mirror-catchup.mjs

@@ -0,0 +1,124 @@
+// spexharness/src/gates/vault-mirror-catchup.mjs
+//
+// SessionStart catch-up for the cloud -> local vault mirror (diagnose HS-XJFQ, acceptance criterion 3:
+// "a Companion or MCP session start against a clone that is behind the cloud closes the gap before the
+// first tool call"). In cloud write mode the console is the system of record and the disk clone is a
+// mirror; this gate starts `hs pull --apply` in the BACKGROUND so the hook returns immediately.
+//
+// Fail-open and silent on every skip: local reliance, no vault root / no heyspex.yaml, kill switch
+// HEYSPEX_VAULT_MIRROR_CATCHUP_OFF=1, or a catch-up that already ran in the last 10 minutes (stamp file).
+// Never denies. Emits one line of additionalContext when it spawns.
+//
+// ctx (all optional, for tests): env, vaultRoot, writeMode, now, exists(p), statMtimeMs(p), mkdirp(p),
+// writeFile(p, s), openLog(p) -> fd, spawnDetached(cmd, args, opts), hsCommand() -> { command, args, shell }.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+import { defaultConfigRoot } from '../config-root.mjs';
+import { resolveDevMode } from '../../../scripts/lib/dev-mode.mjs';
+import { describeHsCommand } from '../../../scripts/lib/hs-command.mjs';
+
+export const id = 'vault-mirror-catchup';
+export const event = 'session_start';
+export const severity = 'info';
+
+export const KILL_ENV = 'HEYSPEX_VAULT_MIRROR_CATCHUP_OFF';
+export const FRESH_WINDOW_MS = 10 * 60 * 1000;
+export const LOG_REL = '.heyspex/vault-mirror-catchup.log';
+export const STAMP_REL = '.heyspex/vault-mirror-catchup.stamp';
+
+/** Resolve how to launch `hs pull --apply`: the PATH shim (shell on Windows) or `node <dispatcher>`. */
+export function defaultHsLaunch() {
+  const d = describeHsCommand();
+  if (d.onPath) return { command: 'hs', args: ['pull', '--apply'], shell: process.platform === 'win32' };
+  if (d.dispatcherPath) return { command: process.execPath, args: [d.dispatcherPath, 'pull', '--apply'], shell: false };
+  return { command: 'hs', args: ['pull', '--apply'], shell: process.platform === 'win32' };
+}
+
+/**
+ * Pure-ish decision: returns { spawn: false } or { spawn: true, vaultRoot, command, args, ... }.
+ * All I/O goes through injected deps.
+ */
+export function decideCatchup(deps = {}) {
+  const env = deps.env ?? process.env;
+  if (String(env[KILL_ENV] ?? '') === '1') return { spawn: false, reason: 'kill-switch' };
+  let writeMode = deps.writeMode;
+  if (!writeMode) {
+    try {
+      writeMode = resolveDevMode({ env }).vaultWriteMode;
+    } catch {
+      return { spawn: false, reason: 'dev-mode-unresolved' };
+    }
+  }
+  if (writeMode !== 'cloud') return { spawn: false, reason: 'local-reliance' };
+  let vaultRoot = deps.vaultRoot;
+  if (vaultRoot === undefined) {
+    try {
+      vaultRoot = defaultConfigRoot();
+    } catch {
+      vaultRoot = null;
+    }
+  }
+  if (!vaultRoot) return { spawn: false, reason: 'no-vault-root' };
+  const exists = deps.exists ?? fs.existsSync;
+  if (!exists(path.join(vaultRoot, 'heyspex.yaml'))) return { spawn: false, reason: 'no-heyspex-yaml' };
+
+  const now = (deps.now ?? Date.now)();
+  const stampPath = path.join(vaultRoot, STAMP_REL);
+  const mtime = (deps.statMtimeMs ?? ((p) => {
+    try {
+      return fs.statSync(p).mtimeMs;
+    } catch {
+      return null;
+    }
+  }))(stampPath);
+  if (typeof mtime === 'number' && now - mtime >= 0 && now - mtime < FRESH_WINDOW_MS) {
+    return { spawn: false, reason: 'stamp-fresh' };
+  }
+  const launch = (deps.hsCommand ?? defaultHsLaunch)();
+  return { spawn: true, vaultRoot, stampPath, logPath: path.join(vaultRoot, LOG_REL), ...launch };
+}
+
+/** Perform the detached spawn for a { spawn: true } decision. Throws on failure (caller fails open). */
+export function startCatchup(d, deps = {}) {
+  const mkdirp = deps.mkdirp ?? ((p) => fs.mkdirSync(p, { recursive: true }));
+  const writeFile = deps.writeFile ?? ((p, s) => fs.writeFileSync(p, s));
+  const openLog = deps.openLog ?? ((p) => fs.openSync(p, 'a'));
+  const spawnDetached = deps.spawnDetached ?? ((cmd, args, opts) => spawn(cmd, args, opts));
+  const env = deps.env ?? process.env;
+  mkdirp(path.dirname(d.logPath));
+  writeFile(d.stampPath, new Date((deps.now ?? Date.now)()).toISOString() + '\n');
+  const fd = openLog(d.logPath);
+  const child = spawnDetached(d.command, d.args, {
+    cwd: d.vaultRoot,
+    env: { ...env, HS_VAULT_ROOT: d.vaultRoot },
+    detached: true,
+    stdio: ['ignore', fd, fd],
+    windowsHide: true,
+    shell: d.shell === true,
+  });
+  child?.on?.('error', () => {});
+  child?.unref?.();
+  return child;
+}
+
+export function run(evt, ctx = {}) {
+  try {
+    const d = decideCatchup(ctx);
+    if (!d.spawn) return { decision: 'allow' };
+    startCatchup(d, ctx);
+    return {
+      decision: 'inject',
+      inject: {
+        additionalContext: `vault mirror catch-up: \`hs pull --apply\` started in the background for ${d.vaultRoot} (log: ${LOG_REL})`,
+        severity: 'info',
+      },
+    };
+  } catch {
+    return { decision: 'allow' };
+  }
+}
+
+export default { id, event, severity, run };

package/spexharness/src/gates/vault-write-tier-guard.decide.mjs

@@ -0,0 +1,125 @@
+// spexharness/src/gates/vault-write-tier-guard.decide.mjs
+//
+// Pure decision for the vault-write-tier-guard PreToolUse gate (HS-FCNH).
+//
+// Problem: on a machine in prod / cloud reliance (`hs dev: prod`) the console
+// reads Neon, and the vault clone on disk is a MIRROR the console never reads
+// back. An agent that hand-edits `<vault>/specs/**/*.md` because a console
+// prompt said so writes into a place nobody reads. This gate denies those disk
+// writes in cloud write mode and names the cloud-routed tool to use instead.
+//
+// No process.exit / stdout here. `fs.existsSync` is the only I/O and is
+// injectable (`deps.exists`).
+//
+// call = { toolName, toolInput }
+// deps = { vaultRoot, writeMode, env, cwd?, exists?, platform? }
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { extractShellTargets } from './_shell-write-targets.mjs';
+
+export const KILL_ENV = 'HEYSPEX_VAULT_WRITE_TIER_GUARD_OFF';
+
+const FILE_TOOLS = new Set(['write', 'edit', 'multiedit', 'notebookedit']);
+const SHELL_TOOLS = new Set(['bash', 'powershell']);
+
+function norm(p, platform) {
+  const r = String(p);
+  return platform === 'win32' ? r.toLowerCase() : r;
+}
+
+/** True when `p` resolves to `<vaultRoot>/specs/**\/*.md` outside `.trash/`. */
+export function isGuardedVaultPath(p, { vaultRoot, cwd, platform = process.platform }) {
+  if (!p || typeof p !== 'string') return false;
+  let abs;
+  try {
+    abs = path.resolve(cwd ?? process.cwd(), p);
+  } catch {
+    return false;
+  }
+  const root = norm(path.resolve(vaultRoot), platform);
+  const target = norm(abs, platform);
+  const rel = path.relative(root, target);
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return false;
+  const segs = rel.split(/[\\/]+/);
+  if (segs[0] !== 'specs' || segs.length < 2) return false;
+  if (segs.includes('.trash')) return false;
+  return path.extname(target) === '.md';
+}
+
+function editTexts(toolInput) {
+  const out = [];
+  for (const k of ['new_string', 'content', 'new_source', 'command']) {
+    if (typeof toolInput?.[k] === 'string') out.push(toolInput[k]);
+  }
+  if (Array.isArray(toolInput?.edits)) {
+    for (const e of toolInput.edits) if (typeof e?.new_string === 'string') out.push(e.new_string);
+  }
+  return out;
+}
+
+function pickTool(toolInput) {
+  return editTexts(toolInput).some((t) => /^summary:/m.test(t))
+    ? 'heyspex_author_summary'
+    : 'heyspex_edit_file';
+}
+
+const ROWS = [
+  ['summary: field', 'heyspex_author_summary { spec_id, summary }  (load via heyspex_load_tools)', 'heyspex_author_summary'],
+  ['body / other frontmatter', 'heyspex_edit_file { file_path, content }      (cloud-routed in this mode)', 'heyspex_edit_file'],
+  ['status', 'heyspex_submit_for_review / heyspex_claim_spec — never hand-edit status', null],
+  ['new spec', 'heyspex_file_spec', null],
+];
+
+export function denyReason(target, tool) {
+  const rows = ROWS.map(([label, use, t]) => {
+    const mark = t === tool ? '=> ' : '   ';
+    return `${mark}${label.padEnd(24)} → ${use}`;
+  }).join('\n');
+  return (
+    `[vault-write-tier-guard] This machine writes the vault to the CLOUD (hs dev: prod). ` +
+    `${target} is a disk mirror the console never reads back (HS-FCNH).\n${rows}\n` +
+    `Break-glass for a human: ${KILL_ENV}=1.`
+  );
+}
+
+/**
+ * @param {{ toolName: string, toolInput: Record<string, unknown> }} call
+ * @param {{ vaultRoot?: string|null, writeMode?: string, env?: Record<string,string|undefined>,
+ *           cwd?: string, exists?: (p: string) => boolean, platform?: string }} deps
+ * @returns {{ allow: boolean, reason?: string, tool?: string }}
+ */
+export function decide(call, deps = {}) {
+  const env = deps.env ?? process.env;
+  if (deps.writeMode !== 'cloud') return { allow: true };
+  if (String(env[KILL_ENV] ?? '') === '1') return { allow: true };
+  const vaultRoot = deps.vaultRoot;
+  if (!vaultRoot || typeof vaultRoot !== 'string') return { allow: true };
+  const exists = deps.exists ?? ((p) => fs.existsSync(p));
+  if (!exists(path.join(vaultRoot, 'heyspex.yaml'))) return { allow: true };
+
+  const platform = deps.platform ?? process.platform;
+  const ctx = { vaultRoot, cwd: deps.cwd, platform };
+  const tool = String(call?.toolName ?? '').toLowerCase();
+  const input = call?.toolInput ?? {};
+
+  if (FILE_TOOLS.has(tool)) {
+    const fp = input.file_path ?? input.notebook_path ?? input.filePath;
+    if (isGuardedVaultPath(fp, ctx)) {
+      return { allow: false, tool: pickTool(input), reason: denyReason(String(fp), pickTool(input)) };
+    }
+    return { allow: true };
+  }
+
+  if (SHELL_TOOLS.has(tool)) {
+    const command = String(input.command ?? '');
+    if (!command) return { allow: true };
+    for (const t of extractShellTargets(command)) {
+      if (isGuardedVaultPath(t, ctx)) {
+        return { allow: false, tool: pickTool(input), reason: denyReason(t, pickTool(input)) };
+      }
+    }
+  }
+  return { allow: true };
+}

package/spexharness/src/gates/vault-write-tier-guard.mjs

@@ -0,0 +1,42 @@
+// spexharness/src/gates/vault-write-tier-guard.mjs
+//
+// Engine gate for HS-FCNH: in cloud write mode (`hs dev: prod`), deny agent
+// disk writes to `<vault>/specs/**/*.md` — the disk copy is a mirror the console
+// never reads back. Decision logic lives in ./vault-write-tier-guard.decide.mjs.
+//
+// Kill switch (human break-glass): HEYSPEX_VAULT_WRITE_TIER_GUARD_OFF=1.
+// Deliberately NOT in LEGACY_EXIT2_BANNER: it emits the modern
+// permissionDecision: deny JSON via the adapter.
+//
+// `ctx` (all optional): vaultRoot, writeMode, env, cwd, exists.
+
+import { defaultConfigRoot } from '../config-root.mjs';
+import { resolveDevMode } from '../../../scripts/lib/dev-mode.mjs';
+import { decide as legacyDecide, KILL_ENV } from './vault-write-tier-guard.decide.mjs';
+
+export const id = 'vault-write-tier-guard';
+export const event = 'before_tool';
+export const severity = 'block';
+
+export function run(evt, ctx = {}) {
+  const env = ctx.env ?? process.env;
+  if (String(env[KILL_ENV] ?? '') === '1') return { decision: 'allow' };
+  let writeMode = ctx.writeMode;
+  if (!writeMode) {
+    try {
+      writeMode = resolveDevMode({ env }).vaultWriteMode;
+    } catch {
+      return { decision: 'allow' };
+    }
+  }
+  if (writeMode !== 'cloud') return { decision: 'allow' };
+  const vaultRoot = ctx.vaultRoot ?? defaultConfigRoot();
+  const verdict = legacyDecide(
+    { toolName: evt?.toolName, toolInput: evt?.toolInput ?? {} },
+    { vaultRoot, writeMode, env, cwd: ctx.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd(), exists: ctx.exists },
+  );
+  if (verdict.allow) return { decision: 'allow' };
+  return { decision: 'deny', reason: verdict.reason };
+}
+
+export default { id, event, severity, run };

package/spexharness/src/intent-classifier.mjs

@@ -34,7 +34,7 @@
 // rule-table.mjs's header). No process.stdin/stdout/exit.
 
 import { loadRuleTable } from './rule-table.mjs';
-import { buildIntentDirective } from './intent-directive.mjs';
+import { buildIntentDirective, ruleMatchesPrompt } from './intent-directive.mjs';
 
 /** This gate's id, for a registry or an audit row. */
 export const GATE_ID = 'intent-classifier';
@@ -56,6 +56,7 @@ export const CLASSIFIER_RULE_IDS = Object.freeze([
   'research-before-decision',
   'settings-intent',
   'defer-intent',
+  'handoff-intent',
   'spec-reference-lookup',
 ]);
 
@@ -113,7 +114,8 @@ export function classifyPrompt(prompt, { vaultRoot, ruleTable } = {}) {
   const table = ruleTable ?? loadRuleTable({ vaultRoot });
   for (const rule of classifierRules(table)) {
     const patterns = compilePatterns(rule);
-    if (patterns.some((re) => re.test(prompt))) {
+    // HS-XDH8: a negation-guarded rule (defer-intent) needs an un-negated occurrence.
+    if (ruleMatchesPrompt(rule, patterns, prompt)) {
       return { rule: rule.rule, sourceProtocol: rule.sourceProtocol ?? null, inject: rule.inject };
     }
   }