heyspex 0.1.0 → 0.2.1

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