heyspex 0.1.0 → 0.2.0

package/spexharness/src/gates/enforce-vault-naming.mjs

@@ -0,0 +1,215 @@
+// spexharness/src/gates/enforce-vault-naming.mjs
+//
+// Engine port of scripts/claude-hooks/enforce-vault-naming.mjs — the
+// PreToolUse guard that blocks file creation violating the HeySpex vault
+// naming conventions (per-directory filename patterns + slug-only zones)
+// BEFORE the file lands on disk. See ./PORTING.md for the recipe this
+// follows and ./env-vault-guard.mjs for the reference port.
+//
+// This module does NOT reimplement the naming rule itself. The actual
+// decision — is this relative path shaped correctly for its directory? —
+// comes straight from the shared, already-pure loader (AC5's own words: "read
+// their word lists and id shapes from loadRuleTable, not a second copy"):
+//   - scripts/claude-hooks/_guardrail-loader.mjs — loadGuardrails,
+//     rulesForSurface, namingViolation. namingViolation reads the
+//     `id-suffix-shape` rule's `naming` payload (compiled from
+//     vault-id-assignment-protocol.md's `enforcement:` block via
+//     spexharness/src/rule-table.mjs, imported by _guardrail-loader.mjs
+//     itself — so this module is already two layers removed from any
+//     hand-coded pattern).
+//   - vendor/heyspex-mcp/vault-resolve.mjs — getActiveConfig(), for the
+//     same optional second vault-root base the original's `vaultRootSafe()`
+//     helper resolves (specs living in a vault split out from the code
+//     repo).
+// 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 naming rule
+// itself (that stays imported, per AC5) — it is candidate-path EXTRACTION
+// glue that carries no rule content of its own: `extractBashTargets` (pulls
+// file-creation targets out of common shell idioms — mv/cp/touch/install/
+// redirects/tee), `normalizeRel` (relativizes a path against the repo root or
+// the resolved vault root), and `formatReason` (pure string formatting of a
+// namingViolation() descriptor) — all three copied verbatim from the
+// original's own (unexported) helpers of the same name, so a future change
+// to the original's extraction heuristics is the only thing that can drift
+// this module, never the naming rule itself.
+//
+// Event mapping: PreToolUse (Write|Edit|MultiEdit|NotebookEdit|Bash|
+// PowerShell) → before_tool. Edit/MultiEdit always allow (unchanged — the
+// original never re-validates an existing file at edit time).
+//
+// Decision mapping: no violations found (including "not our concern" cases —
+// unmanaged tool, path outside both repo bases, no naming rule compiled) →
+// allow. One or more violations → deny, with the SAME joined multi-violation
+// reason text the original wrote to stderr before exit(2).
+//
+// This gate has NO env-var kill switch — the original script documents none
+// (unlike its siblings), so none is ported here. AC4 ("every environment
+// escape hatch the original documented ... covered by a test per hatch")
+// has nothing to cover for this gate; its own test file says so explicitly.
+//
+// Not ported: the original's `appendGuardrailEvent(...)` audit-log write on
+// a block — matching every other port in this set.
+//
+// `ctx` contract (all optional; every field defaults to a real fs/env read):
+//   ctx.cwd            - repo root to resolve candidate paths against.
+//                         Defaults to CLAUDE_PROJECT_DIR, else this repo's
+//                         root.
+//   ctx.getActiveConfig - override for the vault-root resolver (tests can
+//                         pin a second base without touching real vault
+//                         config). Defaults to the real getActiveConfig.
+//   ctx.existsSync      - override for the requireNew (new-file) probe.
+//                         Defaults to a real fs.existsSync.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { loadGuardrails, rulesForSurface, namingViolation } from '../../../scripts/claude-hooks/_guardrail-loader.mjs';
+import { getActiveConfig } from '../../../vendor/heyspex-mcp/vault-resolve.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, '..', '..', '..');
+
+// Copied verbatim from the original's own (unexported) vaultRootSafe.
+function vaultRootSafe(getActiveConfigFn) {
+  try {
+    return getActiveConfigFn()?.repoRootAbs ?? null;
+  } catch {
+    return null; // fail-safe: the code-repo base still applies
+  }
+}
+
+// Copied verbatim from the original's own (unexported) normalizeRel.
+function normalizeRel(absOrRel, root, getActiveConfigFn) {
+  if (!absOrRel || typeof absOrRel !== 'string') return null;
+  const abs = path.isAbsolute(absOrRel) ? absOrRel : path.resolve(root, absOrRel);
+  const bases = [root];
+  const vault = vaultRootSafe(getActiveConfigFn);
+  if (vault && vault !== root) bases.push(vault);
+  for (const base of bases) {
+    const rel = path.relative(base, abs);
+    if (!rel.startsWith('..') && !path.isAbsolute(rel)) {
+      return { rel: rel.split(path.sep).join('/'), abs }; // POSIX for matching
+    }
+  }
+  return null; // outside both repos — not our concern
+}
+
+// Copied verbatim from the original's own (unexported) formatReason.
+function formatReason(v) {
+  const allocHint = v.kind
+    ? `  IDs are auto-minted — do NOT hand-author the filename or id. File via the minter (heyspex_file_spec for agents, or POST /api/specs) so the server generates a conforming '${v.kind}' id from the canonical template.`
+    : `  Reuse the parent spec's id suffix — review docs are named HS-<parent-key>-REV-<fileKey>-<slug>.md.`;
+  const fileKeyHint = v.strictNew
+    ? `  NEW files require a per-file FILE KEY (4 uppercase alphanumerics, at least one letter) between the type label and the title slug — minted by the server, never hand-picked (owner ruling 2026-07-10).`
+    : null;
+  const exampleLine = v.example ? `  Example: ${v.dir}/${v.example}` : null;
+  return [
+    `HeySpex naming violation: ${v.relPath}`,
+    `  Required pattern: ${v.requiredPattern}`,
+    fileKeyHint,
+    exampleLine,
+    allocHint,
+    `  See specs/protocols/vault-id-assignment-protocol.md.`,
+  ]
+    .filter(Boolean)
+    .join('\n');
+}
+
+// Copied verbatim from the original's own (unexported) extractBashTargets —
+// a conservative shell-idiom scanner, not a naming rule.
+function extractBashTargets(command) {
+  if (!command || typeof command !== 'string') return [];
+  const targets = new Set();
+
+  const redirectRe = /(?:>>?|\|\s*tee(?:\s+-a)?)\s+("([^"]+)"|'([^']+)'|(\S+))/g;
+  for (const m of command.matchAll(redirectRe)) {
+    targets.add(m[2] ?? m[3] ?? m[4]);
+  }
+
+  const cmdRe = /\b(?:mv|cp|touch|install|rename|Move-Item|Copy-Item|New-Item)\s+([^|;&\n]+)/g;
+  for (const m of command.matchAll(cmdRe)) {
+    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(m[0].split(/\s/)[0])) {
+      targets.add(args[args.length - 1]);
+    } else {
+      for (const a of args) targets.add(a);
+    }
+  }
+
+  return [...targets]
+    .map((t) => t.replace(/^['"]|['"]$/g, ''))
+    .filter(Boolean)
+    .filter((t) => !/[$`(){}]/.test(t));
+}
+
+/** The vault-naming gate's id — unique across the built-in registry. */
+export const id = 'enforce-vault-naming';
+/** 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, getActiveConfig?: () => { repoRootAbs?: string } | null,
+ *            existsSync?: (p: string) => boolean }} [ctx]
+ * @returns {{ decision: 'allow'|'deny', reason?: string }}
+ */
+export function run(evt, ctx = {}) {
+  const toolName = evt?.toolName;
+  const input = evt?.toolInput ?? {};
+
+  const candidates = [];
+  if (toolName === 'Write') {
+    candidates.push(input.file_path);
+  } else if (toolName === 'Edit' || toolName === 'MultiEdit') {
+    return { decision: 'allow' };
+  } else if (toolName === 'NotebookEdit') {
+    candidates.push(input.notebook_path);
+  } else if (toolName === 'Bash' || toolName === 'PowerShell') {
+    for (const t of extractBashTargets(input.command)) candidates.push(t);
+  } else {
+    return { decision: 'allow' };
+  }
+
+  const root = ctx.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? REPO_ROOT;
+  const rule = rulesForSurface(loadGuardrails(root), 'pretooluse').find((r) => r && r.naming);
+  if (!rule) return { decision: 'allow' };
+
+  const getActiveConfigFn = ctx.getActiveConfig ?? getActiveConfig;
+  const existsSyncFn = ctx.existsSync ?? fs.existsSync;
+
+  const violations = [];
+  for (const c of candidates) {
+    const norm = normalizeRel(c, root, getActiveConfigFn);
+    if (!norm) continue;
+    const { rel, abs } = norm;
+    let requireNew = true;
+    try {
+      requireNew = !existsSyncFn(abs);
+    } catch {
+      requireNew = false; // fs probe failed → lenient (fail-safe, never over-block)
+    }
+    const v = namingViolation(rule, rel, { requireNew });
+    if (v) violations.push(v);
+  }
+
+  if (violations.length > 0) {
+    return { decision: 'deny', reason: violations.map(formatReason).join('\n\n') };
+  }
+
+  return { decision: 'allow' };
+}
+
+export default { id, event, severity, run };

package/spexharness/src/gates/epic-milestone-phrasing-gate.mjs

@@ -0,0 +1,233 @@
+// spexharness/src/gates/epic-milestone-phrasing-gate.mjs
+//
+// Engine port of scripts/claude-hooks/epic-milestone-phrasing-gate.mjs — the
+// Stop-hook gate that catches an agent telling the owner to "promote X to an
+// epic", a sentence that is always wrong (an epic can never exist without a
+// milestone parent; the console's own write path refuses it with
+// `error: "milestone_required"`, and this gate is about the SPOKEN sentence the
+// write gate never sees). See ./PORTING.md for the recipe this follows and
+// ./env-vault-guard.mjs for the reference port.
+//
+// WHY IT IS PORTED (the whole point of [[HS-AZ61-NYPR]] wave 6): before this
+// module the rule lived only in the Claude Code plugin, so a DeepSeek seat or a
+// local-model seat could say the wrong sentence all day and nothing noticed.
+// The gate now runs on the engine's `stop` event, which every front emits
+// through spexharness/src/session-lifecycle.mjs — so the rule reaches every
+// seat, not just the one front that happened to have a hook directory.
+//
+// The original does NOT export a pure decision function (its logic lives inside
+// `main()` alongside `readStdinJson`/`process.stdout.write`), so per PORTING.md
+// step 1's "otherwise" branch the decision logic is re-derived here — but only
+// the GLUE. Every piece carrying rule CONTENT is imported unchanged from the
+// same canonical, dependency-free modules the original itself imports:
+//   - scripts/claude-hooks/_guardrail-loader.mjs — loadGuardrails,
+//     rulesForSurface, isRuleEnabled, compilePatterns, proseOnly,
+//     matchContextAround. The detection pattern, the severity and the toggle
+//     all come from the compiled registry (.heyspex/guardrails.json, authored
+//     in communication-style-protocol.md's `enforcement:` block), so this port
+//     and the original cannot drift on what "the bad shape" IS.
+//   - scripts/claude-hooks/_transcript-text.mjs — lastAssistantText, the same
+//     reader naughty-list-gate.mjs and id-display-format-gate.mjs use for the
+//     Claude Code path.
+// The one string authored HERE is the block reason / warn banner, carried over
+// byte-for-byte from the original's `blockReason()` and its stderr write so the
+// generated shell reproduces the original's output exactly (proved by
+// spexharness/fixtures/ported/).
+//
+// Event/field mapping: a Stop hook → the engine's `stop` event point.
+//   stdin.transcript_path → evt.transcriptPath
+// FRONT-AGNOSTIC READ (the port's actual new capability): the reply text is
+// taken from `ctx.reply` / `evt.text` FIRST — the fields
+// spexharness/src/session-lifecycle.mjs's `stop()` already carries for every
+// front that holds its own answer text — and only falls back to reading a
+// transcript file when neither is present. A DeepSeek seat has no Claude Code
+// transcript; it has the reply in hand, and that is enough for this gate.
+//
+// Decision mapping — the original is a TWO-RUNG gate, same shape as
+// ./enforce-session-sequence.mjs:
+//   real block  (unattended CLAUDE_AGENT=true, or the interactive rung raised
+//               with HEYSPEX_EPIC_MILESTONE_GATE_INTERACTIVE=block)
+//               → `deny` + the original's `blockReason(hits)` text verbatim,
+//                 which the adapter turns back into the Stop contract's
+//                 `{ decision: "block", reason }` stdout.
+//   warn only   (interactive default — the rollout discipline the original
+//               documents: a new mechanical gate ships warn-first)
+//               → `rewrite` with `{ warn: true, reason, stderrText }`, the same
+//                 mapping enforce-session-sequence.mjs uses for its own
+//                 warn rung rather than silently downgrading it to `allow`
+//                 (which would drop the reason a caller may still want) or
+//                 upgrading it to `deny` (a real behavior change).
+//   otherwise   → `allow`.
+//
+// Env hatches (unchanged):
+//   HEYSPEX_EPIC_MILESTONE_GATE_OFF=1              Hard kill switch.
+//   HEYSPEX_EPIC_MILESTONE_GATE_INTERACTIVE=block  Raise interactive to a real block.
+//   CLAUDE_AGENT=true                              Unattended session → real block.
+// The rule also honors its registry `configKey`
+// (agent_behaviors.epic_milestone_phrasing_gate.enabled) via isRuleEnabled.
+//
+// Not ported HERE: the original's `appendGuardrailEvent(...)` audit-log write.
+// A gate module stays a pure decision function; the audit trail is restored by
+// the front — see spexharness/src/adapters/audit.mjs's
+// `epic-milestone-phrasing-gate` case, which reads the `rule` and `hits` this
+// run() carries on both its `deny` and `rewrite` results so it never has to
+// re-derive which rule fired from `reason` text.
+//
+// `ctx` contract (all optional; every field defaults to a real fs/env read):
+//   ctx.reply    - the reply text the front already holds (preferred over any
+//                  transcript read). session-lifecycle.mjs's stop() sets it.
+//   ctx.cwd      - repo root the guardrail registry is resolved 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]]).
+//   ctx.readText - override for the transcript reader (defaults to
+//                  lastAssistantText); tests inject reply text directly instead.
+//   ctx.env      - env var overrides (tests use this instead of mutating
+//                  process.env).
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  loadGuardrails,
+  rulesForSurface,
+  isRuleEnabled,
+  compilePatterns,
+  proseOnly,
+  matchContextAround,
+} from '../../../scripts/claude-hooks/_guardrail-loader.mjs';
+import { lastAssistantText } from '../../../scripts/claude-hooks/_transcript-text.mjs';
+import { defaultConfigRoot } from '../config-root.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, '..', '..', '..');
+
+/** The compiled-registry rule this gate enforces (authored in communication-style-protocol.md). */
+export const RULE_ID = 'epic-milestone-phrasing-gate';
+const OFF_ENV = 'HEYSPEX_EPIC_MILESTONE_GATE_OFF';
+const INTERACTIVE_ENV = 'HEYSPEX_EPIC_MILESTONE_GATE_INTERACTIVE';
+
+/** Real block vs. warn-only, mirroring the original's `isAgent`/`interactiveRung()` pair. */
+function shouldBlockForReal(env) {
+  if (String(env.CLAUDE_AGENT ?? '') === 'true') return true;
+  return String(env[INTERACTIVE_ENV] ?? '').trim().toLowerCase() === 'block';
+}
+
+/**
+ * Byte-for-byte the original hook's `blockReason(hits)`.
+ * @param {Array<{ excerpt: string }>} hits
+ * @returns {string}
+ */
+export function blockReason(hits) {
+  const lines = hits.map((h) => `  • "${h.excerpt}"`);
+  return (
+    `Epic/milestone phrasing violation: your last message described promoting ` +
+    `something directly "to an epic." An epic can never exist without a milestone ` +
+    `parent — the correct next step is always "promote to a milestone" (which ` +
+    `spawns epic stubs underneath it). Rewrite and resend:\n${lines.join('\n')}\n` +
+    `(See specs/memory/lessons/say-promote-to-a-milestone-never.md. Break-glass: ` +
+    `HEYSPEX_EPIC_MILESTONE_GATE_OFF=1.)`
+  );
+}
+
+/**
+ * Byte-for-byte the original hook's interactive-warn stderr write. Kept here
+ * (rather than left to the adapter's generic warn formatter) for the same
+ * reason enforce-session-sequence.mjs keeps its own: the banner names THIS
+ * gate, and the generated shell must reproduce the original's stderr exactly.
+ *
+ * @param {Array<{ excerpt: string }>} hits
+ * @returns {string}
+ */
+export function warnStderrText(hits) {
+  return (
+    `[epic-milestone-phrasing] warning — "promote ... to an epic" in your last message (not blocked):\n` +
+    hits.map((h) => `  • "${h.excerpt}"`).join('\n') +
+    '\n'
+  );
+}
+
+/**
+ * Every registry-pattern hit in the PROSE of `text` (a match inside a code
+ * span, fenced block, wikilink, URL or blockquote is exempt — proseOnly's job,
+ * shared with every other stop gate). One hit per compiled pattern, same as the
+ * original's loop.
+ *
+ * @param {string} text
+ * @param {string} root - where `.heyspex/guardrails.json` (the rule row) is read from.
+ * @param {string} [configRoot] - where `.heyspex/config.yaml` (the toggle) is read
+ *   from; defaults to `root` so a self-contained fixture root still works as one unit.
+ * @returns {Array<{ excerpt: string }>}
+ */
+export function phrasingHits(text, root, configRoot = root) {
+  const rule = rulesForSurface(loadGuardrails(root), 'stop').find((r) => r && r.rule === RULE_ID);
+  if (!rule || !isRuleEnabled(rule, configRoot)) return [];
+  const patterns = compilePatterns(rule);
+  if (!patterns.length) return [];
+  const prose = proseOnly(text);
+  const hits = [];
+  for (const re of patterns) {
+    const m = re.exec(prose);
+    if (m) hits.push({ excerpt: matchContextAround(prose, m.index, m[0].length) });
+  }
+  return hits;
+}
+
+/** The gate's id — unique across the registry. */
+export const id = 'epic-milestone-phrasing-gate';
+/** Runs on the Stop event, same as its Stop Claude Code hook registration. */
+export const event = 'stop';
+/** Caller-defined severity label; the registry rule's own severity is "warn". */
+export const severity = 'warn';
+
+/**
+ * @param {{ point: string, text?: string, transcriptPath?: string }} evt
+ * @param {{ reply?: string, cwd?: string, configRoot?: string, readText?: (p: string) => string|null,
+ *            env?: Record<string, string|undefined> }} [ctx]
+ * @returns {{ decision: 'allow'|'deny'|'rewrite', reason?: string, rule?: string,
+ *             hits?: Array<{ excerpt: string }>, rewrite?: object }}
+ */
+export function run(evt, ctx = {}) {
+  const env = ctx.env ?? process.env;
+  if (String(env[OFF_ENV] ?? '') === '1') return { decision: 'allow' };
+
+  // Front-agnostic read: the reply the front already holds wins; a transcript
+  // is only read when there is no reply text to check (the Claude Code path).
+  const readText = ctx.readText ?? lastAssistantText;
+  let text = typeof ctx.reply === 'string' && ctx.reply ? ctx.reply : null;
+  if (!text && typeof evt?.text === 'string' && evt.text) text = evt.text;
+  if (!text && evt?.transcriptPath) text = readText(evt.transcriptPath) ?? null;
+  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());
+
+  let hits;
+  try {
+    hits = phrasingHits(text, root, configRoot);
+  } catch {
+    return { decision: 'allow' }; // fail-safe: a broken registry never blocks a stop
+  }
+  if (!hits.length) return { decision: 'allow' };
+
+  if (shouldBlockForReal(env)) {
+    return { decision: 'deny', reason: blockReason(hits), rule: RULE_ID, hits };
+  }
+  const reason = blockReason(hits);
+  return {
+    decision: 'rewrite',
+    reason,
+    rule: RULE_ID,
+    hits,
+    rewrite: { warn: true, reason, rule: RULE_ID, hits, stderrText: warnStderrText(hits) },
+  };
+}
+
+export default { id, event, severity, run };