heyspex 0.2.0 → 0.2.2

package/scripts/lib/window-placement.mjs

@@ -0,0 +1,109 @@
+/**
+ * Window placement for the two-pane capture layout
+ * ([[HS-I2YN-ST07-EPIC-two-pane-layout-pipeline-view-on-the]]).
+ *
+ * The owner wants the `hs view` window (pipeline + capture doc) and the
+ * PowerShell SpexCode agent window both visible at once. Neither launcher used
+ * to place its window, so they stacked wherever the OS put them. This module is
+ * the ONE place that decides the geometry; both launchers call it:
+ *
+ *   - `scripts/hs-view.mjs`        -> side "right" (this window)
+ *   - the agent launch (HS-TXFW)   -> `complementarySide("right")` = "left"
+ *
+ * Pure geometry (`computeWindowPlacement`) is separated from the one
+ * side-effecting probe (`getPrimaryWorkArea`) so the maths is unit-testable.
+ *
+ * Safety: placement is always BEST EFFORT. Any failure (non-Windows, probe
+ * timeout, nonsense numbers) yields `null` and the caller simply omits the
+ * position flags, i.e. today's behavior. Multi-monitor: only the primary
+ * monitor's work area is used by default (taskbar excluded), so a window can
+ * never be pushed onto a monitor that was unplugged or a negative coordinate
+ * the OS would clamp unpredictably.
+ */
+import { spawnSync } from 'node:child_process';
+
+/** Sides a window can take. `none` disables placement entirely. */
+export const PLACE_SIDES = new Set(['left', 'right', 'none']);
+
+/** The other half of the screen - what the sibling window should take. */
+export function complementarySide(side) {
+  if (side === 'left') return 'right';
+  if (side === 'right') return 'left';
+  return 'none';
+}
+
+/** Parse `left|right|none` (case-insensitive); anything else -> null. */
+export function parsePlaceSide(value) {
+  const v = String(value ?? '').trim().toLowerCase();
+  return PLACE_SIDES.has(v) ? v : null;
+}
+
+function validWorkArea(w) {
+  return (
+    w &&
+    [w.x, w.y, w.width, w.height].every((n) => Number.isFinite(n)) &&
+    w.width >= 400 &&
+    w.height >= 300
+  );
+}
+
+/**
+ * Geometry for one window on one half of a work area.
+ *
+ * Width is the requested width capped at half the work area, so the two
+ * windows can never overlap; height fills the work area. Returns
+ * `{ x, y, width, height }` or null when placement should be skipped.
+ */
+export function computeWindowPlacement({ workArea, side, width, height }) {
+  if (side !== 'left' && side !== 'right') return null;
+  if (!validWorkArea(workArea)) return null;
+  const half = Math.floor(workArea.width / 2);
+  const w = Math.max(1, Math.min(Number.isFinite(width) && width > 0 ? width : half, half));
+  const h = Math.max(
+    1,
+    Math.min(Number.isFinite(height) && height > 0 ? height : workArea.height, workArea.height),
+  );
+  // Full-height halves unless the caller asked for something shorter.
+  const x = side === 'left' ? workArea.x : workArea.x + workArea.width - w;
+  return { x, y: workArea.y, width: w, height: h };
+}
+
+/** The Chromium app-mode flags for a placement. */
+export function placementFlags(p) {
+  return p ? [`--window-position=${p.x},${p.y}`, `--window-size=${p.width},${p.height}`] : [];
+}
+
+/**
+ * Primary monitor work area (taskbar excluded) in the units Chromium's
+ * `--window-position` uses. Windows only; null elsewhere or on any failure.
+ * Override for tests / unusual setups with `HEYSPEX_VIEW_WORKAREA=x,y,w,h`.
+ */
+export function getPrimaryWorkArea(env = process.env, platform = process.platform) {
+  const override = String(env.HEYSPEX_VIEW_WORKAREA ?? '').trim();
+  if (override) {
+    const [x, y, width, height] = override.split(',').map((s) => Number(s.trim()));
+    const w = { x, y, width, height };
+    return validWorkArea(w) ? w : null;
+  }
+  if (platform !== 'win32') return null;
+  try {
+    const r = spawnSync(
+      'powershell.exe',
+      [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        'Add-Type -AssemblyName System.Windows.Forms; ' +
+          '$a=[System.Windows.Forms.Screen]::PrimaryScreen.WorkingArea; ' +
+          '"$($a.X),$($a.Y),$($a.Width),$($a.Height)"',
+      ],
+      { encoding: 'utf8', timeout: 4000, windowsHide: true },
+    );
+    if (r.status !== 0) return null;
+    const [x, y, width, height] = String(r.stdout).trim().split(',').map(Number);
+    const w = { x, y, width, height };
+    return validWorkArea(w) ? w : null;
+  } catch {
+    return null;
+  }
+}

package/spexharness/src/adapters/claude-code.mjs

@@ -52,6 +52,8 @@ import { fileURLToPath } from 'node:url';
 
 import { createEvent } from '../events.mjs';
 import { recordGuardrailAudit } from './audit.mjs';
+import { detectHarness } from './detect-harness.mjs';
+import { normalizeCopilotPayload, toCopilotResponse } from './copilot.mjs';
 
 /** Claude Code `hook_event_name` → spexharness/src/events.mjs event point.
  * Deliberately does NOT map `SubagentStop` to `stop` — SubagentStop is a
@@ -115,6 +117,8 @@ function fieldsForPoint(point, payload) {
     case 'before_tool':
       fields.toolName = payload?.tool_name;
       fields.toolInput = payload?.tool_input ?? {};
+      // 2026-10-10: carried so a before_tool gate can scan the session so far (diagnose-capture-reminder).
+      if (payload?.transcript_path) fields.transcriptPath = payload.transcript_path;
       break;
     case 'after_tool':
       fields.toolName = payload?.tool_name;
@@ -405,8 +409,12 @@ export async function runGatesAsHook(gates, deps = {}) {
 
 export async function runGateAsHook(gate, deps = {}) {
   try {
-    const payload = deps.payload ?? (await readStdinJson());
-    if (!payload) return;
+    const rawPayload = deps.payload ?? (await readStdinJson());
+    if (!rawPayload) return;
+    // GitHub Copilot runs these same hooks (HS-20SW): positive-signature detection, then the Copilot dialect
+    // (top-level permissionDecision JSON, exit 0 - never exit 2, Copilot would drop the reason).
+    const harness = detectHarness(rawPayload, process.env);
+    const payload = harness === 'copilot' ? normalizeCopilotPayload(rawPayload) : rawPayload;
 
     const engineEvent = resolveEventForGate(payload, gate);
     if (!engineEvent) return; // not this gate's event — allow
@@ -430,7 +438,7 @@ export async function runGateAsHook(gate, deps = {}) {
       }
     }
 
-    const { exitCode, stdout, stderr } = toHookResponse(gate, engineEvent, decision);
+    const { exitCode, stdout, stderr } = (harness === 'copilot' ? toCopilotResponse : toHookResponse)(gate, engineEvent, decision);
     if (stdout) process.stdout.write(stdout);
     if (stderr) process.stderr.write(stderr);
     process.exitCode = exitCode;

package/spexharness/src/adapters/copilot.mjs

@@ -0,0 +1,236 @@
+// spexharness/src/adapters/copilot.mjs
+//
+// GitHub Copilot CLI front for the shared hook gates ([[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]];
+// contract: GitHub Docs "Hooks configuration" + "CLI plugin reference", fetched 2026-10-16;
+// [[HS-0GBS-CTF8-RES-copilot-plugin-parity-with-the-spexcode]]). Pure functions, no I/O.
+//
+// What Copilot does that Claude Code does not:
+//   INPUT   two shapes. camelCase config events `{ sessionId, timestamp, cwd, toolName, toolArgs }` and the
+//           PascalCase shape `.claude/settings.json` rows receive `{ hook_event_name, session_id, timestamp,
+//           cwd, tool_name, tool_input }` (tool names already mapped to Claude's: bash/powershell -> Bash,
+//           create -> Write, edit/apply_patch -> Edit, view -> Read, task -> Agent). No `transcript_path`.
+//   OUTPUT  ONE top-level JSON object on stdout: `{ permissionDecision: allow|deny|ask, permissionDecisionReason }`.
+//           It does NOT read `hookSpecificOutput`. Unparseable stdout is ignored.
+//   EXIT    0 -> stdout parsed. 2 -> always deny (stderr reason lost). ANY other non-zero -> deny ("hook
+//           errored"). Timeout -> fail open. So a Copilot hook prints its deny as JSON and exits 0, never 2.
+//
+// This module maps both directions; ./detect-harness.mjs decides WHEN it applies.
+
+// HeySpex MCP tool names arrive in several spellings depending on the Copilot host (the payload spelling is not
+// documented; [[HS-0GBS-CTF8-RES-copilot-plugin-parity-with-the-spexcode]] residual gap). Every spelling below maps
+// to the Claude-side `mcp__heyspex__<tool>` the gates and `.claude/settings.json` matchers already use:
+//   mcp__heyspex__heyspex_x  mcp__plugin_heyspex_heyspex__heyspex_x  heyspex/heyspex_x  heyspex.heyspex_x  heyspex_x
+const HEYSPEX_MCP_NAME = /^(?:mcp__plugin_heyspex_heyspex__|mcp__heyspex__|heyspex[/.:])?(heyspex_[A-Za-z0-9_]+)$/;
+
+/**
+ * @param {unknown} name
+ * @returns {{ name: string, suffix: string } | null} null when `name` is not a HeySpex MCP tool in a known spelling
+ */
+export function normalizeMcpToolName(name) {
+  if (typeof name !== 'string') return null;
+  const m = HEYSPEX_MCP_NAME.exec(name.trim());
+  return m ? { name: `mcp__heyspex__${m[1]}`, suffix: m[1] } : null;
+}
+
+const COPILOT_TOOL_TO_CLAUDE = {
+  bash: 'Bash',
+  powershell: 'PowerShell',
+  create: 'Write',
+  edit: 'Edit',
+  apply_patch: 'Edit',
+  view: 'Read',
+  task: 'Agent',
+};
+
+function parseArgs(value) {
+  if (value && typeof value === 'object') return value;
+  if (typeof value !== 'string' || !value.trim()) return {};
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Either Copilot payload shape -> the Claude-shaped payload every hook already reads. Never throws; a payload
+ * that is already Claude-shaped passes through with its `hook_event_name`, and unknown fields stay untouched.
+ * @param {unknown} payload
+ * @returns {Record<string, unknown>}
+ */
+export function normalizeCopilotPayload(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return {};
+  const p = /** @type {Record<string, any>} */ (payload);
+  const out = { ...p };
+  if (out.session_id === undefined && typeof p.sessionId === 'string') out.session_id = p.sessionId;
+  if (out.tool_name === undefined && typeof p.toolName === 'string') {
+    out.tool_name = COPILOT_TOOL_TO_CLAUDE[p.toolName] ?? p.toolName;
+  }
+  if (out.tool_input === undefined && p.toolArgs !== undefined) {
+    const args = { ...parseArgs(p.toolArgs) };
+    if (args.file_path === undefined && typeof args.path === 'string') args.file_path = args.path;
+    out.tool_input = args;
+  }
+  if (typeof out.tool_name === 'string') {
+    const mcp = normalizeMcpToolName(out.tool_name);
+    if (mcp) {
+      if (mcp.name !== out.tool_name && out.tool_name_original === undefined) out.tool_name_original = out.tool_name;
+      out.tool_name = mcp.name;
+      out.tool_name_suffix = mcp.suffix;
+    }
+  }
+  if (out.tool_response === undefined && p.toolResult !== undefined) out.tool_response = p.toolResult;
+  if (typeof out.hook_event_name !== 'string') {
+    if (out.tool_response !== undefined) out.hook_event_name = 'PostToolUse';
+    else if (out.tool_name !== undefined) out.hook_event_name = 'PreToolUse';
+    else if (typeof p.prompt === 'string') out.hook_event_name = 'UserPromptSubmit';
+  }
+  return out;
+}
+
+const body = (decision, reason) => JSON.stringify({ permissionDecision: decision, permissionDecisionReason: reason });
+
+/**
+ * A gate decision (decide.mjs shape) -> what a Copilot hook process emits. A deny is ALWAYS exit 0 with the
+ * JSON on stdout (exit 2 would lose the reason). `allow`, `inject` and warn-only rewrites print nothing on
+ * stdout (Copilot has no additionalContext channel for tool hooks).
+ * @param {{ id?: string, event?: unknown }} _gate
+ * @param {{ point?: string }} engineEvent
+ * @param {{ decision?: string, reason?: string, rewrite?: { ask?: boolean, warn?: boolean } }} decision
+ * @returns {{ exitCode: 0, stdout: string, stderr: string }}
+ */
+export function toCopilotResponse(_gate, engineEvent, decision) {
+  const kind = decision?.decision ?? 'allow';
+  const reason = String(decision?.reason ?? 'Denied by a HeySpex hook.');
+  if (kind === 'deny') {
+    const o = { permissionDecision: 'deny', permissionDecisionReason: reason };
+    // a Stop-time deny is a re-drive: carry the Claude stop shape too so either reader acts on it
+    if (engineEvent?.point === 'stop') Object.assign(o, { decision: 'block', reason });
+    return { exitCode: 0, stdout: JSON.stringify(o), stderr: '' };
+  }
+  if (kind === 'rewrite' && decision.rewrite?.ask) return { exitCode: 0, stdout: body('ask', reason), stderr: '' };
+  if (kind === 'rewrite' && decision.rewrite?.warn) {
+    return { exitCode: 0, stdout: '', stderr: reason.endsWith('\n') ? reason : `${reason}\n` };
+  }
+  return { exitCode: 0, stdout: '', stderr: '' };
+}
+
+/**
+ * Rewrite a Claude-dialect stdout blob (`{"hookSpecificOutput":{"permissionDecision":...}}`) into Copilot's
+ * top-level object. Anything else (already top-level, Stop `{decision:"block"}`, additionalContext, plain
+ * text) is returned unchanged. Used by the shared runner for hand-written hooks that print Claude JSON.
+ * @param {string} text
+ * @returns {string}
+ */
+export function rewriteStdoutForCopilot(text) {
+  try {
+    const o = JSON.parse(text);
+    const h = o?.hookSpecificOutput;
+    if (h && typeof h.permissionDecision === 'string') {
+      return body(h.permissionDecision, h.permissionDecisionReason ?? 'Denied by a HeySpex hook.');
+    }
+  } catch {
+    /* not JSON: pass through */
+  }
+  return text;
+}
+
+/**
+ * A hand-written hook that decided "deny" the legacy way (exit 2, reason on stderr) -> the Copilot JSON deny.
+ * @param {string} stderrText
+ * @returns {string}
+ */
+export function denyFromLegacyExit(stderrText) {
+  const reason = String(stderrText ?? '').replace(/\r/g, '').trim() || 'Denied by a HeySpex hook.';
+  return body('deny', reason);
+}
+
+/**
+ * VS Code's Local harness ignores hook matchers, so the runner re-applies them. True when ANY matcher admits the
+ * tool (an empty / `*` / `.*` matcher admits everything; an invalid regex fails open to "admit"). Matchers are
+ * Claude Code's: a regex that must match the WHOLE tool name.
+ * @param {string[]} matchers
+ * @param {string[]} toolNames every spelling of the tool (normalized first, original after)
+ * @returns {boolean}
+ */
+export function toolMatchesAnyMatcher(matchers, toolNames) {
+  if (!Array.isArray(matchers) || matchers.length === 0) return true;
+  const names = toolNames.filter((n) => typeof n === 'string' && n);
+  for (const m of matchers) {
+    if (typeof m !== 'string' || m === '' || m === '*' || m === '**') return true;
+    try {
+      const re = new RegExp(`^(?:${m})$`);
+      if (names.some((n) => re.test(n))) return true;
+    } catch {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** All spellings a gate matcher might name for this (normalized) payload's tool. */
+export function toolNameCandidates(payload) {
+  const names = [];
+  const add = (n) => { if (typeof n === 'string' && n && !names.includes(n)) names.push(n); };
+  add(payload?.tool_name);
+  add(payload?.tool_name_original);
+  if (typeof payload?.tool_name_suffix === 'string') add(`mcp__plugin_heyspex_heyspex__${payload.tool_name_suffix}`);
+  return names;
+}
+
+const CONTEXT_EVENTS = new Set(['SessionStart', 'PostToolUse', 'SubagentStart']);
+
+/**
+ * The ONE place the runner decides what a Copilot hook process may print. Guarantees: the result is '' or a
+ * single valid JSON object. Non-JSON output is dropped (Copilot ignores unparseable stdout anyway). Claude's
+ * `hookSpecificOutput` permission form becomes the top-level form. Copilot drops command-hook output on
+ * `UserPromptSubmit`, so a context-only result there prints nothing (a permission / block result still prints).
+ * For events that DO accept context (sessionStart, postToolUse, subagentStart) the Claude
+ * `hookSpecificOutput.additionalContext` is mirrored to the top-level `additionalContext` Copilot documents.
+ * @param {string} text raw buffered stdout
+ * @param {string} [eventName] normalized hook_event_name
+ * @returns {string}
+ */
+export function finalizeCopilotStdout(text, eventName) {
+  let o;
+  try {
+    o = JSON.parse(rewriteStdoutForCopilot(String(text ?? '')));
+  } catch {
+    return '';
+  }
+  if (!o || typeof o !== 'object' || Array.isArray(o)) return '';
+  const decided = typeof o.permissionDecision === 'string' || o.decision === 'block';
+  if (eventName === 'UserPromptSubmit' && !decided) return '';
+  const ctx = o.hookSpecificOutput?.additionalContext;
+  if (typeof ctx === 'string' && o.additionalContext === undefined && CONTEXT_EVENTS.has(String(eventName))) {
+    o = { ...o, additionalContext: ctx };
+  }
+  return JSON.stringify(o);
+}
+
+/**
+ * Append `extra` to a finished Copilot stdout blob's additionalContext (creating the object when stdout is
+ * empty). A permission decision is never touched. Returns the new stdout.
+ * @param {string} finalText '' or one JSON object
+ * @param {string} extra
+ * @returns {string}
+ */
+export function mergeAdditionalContext(finalText, extra) {
+  if (!extra) return finalText;
+  let o = {};
+  if (finalText) {
+    try { o = JSON.parse(finalText); } catch { return finalText; }
+    if (!o || typeof o !== 'object' || Array.isArray(o)) return finalText;
+  }
+  if (typeof o.permissionDecision === 'string') return finalText;
+  const prev = typeof o.additionalContext === 'string' ? o.additionalContext : o.hookSpecificOutput?.additionalContext;
+  const merged = typeof prev === 'string' && prev ? `${prev}
+
+${extra}` : extra;
+  o.additionalContext = merged;
+  if (o.hookSpecificOutput && typeof o.hookSpecificOutput === 'object') {
+    o.hookSpecificOutput = { ...o.hookSpecificOutput, additionalContext: merged };
+  }
+  return JSON.stringify(o);
+}

package/spexharness/src/adapters/detect-harness.mjs

@@ -0,0 +1,34 @@
+// spexharness/src/adapters/detect-harness.mjs
+//
+// Which agent harness is invoking this hook? ([[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]] Copilot
+// compatibility; contract: GitHub Docs "Hooks configuration", fetched 2026-10-16.) GitHub Copilot CLI runs the
+// hooks registered in `.claude/settings.json` too, but it speaks a different output dialect (ONE top-level
+// `{permissionDecision, permissionDecisionReason}` object, not `hookSpecificOutput`) and treats every
+// non-zero exit as a deny, so the shared runner must know when it is talking to Copilot.
+//
+// DETECTION IS POSITIVE-SIGNATURE ONLY - never "session_id missing". Pure: payload + env in, a string out.
+//   - explicit override  HEYSPEX_HARNESS = copilot | claude-code | cursor      (wins)
+//   - 'copilot'  the payload carries `timestamp` (absent from Claude Code payloads) AND no Cursor marker; or it
+//                is the camelCase config shape ({ sessionId, toolName, toolArgs } with no snake_case twins).
+//   - 'cursor'   `conversation_id` / `workspace_roots` / `cursor_version` present.
+//   - 'claude-code' a `hook_event_name` + `session_id` payload with none of the above.
+//   - 'unknown'  anything else (including a non-object payload). Callers treat unknown like claude-code.
+
+const OVERRIDES = new Set(['copilot', 'claude-code', 'cursor']);
+
+/**
+ * @param {unknown} payload parsed hook stdin (or null)
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {'claude-code' | 'copilot' | 'cursor' | 'unknown'}
+ */
+export function detectHarness(payload, env = process.env) {
+  const forced = String(env?.HEYSPEX_HARNESS ?? '').trim().toLowerCase();
+  if (OVERRIDES.has(forced)) return forced;
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return 'unknown';
+  const p = /** @type {Record<string, unknown>} */ (payload);
+  if ('conversation_id' in p || 'workspace_roots' in p || 'cursor_version' in p) return 'cursor';
+  const camel = ('toolName' in p || 'toolArgs' in p) && !('tool_name' in p);
+  if ('timestamp' in p || camel) return 'copilot';
+  if (typeof p.hook_event_name === 'string' && typeof p.session_id === 'string') return 'claude-code';
+  return 'unknown';
+}

package/spexharness/src/gates/_shell-write-targets.mjs

@@ -0,0 +1,77 @@
+// spexharness/src/gates/_shell-write-targets.mjs
+//
+// Shared conservative shell-write scanner. Extracted from
+// env-vault-guard.decide.mjs (originally the same scanner as
+// guard-auto-memory-writes.mjs) so env-vault-guard and vault-write-tier-guard
+// (HS-FCNH) import ONE implementation instead of drifting copies.
+//
+// Pure: no fs, no process. It only recognises write-SHAPED commands whose
+// targets it can positively identify; callers pair it with a fail-closed
+// text scan (see `mentionsWriteVerb`) for everything it cannot parse
+// (heredocs, `python -c`, `node -e`, variable-expanded targets).
+
+const REDIRECT_RE = /(?:>>?|\|\s*tee(?:\s+-a)?)\s+("([^"]+)"|'([^']+)'|(\S+))/g;
+const CMD_RE =
+  /\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)\s+([^|;&\n]+)/g;
+// In-place editors: `sed -i`, `sed -ibak`, `sed --in-place`, `perl -pi -e`, `perl -i.bak`.
+const INPLACE_RE = /\b(?:sed|perl)\b([^|;&\n]*)/g;
+
+function isInPlaceFlag(token) {
+  return (
+    token === '--in-place' ||
+    token.startsWith('--in-place=') ||
+    /^-[A-Za-z]*i[A-Za-z0-9.]*$/.test(token)
+  );
+}
+
+/** Same conservative shell scanner as guard-auto-memory-writes.mjs, plus in-place editors. */
+export function extractShellTargets(command) {
+  if (!command || typeof command !== 'string') return [];
+  const targets = new Set();
+  for (const m of command.matchAll(REDIRECT_RE)) targets.add(m[2] ?? m[3] ?? m[4]);
+  for (const m of command.matchAll(CMD_RE)) {
+    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);
+    }
+  }
+  // sed -i / perl -i / --in-place: every non-flag operand is a candidate
+  // (the script operand rides along harmlessly — callers match by path).
+  for (const m of command.matchAll(INPLACE_RE)) {
+    const tokens = m[1].trim().split(/\s+/).filter(Boolean);
+    if (!tokens.some(isInPlaceFlag)) continue;
+    for (const t of tokens) if (!t.startsWith('-')) targets.add(t);
+  }
+  // PowerShell: -Path / -FilePath / -LiteralPath <target> on a write cmdlet.
+  if (/\b(?:New-Item|Set-Content|Out-File|Add-Content|Clear-Content)\b/i.test(command)) {
+    for (const m of command.matchAll(/-(?:Path|FilePath|LiteralPath)\s+("([^"]+)"|'([^']+)'|(\S+))/gi))
+      targets.add(m[2] ?? m[3] ?? m[4]);
+  }
+  for (const t of extractInterpreterWriteTargets(command)) targets.add(t);
+  return [...targets]
+    .map((t) => t.replace(/^['"]|['"]$/g, ''))
+    .filter(Boolean)
+    .filter((t) => !/[$`(){}]/.test(t));
+}
+
+/**
+ * Literal-path writes inside inline interpreter bodies: python `open('p','w')`,
+ * node `writeFileSync('p', ...)`. Only a literal path that is the write call's
+ * FIRST argument counts; a body that merely reads or prints is not a write.
+ */
+export function extractInterpreterWriteTargets(command) {
+  if (!command || typeof command !== 'string') return [];
+  const out = [];
+  const pyOpen = /\bopen\s*\(\s*(['"])([^'"]+)\1\s*,\s*['"][wax]/g;
+  const nodeWrite = /\b(?:writeFile|writeFileSync|appendFile|appendFileSync)\s*\(\s*(['"`])([^'"`]+)\1/g;
+  for (const m of command.matchAll(pyOpen)) out.push(m[2]);
+  for (const m of command.matchAll(nodeWrite)) out.push(m[2]);
+  return out;
+}

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

@@ -67,8 +67,9 @@ const REPO_ROOT = path.resolve(HERE, '..', '..', '..');
 
 // Copied verbatim from the original (private consts there) — see the
 // judgment-call note above.
-const GROUNDING_ARTIFACT_REL = path.join('.heyspex', 'research-grounding.json');
-const GROUNDING_FIELDS = ['already_built', 'already_decided', 'owner_reference', 'residual_delta'];
+// 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': {
@@ -141,7 +142,7 @@ function isGroundOnlyResearchLaunch(toolName, input) {
   return typeof input.skill === 'string' && /^hs-res$/i.test(input.skill.trim());
 }
 
-function defaultReadGroundingArtifact(root) {
+export function defaultReadGroundingArtifact(root) {
   try {
     const full = path.join(root, GROUNDING_ARTIFACT_REL);
     if (!fs.existsSync(full)) return null;

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 };