heyspex 0.1.0 → 0.2.0

package/spexharness/src/doctrine/writer.mjs

@@ -0,0 +1,176 @@
+// spexharness/src/doctrine/writer.mjs
+//
+// DR2 (epic [[HS-KNHZ-8CMW-EPIC-spexcode-doctrine-v0-the-foundational]], task
+// [[HS-YMPY-8CMW-TASK-dr2-doctrine-synthesis-a-routed]]) — renders the merged
+// principle set (merge.mjs's output) into the two committed product artifacts:
+// `spexharness/doctrine/SPEXCODE-DOCTRINE.json` (schema-versioned, machine-readable,
+// cited) and `SPEXCODE-DOCTRINE.md` (the human-readable, sectioned document). Pure
+// rendering — {@link renderDoctrineMarkdown}/{@link buildDoctrineJson} do no I/O, so
+// the golden Markdown test never touches disk; {@link writeDoctrineFiles} is the one
+// function that does.
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const DOCTRINE_SCHEMA_VERSION = 1;
+
+/** Section order the Markdown writer renders in — matches the epic's own category list. */
+export const CATEGORY_ORDER = [
+  'delegation',
+  'verification',
+  'communication',
+  'naming',
+  'safety-permissions',
+  'research-grounding',
+  'session-hygiene',
+  'product-taste',
+];
+
+export const CATEGORY_LABELS = {
+  delegation: 'Delegation',
+  verification: 'Verification',
+  communication: 'Communication',
+  naming: 'Naming',
+  'safety-permissions': 'Safety & Permissions',
+  'research-grounding': 'Research & Grounding',
+  'session-hygiene': 'Session Hygiene',
+  'product-taste': 'Product Taste',
+};
+
+const DOCTRINE_HEADER =
+  'This is SpexCode Doctrine — the foundational operating principles distilled from the owner\'s ' +
+  'Claude Code and Command Code sessions and the Command Code taste profile. It is layer 2 of three: ' +
+  '1) SpexDoctrine (the enforced gates in spexharness/src/gates/, never learned), 2) SpexCode Doctrine ' +
+  '(this document — the base every developer profile is built on), 3) SpexCode Profile (the per-' +
+  'developer layer on top, which may refine a principle here but may not silently contradict one).';
+
+/**
+ * Assemble the schema-versioned JSON document. Pure — `learnedAt` must be supplied by
+ * the caller (never `Date.now()` internally) so the golden test is deterministic.
+ *
+ * @param {{ principles: object[], conflicts?: object[], sources?: object, learnedAt: string }} input
+ * @returns {{ schemaVersion: number, learnedAt: string, sources: object, principles: object[], conflicts: object[] }}
+ */
+export function buildDoctrineJson({ principles, conflicts = [], sources = {}, learnedAt }) {
+  return {
+    schemaVersion: DOCTRINE_SCHEMA_VERSION,
+    learnedAt,
+    sources,
+    principles,
+    conflicts,
+  };
+}
+
+/** `claude-code ×5, taste ×1, command-code ×1` — counts an evidence-id list by its `<source>:` prefix. */
+function evidenceBreakdown(evidence) {
+  const counts = new Map();
+  for (const id of evidence ?? []) {
+    const src = typeof id === 'string' && id.includes(':') ? id.slice(0, id.indexOf(':')) : 'unknown';
+    counts.set(src, (counts.get(src) ?? 0) + 1);
+  }
+  return [...counts.entries()].map(([k, v]) => `${k} ×${v}`).join(', ');
+}
+
+function renderPrincipleLine(p) {
+  const conf = typeof p.confidence === 'number' ? p.confidence.toFixed(2) : '0.00';
+  const evidence = Array.isArray(p.evidence) ? p.evidence : [];
+  return `- ${p.text} — confidence ${conf} · evidence ${evidence.length} (${evidenceBreakdown(evidence)})`;
+}
+
+/**
+ * Render the sectioned Markdown document from a JSON-shaped doctrine object
+ * ({@link buildDoctrineJson}'s output, or anything with the same shape). Deterministic:
+ * the same `doc` always renders the same string (no clock reads, no random order —
+ * principles within a category render in their given array order).
+ *
+ * @param {{ learnedAt: string, principles: object[], conflicts?: object[], sources?: object }} doc
+ * @returns {string}
+ */
+export function renderDoctrineMarkdown(doc) {
+  const lines = [];
+  lines.push('# SpexCode Doctrine');
+  lines.push('');
+  lines.push(`_Learned ${doc.learnedAt}_`);
+  lines.push('');
+  lines.push(DOCTRINE_HEADER);
+  lines.push('');
+
+  const byCategory = new Map();
+  for (const p of doc.principles ?? []) {
+    const cat = p.category ?? 'product-taste';
+    const list = byCategory.get(cat) ?? [];
+    list.push(p);
+    byCategory.set(cat, list);
+  }
+
+  const renderSection = (cat, list) => {
+    lines.push(`## ${CATEGORY_LABELS[cat] ?? cat}`);
+    lines.push('');
+    for (const p of list) lines.push(renderPrincipleLine(p));
+    lines.push('');
+  };
+
+  for (const cat of CATEGORY_ORDER) {
+    const list = byCategory.get(cat);
+    if (list && list.length) renderSection(cat, list);
+    byCategory.delete(cat);
+  }
+  // Defensive: any category the seat invented outside CATEGORY_ORDER still renders,
+  // in the stable order it was first seen, rather than being silently dropped.
+  for (const [cat, list] of byCategory) renderSection(cat, list);
+
+  lines.push('## Conflicts');
+  lines.push('');
+  const conflicts = doc.conflicts ?? [];
+  if (!conflicts.length) {
+    lines.push('_None recorded._');
+  } else {
+    for (const c of conflicts) lines.push(`- **${c.category}**: "${c.a}" vs "${c.b}" — headline: ${c.headline}`);
+  }
+  lines.push('');
+
+  lines.push('## Sources');
+  lines.push('');
+  const sources = doc.sources ?? {};
+  lines.push(`- Observations: ${sources.totalObservations ?? 0}`);
+  const bySource = sources.bySource ?? {};
+  for (const [k, v] of Object.entries(bySource)) lines.push(`  - ${k}: ${v}`);
+  // DR5 ([[HS-7Z9E-8CMW-TASK-dr5-vault-knowledge-as-a-doctrine]]) — the vault sets
+  // (decisions, lessons, protocol enforcement, ADRs, the naughty list, CLAUDE.md, ...)
+  // that fed the `vault` row above, broken out with their own per-set counts.
+  const vaultSets = sources.vaultSets ?? {};
+  if (Object.keys(vaultSets).length) {
+    lines.push('  - vault sets:');
+    for (const [k, v] of Object.entries(vaultSets)) lines.push(`    - ${k}: ${v}`);
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+export function defaultDoctrineOutDir(repoRoot) {
+  return join(repoRoot, 'spexharness', 'doctrine');
+}
+
+export function defaultDoctrineMdPath(repoRoot) {
+  return join(defaultDoctrineOutDir(repoRoot), 'SPEXCODE-DOCTRINE.md');
+}
+
+export function defaultDoctrineJsonPath(repoRoot) {
+  return join(defaultDoctrineOutDir(repoRoot), 'SPEXCODE-DOCTRINE.json');
+}
+
+/**
+ * Write both product artifacts for `repoRoot`. The only I/O in this module.
+ * @param {string} repoRoot
+ * @param {ReturnType<typeof buildDoctrineJson>} doc
+ * @returns {{ jsonPath: string, mdPath: string }}
+ */
+export function writeDoctrineFiles(repoRoot, doc) {
+  mkdirSync(defaultDoctrineOutDir(repoRoot), { recursive: true });
+  const jsonPath = defaultDoctrineJsonPath(repoRoot);
+  const mdPath = defaultDoctrineMdPath(repoRoot);
+  writeFileSync(jsonPath, `${JSON.stringify(doc, null, 2)}\n`);
+  writeFileSync(mdPath, `${renderDoctrineMarkdown(doc)}\n`);
+  return { jsonPath, mdPath };
+}

package/spexharness/src/events.mjs

@@ -0,0 +1,84 @@
+// spexharness/src/events.mjs
+//
+// The harness's normalized event model. Every front (Claude Code plugin, `hs
+// chat`, a headless seat) translates whatever its own runtime hands it into
+// one of these six shapes before calling into the gate registry / decider —
+// so a gate is written once against this shape and never against a
+// front-specific payload.
+//
+// This module is pure: no I/O, no process.stdin/stdout, no imports outside
+// node:* stdlib.
+
+/**
+ * The six event points a gate may run on, in the order they occur during a
+ * session:
+ *   1. session_start  — a session begins.
+ *   2. prompt_submit   — the user (or caller) submits a prompt.
+ *   3. before_tool     — a tool is about to run (pre-flight; may deny/rewrite).
+ *   4. after_tool       — a tool finished running (post-flight; may inject).
+ *   5. stop            — the agent is about to stop / hand control back.
+ *   6. session_end     — a session ends.
+ * @type {ReadonlyArray<string>}
+ */
+export const EVENT_POINTS = Object.freeze([
+  'session_start',
+  'prompt_submit',
+  'before_tool',
+  'after_tool',
+  'stop',
+  'session_end',
+]);
+
+const EVENT_POINT_SET = new Set(EVENT_POINTS);
+
+/**
+ * Documented field set per event point. `sessionId` and `ts` are common to
+ * every event (added by {@link createEvent} itself); the arrays below are
+ * the additional fields each event point's `fields` argument is expected to
+ * carry. This is documentation, not a runtime schema — createEvent does not
+ * reject extra or missing fields, so a front can pass whatever its own
+ * runtime already has without a translation step per gate.
+ *
+ * - session_start: cwd, agent
+ * - prompt_submit:  prompt
+ * - before_tool:    toolName, toolInput
+ * - after_tool:     toolName, toolInput, toolResult
+ * - stop:           (none beyond the common fields)
+ * - session_end:    reason
+ * @type {Readonly<Record<string, ReadonlyArray<string>>>}
+ */
+export const EVENT_FIELDS = Object.freeze({
+  session_start: Object.freeze(['cwd', 'agent']),
+  prompt_submit: Object.freeze(['prompt']),
+  before_tool: Object.freeze(['toolName', 'toolInput']),
+  after_tool: Object.freeze(['toolName', 'toolInput', 'toolResult']),
+  stop: Object.freeze([]),
+  session_end: Object.freeze(['reason']),
+});
+
+/**
+ * Build one normalized event object for a gate to run against.
+ *
+ * @param {string} point - one of {@link EVENT_POINTS}. Throws on any other
+ *   value, including a Claude-Code-shaped name like `"PreToolUse"` — callers
+ *   translate into this vocabulary at the edge, not inside a gate.
+ * @param {Record<string, unknown>} [fields] - the event point's documented
+ *   fields (see {@link EVENT_FIELDS}), plus any extra context a front wants
+ *   to carry through to its own gates. Not validated against the field list;
+ *   the list is documentation for gate authors, not a runtime schema.
+ * @returns {Readonly<{ point: string, ts: number } & Record<string, unknown>>}
+ *   A frozen, normalized event object. `ts` defaults to `Date.now()` when
+ *   `fields.ts` is not supplied.
+ */
+export function createEvent(point, fields = {}) {
+  if (!EVENT_POINT_SET.has(point)) {
+    throw new Error(
+      `spexharness: unknown event point "${point}" — expected one of: ${EVENT_POINTS.join(', ')}`,
+    );
+  }
+  return Object.freeze({
+    ts: Date.now(),
+    ...fields,
+    point,
+  });
+}

package/spexharness/src/gates/capture-workflow-gate.mjs

@@ -0,0 +1,202 @@
+// spexharness/src/gates/capture-workflow-gate.mjs
+//
+// Engine port of scripts/claude-hooks/capture-workflow-gate.mjs — the
+// PreToolUse EARLY-WARNING gate for filing an implementation spec
+// (epic/task/milestone) that references the capture currently on deck. See
+// ./PORTING.md for the recipe this follows and ./env-vault-guard.mjs for the
+// reference port.
+//
+// THIS HOOK NEVER DENIES (by design — see the original's header). The real
+// refusal lives in heyspex_file_spec / vendor/heyspex-mcp/capture-stage-gate.mjs,
+// which reads the LIVE capture-on-deck pin (the console / Neon control
+// plane); this hook can only see the OFFLINE file pin
+// (.heyspex/capture-focus.yaml), so it is kept as a narrow, always-silent-
+// unless-matched early warning, never a blocker.
+//
+// The original script does NOT export a pure decision function — its logic
+// is tangled inside `main()` (stdin read, env checks, then the match logic).
+// Per PORTING.md step 1's "otherwise" branch that logic would normally be
+// extracted into the original script itself, but this task's Do-nots forbid
+// touching anything under scripts/claude-hooks/. Rather than hand-copy the
+// original's rule/regex logic (the thing PORTING.md warns will drift), this
+// port imports the SAME shared, already-pure library modules the original
+// hook itself imports for the actual decision surface:
+//   - vendor/heyspex-mcp/capture-stage-gate.mjs — BLOCKED_FILE_SPEC_TYPES,
+//     ALLOWED_FILE_SPEC_TYPES, referencesCapture(). This is the canonical
+//     module the original hook's header says it shares "so the two can
+//     never disagree about which filings count" — importing it here keeps
+//     that same guarantee for the port.
+//   - vendor/heyspex-mcp/capture-focus.mjs — resolveActiveCapture(), which
+//     reads the offline pin + the pinned capture's frontmatter/body.
+// The only code re-derived here is the original's small, non-security
+// glue: stripping the MCP tool-name prefix (bareToolName), and the tiny
+// offline frontmatter scanner + spec loader the original defines locally
+// (parseFrontmatter / loadSpec) purely to satisfy resolveActiveCapture's
+// callback-shaped contract — neither is a rule/regex guard, both are
+// deterministic parsing utilities with no security surface of their own.
+//
+// Decision mapping (documented judgment call, same shape as
+// env-vault-guard.mjs's "ask" → rewrite mapping): a match produces a WARNING
+// carrying the capture id and the sanctioned-exit message — richer than a
+// plain allow, and the original never denies, so silently collapsing this to
+// `allow` would drop information a caller might want to surface (e.g. show
+// the same warning text the Claude Code hook would have written to stderr).
+// Mapped to `rewrite` with `{ warn: true, reason, captureId, type }` rather
+// than `deny` (the hook's own header is explicit: "it never denies") or a
+// silent `allow` (loses the warning). No match, or any early-out (kill
+// switch, wrong tool, allowed/unmatched type, no capture on deck, unrelated
+// filing) → plain `allow`.
+//
+// This gate never hard-denies (matching the original) — "deny" coverage for
+// AC3 ("allow, deny and rewrite each covered by at least one test per gate",
+// checked as one combined `node --test` run across all three ported gates in
+// this task) comes from the sibling enforce-session-sequence gate. See
+// ./enforce-session-sequence.test.mjs.
+//
+// Env hatches (unchanged, either one silences the warning — matching the
+// original, which honors the tool's own break-glass too so one variable
+// covers both layers):
+//   HEYSPEX_CAPTURE_WORKFLOW_GATE_OFF=1
+//   HEYSPEX_CAPTURE_STAGE_GATE_OFF=1
+//
+// Not ported HERE: the original's `appendGuardrailEvent(...)` audit-log
+// write on a match. A gate module stays a pure decision function (AC1: no
+// stdout writes; by the same spirit, no other observability side effects
+// either) — matching env-vault-guard.mjs's port. The `rewrite.captureId` /
+// `rewrite.type` fields below already carry everything a front needs to
+// rebuild that same audit row — see spexharness/src/adapters/audit.mjs,
+// called from spexharness/src/adapters/claude-code.mjs's runGateAsHook.
+//
+// `ctx` contract (all optional; every field defaults to a real fs read, same
+// as the original hook and as spexharness/fixtures/lib/setups.mjs's
+// captureActiveVault — the golden/regression tests below point ctx.cwd at a
+// real scratch vault rather than injecting a fake fs):
+//   ctx.cwd  - repo/vault root to resolve the offline capture pin from.
+//              Defaults to CLAUDE_PROJECT_DIR, else this repo's root.
+//   ctx.env  - env var overrides (tests use this instead of mutating
+//              process.env).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { resolveActiveCapture } from '../../../vendor/heyspex-mcp/capture-focus.mjs';
+import {
+  ALLOWED_FILE_SPEC_TYPES,
+  BLOCKED_FILE_SPEC_TYPES,
+  referencesCapture,
+} from '../../../vendor/heyspex-mcp/capture-stage-gate.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, '..', '..', '..');
+
+// The bare (server-stripped) MCP tool name this gate acts on.
+const FILE_SPEC_TOOL = 'heyspex_file_spec';
+const OFF_ENV_WORKFLOW = 'HEYSPEX_CAPTURE_WORKFLOW_GATE_OFF';
+const OFF_ENV_STAGE = 'HEYSPEX_CAPTURE_STAGE_GATE_OFF';
+
+// Minimal, sync, offline frontmatter parser — mirrors the original hook's
+// local helper of the same name byte-for-byte. Enough for
+// resolveActiveCapture's callbacks (it only reads frontmatter.id / status /
+// promoted_to and the body). Not a full YAML parser; capture frontmatter is
+// flat scalars + simple arrays.
+function parseFrontmatter(content) {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!m) return { frontmatter: {}, body: content };
+  const frontmatter = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('- ')) continue;
+    const colon = trimmed.indexOf(':');
+    if (colon === -1) continue;
+    const key = trimmed.slice(0, colon).trim();
+    let val = trimmed.slice(colon + 1).trim();
+    val = val.replace(/^["']|["']$/g, '');
+    frontmatter[key] = val;
+  }
+  return { frontmatter, body: m[2] ?? '' };
+}
+
+// readFileSync loader for resolveActiveCapture — returns { frontmatter, body }
+// or null when the pinned capture file is missing/unreadable. Mirrors the
+// original hook's local helper of the same name.
+function loadSpec(vaultRoot, specPath) {
+  try {
+    const full = path.join(vaultRoot, specPath);
+    const content = fs.readFileSync(full, 'utf8');
+    return parseFrontmatter(content);
+  } catch {
+    return null;
+  }
+}
+
+// Strip the Claude Code MCP tool prefix (mcp__<server>__<tool>) → bare tool
+// name. Mirrors the original hook's local helper of the same name.
+function bareToolName(name) {
+  if (typeof name !== 'string') return '';
+  const m = name.match(/^mcp__[^_]+(?:_[^_]+)*?__(.+)$/);
+  if (m) return m[1];
+  const idx = name.lastIndexOf('__');
+  return idx === -1 ? name : name.slice(idx + 2);
+}
+
+function warnText(captureId) {
+  return (
+    `[capture-workflow-gate] warning — this filing links the open capture ${captureId}, ` +
+    `which a capture must not become. The sanctioned exit is promote-to-research (\`/hs-res\`). ` +
+    `This hook only warns. heyspex_file_spec is where the rule is enforced, and it ` +
+    `reads the live capture pin rather than the offline file this hook can see.`
+  );
+}
+
+/** The capture-workflow gate's id — unique across the built-in registry. */
+export const id = 'capture-workflow-gate';
+/** Runs pre-tool, same as its PreToolUse Claude Code hook registration. */
+export const event = 'before_tool';
+/** Caller-defined severity label; this gate only ever warns (rewrites) or allows. */
+export const severity = 'warn';
+
+/**
+ * @param {{ point: string, toolName?: string, toolInput?: Record<string, unknown> }} evt
+ * @param {{ cwd?: string, env?: Record<string, string | undefined> }} [ctx]
+ * @returns {{ decision: 'allow'|'rewrite', reason?: string, rewrite?: object }}
+ */
+export function run(evt, ctx = {}) {
+  const env = ctx.env ?? process.env;
+  if (String(env[OFF_ENV_WORKFLOW] ?? '') === '1') return { decision: 'allow' };
+  if (String(env[OFF_ENV_STAGE] ?? '') === '1') return { decision: 'allow' };
+
+  const tool = bareToolName(evt?.toolName);
+  if (tool !== FILE_SPEC_TOOL) return { decision: 'allow' };
+
+  const toolInput = evt?.toolInput ?? {};
+  const type = String(toolInput?.type ?? '').trim().toLowerCase();
+
+  // Only implementation specs are the premature-promotion case. Research /
+  // diagnose / memory / pillar / review filings are sanctioned exits or
+  // unrelated — never warned about.
+  if (!BLOCKED_FILE_SPEC_TYPES.has(type) || ALLOWED_FILE_SPEC_TYPES.has(type)) {
+    return { decision: 'allow' };
+  }
+
+  const root = ctx.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? REPO_ROOT;
+  let resolved;
+  try {
+    resolved = resolveActiveCapture(root, parseFrontmatter, loadSpec);
+  } catch {
+    return { decision: 'allow' }; // discovery failure → stay quiet, fail-safe
+  }
+  if (!resolved || resolved.error || !resolved.spec_id) return { decision: 'allow' };
+
+  // Arg-targeted: only warn when the spec being filed references THIS capture.
+  if (!referencesCapture(toolInput, resolved.spec_id)) return { decision: 'allow' };
+
+  const reason = warnText(resolved.spec_id);
+  return {
+    decision: 'rewrite',
+    reason,
+    rewrite: { warn: true, reason, captureId: resolved.spec_id, type },
+  };
+}
+
+export default { id, event, severity, run };

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

@@ -0,0 +1,33 @@
+// spexharness/src/gates/claim-before-code-gate.decide.mjs
+//
+// Pure decision logic relocated from scripts/claude-hooks/claim-before-code-gate.mjs
+// (HS-IQBF, per PORTING.md's "move the pure decision logic into the gate
+// module itself or a sibling pure module" — the original hook now delegates
+// to this file too, so ./claim-before-code-gate.mjs (the gate) and the
+// original hook's own smoke test both import the SAME code; nothing here is
+// a second copy that can drift). No stdin/stdout/process.exit anywhere in
+// this file.
+
+const EDIT_TOOL_NAMES = new Set(['Edit', 'Write', 'MultiEdit']);
+
+// Paths this gate never blocks: the vault itself (filing the epic IS the
+// required step), hook/state machinery, and anything outside the repo tree.
+// Everything else counts as "code" for this gate's purposes.
+const EXEMPT_PATH_RE = /(?:^|[\\/])(?:specs|\.heyspex|\.claude|\.git)(?:[\\/]|$)/;
+
+function isCodeEditPath(filePath) {
+  if (typeof filePath !== 'string' || !filePath.trim()) return false;
+  const normalized = filePath.replace(/\\/g, '/');
+  return !EXEMPT_PATH_RE.test(normalized);
+}
+
+/**
+ * Pure decision function (exported for the smoke test and the gate): given
+ * the resolved inputs, should this edit be denied?
+ */
+export function shouldDenyEdit({ toolName, filePath, hasMarker, hasNoClaimSignal }) {
+  if (!EDIT_TOOL_NAMES.has(toolName)) return false;
+  if (!isCodeEditPath(filePath)) return false;
+  if (!hasMarker) return false;
+  return hasNoClaimSignal;
+}

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