heyspex 0.1.0 → 0.2.0

package/spexharness/src/git-reflog-audit.mjs

@@ -0,0 +1,294 @@
+// spexharness/src/git-reflog-audit.mjs
+//
+// The SHARED session-close git audit — moved here verbatim from
+// scripts/claude-hooks/git-reflog-audit.mjs (task HS-610I-P3TJ, epic
+// HS-GG01-P3TJ) as wave 6 of [[HS-AZ61-NYPR]] turned that hook into a thin
+// shim over ./gates/git-reflog-audit.mjs. There is exactly ONE copy of the
+// reflog parsing in the tree: this one. The gate imports it; the Claude Code
+// shim reaches it through the gate; scripts/claude-hooks/git-reflog-audit.test.mjs
+// (the original regression suite, unchanged apart from its import path) drives
+// it directly.
+//
+// WHY the rule exists (kept from the original header): every other gate in this
+// family (git-stash-gate, protected-action-intent) works by INTERCEPTING a
+// destructive command as it is issued — bypassed, disabled, or routed around a
+// gap in coverage, the action leaves no independent trace. This is a WITNESS,
+// not a gate: it snapshots git state at session start and diffs it at session
+// close, so a stash or a reset/checkout/rebase that slipped past every other
+// control still shows up in .heyspex/guardrail-history.jsonl — a record
+// independent of the acting agent's honesty.
+//
+// SCOPE: warn only. Never blocks, never denies.
+//
+// Snapshot (session start): writes `{ stash_count, reflog_head_entry,
+// written_at }` to a SESSION-SCOPED file — the filename carries the session id
+// so concurrent sessions on the same working tree never clobber each other's
+// baseline — at `.heyspex/git-reflog-audit/<sessionId>.json`.
+//
+// Diff (stop / session end):
+//   - stash: any INCREASE in `git stash list`'s entry count since the snapshot
+//     names the new top entries (a push always lands at stash@{0}).
+//   - reflog: any HEAD reflog entry newer than the snapshot's recorded head
+//     entry whose action is reset/checkout/rebase is named. Plain commits newer
+//     than the snapshot are NOT flagged — that's normal work. Matching strips
+//     the `HEAD@{N}:` index label before comparing (that label shifts every time
+//     a new entry lands, even when the underlying hash+message didn't change) —
+//     see [[never-chain-cd-with-destructive-git-a]] for why a naive hash-only
+//     compare is not enough: `git stash push` logs its own internal
+//     `reset: moving to HEAD` entry against the SAME hash as the just-committed
+//     HEAD, so hash equality alone can't tell old from new.
+// A clean session (no stash growth, no reset/checkout/rebase reflog entries)
+// appends nothing.
+//
+// TEST ISOLATION: every git call here takes an explicit repoRootPath and shells
+// out as `git -C <repoRootPath> ...` — never a bare `git` relying on cwd, and
+// never a `cd X && git ...` chain.
+//
+// FAIL-SAFE: every exported function degrades to an inert value (null / [] /
+// false) on any git or filesystem failure rather than throwing — this must
+// never break a session start or a session close on its own bug.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { appendGuardrailEvent } from '../../scripts/claude-hooks/_guardrail-events.mjs';
+
+/** The `rule` id every row this module appends is stamped with. */
+export const RULE_ID = 'git-reflog-audit';
+
+/** spexharness/src/ → repo root is two levels up. */
+const DEFAULT_REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+/** Env-first repo-root resolution, matching every pre-cutover hook's own helper. */
+export function repoRoot(env = process.env) {
+  const fromEnv = env.CLAUDE_PROJECT_DIR?.trim();
+  if (fromEnv) return fromEnv.replace(/[\\/]+$/, '');
+  return DEFAULT_REPO_ROOT;
+}
+
+function git(repoRootPath, args) {
+  try {
+    const res = spawnSync('git', ['-C', repoRootPath, ...args], { encoding: 'utf8', timeout: 5000 });
+    if (res.status !== 0) return null;
+    return typeof res.stdout === 'string' ? res.stdout : '';
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `git stash list`, newest first (`stash@{0}` is the top). [] on any failure
+ * (not a repo, git unavailable, etc.) — never throws.
+ */
+export function readStashList(repoRootPath) {
+  const out = git(repoRootPath, ['stash', 'list']);
+  if (out === null) return [];
+  return out.split(/\r?\n/).filter(Boolean);
+}
+
+/**
+ * `git reflog -n <limit>`, newest first. [] on any failure (including a
+ * brand-new repo with no commits yet, where HEAD has no reflog at all).
+ */
+export function readReflogLines(repoRootPath, limit = 50) {
+  const out = git(repoRootPath, ['reflog', '-n', String(limit)]);
+  if (out === null) return [];
+  return out.split(/\r?\n/).filter(Boolean);
+}
+
+/**
+ * Strip the `HEAD@{N}:` index label from a reflog line before comparing two
+ * lines captured at different times — the label shifts by one every time a new
+ * entry is pushed, even when the underlying hash+message is unchanged, so
+ * comparing raw lines would never match a genuinely-unchanged entry.
+ */
+export function normalizeReflogLine(line) {
+  return typeof line === 'string' ? line.replace(/HEAD@\{\d+\}:/, '').trim() : null;
+}
+
+/**
+ * The reflog "action" word for a line — the text right after `HEAD@{N}: ` and
+ * before the next space/colon/paren (`reset: moving to ...` → `reset`;
+ * `rebase (finish): ...` → `rebase`). null when the line doesn't have the
+ * expected shape — never throws.
+ */
+export function reflogAction(line) {
+  if (typeof line !== 'string') return null;
+  const m = /HEAD@\{\d+\}:\s*([a-zA-Z-]+)/.exec(line);
+  return m ? m[1].toLowerCase() : null;
+}
+
+const FLAGGED_REFLOG_ACTIONS = new Set(['reset', 'checkout', 'rebase']);
+
+/**
+ * Snapshot the git state this audit cares about. Never throws — a repo with no
+ * commits yet (empty reflog) or no stash entries yields zeros/nulls.
+ */
+export function captureGitState(repoRootPath) {
+  const stashLines = readStashList(repoRootPath);
+  const reflogLines = readReflogLines(repoRootPath, 1);
+  return {
+    stash_count: stashLines.length,
+    reflog_head_entry: reflogLines[0] ?? null,
+  };
+}
+
+function sanitizeSessionId(sessionId) {
+  const raw =
+    typeof sessionId === 'string' && sessionId.trim() ? sessionId.trim() : 'unknown-session';
+  return raw.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 120);
+}
+
+/** Default session-scoped snapshot path — `.heyspex/git-reflog-audit/<sessionId>.json`. */
+export function snapshotPathFor(repoRootPath, sessionId, snapshotDir = 'git-reflog-audit') {
+  return path.join(repoRootPath, '.heyspex', snapshotDir, `${sanitizeSessionId(sessionId)}.json`);
+}
+
+/**
+ * Session-start half: write the snapshot file. Returns the written snapshot
+ * object, or null on any failure (fail-safe — a write failure here must never
+ * break session start).
+ */
+export function writeSnapshot({ repoRootPath = repoRoot(), sessionId, snapshotPath } = {}) {
+  try {
+    const state = captureGitState(repoRootPath);
+    const snapshot = { ...state, written_at: new Date().toISOString() };
+    const filePath = snapshotPath || snapshotPathFor(repoRootPath, sessionId);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(snapshot));
+    return snapshot;
+  } catch {
+    return null;
+  }
+}
+
+/** Read a previously-written snapshot. null on any failure (missing/corrupt file). */
+export function readSnapshot(snapshotPath) {
+  try {
+    const raw = fs.readFileSync(snapshotPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Diff current git state against a snapshot. Returns
+ *   { newStashEntries: string[], flaggedReflogEntries: string[] }
+ * — both empty on a clean session.
+ */
+export function diffAgainstSnapshot(repoRootPath, snapshot) {
+  const result = { newStashEntries: [], flaggedReflogEntries: [] };
+  if (!snapshot || typeof snapshot !== 'object') return result;
+
+  // --- stash growth -------------------------------------------------------
+  const currentStash = readStashList(repoRootPath);
+  const priorCount = Number.isFinite(snapshot.stash_count) ? snapshot.stash_count : 0;
+  const grown = currentStash.length - priorCount;
+  if (grown > 0) {
+    result.newStashEntries = currentStash.slice(0, grown);
+  }
+
+  // --- reflog: reset/checkout/rebase entries newer than the snapshot ------
+  const priorEntry =
+    typeof snapshot.reflog_head_entry === 'string' ? snapshot.reflog_head_entry : null;
+  const currentReflog = readReflogLines(repoRootPath, 100);
+  if (currentReflog.length && currentReflog[0] !== priorEntry) {
+    const priorNormalized = normalizeReflogLine(priorEntry);
+    const idx =
+      priorNormalized === null
+        ? -1
+        : currentReflog.findIndex((line) => normalizeReflogLine(line) === priorNormalized);
+    // idx === -1 means no baseline (fresh repo) or the old entry fell outside
+    // the fetch window — bounded fallback: everything fetched is "new".
+    const newLines = idx === -1 ? currentReflog : currentReflog.slice(0, idx);
+    result.flaggedReflogEntries = newLines.filter((line) =>
+      FLAGGED_REFLOG_ACTIONS.has(reflogAction(line)),
+    );
+  }
+
+  return result;
+}
+
+/**
+ * The human-readable half of a flagged diff — `new stash: … ; reflog: …`, the
+ * exact `matchContext` string the guardrail-history row carries. Pure.
+ *
+ * @param {{ newStashEntries?: string[], flaggedReflogEntries?: string[] }} diff
+ * @returns {string} '' when nothing was flagged.
+ */
+export function describeDiff(diff) {
+  const parts = [];
+  if (diff?.newStashEntries?.length) parts.push(`new stash: ${diff.newStashEntries.join(' | ')}`);
+  if (diff?.flaggedReflogEntries?.length) {
+    parts.push(`reflog: ${diff.flaggedReflogEntries.join(' | ')}`);
+  }
+  return parts.join(' ; ');
+}
+
+/** True when a diff has anything worth warning about. Pure. */
+export function isFlagged(diff) {
+  return Boolean(diff?.newStashEntries?.length || diff?.flaggedReflogEntries?.length);
+}
+
+/**
+ * Stop / session-end half: read the snapshot, diff, and — only if something was
+ * flagged — append ONE warn row to guardrail-history.jsonl naming it. Returns
+ * the diff result (so a caller/test can assert on it), or null when there was
+ * no snapshot to compare against (nothing to do, no false-flag risk).
+ *
+ * @param {{ repoRootPath?: string, sessionId?: string, snapshotPath?: string,
+ *   append?: (row: object, repoRoot: string) => unknown }} [opts]
+ *   `append` — override the guardrail-history writer (tests, and any front that
+ *   wants the decision without the file write).
+ */
+export function runSessionEnd({
+  repoRootPath = repoRoot(),
+  sessionId,
+  snapshotPath,
+  append = appendGuardrailEvent,
+} = {}) {
+  const filePath = snapshotPath || snapshotPathFor(repoRootPath, sessionId);
+  const snapshot = readSnapshot(filePath);
+  if (!snapshot) return null;
+
+  const diff = diffAgainstSnapshot(repoRootPath, snapshot);
+  if (!isFlagged(diff)) return diff;
+
+  try {
+    append(
+      {
+        rule: RULE_ID,
+        surface: 'session-close',
+        severity: 'warn',
+        decision: 'warn',
+        matchContext: describeDiff(diff),
+      },
+      repoRootPath,
+    );
+  } catch {
+    // observability must never break the session close
+  }
+
+  return diff;
+}
+
+export default {
+  RULE_ID,
+  captureGitState,
+  describeDiff,
+  diffAgainstSnapshot,
+  isFlagged,
+  normalizeReflogLine,
+  readReflogLines,
+  readSnapshot,
+  readStashList,
+  reflogAction,
+  repoRoot,
+  runSessionEnd,
+  snapshotPathFor,
+  writeSnapshot,
+};

package/spexharness/src/intent-classifier.mjs

@@ -0,0 +1,194 @@
+// spexharness/src/intent-classifier.mjs
+//
+// Intent classification as an engine module on the prompt_submit event (HS-5ISS, epic
+// HS-1YDJ), replacing scripts/claude-hooks/_intent-classifier-router.mjs's per-prompt prose
+// injection with a mechanical lexical check against the engine's own compiled rule table
+// (./rule-table.mjs's loadRuleTable — the same registry _guardrail-loader.mjs reads, so this
+// module and the Claude Code hook agree about what a rule's pattern set and inject text are;
+// neither re-derives the other's regex).
+//
+// THE COST FIX (why this task exists): the original hook's Layer 2 ("self_check" semantic
+// mode) injects a multi-behavior "gate" block — one section per classifier behavior, several
+// KB of behavior descriptions — on every prompt that MISSES every lexical pattern and is at
+// least 12 characters long. That fires on almost every substantive prompt (an ordinary work
+// order matches none of the five behaviors' regex), which is the ~6.5 KB/prompt the epic
+// measured. This module drops that speculative layer entirely: classification here is
+// LEXICAL ONLY. A rule's `inject` text is resolved and returned only when one of its own
+// compiled patterns actually matches the prompt (AC2, "the directive is fetched only when a
+// gate fires") — a prompt that matches nothing produces `{ decision: 'allow' }` with no
+// injected text at all, which is the <500-byte target on a plain prompt (AC3).
+//
+// SCOPE NOTE: `classifyPrompt` is the LEXICAL core and stays pure — it returns the matched
+// rule's raw inject, nothing more. The per-behavior enrichment the plugin applies on top —
+// capture-on-idea's {{CONFIRM_MODE}} substitution, the capture-kind and thread-split-mode
+// hints, research-before-decision's appended source hint, the env/config kill switches, the
+// injected-content guard and the CONFIRMED MATCH marker — used to live only in
+// scripts/claude-hooks/_intent-classifier-router.mjs, so a SpexCode seat saw a different
+// (and, with the literal `{{CONFIRM_MODE}}` token, visibly unfinished) directive from the
+// one Claude Code injects for the same prompt. HS-N01T moved that assembly into
+// ./intent-directive.mjs, which BOTH the router and this gate's `run()` call — so the inject
+// this gate returns is now byte-identical to the plugin's. The semantic (Layer 2 self-check /
+// opt-in model-classify) layer stays in the router, unported.
+//
+// Pure: no I/O of its own beyond loadRuleTable's fs.readFileSync (itself fail-safe — see
+// rule-table.mjs's header). No process.stdin/stdout/exit.
+
+import { loadRuleTable } from './rule-table.mjs';
+import { buildIntentDirective } from './intent-directive.mjs';
+
+/** This gate's id, for a registry or an audit row. */
+export const GATE_ID = 'intent-classifier';
+/** Runs on the prompt-submit event, mirroring the retired hook's UserPromptSubmit wiring. */
+export const EVENT = 'prompt_submit';
+
+/**
+ * The rule table carries every `userpromptsubmit` rule, including
+ * `communication-style-prime` (HS-XIYJ's rule — an unconditional `[\s\S]` pattern that would
+ * "match" every prompt) and severity `prime` rules with no patterns at all. Intent
+ * classification is specifically the five mutually-exclusive INTENT rules the original
+ * router's `CLASSIFIER_BEHAVIORS` catalog named — restricting to these ids is what keeps
+ * this module from reinventing the always-on communication-style injection XIYJ retires
+ * separately.
+ * @type {ReadonlyArray<string>}
+ */
+export const CLASSIFIER_RULE_IDS = Object.freeze([
+  'capture-on-idea',
+  'research-before-decision',
+  'settings-intent',
+  'defer-intent',
+  'spec-reference-lookup',
+]);
+
+/** Compile a rule's string patterns into case-insensitive RegExps, skipping any that fail
+ *  to compile (a corrupt pattern degrades to "never matches", never a throw). */
+function compilePatterns(rule) {
+  const patterns = Array.isArray(rule?.patterns) ? rule.patterns : [];
+  const compiled = [];
+  for (const source of patterns) {
+    try {
+      compiled.push(new RegExp(source, 'i'));
+    } catch {
+      // corrupt pattern in the table — skip it, fail-safe.
+    }
+  }
+  return compiled;
+}
+
+/** The classifier rules eligible to fire, in {@link CLASSIFIER_RULE_IDS} order (the
+ *  deterministic lexical tiebreak, mirroring the original router's BEHAVIOR_ORDER). */
+function classifierRules(table) {
+  const byId = new Map((table?.rules ?? []).map((r) => [r?.rule, r]));
+  const rules = [];
+  for (const id of CLASSIFIER_RULE_IDS) {
+    const rule = byId.get(id);
+    if (rule && typeof rule.inject === 'string' && rule.inject.trim() && rule.surfaces?.includes('userpromptsubmit')) {
+      rules.push(rule);
+    }
+  }
+  return rules;
+}
+
+/**
+ * @typedef {object} IntentClassification
+ * @property {string} rule            the matched rule's id (e.g. 'capture-on-idea').
+ * @property {string} sourceProtocol  the protocol that authored the rule.
+ * @property {string} inject          the rule's raw inject text (unmodified — see the
+ *   SCOPE NOTE above; per-behavior enrichment/substitution is not applied here).
+ */
+
+/**
+ * Classify a prompt against the engine's compiled rule table. First matching rule (in
+ * {@link CLASSIFIER_RULE_IDS} order) wins; a full miss returns null — no directive is
+ * resolved, matching AC2/AC3.
+ *
+ * @param {string} prompt
+ * @param {{ vaultRoot?: string, ruleTable?: { rules: object[] } }} [opts]
+ *   `ruleTable` is injectable so a test never depends on the live
+ *   `.heyspex/guardrails.json`/built-in table; omitted, it loads the real one via
+ *   {@link loadRuleTable}.
+ * @returns {IntentClassification|null}
+ */
+export function classifyPrompt(prompt, { vaultRoot, ruleTable } = {}) {
+  if (typeof prompt !== 'string' || !prompt.trim()) return null;
+  const table = ruleTable ?? loadRuleTable({ vaultRoot });
+  for (const rule of classifierRules(table)) {
+    const patterns = compilePatterns(rule);
+    if (patterns.some((re) => re.test(prompt))) {
+      return { rule: rule.rule, sourceProtocol: rule.sourceProtocol ?? null, inject: rule.inject };
+    }
+  }
+  return null;
+}
+
+/**
+ * The engine gate: runs on `prompt_submit`, classifies the prompt, and only when a rule
+ * actually fires does it return an `inject` decision carrying that rule's directive. A miss
+ * — including the common "plain prompt, matches nothing" case — is a plain `allow` with no
+ * injected text, satisfying AC3's <500-byte-on-a-plain-prompt target by construction (an
+ * `allow` decision carries no `inject` field at all).
+ *
+ * HS-N01T: a hit is then run through ./intent-directive.mjs's `buildIntentDirective` — the
+ * SAME eligibility check (env kill switch, config toggle, injected-content guard) and the
+ * SAME directive assembly (confirm-mode substitution, kind/routing hints, CONFIRMED MATCH
+ * marker) the Claude Code hook applies — so `inject.additionalContext` is what the plugin
+ * would have injected, never the raw inject with a literal `{{CONFIRM_MODE}}`. An
+ * ineligible behavior is an `allow`. A rule the behavior catalog does not know (or a row
+ * the plugin router would never fire) keeps the pre-N01T raw passthrough.
+ *
+ * `ctx` (all optional): `vaultRoot`/`repoRoot` — the app root holding `.heyspex/`;
+ * `ruleTable` — an injected table (tests); `env` — env overrides instead of `process.env`;
+ * `getSetting(repoRoot, key)` — an injected settings reader so a test never reads the real
+ * config (see ./intent-directive.mjs's header for the accepted shapes).
+ *
+ * @param {{ point: string, prompt?: string }} evt
+ * @param {{ vaultRoot?: string, repoRoot?: string, ruleTable?: object, env?: object, getSetting?: Function }} [ctx]
+ * @returns {{ decision: 'allow' }|{ decision: 'inject', reason: string, inject: { additionalContext: string, rule: string, behavior: string|null } }}
+ */
+export function run(evt, ctx = {}) {
+  const repoRoot = ctx.repoRoot ?? ctx.vaultRoot;
+  // One table load for both the lexical match and the directive resolution.
+  const ruleTable = ctx.ruleTable ?? loadRuleTable({ vaultRoot: repoRoot });
+  const hit = classifyPrompt(evt?.prompt, { ruleTable });
+  if (!hit) return { decision: 'allow' };
+  let built;
+  try {
+    built = buildIntentDirective(hit.rule, evt.prompt, {
+      repoRoot,
+      ruleTable,
+      env: ctx.env,
+      getSetting: ctx.getSetting,
+    });
+  } catch {
+    // The directive assembly is best-effort enrichment; a crash in it must never turn a
+    // confirmed lexical fire into silence. Degrade to the raw inject.
+    built = { behavior: null, additionalContext: null };
+  }
+  if (built === null) return { decision: 'allow' }; // killed by env/config/injected-content guard
+  return {
+    decision: 'inject',
+    reason: `intent-classifier: ${hit.rule} fired`,
+    inject: {
+      additionalContext: built.additionalContext ?? hit.inject,
+      rule: hit.rule,
+      behavior: built.behavior,
+    },
+  };
+}
+
+/**
+ * Caller-defined severity label. `prime` is the severity every rule in
+ * {@link CLASSIFIER_RULE_IDS} carries in the compiled registry — this gate never
+ * denies, it only primes a turn with the matched rule's directive.
+ *
+ * Added in wave 6 of [[HS-AZ61-NYPR]]: the module was written as a gate but was
+ * registered by nothing, so the classification it owns ran on no front at all.
+ * spexharness/src/gates/index.mjs now registers it (a registry row needs a
+ * severity for `hs harness gates` to print, hence this export), and
+ * spexharness/src/plugin-hook-coverage.test.mjs pins that registration so the
+ * Claude Code `intent-classifier-trigger` hook's coverage cannot silently lapse
+ * again.
+ */
+export const SEVERITY = 'prime';
+
+const gate = { id: GATE_ID, event: EVENT, severity: SEVERITY, run };
+export default gate;