heyspex 0.2.0 → 0.2.1

package/scripts/lib/directive-obligations.mjs

@@ -0,0 +1,349 @@
+// scripts/lib/directive-obligations.mjs
+//
+// [[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]] - "a directive was issued and still
+// owes a capture" as DURABLE state. The capture_on_idea directive injected at UserPromptSubmit is
+// advisory text; nothing recorded that it was issued, so when the agent skipped the capture every
+// downstream gate failed open (they all key on a capture that exists). This module is the pure
+// core of the fix: read / arm / satisfy / waive / isOutstanding over ONE state file,
+// `.heyspex/directive-obligations.json`, scoped by session id:
+//
+//   { session_id, prompt_count, claims: [spec ids], build_waived,
+//     obligations: [ { id, kind: "capture", prompt_n, issued_at, prompt_sha,
+//                      satisfied: false, waived: null, stop_blocked_at? } ] }
+//
+// Root convention: the same as `.heyspex/capture-gate-state.json` (scripts/lib/capture-execution-guard.mjs):
+// the project root the hook runs in (CLAUDE_PROJECT_DIR, else the payload cwd, else this checkout).
+//
+// Consumers:
+//   - scripts/lib/capture-verbatim-append.mjs      (UserPromptSubmit: arms)
+//   - spexharness/src/gates/directive-obligation-gate.mjs (PreToolUse deny, PostToolUse satisfy, Stop re-drive)
+//
+// DEPENDENCY-FREE on purpose (node:* only): this ships in the customer hook kit (customer-kit.mjs
+// scope 'customer'), so it must not import any platform-only module.
+//
+// FAIL OPEN everywhere: an unreadable or malformed state file, a missing session id, an expired
+// obligation all read as "nothing owed". Only a fresh, this-session, unsatisfied, unwaived
+// obligation can ever refuse anything.
+//
+// Several agents may share one project root: the top level is the most recent writer's record and the others
+// are parked under `others` (see the state-file section), so no session erases another's obligation.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { hasFreshNoClaimSignal } from '../claude-hooks/claim-liveness-shared.mjs';
+
+export const OBLIGATIONS_REL = path.join('.heyspex', 'directive-obligations.json');
+/** Same ceiling as capture-execution-guard's STATE_MAX_AGE_MS: an obligation older than this stops gating. */
+export const OBLIGATION_TTL_MS = 6 * 60 * 60 * 1000;
+export const MAX_OBLIGATIONS = 20;
+
+/** Owner/env kill switch; the config twin is agent_behaviors.directive_obligation_gate.enabled. */
+export const GATE_OFF_ENV = 'HEYSPEX_DIRECTIVE_OBLIGATION_GATE_OFF';
+export const GATE_CONFIG_KEY = 'agent_behaviors.directive_obligation_gate.enabled';
+/** Narrower config key: turns off ONLY the claim-before-build rule. */
+export const CLAIM_RULE_CONFIG_KEY = 'agent_behaviors.directive_obligation_gate.claim_before_build.enabled';
+
+// ── tool-name classification (suffix match: bare, mcp__heyspex__ and plugin-scoped spellings) ──
+
+/** A tool call that discharges a capture obligation. */
+const SATISFYING_TOOL_RE = /(?:^|__)heyspex_(?:update_capture|promote_capture\w*|file_spec)$/;
+const CLAIM_ACQUIRE_RE = /(?:^|__)heyspex_(?:claim_spec|claim_acquire|claim_file)$/;
+const CLAIM_RELEASE_RE = /(?:^|__)heyspex_(?:release_spec|claim_release|defer_spec)$/;
+
+export function isSatisfyingTool(toolName, toolInput) {
+  const name = String(toolName ?? '');
+  if (SATISFYING_TOOL_RE.test(name)) return true;
+  if (name === 'Skill') {
+    const skill = String(toolInput?.skill ?? toolInput?.name ?? '');
+    return /(?:^|:)hs-capture$/.test(skill.trim().replace(/^\//, ''));
+  }
+  return false;
+}
+export const isClaimAcquireTool = (toolName) => CLAIM_ACQUIRE_RE.test(String(toolName ?? ''));
+export const isClaimReleaseTool = (toolName) => CLAIM_RELEASE_RE.test(String(toolName ?? ''));
+
+/** True when a tool response says the call failed (a failed capture write must not discharge anything). */
+export function toolResultFailed(toolResult) {
+  if (!toolResult || typeof toolResult !== 'object') return false;
+  return toolResult.is_error === true || toolResult.isError === true || toolResult.success === false;
+}
+
+// ── negation ────────────────────────────────────────────────────────────────
+
+// "don't capture this", "no need to log it", "without capturing", "skip the capture". Prompts that say
+// this must arm nothing: the owner's word stands (DISCARD_RE in capture-verbatim-append covers the
+// line-initial forms; this covers the mid-sentence ones).
+const CAPTURE_NEGATED_RE =
+  /\b(?:don'?t|do\s+not|dont|never|no\s+need\s+to|no\s+need\s+for|without|skip(?:ping)?|stop)\b[^.!?\n]{0,40}\b(?:captur\w*|log(?:ging)?\s+(?:it|this|that)|record(?:ing)?\s+(?:it|this|that))/i;
+const NO_CAPTURE_RE = /\bno\s+captures?\b/i;
+
+export function isCaptureNegated(prompt) {
+  const s = String(prompt ?? '').replace(/’/g, "'");
+  return CAPTURE_NEGATED_RE.test(s) || NO_CAPTURE_RE.test(s);
+}
+
+// ── path classification ─────────────────────────────────────────────────────
+
+const CODE_EXT_RE =
+  /\.(?:mjs|cjs|js|jsx|ts|tsx|mts|cts|cs|py|go|rs|rb|java|kt|swift|sql|css|scss|html|ps1|sh|vue|svelte|php|c|cc|cpp|h|hpp|json|ya?ml|toml|xaml|csproj|sln)$/i;
+const EXEMPT_DIR_RE = /(?:^|\/)(?:specs|\.heyspex|\.claude|\.cursor|\.git|node_modules)(?:\/|$)/;
+
+function norm(p) {
+  return String(p ?? '').replace(/\\/g, '/');
+}
+
+function underRoot(file, root) {
+  if (!root) return false;
+  const f = norm(path.resolve(file));
+  const r = norm(path.resolve(root)).replace(/\/+$/, '');
+  const eq = process.platform === 'win32' ? (a, b) => a.toLowerCase() === b.toLowerCase() : (a, b) => a === b;
+  return eq(f, r) || (f.length > r.length && eq(f.slice(0, r.length), r) && f[r.length] === '/');
+}
+
+/**
+ * Is `p` a PRODUCT-CODE path - a code/config file outside the vault container, the vault root,
+ * `.heyspex/`, `.claude/`, `.git/` and `node_modules/`? Writes to those are never gated.
+ * @param {string} p
+ * @param {{ cwd?: string, vaultRoot?: string }} [opts]
+ */
+export function isProductCodePath(p, { cwd, vaultRoot } = {}) {
+  const raw = String(p ?? '').trim();
+  if (!raw) return false;
+  const abs = path.isAbsolute(raw) ? raw : path.resolve(cwd ?? process.cwd(), raw);
+  const n = norm(abs);
+  if (EXEMPT_DIR_RE.test(n)) return false;
+  // outside the project tree (a scratchpad, the sibling vault checkout, a temp dir) is never product code
+  if (cwd && !underRoot(abs, cwd)) return false;
+  if (vaultRoot && underRoot(abs, vaultRoot)) return false;
+  return CODE_EXT_RE.test(n);
+}
+
+// ── state file ──────────────────────────────────────────────────────────────
+//
+// SHAPE: the top level is the MOST RECENT writing session's record (`session_id`, `obligations`, ...) - the
+// documented shape. When a different session writes, the previous top-level record is parked under `others`
+// (keyed by session id, TTL-pruned, capped) and restored when that session writes or reads again, so two
+// agents sharing one project root never erase each other's obligations.
+
+const SESSION_FIELDS = ['prompt_count', 'claims', 'build_waived', 'captured_at', 'obligations', 'updated_at'];
+export const MAX_PARKED_SESSIONS = 8;
+
+function emptyRecord() {
+  return { prompt_count: 0, claims: [], build_waived: false, obligations: [] };
+}
+
+function pickRecord(full) {
+  const rec = {};
+  for (const k of SESSION_FIELDS) if (full[k] !== undefined) rec[k] = full[k];
+  return rec;
+}
+
+function loadFull(root) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(root, OBLIGATIONS_REL), 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+    if (parsed.obligations !== undefined && !Array.isArray(parsed.obligations)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * This session's record (with `session_id` set), or - when the file holds no record for it - the raw
+ * top-level object (whose `session_id` then differs, so every `outstanding(state, sessionId)` check reads
+ * "nothing owed"). Null when the file is absent / unreadable / malformed: every caller fails open on null.
+ * @param {string} root
+ * @param {string} [sessionId]
+ */
+export function readObligations(root, sessionId) {
+  const full = loadFull(root);
+  if (!full || !sessionId || full.session_id === sessionId) return full;
+  const parked = full.others?.[sessionId];
+  return parked && typeof parked === 'object' ? { ...emptyRecord(), ...parked, session_id: sessionId } : full;
+}
+
+/** Atomic best-effort write (a failed write only means the gate fails open). */
+export function writeObligations(root, state) {
+  try {
+    const full = path.join(root, OBLIGATIONS_REL);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    const tmp = `${full}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify({ ...state, written_at: new Date().toISOString() }, null, 2) + '\n', 'utf8');
+    fs.renameSync(tmp, full);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read-modify-write ONE session's record. `fn(record)` mutates it; the file is rotated so this session is the
+ * top-level record and the previous one is parked. Returns whatever `fn` returns, or null when the write failed.
+ */
+function mutate(root, sessionId, fn, now = Date.now()) {
+  if (!root || typeof sessionId !== 'string' || !sessionId.trim()) return null;
+  const sid = sessionId.trim();
+  const full = loadFull(root);
+  let others = {};
+  let rec = emptyRecord();
+  if (full) {
+    others = full.others && typeof full.others === 'object' ? { ...full.others } : {};
+    if (full.session_id === sid) {
+      rec = { ...rec, ...pickRecord(full) };
+    } else {
+      if (typeof full.session_id === 'string' && full.session_id) others[full.session_id] = pickRecord(full);
+      if (others[sid]) rec = { ...rec, ...others[sid] };
+      delete others[sid];
+    }
+  }
+  if (!Array.isArray(rec.obligations)) rec.obligations = [];
+  if (!Array.isArray(rec.claims)) rec.claims = [];
+  const out = fn(rec);
+  rec.updated_at = new Date(now).toISOString();
+  const keep = Object.entries(others)
+    .filter(([, o]) => now - Date.parse(o?.updated_at ?? 0) <= OBLIGATION_TTL_MS)
+    .sort((a, b) => Date.parse(b[1].updated_at) - Date.parse(a[1].updated_at))
+    .slice(0, MAX_PARKED_SESSIONS);
+  const next = { session_id: sid, ...rec, others: Object.fromEntries(keep) };
+  return writeObligations(root, next) ? (out === undefined ? true : out) : null;
+}
+
+export function promptSha(prompt) {
+  return crypto.createHash('sha256').update(String(prompt ?? '')).digest('hex').slice(0, 16);
+}
+
+/**
+ * Record "a capture directive was issued for this prompt and still owes a capture".
+ * Idempotent per (session, prompt): re-arming the same prompt text adds nothing.
+ * @returns {object|null} the obligation, or null (no session id / write failed)
+ */
+export function armCapture({ root, sessionId, prompt, now = Date.now() }) {
+  return mutate(root, sessionId, (rec) => {
+    const sha = promptSha(prompt);
+    const existing = rec.obligations.find((o) => o.prompt_sha === sha && o.kind === 'capture' && !o.satisfied && !o.waived);
+    if (existing) return existing;
+    rec.prompt_count = (Number(rec.prompt_count) || 0) + 1;
+    const ob = {
+      id: `cap-${rec.prompt_count}-${sha.slice(0, 8)}`,
+      kind: 'capture',
+      prompt_n: rec.prompt_count,
+      issued_at: new Date(now).toISOString(),
+      prompt_sha: sha,
+      satisfied: false,
+      waived: null,
+    };
+    rec.obligations = [...rec.obligations, ob].slice(-MAX_OBLIGATIONS);
+    return ob;
+  }, now);
+}
+
+/**
+ * A capture tool call was seen: discharge every outstanding obligation of this session and remember
+ * that this session has captured (a road to code for the claim-before-build rule).
+ */
+export function satisfyAll({ root, sessionId, now = Date.now() }) {
+  return mutate(root, sessionId, (rec) => {
+    for (const o of rec.obligations) {
+      if (!o.satisfied && !o.waived) {
+        o.satisfied = true;
+        o.satisfied_at = new Date(now).toISOString();
+      }
+    }
+    rec.captured_at = new Date(now).toISOString();
+  }, now) !== null;
+}
+
+/** Owner-visible waiver of every outstanding obligation (the break-glass in data form). */
+export function waiveAll({ root, sessionId, reason = 'waived', now = Date.now() }) {
+  const cur = readObligations(root, sessionId);
+  if (!isOutstanding(cur, sessionId, now)) return false;
+  return mutate(root, sessionId, (rec) => {
+    for (const o of rec.obligations) {
+      if (!o.satisfied && !o.waived) o.waived = { reason: String(reason), at: new Date(now).toISOString() };
+    }
+  }, now) !== null;
+}
+
+/** The outstanding (unsatisfied, unwaived, unexpired) obligations of `sessionId` in `state`. */
+export function outstanding(state, sessionId, now = Date.now()) {
+  if (!state || !sessionId || state.session_id !== sessionId || !Array.isArray(state.obligations)) return [];
+  return state.obligations.filter((o) => {
+    if (!o || o.satisfied || o.waived) return false;
+    const issued = Date.parse(o.issued_at ?? '');
+    return Number.isFinite(issued) && now - issued <= OBLIGATION_TTL_MS;
+  });
+}
+
+export function isOutstanding(state, sessionId, now = Date.now()) {
+  return outstanding(state, sessionId, now).length > 0;
+}
+
+/** Mark the Stop re-drive as spent so a second Stop never loops. */
+export function markStopBlocked({ root, sessionId, now = Date.now() }) {
+  return mutate(root, sessionId, (rec) => {
+    for (const o of outstanding({ session_id: sessionId, obligations: rec.obligations }, sessionId, now)) {
+      o.stop_blocked_at = new Date(now).toISOString();
+    }
+  }, now) !== null;
+}
+
+/** Record a claim acquire / release observed in PostToolUse (the claim-before-build rule reads it). */
+export function trackClaim({ root, sessionId, specId, release = false }) {
+  return mutate(root, sessionId, (rec) => {
+    const id = String(specId ?? '*');
+    const set = new Set(rec.claims);
+    if (release) {
+      if (id === '*') set.clear();
+      else { set.delete(id); set.delete('*'); }
+    } else {
+      set.add(id);
+    }
+    rec.claims = [...set];
+  }) !== null;
+}
+
+// ── "does this session already have a road to code?" (claim-before-build) ────
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Does `.heyspex/active-claims.json` (or HEYSPEX_CLAIMS_PATH) carry a claim for this session? */
+export function sessionHoldsClaimOnDisk(root, sessionId, env = process.env) {
+  const p = String(env.HEYSPEX_CLAIMS_PATH ?? '').trim() || path.join(root, '.heyspex', 'active-claims.json');
+  const claims = readJson(p)?.claims;
+  if (!claims || typeof claims !== 'object') return false;
+  return Object.values(claims).some((c) => c?.sessionId === sessionId);
+}
+
+/** Is a capture on deck for THIS session (fresh capture-gate-state.json naming one)? */
+export function sessionHasCaptureOnDeck(root, sessionId, now = Date.now()) {
+  const s = readJson(path.join(root, '.heyspex', 'capture-gate-state.json'));
+  if (!s || !s.capture_id || s.session_id !== sessionId) return false;
+  const at = Date.parse(s.written_at ?? '');
+  return Number.isFinite(at) && now - at <= OBLIGATION_TTL_MS;
+}
+
+/**
+ * Has this session a road to code? Aligned with claim-before-code-gate: claim-before-build denies ONLY when this
+ * session's claim-liveness heartbeat has CONFIRMED there is no active claim (a fresh `noClaimUntil` in
+ * .heyspex/claim-liveness-cache.json) - in prod mode claims live in the cloud, so "no local claim record" proves
+ * nothing and a heartbeat that has not spoken fails OPEN. Positive signals (an explicit waiver, a claim recorded
+ * by the PostToolUse half, a capture write, a claim on disk, an on-deck capture) open the road regardless.
+ */
+export function hasRoadToCode({ root, sessionId, state, now = Date.now(), env = process.env }) {
+  if (state?.session_id === sessionId) {
+    if (state.build_waived === true || state.captured_at) return true;
+    if (Array.isArray(state.claims) && state.claims.length > 0) return true;
+    if (Array.isArray(state.obligations) && state.obligations.some((o) => o?.satisfied === true || o?.waived)) return true;
+  }
+  if (sessionHoldsClaimOnDisk(root, sessionId, env) || sessionHasCaptureOnDeck(root, sessionId, now)) return true;
+  return !hasFreshNoClaimSignal(sessionId, root);
+}

package/scripts/lib/hook-dispositions.mjs

@@ -0,0 +1,210 @@
+// hook-dispositions.mjs - ONE table: what each HeySpex hook becomes on each host.
+//
+// Source: [[HS-0GBS-CTF8-RES-copilot-plugin-parity-with-the-spexcode]] ("Enforcement parity matrix"
+// and "Every hook, with event and matcher"), plus scripts/cursor-hooks/manifest.mjs for Cursor.
+// Parity is not identity: this table is the published statement of where a host enforces a gate
+// as a hard deny / re-drive, where it only advises, and where it cannot run the gate at all.
+//
+// Disposition vocabulary (per hook, per host):
+//   mapped             the host has a trigger and the gate keeps its meaning (hard deny, hard re-drive,
+//                      or an advisory/side effect that IS delivered).
+//   advisory-degraded  the hook is registered (or registrable) but its effect is weaker than on Claude
+//                      Code (output dropped, channel changed, dormant until armed). `note` says how.
+//   unportable         the host has no trigger. `control` names what covers the gap instead.
+//   not-shipped        platform-scoped hook (heyspex-app development machinery); never installed in a
+//                      customer repo, so it has no customer-host disposition.
+//
+// This module is dependency-free on purpose (customer-kit.mjs and the tests import it; it must not
+// import them back). The parity test (hook-dispositions.test.mjs) ties it to CLAUDE_HOOK_ROWS, the
+// generated plugin hooks.json, the Cursor manifest and the cloud-agent manifest.
+
+/** @typedef {'claude-code' | 'cursor' | 'copilot'} Host */
+/** @typedef {'mapped' | 'advisory-degraded' | 'unportable' | 'not-shipped'} Disposition */
+/** @typedef {{ disposition: Disposition, note?: string, control?: string }} Entry */
+
+export const HOSTS = Object.freeze(['claude-code', 'cursor', 'copilot']);
+export const DISPOSITIONS = Object.freeze(['mapped', 'advisory-degraded', 'unportable', 'not-shipped']);
+
+/** @param {string} [note] */
+const mapped = (note) => Object.freeze({ disposition: 'mapped', ...(note ? { note } : {}) });
+/** @param {string} note */
+const degraded = (note) => Object.freeze({ disposition: 'advisory-degraded', note });
+/** @param {string} control */
+const unportable = (control) => Object.freeze({ disposition: 'unportable', control });
+const notShipped = Object.freeze({ disposition: 'not-shipped' });
+
+const CC = mapped();
+
+// Shared wordings.
+const COPILOT_PROMPT_DROPPED =
+  'Copilot drops command-hook output on userPromptSubmitted (no prompt-time context channel); the text moves to sessionStart / .github/copilot-instructions.md.';
+const CURSOR_PROMPT_USER_MESSAGE =
+  'Cursor beforeSubmitPrompt honors user_message only (no additional_context): the text surfaces in the transcript instead of as invisible context.';
+const COPILOT_NO_PLAN_TOOL =
+  'MCP preflight refusals (heyspex_claim_spec / heyspex_submit_for_review / heyspex_save_research) + .github/copilot-instructions.md plan rule (state the plan in chat, claim the spec before editing) + HS-20SW directive-obligation-gate claim-before-build deny';
+
+/**
+ * hook name -> per-host entry. Keyed by the token after `_run.mjs` in CLAUDE_HOOK_ROWS.
+ * @type {Readonly<Record<string, Readonly<Record<Host, Entry>>>>}
+ */
+export const HOOK_DISPOSITIONS = Object.freeze({
+  // ── customer: session start / compaction ──────────────────────────────────
+  'wip-checkpoint': {
+    'claude-code': CC,
+    cursor: mapped('preCompact is relayed as SessionStart(compact).'),
+    copilot: mapped('sessionStart additionalContext is delivered; the preCompact leg writes WIP only (no output channel), re-injected at the next sessionStart.'),
+  },
+  'inject-doctrine': { 'claude-code': CC, cursor: mapped(), copilot: mapped('sessionStart additionalContext.') },
+  'check-auto-memory-budget': { 'claude-code': CC, cursor: mapped(), copilot: mapped('sessionStart additionalContext.') },
+  'check-claude-md-budget': { 'claude-code': CC, cursor: mapped(), copilot: mapped('sessionStart additionalContext.') },
+  'git-reflog-audit': { 'claude-code': CC, cursor: mapped(), copilot: mapped('sessionStart additionalContext and agentStop.') },
+  'vault-mirror-catchup': { 'claude-code': CC, cursor: mapped(), copilot: mapped('Detached side effect on sessionStart.') },
+
+  // ── customer: every user turn ─────────────────────────────────────────────
+  'preflight-reminder': {
+    'claude-code': CC,
+    cursor: degraded(CURSOR_PROMPT_USER_MESSAGE),
+    copilot: degraded(`${COPILOT_PROMPT_DROPPED} Real enforcement is the MCP preflight refusal.`),
+  },
+  'intent-classifier-trigger': {
+    'claude-code': CC,
+    cursor: degraded(CURSOR_PROMPT_USER_MESSAGE),
+    copilot: degraded(
+      `${COPILOT_PROMPT_DROPPED} The hook still runs and arms obligation state; the HS-20SW directive-obligation-gate turns that state into a hard deny.`,
+    ),
+  },
+  'inject-communication-style': {
+    'claude-code': CC,
+    cursor: degraded(CURSOR_PROMPT_USER_MESSAGE),
+    copilot: degraded(COPILOT_PROMPT_DROPPED),
+  },
+  'inject-vault-context': {
+    'claude-code': CC,
+    cursor: degraded(CURSOR_PROMPT_USER_MESSAGE),
+    copilot: degraded(`${COPILOT_PROMPT_DROPPED} Per-prompt vault retrieval has no Copilot channel at all.`),
+  },
+
+  // ── customer: before a tool call (hard gates) ─────────────────────────────
+  'git-identity-guard': { 'claude-code': CC, cursor: mapped('beforeShellExecution. Always on.'), copilot: mapped('preToolUse on bash/powershell. Always on.') },
+  'vault-write-tier-guard': { 'claude-code': CC, cursor: mapped(), copilot: mapped('preToolUse on create/edit/bash/powershell.') },
+  'settings-write-gate': { 'claude-code': CC, cursor: mapped(), copilot: mapped('preToolUse on create/edit/bash/powershell and the MCP settings tool.') },
+  'emit-claim-status': { 'claude-code': CC, cursor: mapped(), copilot: mapped('Telemetry on preToolUse/postToolUse/agentStop; the cloud agent needs a network allow rule for the console.') },
+  'enforce-vault-naming': { 'claude-code': CC, cursor: mapped(), copilot: mapped('preToolUse on create/bash/powershell.') },
+  'guard-auto-memory-writes': { 'claude-code': CC, cursor: mapped(), copilot: mapped('preToolUse on create/bash/powershell.') },
+  'directive-obligation-gate': {
+    'claude-code': CC,
+    cursor: mapped(),
+    copilot: mapped('HS-20SW: hard deny on task/create/edit/write-shaped shell while a capture obligation is unmet; the only hard capture-on-idea guarantee on Copilot.'),
+  },
+  'claim-before-code-gate': {
+    'claude-code': CC,
+    cursor: degraded('Armed only by plan-exit-ingest-gate, which has no Cursor trigger, so it stays dormant; covered by the HS-20SW claim-before-build rule.'),
+    copilot: degraded('Armed only by plan-exit-ingest-gate, which has no Copilot trigger (no ExitPlanMode tool), so it stays dormant; covered by the HS-20SW claim-before-build rule.'),
+  },
+  'capture-workflow-gate': {
+    'claude-code': CC,
+    cursor: mapped(),
+    copilot: mapped('preToolUse on the MCP heyspex_file_spec tool; MCP tool naming in hook payloads is unverified live (matched by suffix).'),
+  },
+  'diagnose-capture-reminder': {
+    'claude-code': CC,
+    cursor: mapped('preToolUse agent_message delivers the reminder.'),
+    copilot: degraded('Copilot preToolUse has no context channel for an inject, so this advisory is silent (lost).'),
+  },
+  'git-stash-gate': {
+    'claude-code': CC,
+    cursor: mapped(),
+    copilot: mapped('The Claude "ask" becomes a deny where no user is present (cloud agent, CLI autopilot).'),
+  },
+  'research-protocol-gate': { 'claude-code': CC, cursor: mapped('Always on.'), copilot: mapped('preToolUse on web_fetch/web_search and the MCP save_research tool. Always on; the MCP refusal duplicates it.') },
+  'research-method-guard': {
+    'claude-code': CC,
+    cursor: mapped('preToolUse with a Skill|Workflow tool filter. Always on.'),
+    copilot: unportable('MCP preflight refusal on heyspex_save_research (hard floor, hook-independent) + .github/copilot-instructions.md research rule; Copilot has no Skill or Workflow tool to hook.'),
+  },
+  'deep-research-cost-gate': {
+    'claude-code': CC,
+    cursor: mapped('preToolUse with a Workflow|Skill tool filter.'),
+    copilot: unportable('MCP preflight refusal on heyspex_save_research + .github/copilot-instructions.md cost-confirmation rule; Copilot has no Skill or Workflow tool to hook.'),
+  },
+  'plan-review-gate': {
+    'claude-code': CC,
+    cursor: unportable('.cursor/rules/plan-review-required.mdc (always-on rule)'),
+    copilot: unportable(COPILOT_NO_PLAN_TOOL),
+  },
+  'plan-exit-ingest-gate': {
+    'claude-code': CC,
+    cursor: unportable('.cursor/rules/plan-review-required.mdc + spec-creation-linkage.mdc'),
+    copilot: unportable(COPILOT_NO_PLAN_TOOL),
+  },
+
+  // ── customer: end of turn / session ───────────────────────────────────────
+  'naughty-list-gate': { 'claude-code': CC, cursor: mapped('stop followup_message re-drive.'), copilot: mapped('agentStop {decision:"block"} re-drive, capped at 8 consecutive blocks.') },
+  'id-display-format-gate': { 'claude-code': CC, cursor: mapped('stop followup_message re-drive.'), copilot: mapped('agentStop re-drive; reads the transcript (format is not a stable API).') },
+  'epic-milestone-phrasing-gate': { 'claude-code': CC, cursor: mapped('stop followup_message re-drive.'), copilot: mapped('agentStop re-drive; reads the transcript (format is not a stable API).') },
+  'enforce-session-sequence': { 'claude-code': CC, cursor: mapped('stop followup_message re-drive.'), copilot: mapped('agentStop re-drive, capped at 8 consecutive blocks.') },
+  'notify-status-flip': { 'claude-code': CC, cursor: mapped(), copilot: mapped('Side effect on postToolUse.') },
+  'close-terminal-on-ship': { 'claude-code': CC, cursor: mapped(), copilot: mapped('Side effect on postToolUse / sessionEnd.') },
+  'scripts/stamp-provenance-on-edit.mjs': { 'claude-code': CC, cursor: mapped(), copilot: mapped('Side effect on postToolUse.') },
+  'session-end': { 'claude-code': CC, cursor: mapped(), copilot: mapped('sessionEnd.') },
+
+  // ── platform: heyspex-app development machinery (never installed in a customer repo) ──
+  'inject-dev-server-awareness': { 'claude-code': CC, cursor: mapped(), copilot: notShipped },
+  'inject-coo-seat': { 'claude-code': CC, cursor: mapped(), copilot: notShipped },
+  'coo-guard-check': { 'claude-code': CC, cursor: mapped(), copilot: notShipped },
+  'coo-denylist-gate': { 'claude-code': CC, cursor: mapped(), copilot: notShipped },
+  'agent-spawn-delegation-gate': { 'claude-code': CC, cursor: mapped('subagentStart.'), copilot: notShipped },
+  'capture-execution-gate': { 'claude-code': CC, cursor: mapped('beforeShellExecution + subagentStart.'), copilot: notShipped },
+  'check-mcp-freshness-hook': { 'claude-code': CC, cursor: mapped(), copilot: notShipped },
+  'dev-server-task-reminder': { 'claude-code': CC, cursor: mapped(), copilot: notShipped },
+  'env-vault-guard': { 'claude-code': CC, cursor: mapped('Always on.'), copilot: notShipped },
+  'log-session-activity': { 'claude-code': CC, cursor: mapped(), copilot: notShipped },
+});
+
+/**
+ * The entry for one hook on one host, or null when the hook is not in the table.
+ * @param {string} hook
+ * @param {Host} host
+ * @returns {Entry | null}
+ */
+export function dispositionFor(hook, host) {
+  return HOOK_DISPOSITIONS[hook]?.[host] ?? null;
+}
+
+/**
+ * Every hook name whose disposition on `host` is `kind`, in table order.
+ * @param {Host} host
+ * @param {Disposition} kind
+ * @returns {string[]}
+ */
+export function listByDisposition(host, kind) {
+  return Object.keys(HOOK_DISPOSITIONS).filter((h) => HOOK_DISPOSITIONS[h][host]?.disposition === kind);
+}
+
+/** Per-host counts, for reports and docs. */
+export function dispositionCounts() {
+  const out = {};
+  for (const host of HOSTS) {
+    out[host] = Object.fromEntries(DISPOSITIONS.map((k) => [k, listByDisposition(host, k).length]));
+  }
+  return out;
+}
+
+const escCell = (s) => String(s).replace(/\|/g, '\\|');
+
+/**
+ * The published list of customer gates that are weaker than, or absent from, a host, as a markdown table.
+ * Generated here so the README / docs can be checked against it (see hook-dispositions.test.mjs).
+ * @param {Host} host
+ * @param {(hook: string) => boolean} isCustomer
+ */
+export function renderGapTable(host, isCustomer) {
+  const rows = [];
+  for (const kind of /** @type {const} */ (['unportable', 'advisory-degraded'])) {
+    for (const hook of listByDisposition(host, kind).filter(isCustomer)) {
+      const e = HOOK_DISPOSITIONS[hook][host];
+      rows.push(`| \`${hook}\` | ${kind} | ${escCell(kind === 'unportable' ? e.control : e.note)} |`);
+    }
+  }
+  return ['| Gate | Disposition | Compensating control / what is lost |', '| --- | --- | --- |', ...rows].join('\n');
+}

package/scripts/lib/hook-vault-header.mjs

@@ -0,0 +1,30 @@
+/**
+ * hook-vault-header.mjs — the repo-bound `x-heyspex-vault-id` header for hook
+ * and script HTTP calls to the console (owner principles P1/P2, 2026-10-16).
+ *
+ * A hook runs inside the repo an agent is opened in; the vault it talks about
+ * is that repo's bound vault (heyspex.yaml / satellite marker / manifest pin),
+ * never the account-wide active pointer. A bearer call that names no vault is
+ * refused by the console (409 vault-scope-required), which several hooks
+ * swallowed and then silently served stale disk data (diag HS-5M0G).
+ *
+ * `hookVaultHeaders()` returns `{ 'x-heyspex-vault-id': <id> }` for a bound,
+ * registered repo and `{}` when the repo is unbound (account-pointer-only,
+ * unregistered, or the resolver throws): the hook then sends no vault id, the
+ * console refuses, and the hook degrades exactly as it did before - it NEVER
+ * substitutes the pointer vault. Never throws.
+ */
+import { getVaultIdHeader } from '../../vendor/heyspex-mcp/console-fetch.mjs';
+
+/**
+ * @param {{ resolve?: () => Record<string, string> }} [opts] test seam
+ * @returns {Record<string, string>}
+ */
+export function hookVaultHeaders({ resolve = getVaultIdHeader } = {}) {
+  try {
+    const header = resolve();
+    return header && typeof header === 'object' ? { ...header } : {};
+  } catch {
+    return {};
+  }
+}