heyspex 0.1.0 → 0.2.1

package/spexharness/src/gates/claim-before-code-gate.mjs

@@ -0,0 +1,129 @@
+// spexharness/src/gates/claim-before-code-gate.mjs
+//
+// Engine port of scripts/claude-hooks/claim-before-code-gate.mjs — the
+// PreToolUse gate that denies the first post-plan CODE edit made by a
+// session that exited plan mode with no active claim
+// ([[HS-38J5-2BXD-DIAG-plan-execute-boundary-has-no-ingest-clai]] item 2).
+// 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. The pure
+// decision function — `shouldDenyEdit({ toolName, filePath, hasMarker,
+// hasNoClaimSignal })` — with no stdin/stdout/process-exit of its own, lives
+// in ./claim-before-code-gate.decide.mjs (relocated out of the original hook
+// script, HS-IQBF; see PORTING.md and that sibling module's own header for
+// why) and is IMPORTED here unchanged: it already encapsulates the
+// tool-name filter (EDIT_TOOL_NAMES) and the code-path filter
+// (isCodeEditPath) internally, so this module never needs its own copy of
+// either.
+//
+// The two SIGNAL readers (hasMarker / hasNoClaimSignal) are also imported
+// unchanged, not re-derived:
+//   - scripts/claude-hooks/plan-exit-ingest-gate.mjs — hasFreshPlanExitMarker,
+//     repoRoot. Also guarded by its own INVOKED_DIRECTLY check.
+//   - scripts/claude-hooks/claim-liveness-shared.mjs — resolveSessionId,
+//     hasFreshNoClaimSignal. A dependency-free shared module with no
+//     unconditional main() at all (its own async orchestration function is
+//     exported, never self-invoked at import time).
+//
+// Event mapping: PreToolUse (Edit|Write|MultiEdit) → before_tool.
+//   stdin.session_id / stdin.conversation_id → evt.sessionId (resolveSessionId
+//     also falls back to the real process env, unchanged).
+//   stdin.tool_input.file_path (or .path) → evt.toolInput.file_path/.path.
+//
+// Decision mapping — TWO rungs, same shape as plan-review-gate.mjs's port:
+// CLAUDE_AGENT=true or HEYSPEX_CLAIM_GATE_INTERACTIVE=block ("forReal") maps
+// a `shouldDenyEdit` true to a real `deny`; the interactive default maps the
+// SAME finding to a `rewrite` envelope (`{ warn: true, reason, rule }`) — the
+// edit still proceeds, matching the original's stderr-only warn path
+// exactly. `shouldDenyEdit` false (no marker, no fresh no-claim signal, wrong
+// tool, or a specs/.heyspex/.claude/.git path) → plain `allow`.
+//
+// Not ported: the original's `appendGuardrailEvent(...)` audit-log write on
+// a fire — matching every other port in this set.
+//
+// Env hatches (unchanged):
+//   HEYSPEX_CLAIM_GATE_OFF=1          Hard kill switch — silences both rungs.
+//   HEYSPEX_CLAIM_GATE_INTERACTIVE=block  Raise the interactive rung to a real deny.
+//   CLAUDE_AGENT=true                 Unattended session → real deny (unchanged).
+//
+// `ctx` contract (all optional; every field defaults to a real fs/env read):
+//   ctx.cwd                  - repo root to resolve the plan-exit marker and
+//                              claim-liveness cache from. Defaults to
+//                              plan-exit-ingest-gate.mjs's own repoRoot()
+//                              (CLAUDE_PROJECT_DIR, else this repo's root).
+//   ctx.sessionId             - override for the resolved session id (tests
+//                              pin this directly instead of an env var).
+//                              Defaults to resolveSessionId() against
+//                              `{ session_id: evt.sessionId }`.
+//   ctx.env                  - env var overrides (tests use this instead of
+//                              mutating process.env).
+
+import { resolveSessionId, hasFreshNoClaimSignal } from '../../../scripts/claude-hooks/claim-liveness-shared.mjs';
+import { hasFreshPlanExitMarker, repoRoot as planExitRepoRoot } from '../../../scripts/claude-hooks/plan-exit-ingest-gate.mjs';
+import { shouldDenyEdit } from './claim-before-code-gate.decide.mjs';
+
+// Copied verbatim from the original's own (unexported) denyReason.
+function denyReason() {
+  return (
+    'HEYSPEX claim gate: this session exited plan mode and has no active claim — ' +
+    'the plan→execute boundary requires filing the epic (if not yet filed) and calling ' +
+    'heyspex_claim_spec before the first code edit ([[HS-38J5-2BXD-DIAG-plan-execute-boundary-has-no-ingest-clai]]). ' +
+    'Claim the spec you are working, then retry this edit. ' +
+    '(Break-glass: set HEYSPEX_CLAIM_GATE_OFF=1 for this session.)'
+  );
+}
+
+function shouldBlockForReal(env) {
+  return env.CLAUDE_AGENT === 'true' || env.HEYSPEX_CLAIM_GATE_INTERACTIVE === 'block';
+}
+
+/** The claim-before-code gate's id — unique across the built-in registry. */
+export const id = 'claim-before-code-gate';
+/** Runs pre-tool, same as its PreToolUse Claude Code hook registration. */
+export const event = 'before_tool';
+/** Caller-defined severity label; this gate can deny, so it is "block". */
+export const severity = 'block';
+
+/**
+ * @param {{ point: string, toolName?: string, toolInput?: Record<string, unknown>, sessionId?: string }} evt
+ * @param {{ cwd?: string, sessionId?: string, env?: Record<string, string | undefined> }} [ctx]
+ * @returns {{ decision: 'allow'|'deny'|'rewrite', reason?: string, rewrite?: object }}
+ */
+export function run(evt, ctx = {}) {
+  const env = ctx.env ?? process.env;
+  if (String(env.HEYSPEX_CLAIM_GATE_OFF ?? '') === '1') {
+    return { decision: 'allow' };
+  }
+
+  const toolName = evt?.toolName;
+  const toolInput = evt?.toolInput ?? {};
+  const filePath = toolInput.file_path ?? toolInput.path;
+
+  const sessionId = ctx.sessionId ?? resolveSessionId({ session_id: evt?.sessionId });
+  if (!sessionId) return { decision: 'allow' }; // can't scope the check — fail open
+
+  const root = ctx.cwd ?? planExitRepoRoot();
+  const hasMarker = hasFreshPlanExitMarker(sessionId, root);
+  const hasNoClaimSignal = hasFreshNoClaimSignal(sessionId, root);
+
+  if (!shouldDenyEdit({ toolName, filePath, hasMarker, hasNoClaimSignal })) {
+    return { decision: 'allow' };
+  }
+
+  const reason = denyReason();
+  const forReal = shouldBlockForReal(env);
+  if (forReal) return { decision: 'deny', reason };
+
+  // Interactive warn path: byte-for-byte the original hook's fireDeny()
+  // stderr banner ([claim-before-code-gate] warning — ...\n(Interactive
+  // session: ...)\n) — kept here (not left to a generic adapter formatter)
+  // because it is gate-specific text, same convention as naughty-list-gate's
+  // and capture-workflow-gate's own self-contained warn reasons.
+  const warnReason =
+    `[claim-before-code-gate] warning — ${reason}\n` +
+    '(Interactive session: this only warns. Set HEYSPEX_CLAIM_GATE_INTERACTIVE=block to enforce it here too.)\n';
+  return { decision: 'rewrite', reason: warnReason, rewrite: { warn: true, reason: warnReason, rule: 'claim-before-code-gate' } };
+}
+
+export default { id, event, severity, run };

package/spexharness/src/gates/deep-research-cost-gate.mjs

@@ -0,0 +1,275 @@
+// spexharness/src/gates/deep-research-cost-gate.mjs
+//
+// Engine port of scripts/claude-hooks/deep-research-cost-gate.mjs — the
+// PreToolUse cost-confirmation + grounding gate over a Workflow/Skill call
+// that launches deep-research (HS-BLH1 grounding extension, epic HS-7HR9).
+// See ./PORTING.md for the general recipe this follows.
+//
+// JUDGMENT CALL — bigger than git-stash-gate.mjs's, read before touching
+// this file: the original script exports NOTHING — no pure decision
+// function, not even its `COST` table or its regex matchers. Its entire
+// decision (inlineScriptTarget / resolveTarget / groundingBlock /
+// isGroundOnlyResearchLaunch / the COST table) is private to the module and
+// tangled with `main()`'s stdin read, stdout write and exit. PORTING.md's
+// step-1 default remedy — extract a pure function INSIDE the original — is
+// exactly what this porting task's own brief forbids for this pass ("do NOT
+// delete or edit anything under scripts/claude-hooks/ ... shells come
+// later"). So, unlike the reference port and unlike git-stash-gate.mjs's
+// port (which could reuse several already-exported primitives), THIS module
+// re-derives the original's decision logic by hand — copied verbatim where
+// the original's own strings/tables are copyable (the COST table, the
+// deny/ask message templates, the grounding-artifact field list), so
+// today's golden fixtures still match. The one real import is
+// `loadResearchFocus` (vendor/heyspex-mcp/research-focus.mjs), which WAS
+// already exported and pure — reused, not re-derived. If the original
+// script is ever changed to export its logic (the "shells come later" plan
+// this brief refers to), this module's private copies should be deleted in
+// favor of importing the real thing — until then, a change to the
+// original's regexes/COST table needs a matching edit here, and vice versa;
+// there is no structural drift-proofing possible while the original stays
+// unexported.
+//
+// Event mapping: PreToolUse (Workflow|Skill) → before_tool.
+// Decision mapping: allow stays allow; the inline-script backstop's `deny`
+// stays `deny`; the grounding block's `deny` stays `deny`; the cost
+// confirmation's `ask` is carried forward as a `rewrite` envelope
+// (`{ ask: true, reason }`) — the same mapping env-vault-guard.mjs's
+// reference port uses for its own `ask` case, since the engine has no
+// synchronous-approval primitive.
+//
+// Env hatches (unchanged): HEYSPEX_DEEP_RESEARCH_GATE_OFF=1 (mutes the whole
+// gate), HEYSPEX_RESEARCH_GROUNDING_GATE_OFF=1 (mutes only the grounding
+// check — the cost ask still fires).
+//
+// `ctx` contract (all optional):
+//   ctx.env                        - env var overrides (falls back to
+//                                     process.env).
+//   ctx.cwd                        - vault root to resolve the
+//                                     research-focus pin and grounding
+//                                     artifact from. Defaults to
+//                                     CLAUDE_PROJECT_DIR, else this repo's
+//                                     root.
+//   ctx.loadResearchFocus(root)    - override for the research-focus
+//                                     reader. Defaults to the real
+//                                     loadResearchFocus.
+//   ctx.readGroundingArtifact(root) - override for the grounding-artifact
+//                                     reader. Tests inject fakes here
+//                                     instead of touching disk.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { loadResearchFocus } from '../../../vendor/heyspex-mcp/research-focus.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, '..', '..', '..');
+
+// Copied verbatim from the original (private consts there) — see the
+// judgment-call note above.
+// Exported (additive, HS-KNJ8) so scripts/lib/capture-execution-guard.mjs reads the SAME record with the SAME shape.
+export const GROUNDING_ARTIFACT_REL = path.join('.heyspex', 'research-grounding.json');
+export const GROUNDING_FIELDS =['already_built', 'already_decided', 'owner_reference', 'residual_delta'];
+
+const COST = {
+  'deep-research': {
+    agents: '~97',
+    label: 'the BUILT-IN deep-research',
+    extra:
+      ' This is the EXPENSIVE built-in harness and it RATE-LIMITS. Strongly prefer a HeySpex bounded profile instead: deep-research-thorough (~31 agents) or deep-research-quick (~19 agents).',
+  },
+  'deep-research-thorough': {
+    agents: '~31',
+    label: 'deep-research-thorough (HeySpex bounded, 3-vote)',
+    extra: '',
+  },
+  'deep-research-medium': {
+    agents: '~24',
+    label: 'deep-research-medium (HeySpex bounded, 2-vote)',
+    extra: '',
+  },
+  'deep-research-quick': {
+    agents: '~19',
+    label: 'deep-research-quick (HeySpex bounded, single-vote)',
+    extra: '',
+  },
+};
+
+// Detect the recurring broken launch: a hand-authored inline `script` (often
+// with a `title` like "dynamic workflow: deep-research-thorough") that does
+// not lead with `export const meta` → the harness rejects it. We only trip
+// when there is NO `name`/`scriptPath` (the correct paths) but an inline
+// `script`/`title` clearly targets a deep-research profile. Copied verbatim
+// from the original — see the judgment-call note above.
+function inlineScriptTarget(input) {
+  if (typeof input.name === 'string' || typeof input.scriptPath === 'string') return null;
+  const hay = `${typeof input.script === 'string' ? input.script : ''}\n${typeof input.title === 'string' ? input.title : ''}`;
+  if (!hay.trim()) return null;
+  if (/deep-research-thorough/.test(hay)) return 'deep-research-thorough';
+  if (/deep-research-medium/.test(hay)) return 'deep-research-medium';
+  if (/deep-research-quick/.test(hay)) return 'deep-research-quick';
+  if (/deep-research/.test(hay)) return 'deep-research-thorough'; // steer built-in/unmapped to the bounded default
+  return null;
+}
+
+// Resolve which deep-research target a Workflow/Skill call refers to, or
+// null. Copied verbatim from the original.
+function resolveTarget(toolName, input) {
+  const candidates = [];
+  if (toolName === 'Workflow') {
+    if (typeof input.name === 'string') candidates.push(input.name);
+    if (typeof input.scriptPath === 'string') candidates.push(input.scriptPath);
+  } else if (toolName === 'Skill') {
+    if (typeof input.skill === 'string') candidates.push(input.skill);
+  }
+  for (const c of candidates) {
+    if (Object.prototype.hasOwnProperty.call(COST, c)) return c;
+  }
+  for (const c of candidates) {
+    if (/deep-research-thorough/.test(c)) return 'deep-research-thorough';
+    if (/deep-research-medium/.test(c)) return 'deep-research-medium';
+    if (/deep-research-quick/.test(c)) return 'deep-research-quick';
+    if (/deep-research/.test(c)) return 'deep-research';
+  }
+  return null;
+}
+
+// `/hs-res` spends no Anthropic tokens (so no cost ask), but IS still a full
+// external research pass and must still be grounded. Copied verbatim from
+// the original.
+function isGroundOnlyResearchLaunch(toolName, input) {
+  if (toolName !== 'Skill') return false;
+  return typeof input.skill === 'string' && /^hs-res$/i.test(input.skill.trim());
+}
+
+export function defaultReadGroundingArtifact(root) {
+  try {
+    const full = path.join(root, GROUNDING_ARTIFACT_REL);
+    if (!fs.existsSync(full)) return null;
+    return JSON.parse(fs.readFileSync(full, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Returns a deny-reason string when a promotion-driven deep-research launch
+// is NOT grounded, else null (allow). Copied verbatim from the original
+// (parameterized on `root`/`deps` instead of calling repoRoot() and the
+// module-level readers directly, so ctx can override both for tests).
+function groundingBlock(root, deps) {
+  let focus;
+  try {
+    focus = deps.loadResearchFocus(root);
+  } catch {
+    return null; // discovery failure → fail open
+  }
+  const sourceIdeaId = focus?.source_idea_id;
+  if (!sourceIdeaId) return null; // no promotion pin → not gated
+
+  const artifact = deps.readGroundingArtifact(root);
+  const grounded =
+    artifact &&
+    typeof artifact === 'object' &&
+    artifact.source_idea_id === sourceIdeaId &&
+    GROUNDING_FIELDS.every((k) => typeof artifact[k] === 'string' && artifact[k].trim());
+  if (grounded) return null;
+
+  const why = !artifact
+    ? 'no grounding artifact was found'
+    : artifact.source_idea_id !== sourceIdeaId
+      ? `the grounding artifact is for a different idea (${artifact.source_idea_id ?? 'unknown'})`
+      : 'the grounding artifact is missing already_built / already_decided / owner_reference / residual_delta';
+  return (
+    `Deep-research launch blocked: this is a promotion-driven research run for ${sourceIdeaId}, but ${why}. ` +
+    `Ground FIRST so you research only the residual unknown, not work that already ships or is already decided ` +
+    `(the HS-VDPB → HS-LKCO burn re-derived companion features that already exist). Do both routes:\n` +
+    `  route-1 (plans): heyspex_recall_memories + /hs-ground on the idea.\n` +
+    `  route-2 (code): check companion/ · spex-console/ · scripts/ · the \`hs\` CLI, PLUS the feature's use case / roadmap / open tasks.\n` +
+    `  route-3 (owner's working reference): does the owner ALREADY RUN something that does this — a service, container, script, or tool on their own machine? Inspect it and record what it showed. This is the cheapest and highest-authority evidence there is.\n` +
+    `Then record the result to ${GROUNDING_ARTIFACT_REL} as ` +
+    `{ "source_idea_id": "${sourceIdeaId}", "already_built": "...", "already_decided": "...", "owner_reference": "...", "residual_delta": "...", "recorded_at": "<ISO>" } ` +
+    `and relaunch with the RESIDUAL DELTA as the question. If grounding shows it is already built/decided, do NOT launch — record and stop. ` +
+    `(Break-glass: set HEYSPEX_RESEARCH_GROUNDING_GATE_OFF=1.)`
+  );
+}
+
+/** The deep-research cost/grounding gate's id — unique across the built-in registry. */
+export const id = 'deep-research-cost-gate';
+/** Runs pre-tool, same as its PreToolUse Claude Code hook registration. */
+export const event = 'before_tool';
+/** Caller-defined severity label; this gate can deny, so it is "block". */
+export const severity = 'block';
+
+/**
+ * @param {{ point: string, toolName?: string, toolInput?: Record<string, unknown> }} evt
+ * @param {{ cwd?: string, loadResearchFocus?: (root: string) => object | null,
+ *            readGroundingArtifact?: (root: string) => object | null,
+ *            env?: Record<string, string | undefined> }} [ctx]
+ * @returns {{ decision: 'allow'|'deny'|'rewrite', reason?: string, rewrite?: object }}
+ */
+export function run(evt, ctx = {}) {
+  const env = ctx.env ?? process.env;
+  if (String(env.HEYSPEX_DEEP_RESEARCH_GATE_OFF ?? '') === '1') {
+    return { decision: 'allow' };
+  }
+
+  const toolName = evt?.toolName;
+  if (toolName !== 'Workflow' && toolName !== 'Skill') {
+    return { decision: 'allow' };
+  }
+
+  const input = evt?.toolInput ?? {};
+  const root = ctx.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? REPO_ROOT;
+  const deps = {
+    loadResearchFocus: ctx.loadResearchFocus ?? loadResearchFocus,
+    readGroundingArtifact: ctx.readGroundingArtifact ?? defaultReadGroundingArtifact,
+  };
+
+  // Backstop: a hand-authored inline-script deep-research launch (no
+  // name/scriptPath) would fail the harness's own validator. Deny it with
+  // the exact corrective so the caller relaunches by scriptPath instead.
+  if (toolName === 'Workflow') {
+    const inlineProfile = inlineScriptTarget(input);
+    if (inlineProfile) {
+      return {
+        decision: 'deny',
+        reason:
+          `Don't hand-author an inline deep-research workflow script — that trips the ` +
+          `"export const meta must be the FIRST statement" validator (the recurring ` +
+          `"dynamic workflow: ${inlineProfile}" launch error). Relaunch it via scriptPath so the ` +
+          `validated file loads: Workflow({ scriptPath: '.claude/workflows/${inlineProfile}.js', args: '<the research question>' }). ` +
+          `Do NOT use the Workflow \`name\` parameter (its loader trips the same validator) and do NOT invoke it via the Skill tool.`,
+      };
+    }
+  }
+
+  const target = resolveTarget(toolName, input);
+  const groundingOff = String(env.HEYSPEX_RESEARCH_GROUNDING_GATE_OFF ?? '') === '1';
+
+  // Grounding applies to every external research pass, including the
+  // zero-cost /hs-res path — which is grounded but never cost-asked.
+  if (!target) {
+    if (isGroundOnlyResearchLaunch(toolName, input) && !groundingOff) {
+      const groundingDeny = groundingBlock(root, deps);
+      if (groundingDeny) return { decision: 'deny', reason: groundingDeny };
+    }
+    return { decision: 'allow' }; // not a cost-bearing deep-research invocation
+  }
+
+  // Grounding gate: a promotion-driven deep-research launch must be grounded
+  // first. Runs before the cost ask so an ungrounded launch is denied, not
+  // merely cost-confirmed. Muted independently of the cost gate.
+  if (!groundingOff) {
+    const groundingDeny = groundingBlock(root, deps);
+    if (groundingDeny) return { decision: 'deny', reason: groundingDeny };
+  }
+
+  const c = COST[target];
+  const reason =
+    `Deep-research about to run: ${c.label} — ${c.agents} agent calls ` +
+    `(fan-out web search → fetch → adversarially verify → synthesize).${c.extra} ` +
+    `Approve to spend those tokens, or cancel and choose the cheaper profile.`;
+  return { decision: 'rewrite', reason, rewrite: { ask: true, reason } };
+}
+
+export default { id, event, severity, run };

package/spexharness/src/gates/diagnose-capture-reminder.mjs

@@ -0,0 +1,112 @@
+// spexharness/src/gates/diagnose-capture-reminder.mjs
+//
+// PreToolUse WARN-ONLY reminder (diagnose HS-IK2D, 2026-10-10). A diagnose (or research) filed straight
+// through heyspex_file_spec passes every other gate: capture-workflow-gate and
+// vendor/heyspex-mcp/capture-stage-gate.mjs deliberately ALLOW `type: diagnose|research` because they are
+// the sanctioned exits. That left a hole — an owner's complaint could become a diagnose with NO capture
+// ever holding their verbatim words. This gate closes the hole without blocking: when a diagnose/research
+// is filed without `frontmatter.promoted_from` and the session transcript shows no capture tool call
+// before it, it injects a reminder (additionalContext) telling the agent to capture first.
+//
+// Never denies. Fail-open on every unknowable (no transcript, unreadable, bad JSON, wrong tool).
+// Kill switch: HEYSPEX_DIAGNOSE_CAPTURE_REMINDER_OFF=1.
+//
+// ctx (all optional): ctx.env, ctx.readFile(path) -> string|null, ctx.sessionRecord (non-Claude fronts:
+// { toolCalls: [{ name }] }, used when no transcript path exists).
+
+import fs from 'node:fs';
+
+export const id = 'diagnose-capture-reminder';
+export const event = 'before_tool';
+export const severity = 'warn';
+
+const OFF_ENV = 'HEYSPEX_DIAGNOSE_CAPTURE_REMINDER_OFF';
+const FILE_SPEC_TOOL = 'heyspex_file_spec';
+const REMINDED_TYPES = new Set(['diagnose', 'research']);
+// A capture tool call anywhere earlier in the session counts as "the capture happened".
+const CAPTURE_TOOL_RE = /heyspex_(?:active_capture|update_capture|promote_capture_to_diagnose|promote_capture)\b/;
+
+export const REMINDER_TEXT =
+  "No capture precedes this diagnose — run heyspex_active_capture + heyspex_update_capture with the owner's " +
+  'verbatim words, then heyspex_promote_capture_to_diagnose. Direct filing is for bugs found mid-work only.';
+
+function bareToolName(name) {
+  if (typeof name !== 'string') return '';
+  const idx = name.lastIndexOf('__');
+  return idx === -1 ? name : name.slice(idx + 2);
+}
+
+function defaultReadFile(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/** True when the transcript JSONL holds an assistant tool_use of a capture tool. */
+export function transcriptHasCaptureCall(raw) {
+  if (typeof raw !== 'string') return false;
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line || !line.includes('capture')) continue; // cheap pre-filter
+    let evt;
+    try {
+      evt = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const content = evt?.message?.content;
+    if (!Array.isArray(content)) continue;
+    for (const block of content) {
+      if (block?.type === 'tool_use' && typeof block.name === 'string' && CAPTURE_TOOL_RE.test(block.name)) return true;
+    }
+  }
+  return false;
+}
+
+function recordHasCaptureCall(record) {
+  const calls = Array.isArray(record?.toolCalls) ? record.toolCalls : [];
+  return calls.some((c) => typeof c?.name === 'string' && CAPTURE_TOOL_RE.test(c.name));
+}
+
+/**
+ * @param {{ point: string, toolName?: string, toolInput?: object, transcriptPath?: string, sessionRecord?: object }} evt
+ * @param {{ env?: object, readFile?: (p: string) => string|null, sessionRecord?: object }} [ctx]
+ * @returns {{ decision: 'allow'|'inject', reason?: string, inject?: { additionalContext: string } }}
+ */
+export function run(evt, ctx = {}) {
+  try {
+    const env = ctx.env ?? process.env;
+    if (String(env[OFF_ENV] ?? '') === '1') return { decision: 'allow' };
+    if (bareToolName(evt?.toolName) !== FILE_SPEC_TOOL) return { decision: 'allow' };
+
+    const input = evt?.toolInput ?? {};
+    const type = String(input?.type ?? '').trim().toLowerCase();
+    if (!REMINDED_TYPES.has(type)) return { decision: 'allow' };
+
+    const promotedFrom = input?.frontmatter?.promoted_from ?? input?.promoted_from;
+    if (promotedFrom != null && String(Array.isArray(promotedFrom) ? promotedFrom.join('') : promotedFrom).trim()) {
+      return { decision: 'allow' }; // came through a capture promotion
+    }
+
+    const transcriptPath = evt?.transcriptPath;
+    const record = evt?.sessionRecord ?? ctx.sessionRecord ?? null;
+    if (!transcriptPath && !record) return { decision: 'allow' }; // unknowable -> fail open
+
+    let captured;
+    if (transcriptPath) {
+      const raw = (ctx.readFile ?? defaultReadFile)(transcriptPath);
+      if (raw == null) return { decision: 'allow' }; // unreadable -> fail open
+      captured = transcriptHasCaptureCall(raw);
+    } else {
+      captured = recordHasCaptureCall(record);
+    }
+    if (captured) return { decision: 'allow' };
+
+    return { decision: 'inject', reason: REMINDER_TEXT, inject: { additionalContext: REMINDER_TEXT } };
+  } catch {
+    return { decision: 'allow' };
+  }
+}
+
+export default { id, event, severity, run };

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]]'
+  );
+}