heyspex 0.1.0 → 0.2.0

package/scripts/claude-hooks/check-claude-md-budget.mjs

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+// Claude Code SessionStart hook → CLAUDE.md (agent contract) budget check.
+//
+// CLAUDE.md is the always-loaded agent contract: every byte is injected into
+// context at the start of every session. Unlike the auto-memory index there is no
+// hard harness cap, but compliance degrades as it grows — Anthropic's own guidance
+// is "bloated CLAUDE.md files cause Claude to ignore your actual instructions," and
+// practitioner testing reports compliance dropping sharply past ~200 lines (rules
+// get buried). So this is a SOFT quality budget, not a data-loss cap.
+//
+// The warn thresholds are user-configurable from the HeySpex Console at
+// Settings → Config → Memory (persisted in spex-console/settings.json under
+// `agentMemory`): an on/off toggle plus the line + byte target. Defaults below
+// (120 lines / 15KB) are the lean target this file was trimmed to (see
+// [[minimizing-claude-md-thin-agent-contract]],
+// [[HS-TASK-AIU4-claude-md-trim-procedures-to-mcp-pointers]]); past ~200 lines
+// compliance drops sharply (rules get buried). It stays SILENT while CLAUDE.md is
+// lean and, once it crosses the target, names the largest sections to trim and
+// reminds the agent of the keep/cut test: "Would removing this line cause Claude to
+// make mistakes? If not, cut it." Detail belongs in a procedure (fetched on demand
+// via heyspex_get_procedure), not here.
+//
+// Mirrors check-auto-memory-budget.mjs (same env-gate + exit-0 discipline).
+//
+// Env gate:
+//   CLAUDE_AGENT=true                  opt in (unset → silent, so interactive
+//                                      humans aren't spammed).
+//   HEYSPEX_CLAUDE_MD_BUDGET_OFF=1     hard kill switch — silent even when opted in.
+//   HEYSPEX_CLAUDE_MD_FILE=<path>      override the resolved CLAUDE.md path
+//                                      (used by the smoke test; also a manual escape hatch).
+//   HEYSPEX_CLAUDE_MD_SETTINGS_FILE=<path>  override the spex-console/settings.json
+//                                      path read for the budget knobs (smoke test).
+//
+// MUST exit 0 on every path — a hook that breaks Claude Code is worse than one
+// that silently does nothing.
+//
+// Output shape: { hookSpecificOutput: { hookEventName, additionalContext } }.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getActiveConfig } from '../../vendor/heyspex-mcp/vault-resolve.mjs';
+
+const COMPLIANCE_CLIFF_LINES = 200; // documented point where rules get buried
+const DEFAULT_MAX_LINES = 120; // lean target; overridable in Console settings
+const DEFAULT_MAX_BYTES = 15000; // ~14.6 KiB; overridable in Console settings
+const MAX_SECTIONS = 6;
+
+// Duplication detection ([[HS-UFQS-5PQ2-DIAG]]): "Size is not the violation —
+// duplication is. A budget check that only counts lines will keep passing
+// while the file rots." A line/byte-lean CLAUDE.md can still carry a stale
+// inlined copy of a procedure — this check fires independent of the size
+// budget above. Conservative on purpose (exact-line match, length floor,
+// headers/tables excluded) to avoid flagging shared boilerplate as a false
+// positive; it is meant to catch verbatim paragraph-level copies, not any
+// shared phrase.
+const DUPLICATE_MIN_LINE_LENGTH = 50;
+const MAX_DUPLICATE_HITS_SHOWN = 5;
+
+function normalizeLineForDupeCheck(line) {
+  return line.trim().replace(/\s+/g, ' ');
+}
+
+function isCheckableLine(line) {
+  if (line.length < DUPLICATE_MIN_LINE_LENGTH) return false;
+  if (line.startsWith('#')) return false; // headings repeat by design, not real dup
+  if (line.startsWith('|')) return false; // table rows (change-log rows etc.)
+  if (line.startsWith('```')) return false;
+  return true;
+}
+
+export function resolveProtocolsDir(projectDir) {
+  const override = process.env.HEYSPEX_CLAUDE_MD_PROTOCOLS_DIR;
+  if (override && override.trim()) return override;
+  // Since the repo split (2026-08-31) protocols live in the vault clone, not the
+  // project dir — prefer the registry-resolved vault when the local dir is gone.
+  const local = path.join(projectDir, 'specs', 'protocols');
+  if (fs.existsSync(local)) return local;
+  try {
+    const vault = getActiveConfig()?.repoRootAbs;
+    if (vault) return path.join(vault, 'specs', 'protocols');
+  } catch {
+    // registry unreadable — fall through to the local default
+  }
+  return local;
+}
+
+/** normalized line → Set of protocol basenames it appears in verbatim. PURE given fs snapshot. */
+export function collectProtocolLines(protocolsDir) {
+  const map = new Map();
+  let entries = [];
+  try {
+    entries = fs.readdirSync(protocolsDir).filter((f) => f.toLowerCase().endsWith('.md'));
+  } catch {
+    return map; // no protocols dir (fixture / misconfigured repo) → nothing to compare against
+  }
+  for (const file of entries) {
+    let text;
+    try {
+      text = fs.readFileSync(path.join(protocolsDir, file), 'utf8');
+    } catch {
+      continue;
+    }
+    for (const raw of text.split(/\r?\n/)) {
+      const line = normalizeLineForDupeCheck(raw);
+      if (!isCheckableLine(line)) continue;
+      if (!map.has(line)) map.set(line, new Set());
+      map.get(line).add(file);
+    }
+  }
+  return map;
+}
+
+/**
+ * Lines in `content` (CLAUDE.md) that appear verbatim in a `specs/protocols/*.md`
+ * file. Returns [] when nothing matches (including when the protocols dir is
+ * absent/empty — never throws). Pure given the protocolLines snapshot.
+ */
+export function detectDuplicateLines(content, protocolLines) {
+  if (protocolLines.size === 0) return [];
+  const hits = [];
+  const seen = new Set(); // de-dupe repeated identical lines within CLAUDE.md itself
+  for (const raw of content.split(/\r?\n/)) {
+    const line = normalizeLineForDupeCheck(raw);
+    if (!isCheckableLine(line) || seen.has(line)) continue;
+    const files = protocolLines.get(line);
+    if (files && files.size > 0) {
+      hits.push({ line, files: [...files] });
+      seen.add(line);
+    }
+  }
+  return hits;
+}
+
+function buildDuplicationReport(hits) {
+  if (!hits || hits.length === 0) return null;
+  const out = [
+    `CLAUDE.md duplication check — ${hits.length} line(s) match specs/protocols/*.md verbatim. ` +
+      `CLAUDE.md is always-loaded; an inlined copy silently overrides the live procedure once the ` +
+      `procedure is updated and the copy isn't. Replace with a one-line pointer (e.g. ` +
+      `"heyspex_get_procedure({ name: '<protocol>' })") instead of the inlined text.`,
+  ];
+  for (const h of hits.slice(0, MAX_DUPLICATE_HITS_SHOWN)) {
+    const preview = h.line.length > 90 ? `${h.line.slice(0, 90)}…` : h.line;
+    out.push(`  • "${preview}" — also verbatim in ${h.files.join(', ')}`);
+  }
+  if (hits.length > MAX_DUPLICATE_HITS_SHOWN) {
+    out.push(`  …and ${hits.length - MAX_DUPLICATE_HITS_SHOWN} more.`);
+  }
+  return out.join('\n');
+}
+
+function repoRoot() {
+  // scripts/claude-hooks/ → up two levels.
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+
+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) {
+  if (!additionalContext) return;
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName: eventName, additionalContext },
+    }),
+  );
+}
+
+function resolveClaudeMdFile(projectDir) {
+  const override = process.env.HEYSPEX_CLAUDE_MD_FILE;
+  if (override && override.trim()) return override;
+  return path.join(projectDir, 'CLAUDE.md');
+}
+
+// Read the user's budget knobs from the Console settings file (Settings → Config →
+// Memory writes `agentMemory` here). Missing/malformed → defaults. Standalone JSON
+// read so this .mjs hook needs no TS import.
+function resolveBudget(projectDir) {
+  const file =
+    process.env.HEYSPEX_CLAUDE_MD_SETTINGS_FILE?.trim() ||
+    path.join(projectDir, 'spex-console', 'settings.json');
+  let mem = {};
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (parsed && typeof parsed.agentMemory === 'object' && parsed.agentMemory) {
+      mem = parsed.agentMemory;
+    }
+  } catch {
+    // absent / malformed → defaults
+  }
+  const enabled = typeof mem.budgetEnabled === 'boolean' ? mem.budgetEnabled : true;
+  const maxLines =
+    typeof mem.budgetMaxLines === 'number' && mem.budgetMaxLines > 0
+      ? Math.floor(mem.budgetMaxLines)
+      : DEFAULT_MAX_LINES;
+  const maxBytes =
+    typeof mem.budgetMaxBytes === 'number' && mem.budgetMaxBytes > 0
+      ? Math.floor(mem.budgetMaxBytes)
+      : DEFAULT_MAX_BYTES;
+  return { enabled, maxLines, maxBytes };
+}
+
+// Group lines under their nearest `## ` heading and measure each section's size,
+// so the report can name the heaviest sections to trim first.
+function analyze(content) {
+  const bytes = Buffer.byteLength(content, 'utf8');
+  const lines = content.split(/\r?\n/);
+  const sections = [];
+  let current = { title: '(preamble)', lineCount: 0 };
+  for (const line of lines) {
+    const m = line.match(/^##\s+(.+?)\s*$/); // top sections are `## `; deeper ones roll up
+    if (m) {
+      sections.push(current);
+      current = { title: m[1], lineCount: 0 };
+    }
+    current.lineCount += 1;
+  }
+  sections.push(current);
+  sections.sort((a, b) => b.lineCount - a.lineCount);
+  return { bytes, lineCount: lines.length, sections };
+}
+
+function buildReport(analysis, filePath, budget) {
+  const { bytes, lineCount, sections } = analysis;
+  if (lineCount < budget.maxLines && bytes < budget.maxBytes) return null; // lean → silent
+  const kb = (bytes / 1024).toFixed(1);
+  const maxKb = (budget.maxBytes / 1024).toFixed(1);
+  const out = [
+    `CLAUDE.md budget check — ${filePath}`,
+    `CLAUDE.md is ${lineCount} lines / ${kb}KB, past your ${budget.maxLines}-line / ${maxKb}KB ` +
+      `target (Settings → Config → Memory; past ~${COMPLIANCE_CLIFF_LINES} lines rule compliance ` +
+      `drops sharply — the compliance cliff). It is always-loaded, so trim it: move detail into a ` +
+      `procedure (fetched on demand via heyspex_get_procedure) and keep only the non-negotiable ` +
+      `contract. For each line ask "Would removing this cause Claude to make mistakes? If not, cut ` +
+      `it." See [[minimizing-claude-md-thin-agent-contract]].`,
+  ];
+  const heaviest = sections.filter((s) => s.title !== '(preamble)').slice(0, MAX_SECTIONS);
+  if (heaviest.length) {
+    out.push('Largest sections (trim or push to a procedure first):');
+    for (const s of heaviest) out.push(`  • ${s.lineCount} lines — ${s.title}`);
+  }
+  return out.join('\n');
+}
+
+async function main() {
+  if (process.env.HEYSPEX_CLAUDE_MD_BUDGET_OFF === '1') return;
+  // No CLAUDE_AGENT gate ([[HS-DT9L-NLR7-DIAG-nine-hooks-are-switched-off-in]]).
+  // This used to exit early in interactive sessions, so the one check on the
+  // always-loaded agent contract never ran where that file is actually edited —
+  // and nothing else guards it either ([[HS-UFQS-5PQ2-DIAG-nothing-gates-an-edit-to-claude-md]]).
+  // Safe to run everywhere: it emits NOTHING while the file is inside budget
+  // (measured 0 bytes on 2026-08-15), so it speaks only when there is something
+  // to say. Break-glass stays HEYSPEX_CLAUDE_MD_BUDGET_OFF=1.
+
+  const raw = await readStdinJson();
+  if (!raw) return;
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  if (payload?.hook_event_name !== 'SessionStart') return;
+
+  const projectDir =
+    (typeof payload.cwd === 'string' && payload.cwd) || process.env.CLAUDE_PROJECT_DIR || repoRoot();
+
+  const budget = resolveBudget(projectDir);
+  if (!budget.enabled) return; // user turned the gate off in Console settings
+
+  const file = resolveClaudeMdFile(projectDir);
+  let content;
+  try {
+    content = fs.readFileSync(file, 'utf8');
+  } catch {
+    return; // absent / unreadable → silent
+  }
+
+  // Duplication runs independent of the size budget above ([[HS-UFQS-5PQ2-DIAG]]):
+  // a lean, under-budget CLAUDE.md can still carry a stale inlined procedure copy.
+  const sizeReport = buildReport(analyze(content), file, budget);
+  const protocolLines = collectProtocolLines(resolveProtocolsDir(projectDir));
+  const dupReport = buildDuplicationReport(detectDuplicateLines(content, protocolLines));
+  const combined = [sizeReport, dupReport].filter(Boolean).join('\n\n');
+
+  emit('SessionStart', combined || null);
+}
+
+// Only run the hook when this file is executed directly (the Claude Code
+// hooks runner spawns it as a subprocess) — NOT on import. Without this guard,
+// a test/gate script that imports the pure helpers above (resolveProtocolsDir,
+// collectProtocolLines, detectDuplicateLines — reused by
+// scripts/check-claude-md-duplication.mjs per PORTING.md's "import, don't
+// re-derive") would also trigger main()'s stdin read as a side effect, which
+// registers stdin listeners that outlive the read and hang the importing
+// process ([[HS-STRB-NYPR-TASK-replace-every-inline-copy-of-a]]).
+const isDirectExecution =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isDirectExecution) {
+  main().catch(() => {
+    // Never break Claude Code on a hook failure.
+  });
+}

package/scripts/claude-hooks/check-mcp-freshness-hook.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/check-mcp-freshness-hook.mjs (the rule's mapping lives
+// in spexharness/src/mcp-freshness.mjs, the freshness FACT in
+// scripts/check-mcp-freshness.mjs).
+
+import { runGateAsHook } from '../../spexharness/src/adapters/claude-code.mjs';
+import gate from '../../spexharness/src/gates/check-mcp-freshness-hook.mjs';
+
+await runGateAsHook(gate);

package/scripts/claude-hooks/claim-before-code-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/claim-before-code-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/claim-before-code-gate.mjs';
+
+await runGateAsHook(gate);