heyspex 0.1.0 → 0.2.0

package/scripts/claude-hooks/dev-server-task-reminder.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// Thin shell over the spexharness engine port of this gate (wave 6 of
+// [[HS-AZ61-NYPR]]). Same shape as the twelve shells
+// scripts/generate-hook-shells.mjs writes; this one is authored rather than
+// generated only because it is not part of that generator's frozen twelve.
+// To change what this gate DECIDES, edit
+// spexharness/src/gates/dev-server-task-reminder.mjs. The classification, the
+// worktree bypass, the front read and the fleet-queue claim wrapper live in
+// spexharness/src/dev-server-control.mjs — one copy in the tree, shared by the
+// gate, this shell, and ./dev-server-task-reminder.smoke.mjs.
+
+import { runGateAsHook } from '../../spexharness/src/adapters/claude-code.mjs';
+import gate from '../../spexharness/src/gates/dev-server-task-reminder.mjs';
+
+await runGateAsHook(gate);

package/scripts/claude-hooks/emit-claim-status.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// Claude Code + Cursor CLI hook → console claim-status / heartbeat emitter.
+// ([[HS-TASK-P89W]] / [[HS-EPIC-2BKX]] / [[HS-TASK-A3FE]] producer path)
+//
+// Resolves the agent session id from stdin payload + host env, then PATCHes
+// `/api/control/active-claims/heartbeat` (tier-dispatched — works on Neon and
+// free-file tiers). Does NOT read `.heyspex/active-claims.json`.
+//
+// MUST exit 0 on every failure path — a hook that breaks the agent is worse
+// than a hook that silently does nothing.
+//
+// CLI: emit-claim-status.mjs [--event=PreToolUse|preToolUse|Stop|stop|PostToolUse|postToolUse]
+//   --event is optional; falls back to stdin.hook_event_name.
+
+import {
+  emitClaimLivenessFromHook,
+  parseArgs,
+  readStdin,
+} from './claim-liveness-shared.mjs';
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const stdinRaw = await readStdin();
+  let payload = null;
+  if (stdinRaw) {
+    try {
+      payload = JSON.parse(stdinRaw);
+    } catch {
+      // Non-JSON stdin — proceed with null payload; event must come from --event.
+    }
+  }
+
+  await emitClaimLivenessFromHook({
+    eventArg: args.event,
+    payload,
+  });
+}
+
+main().catch(() => {
+  // Swallow — never break the host agent on a hook failure.
+});

package/scripts/claude-hooks/enforce-session-sequence.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// GENERATED by scripts/generate-hook-shells.mjs (HS-IQBF) — do not hand-edit.
+// This file only wires Claude Code's hook stdin/stdout contract to the
+// spexharness engine port of this gate. To change what this gate DECIDES,
+// edit spexharness/src/gates/enforce-session-sequence.mjs. To change the SHAPE of this shell,
+// edit the generator, then rerun: node scripts/generate-hook-shells.mjs
+
+import { runGateAsHook } from '../../spexharness/src/adapters/claude-code.mjs';
+import gate from '../../spexharness/src/gates/enforce-session-sequence.mjs';
+
+await runGateAsHook(gate);

package/scripts/claude-hooks/enforce-vault-naming.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// GENERATED by scripts/generate-hook-shells.mjs (HS-IQBF) — do not hand-edit.
+// This file only wires Claude Code's hook stdin/stdout contract to the
+// spexharness engine port of this gate. To change what this gate DECIDES,
+// edit spexharness/src/gates/enforce-vault-naming.mjs. To change the SHAPE of this shell,
+// edit the generator, then rerun: node scripts/generate-hook-shells.mjs
+
+import { runGateAsHook } from '../../spexharness/src/adapters/claude-code.mjs';
+import gate from '../../spexharness/src/gates/enforce-vault-naming.mjs';
+
+await runGateAsHook(gate);

package/scripts/claude-hooks/env-vault-guard.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// GENERATED by scripts/generate-hook-shells.mjs (HS-IQBF) — do not hand-edit.
+// This file only wires Claude Code's hook stdin/stdout contract to the
+// spexharness engine port of this gate. To change what this gate DECIDES,
+// edit spexharness/src/gates/env-vault-guard.mjs. To change the SHAPE of this shell,
+// edit the generator, then rerun: node scripts/generate-hook-shells.mjs
+
+import { runGateAsHook } from '../../spexharness/src/adapters/claude-code.mjs';
+import gate from '../../spexharness/src/gates/env-vault-guard.mjs';
+
+await runGateAsHook(gate);

package/scripts/claude-hooks/epic-milestone-phrasing-gate.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// GENERATED by scripts/generate-hook-shells.mjs (HS-IQBF) — do not hand-edit.
+// This file only wires Claude Code's hook stdin/stdout contract to the
+// spexharness engine port of this gate. To change what this gate DECIDES,
+// edit spexharness/src/gates/epic-milestone-phrasing-gate.mjs. To change the SHAPE of this shell,
+// edit the generator, then rerun: node scripts/generate-hook-shells.mjs
+
+import { runGateAsHook } from '../../spexharness/src/adapters/claude-code.mjs';
+import gate from '../../spexharness/src/gates/epic-milestone-phrasing-gate.mjs';
+
+await runGateAsHook(gate);

package/scripts/claude-hooks/git-identity-guard.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// GENERATED by scripts/generate-hook-shells.mjs (HS-IQBF) — do not hand-edit.
+// This file only wires Claude Code's hook stdin/stdout contract to the
+// spexharness engine port of this gate. To change what this gate DECIDES,
+// edit spexharness/src/gates/git-identity-guard.mjs. To change the SHAPE of this shell,
+// edit the generator, then rerun: node scripts/generate-hook-shells.mjs
+
+import { runGateAsHook } from '../../spexharness/src/adapters/claude-code.mjs';
+import gate from '../../spexharness/src/gates/git-identity-guard.mjs';
+
+await runGateAsHook(gate);

package/scripts/claude-hooks/git-reflog-audit.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// Thin shell over the spexharness engine port of this gate (wave 6 of
+// [[HS-AZ61-NYPR]]). `.claude/settings.json` wires this ONE script to BOTH
+// SessionStart and Stop, so it uses `runGatesAsHook` — read stdin once, run
+// whichever of the pair is registered for the incoming event.
+//
+// To change what this gate DECIDES, edit
+// spexharness/src/gates/git-reflog-audit.mjs. The reflog/stash audit logic
+// itself lives in spexharness/src/git-reflog-audit.mjs — one copy in the tree,
+// shared by the gate, this shell, and ./git-reflog-audit.test.mjs.
+
+import { runGatesAsHook } from '../../spexharness/src/adapters/claude-code.mjs';
+import gate, { snapshotGate } from '../../spexharness/src/gates/git-reflog-audit.mjs';
+
+await runGatesAsHook([snapshotGate, gate]);

package/scripts/claude-hooks/git-stash-gate.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// GENERATED by scripts/generate-hook-shells.mjs (HS-IQBF) — do not hand-edit.
+// This file only wires Claude Code's hook stdin/stdout contract to the
+// spexharness engine port of this gate. To change what this gate DECIDES,
+// edit spexharness/src/gates/git-stash-gate.mjs. To change the SHAPE of this shell,
+// edit the generator, then rerun: node scripts/generate-hook-shells.mjs
+
+import { runGateAsHook } from '../../spexharness/src/adapters/claude-code.mjs';
+import gate from '../../spexharness/src/gates/git-stash-gate.mjs';
+
+await runGateAsHook(gate);

package/scripts/claude-hooks/guard-auto-memory-writes.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// Claude Code PreToolUse hook → keeps the Claude Code auto-memory directory thin by
+// blocking NEW topic-file creation there, redirecting durable HeySpex knowledge to
+// the vault.
+//
+// Per the retention policy ([[auto-memory-index-hygiene]] / [[HS-VN9W-RES]]) the
+// auto-memory index (~/.claude/projects/<repo>/memory/) is a curated working-set +
+// ROUTER over the vault — NOT a store. Durable HeySpex facts belong in the vault
+// (specs/memory/, via heyspex_file_spec), which is served dynamically by
+// heyspex_recall_memories. Writing new `<slug>.md` topic files into the auto-memory
+// dir is what re-bloats the always-loaded index over time (each new topic file earns
+// an index line). This hook is the prevention half; the self-heal pass in
+// check-auto-memory-budget.mjs is the cure half.
+//
+// What is blocked: creating a NEW `.md` topic file (anything other than MEMORY.md)
+// under `…/.claude/projects/<repo>/memory/`.
+// What is allowed: writing MEMORY.md itself (the router line + sanctioned pinned
+// working set), and Edit on any existing file (migrations, pinned-set tweaks).
+//
+// Env:
+//   HEYSPEX_AUTO_MEMORY_WRITE_GUARD_OFF=1   kill switch — never blocks.
+//
+// Stdin: Claude Code hook JSON ({tool_name, tool_input, ...}).
+// Exit 0 = allow. Exit 2 = block (stderr surfaces back to the model).
+// FAIL-SAFE: any internal error → exit 0 (never strand the agent).
+
+import path from 'node:path';
+
+// Matches a path inside a Claude Code auto-memory dir: `…/.claude/projects/<repo>/memory/`.
+// Tolerant of either path separator (Windows or POSIX) in the raw tool input.
+const AUTO_MEMORY_DIR_RE = /[\\/]\.claude[\\/]projects[\\/][^\\/]+[\\/]memory[\\/]/i;
+
+function isGuardedTopicFile(p) {
+  if (!p || typeof p !== 'string') return false;
+  if (!AUTO_MEMORY_DIR_RE.test(p)) return false;
+  const base = path.basename(p);
+  if (!/\.md$/i.test(base)) return false; // only markdown topic files
+  if (base.toUpperCase() === 'MEMORY.MD') return false; // the index itself is allowed
+  return true;
+}
+
+// Heuristic shell scanner — pulls file-creation targets out of common Bash /
+// PowerShell idioms so a topic file written via `echo > slug.md` or `New-Item`
+// can't sneak past the Write|NotebookEdit guard. Mirrors the conservative scanner
+// in enforce-vault-naming.mjs. Conservative by design: a missed target only means
+// the guard stays silent (fail-open), never a false block of legitimate work.
+function extractShellTargets(command) {
+  if (!command || typeof command !== 'string') return [];
+  const targets = new Set();
+
+  // 1. Redirects: `> path` / `>> path` / `| tee path` / `| tee -a path`.
+  const redirectRe = /(?:>>?|\|\s*tee(?:\s+-a)?)\s+("([^"]+)"|'([^']+)'|(\S+))/g;
+  for (const m of command.matchAll(redirectRe)) targets.add(m[2] ?? m[3] ?? m[4]);
+
+  // 2. mv / cp / touch / install / Set-Content / New-Item etc. — destination args.
+  const cmdRe =
+    /\b(?:mv|cp|touch|install|rename|tee|Move-Item|Copy-Item|New-Item|Set-Content|Out-File|Add-Content)\s+([^|;&\n]+)/g;
+  for (const m of command.matchAll(cmdRe)) {
+    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]); // last arg is the destination
+    } else {
+      for (const a of args) targets.add(a); // touch / New-Item / *-Content: each is a target
+    }
+  }
+
+  return [...targets]
+    .map((t) => t.replace(/^['"]|['"]$/g, ''))
+    .filter(Boolean)
+    .filter((t) => !/[$`(){}]/.test(t)); // skip command substitutions / non-paths
+}
+
+function reason(p) {
+  return [
+    `HeySpex auto-memory guard: ${p}`,
+    `  The Claude Code auto-memory directory is a thin curated index + router over the`,
+    `  vault — not a knowledge store. Do NOT create new topic files here; durable HeySpex`,
+    `  facts belong in the vault and load on demand via heyspex_recall_memories.`,
+    `  → File this as a vault memory instead: heyspex_file_spec`,
+    `    (memory-lesson / memory-decision / memory-reference / memory-ui-pattern).`,
+    `  → A genuinely machine-local fact (this physical box's hardware, a per-machine path)`,
+    `    goes to the vault as a memory-reference tagged 'machine-local'.`,
+    `  Only MEMORY.md (the router line + sanctioned [pinned] working set) lives here.`,
+    `  See specs/protocols/auto-memory-index-hygiene.md.`,
+  ].join('\n');
+}
+
+async function readStdinJson() {
+  if (process.stdin.isTTY) return null;
+  let buf = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) buf += chunk;
+  if (!buf.trim()) return null;
+  try {
+    return JSON.parse(buf);
+  } catch {
+    return null;
+  }
+}
+
+function block(msg) {
+  process.stderr.write(`\n[HeySpex auto-memory guard]\n${msg}\n`);
+  process.exit(2);
+}
+
+async function main() {
+  if (process.env.HEYSPEX_AUTO_MEMORY_WRITE_GUARD_OFF === '1') return;
+
+  const payload = await readStdinJson();
+  if (!payload) return;
+
+  const toolName = payload.tool_name;
+  const input = payload.tool_input ?? {};
+
+  // Only guard file CREATION. Edit/MultiEdit on existing files is fine (migrations,
+  // pinned-set tweaks); the file already exists, so it is not new re-bloat.
+  let targets = [];
+  if (toolName === 'Write') targets = [input.file_path];
+  else if (toolName === 'NotebookEdit') targets = [input.notebook_path];
+  else if (toolName === 'Bash' || toolName === 'PowerShell')
+    targets = extractShellTargets(input.command); // close the shell-redirect bypass
+  else return; // unrelated tool
+
+  for (const target of targets) {
+    if (isGuardedTopicFile(target)) block(reason(target)); // block() exits on first hit
+  }
+}
+
+main().catch(() => {
+  // Fail-open: never block legitimate work on a hook crash.
+  process.exit(0);
+});

package/scripts/claude-hooks/id-display-format-gate.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// GENERATED by scripts/generate-hook-shells.mjs (HS-IQBF) — do not hand-edit.
+// This file only wires Claude Code's hook stdin/stdout contract to the
+// spexharness engine port of this gate. To change what this gate DECIDES,
+// edit spexharness/src/gates/id-display-format-gate.mjs. To change the SHAPE of this shell,
+// edit the generator, then rerun: node scripts/generate-hook-shells.mjs
+
+import { runGateAsHook } from '../../spexharness/src/adapters/claude-code.mjs';
+import gate from '../../spexharness/src/gates/id-display-format-gate.mjs';
+
+await runGateAsHook(gate);

package/scripts/claude-hooks/inject-communication-style.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// Claude Code hook → RETIRED UserPromptSubmit injection of the OWNER COMMUNICATION STYLE rules.
+//
+// RETIRED (HS-XIYJ, epic HS-1YDJ, 2026-09-09).
+//
+// WHY THIS EXISTED
+// -----------------
+// This hook used to inject the compiled `communication-style-prime` rule's full prose
+// (specs/protocols/communication-style-protocol.md, ~3.0 KB) into EVERY UserPromptSubmit
+// turn, unconditionally — added after the owner asked for plain English twice (2026-08-11,
+// 2026-08-14; see git history for the full rationale) because a memory lesson and a
+// preflight reminder both failed to reach an ordinary interactive turn.
+//
+// WHY IT IS RETIRED NOW
+// ----------------------
+// The epic measured this hook as ~3.0 KB of every single prompt's budget, on top of the
+// intent classifier's own per-prompt cost (HS-5ISS) — together the largest mechanical, non-
+// content share of a seat's context window. The voice epic's first profile is the intended
+// replacement mechanism for carrying writing-style behavior across turns without re-teaching
+// it every one; this task's job is narrower — make the injection actually stop, and prove it
+// stopped via measurement (spexharness/src/context-budget.mjs, HS-7UAQ) rather than just
+// trusting a diff.
+//
+// THIS FILE IS KEPT, NOT DELETED
+// -------------------------------
+// `.claude/settings.json` still names `inject-communication-style` as the UserPromptSubmit
+// hook and scripts/claude-hooks/_run.mjs dispatches to it by that name on every prompt —
+// deleting the file would turn a silent no-op into a "hook not found" stderr line on every
+// turn instead. `main()` below now ALWAYS returns without emitting anything; the decision
+// lives in {@link shouldInject}, a one-line function kept separate from `main()` so a test
+// can assert the retirement directly instead of only inferring it from captured stdout, and
+// so any future un-retirement is a one-line change here rather than a rewrite.
+//
+//   HEYSPEX_COMMUNICATION_STYLE_OFF=1              Historical kill switch — still honored
+//                                                    (checked first, same as before), though
+//                                                    shouldInject() already returns false
+//                                                    unconditionally regardless of its value.
+//   agent_behaviors.communication_style.enabled    Historical config toggle — no longer read;
+//                                                    the registry lookup this hook used to do
+//                                                    is gone, so a stale/missing/corrupt
+//                                                    .heyspex/guardrails.json can no longer
+//                                                    affect this hook either way.
+
+/**
+ * Should this hook inject the communication-style prose? Retired: always false. Kept as a
+ * named export (rather than inlined into `main()`) so this is the ONE place the retirement
+ * decision lives, and a test asserts it directly.
+ * @returns {boolean}
+ */
+export function shouldInject() {
+  return false;
+}
+
+/**
+ * The hook body. Reads nothing and writes nothing — retirement means there is no longer
+ * anything for it to read the payload FOR. Exported so a test can call it directly and
+ * capture stdout around it.
+ * @returns {Promise<void>}
+ */
+export async function main() {
+  if (!shouldInject()) return; // retired — see module header.
+}
+
+main().catch(() => {
+  // Never break Claude Code on a hook failure.
+});

package/scripts/claude-hooks/inject-coo-seat.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// Claude Code hook → SessionStart injection of dev-factory seat mandates.
+//
+// Reads the seats registry at dev-factory/seats.json. When settings.cooMode is
+// true, injects one line per ACTIVE seat so every new session opens already
+// holding its seat (delegate-first COO orchestration) without being told:
+//
+//   DEV-FACTORY SEAT: <title> — <mandate>
+//
+// Toggle lives in the console at Settings > ADMIN > Dev-Factory (persisted via
+// PATCH /api/admin/factory/seats). Hard requirements honored here:
+//   - additive: registered as its OWN SessionStart hook entry; the existing
+//     dev-server awareness injection (inject-dev-server-awareness.mjs) is untouched.
+//   - non-fatal: missing/corrupt seats.json, cooMode false, or no active seats
+//     → inject nothing and exit 0 (the fail-silent hook contract).
+//   - fast: one local file read; no network calls.
+//   HEYSPEX_COO_SEAT_OFF=1  Kill switch — exits silently.
+//
+// Output shape (same as the sibling SessionStart hooks):
+//   { hookSpecificOutput: { hookEventName, additionalContext } }
+
+// buildSeatContext + repoRoot moved to the shared lib so Command Code
+// (sync into COMMANDCODE.md) and Cursor (sync into a .cursor rule) inject the
+// byte-identical seat context — see dev-factory/lib/seat-context.mjs.
+import { buildSeatContext } from '../../dev-factory/lib/seat-context.mjs';
+
+async function readStdinJson() {
+  if (process.stdin.isTTY) return null;
+  return new Promise((resolve) => {
+    let buf = '';
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    const timer = setTimeout(() => finish(buf || ''), 200);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      buf += chunk;
+    });
+    process.stdin.on('end', () => {
+      clearTimeout(timer);
+      finish(buf);
+    });
+    process.stdin.on('error', () => {
+      clearTimeout(timer);
+      finish(buf);
+    });
+  });
+}
+
+function emit(eventName, additionalContext) {
+  process.stdout.write(
+    JSON.stringify({ hookSpecificOutput: { hookEventName: eventName, additionalContext } }),
+  );
+}
+
+async function main() {
+  if (process.env.HEYSPEX_COO_SEAT_OFF === '1') return;
+  const context = buildSeatContext();
+  if (!context) return; // cooMode off / no registry / no active seats
+  const raw = await readStdinJson();
+  let event = 'SessionStart';
+  if (raw) {
+    try {
+      const payload = JSON.parse(raw);
+      if (payload?.hook_event_name) event = payload.hook_event_name;
+    } catch {
+      // Non-JSON stdin — default to SessionStart and emit anyway.
+    }
+  }
+  emit(event, context);
+}
+
+main().catch(() => {
+  // Never break Claude Code on a hook failure.
+});

package/scripts/claude-hooks/inject-dev-server-awareness.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// GENERATED by scripts/generate-hook-shells.mjs (HS-IQBF) — do not hand-edit.
+// This file only wires Claude Code's hook stdin/stdout contract to the
+// spexharness engine port of this gate. To change what this gate DECIDES,
+// edit spexharness/src/gates/dev-server-awareness-gate.mjs. To change the SHAPE of this shell,
+// edit the generator, then rerun: node scripts/generate-hook-shells.mjs
+
+import { runGateAsHook } from '../../spexharness/src/adapters/claude-code.mjs';
+import gate from '../../spexharness/src/gates/dev-server-awareness-gate.mjs';
+
+await runGateAsHook(gate);

package/scripts/claude-hooks/inject-doctrine.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Thin shell over the spexharness engine gate (HS-X3S1, DR3). Same shape as
+// inject-vault-context.mjs's own shell — this one is authored rather than
+// generated (like that one) because it is not part of
+// scripts/generate-hook-shells.mjs's frozen twelve. To change what this
+// injection DECIDES, edit spexharness/src/gates/inject-doctrine-gate.mjs
+// (the rendering itself lives in spexharness/src/doctrine/inject.mjs, shared
+// with every SpexCode seat's own bootstrap — session-bootstrap.mjs).
+
+import { runGateAsHook } from '../../spexharness/src/adapters/claude-code.mjs';
+import gate from '../../spexharness/src/gates/inject-doctrine-gate.mjs';
+
+await runGateAsHook(gate);

package/scripts/claude-hooks/inject-vault-context.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// Thin shell over the spexharness engine port of this gate (wave 6 of
+// [[HS-AZ61-NYPR]]). Same shape as the twelve shells
+// scripts/generate-hook-shells.mjs writes; this one is authored rather than
+// generated only because it is not part of that generator's frozen twelve.
+// To change what this gate DECIDES, edit
+// spexharness/src/gates/inject-vault-context.mjs (the scoring stays in
+// ./_vault-retrieval.mjs; the byte accounting in
+// spexharness/src/context-budget.mjs).
+
+import { runGateAsHook } from '../../spexharness/src/adapters/claude-code.mjs';
+import gate from '../../spexharness/src/gates/inject-vault-context.mjs';
+
+await runGateAsHook(gate);