heyspex 0.1.0 → 0.2.1

package/spexharness/src/gates/naughty-list-gate.mjs

@@ -0,0 +1,213 @@
+// spexharness/src/gates/naughty-list-gate.mjs
+//
+// Engine port of scripts/claude-hooks/naughty-list-gate.mjs — the Stop hook
+// that enforces the "naughty list" (banned metaphorical jargon,
+// [[HS-PROTO-terminology-governance]]) on the agent's own final message. See
+// ./PORTING.md for the recipe this follows and ./env-vault-guard.mjs for the
+// reference port.
+//
+// This module does NOT reimplement the vocabulary rule itself (AC5's own
+// words: "read their word lists ... from loadRuleTable, not a second copy").
+// The actual decision — does this prose contain a banned term? — comes
+// straight from the shared, already-pure loader:
+//   - scripts/claude-hooks/_guardrail-loader.mjs — loadGuardrails,
+//     rulesForSurface, isRuleEnabled, vocabularyViolations.
+//     vocabularyViolations owns the per-user `.heyspex/terminology.local.json`
+//     override merge (resolveVocabulary) AND the prose exemptions (code
+//     spans, fenced blocks, [[wikilinks]], URLs, blockquotes via proseOnly)
+//     internally — this module never reimplements either.
+//   - scripts/claude-hooks/_transcript-text.mjs — lastAssistantText, the same
+//     shared transcript-text reader id-display-format-gate.mjs's port also
+//     uses (split out of this hook's original sole ownership specifically so
+//     a second Stop-hook scanner wouldn't fork a copy).
+// Both are dependency-free / no import hazard, matching enforce-session-
+// sequence.mjs's port.
+//
+// JUDGMENT CALL — the original script does NOT export a pure decision
+// function; its logic is tangled inside main()'s stdin read. Per PORTING.md
+// step 1's "otherwise" branch this would normally move into the original
+// script itself, but this task's Do-nots forbid touching anything under
+// scripts/claude-hooks/. What is re-derived here is NOT the vocabulary rule
+// (that stays imported, per AC5) — it is pure string-formatting glue
+// (`reasonLines`, `blockReason`, the warn-stderr message template) copied
+// verbatim from the original's own (unexported) helpers, plus the
+// interactive-rung resolver (`interactiveRung`, reading
+// HEYSPEX_NAUGHTY_LIST_INTERACTIVE) copied verbatim too.
+//
+// Event mapping: Stop → stop. `stdin.transcript_path` → `evt.transcriptPath`.
+//
+// Decision mapping — TWO rungs (AC4's "including the naughty-list gate's
+// warn-versus-block rung"): CLAUDE_AGENT=true selects the "isAgent" branch,
+// which blocks on any block-severity hit; the interactive default (agent
+// unset, HEYSPEX_NAUGHTY_LIST_INTERACTIVE not raised to "block") maps the
+// SAME hits to a `rewrite` envelope (`{ warn: true, reason, hits }`) instead
+// — the stop is still allowed, matching the original's stderr-only warn path
+// exactly (never silently upgraded to deny, never silently downgraded to a
+// plain allow that would drop the reason text). This gives this gate natural
+// coverage of all three engine decisions (AC3): allow on clean prose or no
+// vocabulary rule compiled, deny on a block-severity hit in the real-block
+// rung, rewrite on the warn rung (or on a warn-severity-only hit in any
+// rung).
+//
+// Not ported HERE: the original's `appendGuardrailEvent(...)` audit-log
+// write on every block-severity hit (fired even in the warn rung, to build
+// the evidence log the rung is raised on) — matching every other port in
+// this set. This `run()` still carries the block-severity hits forward as a
+// top-level `blockHits` field on its `deny` AND `rewrite` results (never on
+// a plain `allow`, and never including warn-severity-only hits — the
+// original's own loop only ever logs block-severity hits, whichever rung
+// the run happens to be on) so a FRONT can rebuild that exact per-hit audit
+// trail without re-deriving hit words/contexts from `reason` text — see
+// spexharness/src/adapters/audit.mjs, called from
+// spexharness/src/adapters/claude-code.mjs's runGateAsHook.
+//
+// Env hatches (unchanged):
+//   HEYSPEX_NAUGHTY_LIST_OFF=1               Hard kill switch — silences both rungs.
+//   HEYSPEX_NAUGHTY_LIST_INTERACTIVE=block   Raise the interactive rung to a real deny.
+//   CLAUDE_AGENT=true                        Unattended session → real deny (unchanged).
+// Also honors the rule's own registry configKey
+// (agent_behaviors.terminology_enforcement.enabled) via isRuleEnabled.
+//
+// `ctx` contract (all optional; every field defaults to a real fs/env read):
+//   ctx.cwd  - repo root to resolve the guardrail registry + terminology
+//              override from. Defaults to CLAUDE_PROJECT_DIR, else this
+//              repo's root. When given it is a self-contained fixture root and
+//              the rule's config toggle is read from it too.
+//   ctx.configRoot - the directory holding `.heyspex/config.yaml` (the rule's
+//              configKey toggle); wins over ctx.cwd for that read. With neither,
+//              the VAULT root (../config-root.mjs `defaultConfigRoot()`) — never
+//              CLAUDE_PROJECT_DIR, which under Claude Code is the app checkout,
+//              not where the settings file lives
+//              ([[HS-4C76-9W86-DIAG-heyspex-config-yaml-has-no-single-home]]).
+//              The terminology override stays on ctx.cwd (a code-repo artifact).
+//   ctx.env  - env var overrides (tests use this instead of mutating
+//              process.env).
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { lastAssistantText } from '../../../scripts/claude-hooks/_transcript-text.mjs';
+import {
+  loadGuardrails,
+  rulesForSurface,
+  isRuleEnabled,
+  vocabularyViolations,
+} from '../../../scripts/claude-hooks/_guardrail-loader.mjs';
+import { defaultConfigRoot } from '../config-root.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, '..', '..', '..');
+
+// Copied verbatim from the original's own (unexported) reasonLines.
+function reasonLines(hits) {
+  const seen = new Map();
+  for (const h of hits) if (!seen.has(h.word)) seen.set(h.word, h.fix);
+  return [...seen.entries()].map(([word, fix]) => `  • "${word}" → ${fix}`);
+}
+
+// Copied verbatim from the original's own (unexported) blockReason.
+function blockReason(hits) {
+  return (
+    `Naughty-list violation: your last message used banned metaphorical jargon ` +
+    `(the HeySpex default list from specs/naughty-list.md, also the owner's preference). ` +
+    `Rewrite those words in plain literal language and resend:\n${reasonLines(hits).join('\n')}\n` +
+    `(To refer to a banned word as a word, wrap it in backticks. Customize per checkout via ` +
+    `.heyspex/terminology.local.json {add,allow,remove}. Break-glass: HEYSPEX_NAUGHTY_LIST_OFF=1.)`
+  );
+}
+
+// Copied verbatim from the original's own (unexported) warn message template.
+function warnReason(hits) {
+  return `[naughty-list] warning — banned terms in your last message (not blocked):\n${reasonLines(hits).join('\n')}\n`;
+}
+
+// Copied verbatim from the original's own (unexported) interactiveRung.
+function interactiveRung(env) {
+  const raw = String(env.HEYSPEX_NAUGHTY_LIST_INTERACTIVE ?? '').trim().toLowerCase();
+  return raw === 'block' ? 'block' : 'warn';
+}
+
+/**
+ * The prose this stop event is about. A front that ALREADY holds the reply (`hs chat`, a
+ * headless seat, the bench — none of which write a Claude Code transcript file) passes it on
+ * the event as `text`, or on the ctx as `reply`; a Claude Code hook shell passes only
+ * `transcriptPath` and the text is read from it. Checked in that order, so the same gate runs
+ * on every front instead of silently allowing everything on the ones with no transcript —
+ * which is exactly what it did before (QC finding, 2026-09-10). The `ctx.reply` name matches
+ * enforce-session-sequence.mjs's stop-time corrector, which already took the reply that way.
+ *
+ * @param {{ text?: string, transcriptPath?: string }} evt
+ * @param {{ reply?: string }} ctx
+ * @param {(p: string) => string|null} readTranscript
+ * @returns {string}
+ */
+function stopEventText(evt, ctx, readTranscript) {
+  if (typeof ctx?.reply === 'string' && ctx.reply) return ctx.reply;
+  if (typeof evt?.text === 'string' && evt.text) return evt.text;
+  const transcriptPath = evt?.transcriptPath;
+  if (!transcriptPath) return '';
+  return readTranscript(transcriptPath) ?? '';
+}
+
+/** The naughty-list gate's id — unique across the built-in registry. */
+export const id = 'naughty-list-gate';
+/** Runs on the Stop event, same as its Stop Claude Code hook registration. */
+export const event = 'stop';
+/** Caller-defined severity label; this gate can deny, so it is "block". */
+export const severity = 'block';
+
+/**
+ * @param {{ point: string, text?: string, transcriptPath?: string }} evt
+ * @param {{ cwd?: string, configRoot?: string, reply?: 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_NAUGHTY_LIST_OFF ?? '') === '1') {
+    return { decision: 'allow' };
+  }
+
+  const isAgent = env.CLAUDE_AGENT === 'true';
+  const warnOnly = !isAgent && interactiveRung(env) !== 'block';
+
+  const text = stopEventText(evt, ctx, lastAssistantText);
+  if (!text) return { decision: 'allow' };
+
+  const root = ctx.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? REPO_ROOT;
+  const configRoot = ctx.configRoot ?? (ctx.cwd ? ctx.cwd : defaultConfigRoot());
+  const guardrails = loadGuardrails(root);
+  const rules = rulesForSurface(guardrails, 'stop').filter((r) => r && r.kind === 'vocabulary');
+  if (!rules.length) return { decision: 'allow' };
+
+  const blockHits = [];
+  const warnHits = [];
+  for (const rule of rules) {
+    if (!isRuleEnabled(rule, configRoot)) continue;
+    const hits = vocabularyViolations(rule, text, root);
+    if (!hits.length) continue;
+    (rule.severity === 'block' ? blockHits : warnHits).push(...hits);
+  }
+
+  if (blockHits.length && !warnOnly) {
+    return { decision: 'deny', reason: blockReason(blockHits), blockHits };
+  }
+
+  const softHits = warnOnly ? [...blockHits, ...warnHits] : warnHits;
+  if (softHits.length) {
+    const reason = warnReason(softHits);
+    // `blockHits` (block-severity hits ONLY, never the warn-severity ones
+    // folded into `softHits`/`rewrite.hits` for display) rides separately so
+    // a front's audit log matches the original's own loop, which logs a row
+    // per block-severity hit on every rung — never for a warn-severity hit.
+    return {
+      decision: 'rewrite',
+      reason,
+      rewrite: { warn: true, reason, hits: softHits },
+      ...(blockHits.length ? { blockHits } : {}),
+    };
+  }
+
+  return { decision: 'allow' };
+}
+
+export default { id, event, severity, run };

package/spexharness/src/gates/plan-review-gate.mjs

@@ -0,0 +1,233 @@
+// spexharness/src/gates/plan-review-gate.mjs
+//
+// Engine port of scripts/claude-hooks/plan-review-gate.mjs — the PreToolUse
+// gate over ExitPlanMode that enforces the V1 → quality+canonical check → V2
+// contract (a heyspex_plan_review marker) and, once that passes, the QC
+// gut-check marker (heyspex_plan_qc) — both keyed by sha256(plan content),
+// [[HS-EPIC-PLRV]]. See ./PORTING.md for the recipe this follows and
+// ./env-vault-guard.mjs for the reference port.
+//
+// JUDGMENT CALL — read before touching this file: the original script does
+// NOT export a pure decision function; its logic (resolvePlan, denyReason,
+// denyReasonQc, shouldBlockForReal, fireDeny) is tangled with main()'s stdin
+// read. This task's Do-nots forbid touching anything under
+// scripts/claude-hooks/, so per PORTING.md step 1's "otherwise" branch this
+// module re-derives the plumbing here. What is re-derived is NOT
+// security-relevant regex/rule logic — it is (a) the marker-path
+// construction (a plain sha256(plan content) → `.heyspex/plan-reviews/` /
+// `.heyspex/plan-qc/` join, no judgment call baked in) and (b) the deny-
+// reason string TEMPLATES, copied verbatim from the original's own
+// (unexported) `denyReason`/`denyReasonQc` functions so the text a caller
+// sees is byte-identical to what the original would have written — the same
+// "copy verbatim where the original's own strings are copyable" approach
+// deep-research-cost-gate.mjs's port documents for its own unexported COST
+// table and message templates. If the original script is ever changed to
+// export these, this module's copies should be deleted in favor of the real
+// thing.
+//
+// Event mapping: PreToolUse (ExitPlanMode) → before_tool. The original's own
+// defense-in-depth tool-name check (`tool_name !== 'ExitPlanMode'` → allow)
+// is preserved here.
+//
+// Decision mapping — TWO independent rungs, same two-rung shape as
+// enforce-session-sequence.mjs's port: CLAUDE_AGENT=true or
+// HEYSPEX_PLAN_REVIEW_GATE_INTERACTIVE=block ("forReal") maps a missing
+// marker to a real `deny`; the interactive default maps the SAME missing-
+// marker finding to a `rewrite` envelope (`{ warn: true, reason, rule }`) —
+// the stop is still allowed, matching the original's stderr-only warn path
+// exactly (never silently upgraded to deny, never silently downgraded to a
+// plain allow that would drop the reason text). This gives this gate natural
+// coverage of all three engine decisions (AC3): allow when both markers are
+// present (or the tool isn't ExitPlanMode), deny on the unattended/raised
+// rung, rewrite on the interactive-default rung.
+//
+// Not ported: the original's `appendGuardrailEvent(...)` audit-log write on
+// a fire — matching every other port in this set (a gate module here is a
+// pure decision function with no other observability side effects; a front
+// that wants the same audit trail logs `denials`/`rewrites` itself).
+//
+// Env hatches (unchanged):
+//   HEYSPEX_PLAN_REVIEW_GATE_OFF=1              Hard kill switch — silences both rungs and both markers.
+//   HEYSPEX_PLAN_REVIEW_GATE_INTERACTIVE=block  Raise the interactive rung to a real deny (V1 half only).
+//   HEYSPEX_PLAN_QC_GATE_OFF=1                  Mute the QC-marker half only (the V1 half still gates).
+//   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 marker directories
+//                               from. Defaults to CLAUDE_PROJECT_DIR, else
+//                               this repo's root.
+//   ctx.env                  - env var overrides (tests use this instead of
+//                               mutating process.env).
+//   ctx.resolvePlanFallback  - override for the original's `~/.claude/plans/`
+//                               most-recently-mtimed-file fallback (used only
+//                               when the tool input carries no inline
+//                               `plan`). Defaults to a real fs scan of the
+//                               real home directory; every fixture here
+//                               supplies an inline plan, so this fallback is
+//                               never exercised by the golden/regression
+//                               tests, only kept for behavioral parity.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, '..', '..', '..');
+const PROCEDURE_NAME = 'plan-quality-canonical-check';
+
+// Copied verbatim from the original's own (unexported) resolvePlan — see the
+// judgment-call note above.
+function defaultResolvePlanFallback() {
+  try {
+    const plansDir = path.join(os.homedir(), '.claude', 'plans');
+    const entries = fs
+      .readdirSync(plansDir)
+      .map((name) => path.join(plansDir, name))
+      .filter((p) => {
+        try {
+          return fs.statSync(p).isFile();
+        } catch {
+          return false;
+        }
+      })
+      .map((p) => ({ p, mtime: fs.statSync(p).mtimeMs }))
+      .sort((a, b) => b.mtime - a.mtime);
+    if (entries.length > 0) {
+      const content = fs.readFileSync(entries[0].p, 'utf8');
+      return { content, source: entries[0].p };
+    }
+  } catch {
+    // No plans dir / unreadable — fall through.
+  }
+  return null;
+}
+
+function resolvePlan(toolInput, ctx) {
+  const inline = toolInput?.plan;
+  if (typeof inline === 'string' && inline.trim()) {
+    return { content: inline, source: 'tool_input.plan' };
+  }
+  const fallback = ctx.resolvePlanFallback ?? defaultResolvePlanFallback;
+  try {
+    return fallback();
+  } catch {
+    return null;
+  }
+}
+
+// Copied verbatim from the original's own (unexported) denyReason.
+function denyReason(planSource) {
+  const where = planSource ? ` (plan at ${planSource})` : '';
+  return (
+    `Plan V1 detected${where}. Before leaving plan mode, run ` +
+    `heyspex_plan_review({ plan_content: <the plan you are about to submit> }) ` +
+    `(or plan_path if the plan is on disk), fold the findings into a V2 revision ` +
+    `of the plan, then call ExitPlanMode again with the revised plan. This gate ` +
+    `is non-skippable — it enforces the V1 → quality+canonical check → V2 ` +
+    `contract; see ${PROCEDURE_NAME}.md. ` +
+    `(Break-glass: set HEYSPEX_PLAN_REVIEW_GATE_OFF=1.)`
+  );
+}
+
+// Copied verbatim from the original's own (unexported) denyReasonQc.
+function denyReasonQc(planSource) {
+  const where = planSource ? ` (plan at ${planSource})` : '';
+  return (
+    `Plan-review passed, but the QC gut-check has not run for this plan ` +
+    `version${where}. Before leaving plan mode, run the \`/hs-qc\` gut-check, fold ` +
+    `its findings into the plan, then call ` +
+    `heyspex_plan_qc({ plan_content: <the plan you are about to submit>, ` +
+    `findings_summary: <what the gut-check actually found> }) to record ` +
+    `Proof-of-Use, then call ExitPlanMode again. This gate is non-skippable; ` +
+    `see ${PROCEDURE_NAME}.md. (Break-glass for the QC half only: set ` +
+    `HEYSPEX_PLAN_QC_GATE_OFF=1.)`
+  );
+}
+
+function shouldBlockForReal(env) {
+  return env.CLAUDE_AGENT === 'true' || env.HEYSPEX_PLAN_REVIEW_GATE_INTERACTIVE === 'block';
+}
+
+// Byte-for-byte the original hook's own interactive-warn stderr banner
+// (fireDeny()'s `else` branch) — kept here rather than left to the adapter's
+// generic warn formatter because the second line names THIS gate's own env
+// var, same convention as claim-before-code-gate.mjs's warnReason.
+function warnStderrText(reason) {
+  return (
+    `[plan-review-gate] warning — ${reason}\n` +
+    '(Interactive session: this only warns. Set HEYSPEX_PLAN_REVIEW_GATE_INTERACTIVE=block to enforce it here too.)\n'
+  );
+}
+
+/** The plan-review gate's id — unique across the built-in registry. */
+export const id = 'plan-review-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> }} evt
+ * @param {{ cwd?: string, env?: Record<string, string | undefined>,
+ *            resolvePlanFallback?: () => { content: string, source: string } | null }} [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_PLAN_REVIEW_GATE_OFF ?? '') === '1') {
+    return { decision: 'allow' };
+  }
+
+  // Defense-in-depth: the real settings.json matcher already scopes this to
+  // ExitPlanMode, but never gate any other tool even if mis-wired.
+  if (evt?.toolName !== 'ExitPlanMode') {
+    return { decision: 'allow' };
+  }
+
+  const plan = resolvePlan(evt?.toolInput ?? {}, ctx);
+  if (!plan) {
+    // Can't find the plan content to hash → fail open (allow), same as the original.
+    return { decision: 'allow' };
+  }
+
+  const root = ctx.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? REPO_ROOT;
+  const hash = createHash('sha256').update(plan.content).digest('hex');
+  const reviewMarker = path.join(root, '.heyspex', 'plan-reviews', `${hash}.json`);
+  const forReal = shouldBlockForReal(env);
+
+  if (!fs.existsSync(reviewMarker)) {
+    const reason = denyReason(plan.source);
+    return forReal
+      ? { decision: 'deny', reason }
+      : {
+          decision: 'rewrite',
+          reason,
+          rewrite: { warn: true, reason, rule: 'plan-review-gate:v1', stderrText: warnStderrText(reason) },
+        };
+  }
+
+  // Plan-review passed. Now require the QC gut-check marker for the SAME
+  // plan hash — unless the QC half is muted (the master kill switch above
+  // mutes both).
+  if (String(env.HEYSPEX_PLAN_QC_GATE_OFF ?? '') === '1') {
+    return { decision: 'allow' };
+  }
+
+  const qcMarker = path.join(root, '.heyspex', 'plan-qc', `${hash}.json`);
+  if (fs.existsSync(qcMarker)) {
+    return { decision: 'allow' };
+  }
+
+  const reasonQc = denyReasonQc(plan.source);
+  return forReal
+    ? { decision: 'deny', reason: reasonQc }
+    : {
+        decision: 'rewrite',
+        reason: reasonQc,
+        rewrite: { warn: true, reason: reasonQc, rule: 'plan-review-gate:qc', stderrText: warnStderrText(reasonQc) },
+      };
+}
+
+export default { id, event, severity, run };