heyspex 0.1.0 → 0.2.0

package/scripts/claude-hooks/_env-vault-events.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// Env-vault audit writer (HS-JYTT / HS-I52T) — append one AuditEventRow to
+// `.heyspex/env-vault-history.jsonl` each time something touches (or is
+// stopped from touching) the env vault's secrets.
+//
+// Two writers share this ledger file, distinguished by event_kind:
+//   - the PreToolUse guard hook (this module's caller) writes
+//     `env_vault.policy_decision` rows — a policy deny/ask on an agent-issued
+//     secret-touching command;
+//   - the `hs env` CLI (spex-console/src/lib/env-vault/audit.ts, HS-N2UP)
+//     writes `env_vault.secret_touch` rows — which keys were actually
+//     injected into which command.
+//
+// Same design rules as ./_guardrail-events.mjs (the pattern this follows):
+// dependency-free (hooks have no Neon access), row shape is the canonical
+// AuditEventRow { timestamp, event_kind, actor, spec_id, metadata }, and
+// observability must NEVER break the hook — every error is swallowed.
+// Metadata carries names and dispositions only, never a secret value.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const DEFAULT_REPO_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+);
+
+function repoRootFromEnv() {
+  const fromEnv = process.env.CLAUDE_PROJECT_DIR?.trim();
+  if (fromEnv) return fromEnv.replace(/[\\/]+$/, '');
+  return DEFAULT_REPO_ROOT;
+}
+
+function cleanMeta(meta) {
+  const out = {};
+  for (const [k, v] of Object.entries(meta)) {
+    if (v !== undefined && v !== null) out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Append one env-vault policy-decision event. Returns true on a successful
+ * write, false on any (swallowed) failure. `decision` is required; the rest
+ * is best-effort context.
+ */
+export function appendEnvVaultEvent(
+  { eventKind = 'env_vault.policy_decision', decision, verb = null, profile = null, source = null, tool = null } = {},
+  repoRoot = repoRootFromEnv(),
+) {
+  try {
+    if (!decision) return false;
+    const row = {
+      timestamp: new Date().toISOString(),
+      event_kind: eventKind,
+      actor: process.env.HEYSPEX_GUARDRAIL_ACTOR?.trim() || 'Claude Code',
+      spec_id: null,
+      metadata: cleanMeta({ decision, verb, profile, source, tool }),
+    };
+    const file = path.join(repoRoot, '.heyspex', 'env-vault-history.jsonl');
+    fs.appendFileSync(file, JSON.stringify(row) + '\n');
+    return true;
+  } catch {
+    return false; // fail-safe: never let observability break a hook
+  }
+}

package/scripts/claude-hooks/_guardrail-events.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// Guardrail observability writer ([[HS-EPIC-ZGWR]] Phase 6) — append one
+// `guardrail.fired` audit row to `.heyspex/guardrail-history.jsonl` each time a
+// guardrail hook fires (a block, a rewrite, a prime). This is the file-based event
+// log the audit export folds into specs/events/YYYY-MM.jsonl (shared monitoring seam
+// with [[HS-EPIC-0016]]).
+//
+// WHY A LOCAL FILE (both tiers): the Claude Code hooks are dependency-free and have NO
+// Neon access — they cannot write spec_events directly. So the guardrail log is always
+// local; the server-side export reads it as an ALWAYS-ON source (regardless of tier),
+// alongside the Neon tables / free-tier file logs. Same `.heyspex/*-history.jsonl`
+// runtime-file family as claim-history / focus-history, and like them GIT-TRACKED
+// (the free tier's live event store — a clone IS the audit trail;
+// [[free-tier-makes-runtime-files-non-retireable]]). The deduped, month-partitioned
+// export copy lives in committed specs/events/YYYY-MM.jsonl.
+//
+// ROW SHAPE: already the canonical AuditEventRow
+//   { timestamp, event_kind:"guardrail.fired", actor, spec_id, metadata }
+// so the reader (free-event-readers.ts loadGuardrailEventRows) only validates the
+// timestamp and passes through. metadata carries { rule, surface, severity, decision,
+// relPath?, match_context? } — the fired rule, where it fired, the disposition, and
+// a bounded window of the prose that matched.
+//
+// FAIL-SAFE: observability must NEVER break a guardrail hook. Every error is swallowed;
+// a missing .heyspex/ dir, an unwritable disk, anything → silent no-op.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Kept in step with _guardrail-loader.mjs; inlined so this stays dependency-free. */
+const MATCH_CONTEXT_MAX_CHARS = 200;
+
+export const DEFAULT_REPO_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+);
+
+function repoRootFromEnv() {
+  const fromEnv = process.env.CLAUDE_PROJECT_DIR?.trim();
+  if (fromEnv) return fromEnv.replace(/[\\/]+$/, '');
+  return DEFAULT_REPO_ROOT;
+}
+
+function cleanMeta(meta) {
+  const out = {};
+  for (const [k, v] of Object.entries(meta)) {
+    if (v !== undefined && v !== null) out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Append a guardrail-fired event. All fields optional except `rule`; unknown ones are
+ * dropped. Returns true on a successful write, false on any (swallowed) failure — so a
+ * caller can branch in a test, but a hook can ignore the result.
+ */
+export function appendGuardrailEvent(
+  {
+    rule,
+    surface = null,
+    severity = null,
+    decision = null,
+    specId = null,
+    relPath = null,
+    matchContext = null,
+  } = {},
+  repoRoot = repoRootFromEnv(),
+) {
+  try {
+    if (!rule) return false;
+    // `match_context` is the bounded window of prose the rule matched in
+    // ([[HS-N71O-P3XQ-DIAG-six-new-qc-gates-fail-cold-verification]] item 10).
+    // Without it a row said only WHICH word fired, and a reviewer could not tell a
+    // false positive from a real hit — which is the evidence needed before raising
+    // a gate from warn to block. Collapsed to one line and hard-capped here as
+    // well as at the source, so an oversized value cannot bloat the log.
+    const context =
+      typeof matchContext === 'string' && matchContext.trim()
+        ? matchContext.replace(/\s+/g, ' ').trim().slice(0, MATCH_CONTEXT_MAX_CHARS)
+        : null;
+    const row = {
+      timestamp: new Date().toISOString(),
+      event_kind: 'guardrail.fired',
+      actor: process.env.HEYSPEX_GUARDRAIL_ACTOR?.trim() || 'Claude Code',
+      spec_id: typeof specId === 'string' ? specId : null,
+      metadata: cleanMeta({ rule, surface, severity, decision, relPath, match_context: context }),
+    };
+    const file = path.join(repoRoot, '.heyspex', 'guardrail-history.jsonl');
+    fs.appendFileSync(file, JSON.stringify(row) + '\n');
+    return true;
+  } catch {
+    return false; // fail-safe: never let observability break a hook
+  }
+}

package/scripts/claude-hooks/_guardrail-loader.mjs

@@ -0,0 +1,494 @@
+#!/usr/bin/env node
+// Shared loader for the HeySpex guardrail registry (.heyspex/guardrails.json).
+//
+// The registry is compiled from protocol `enforcement:` frontmatter by
+// scripts/build-guardrails.mjs ([[HS-EPIC-ZGWR]] phase 1, design [[HS-RES-GHKO]]
+// §6/§8). This module is the runtime read side that the Claude Code hooks import
+// instead of hand-coding their own rule tables — one authored source, no
+// prose↔JS drift.
+//
+// DELIBERATELY DEPENDENCY-FREE. Hooks fire on every prompt/tool call and must run
+// on a fresh clone with no `npm install` (spex-console/node_modules absent), so
+// this reads the *compiled JSON* with the stdlib only — never js-yaml, never the
+// protocol YAML. (build-guardrails.mjs is the one allowed to use js-yaml; it is a
+// build step, not a per-prompt hook.)
+//
+// FAIL-SAFE CONTRACT (non-negotiable, [[HS-RES-GHKO]] §7): every function degrades
+// to a safe empty/enabled result on any error. A corrupt or missing registry must
+// never throw into a hook — the worst outcome is a guardrail going silent, never a
+// stranded agent. Callers wrap their own bodies in try/catch and exit 0 too.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { loadRuleTable } from '../../spexharness/src/rule-table.mjs';
+import { defaultConfigRoot } from '../../spexharness/src/config-root.mjs';
+
+// TWO ROOTS, split by what lives under `.heyspex/` at each
+// ([[HS-4C76-9W86-DIAG-heyspex-config-yaml-has-no-single-home]]):
+//
+//   - DEFAULT_REPO_ROOT — the CODE checkout (scripts/claude-hooks/ → two levels
+//     up). The guardrail registry (`.heyspex/guardrails.json`, compiled by
+//     scripts/build-guardrails.mjs) and the per-user terminology override are
+//     code-repo artifacts and stay here. `loadGuardrails` / `resolveVocabulary`
+//     default to it.
+//   - the CONFIG root — `.heyspex/config.yaml` is the workflow-settings file and
+//     per ADR-0009 lives at the VAULT root, which since the 2026-08-31 repo split
+//     is a separate checkout. `isConfigKeyEnabled` / `readConfigLeafRaw` /
+//     `resolveConfirmMode` / `isRuleEnabled` default to `defaultConfigRoot()`
+//     (spexharness/src/config-root.mjs → vault-resolve's `repoRootAbs`, falling
+//     back to the code root only if resolution throws). Resolved lazily at call
+//     time, never at import, so a hook's startup cost is unchanged.
+//
+// Every function keeps its `repoRoot` parameter: an explicit argument always
+// wins over either default (tests and callers with a fixture root rely on it).
+export const DEFAULT_REPO_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+);
+
+// Sentinels that mark harness-injected content arriving through the
+// UserPromptSubmit channel (background-task notifications, system reminders, slash-
+// command envelopes). They can contain a rule's trigger phrase verbatim but are NOT
+// a genuine human prompt, so a rule with `ignoreInjectedContent` must not fire on
+// them. Shared here so every surface uses one guard list.
+export const INJECTED_CONTENT_SENTINELS = [
+  '<task-notification>',
+  '<system-reminder>',
+  '[SYSTEM NOTIFICATION',
+  '<command-message>',
+  '<command-name>',
+  '<local-command-stdout>',
+];
+
+export function containsInjectedContent(text) {
+  if (typeof text !== 'string') return false;
+  return INJECTED_CONTENT_SENTINELS.some((s) => text.includes(s));
+}
+
+// Stricter, false-positive-safe variant: is the message a genuine harness ENVELOPE
+// (a task-notification / system-reminder / slash-command envelope delivered AS the
+// prompt), rather than user text that merely QUOTES a sentinel? A real envelope leads
+// with its tag; a user pasting a transcript or terminal logs leads with their own
+// words. `containsInjectedContent` (substring anywhere) wrongly suppresses the latter
+// — which silently kills an autonomous trigger the moment the user pastes logs, the
+// exact time they are offloading an idea (evidence: the HeySpex Intent Classifier
+// capture no-fire, 2026-07-11). Intent-classifier surfaces should prefer THIS check.
+export function startsWithInjectedContent(text) {
+  if (typeof text !== 'string') return false;
+  const head = text.trimStart();
+  return INJECTED_CONTENT_SENTINELS.some((s) => head.startsWith(s));
+}
+
+/**
+ * Load the guardrail rule table. Returns `{ rules: [...] }` — ALWAYS the full
+ * built-in rule set at minimum (spexharness/src/rule-table.mjs `loadRuleTable`),
+ * merged with whatever overrides `<repoRoot>/.heyspex/guardrails.json` supplies.
+ *
+ * This used to fail-safe to `{ rules: [] }` (every guardrail silently OFF) on a
+ * missing or corrupt file — that was the exact "fresh customer vaults ship with
+ * zero naming enforcement" gap [[HS-RY2N-91GR-DIAG-fresh-customer-vaults-ship-with-zero]]
+ * named. `loadRuleTable` fixes the failure mode at its source: the standard
+ * rules live in code, so a missing/corrupt file can no longer turn any of them
+ * off. This function keeps that guarantee and only adds the stderr visibility
+ * a present-but-broken file deserves (loadRuleTable itself is silent/pure).
+ */
+export function loadGuardrails(repoRoot = DEFAULT_REPO_ROOT) {
+  const { rules, warnings } = loadRuleTable({ vaultRoot: repoRoot });
+
+  for (const warning of warnings) {
+    if (warning.code === 'corrupt_file') {
+      process.stderr.write(
+        `[guardrail-loader] .heyspex/guardrails.json is corrupt — falling back to the built-in rule set ` +
+          `(nothing is disabled). ${warning.message} Rebuild with \`node scripts/build-guardrails.mjs\`.\n`,
+      );
+    } else if (warning.code === 'unknown_rule') {
+      process.stderr.write(`[guardrail-loader] ${warning.message}\n`);
+    }
+  }
+
+  // HS-RY2N: a MISSING registry file used to mean every guardrail was OFF; now
+  // it just means the on-disk overrides are unavailable — the built-in rule set
+  // still runs. Still worth a loud note in a real HeySpex vault (heyspex.yaml
+  // present) so a missing compiled file doesn't go unnoticed, but it is no
+  // longer an enforcement outage.
+  if (warnings.length === 0 && !fs.existsSync(path.join(repoRoot, '.heyspex', 'guardrails.json'))) {
+    if (fs.existsSync(path.join(repoRoot, 'heyspex.yaml'))) {
+      process.stderr.write(
+        '[guardrail-loader] heyspex.yaml marks this as a HeySpex vault, but .heyspex/guardrails.json ' +
+          'does not exist — running on the built-in rule set only (no on-disk severity/configKey overrides). ' +
+          'Platform repo: run `node scripts/build-guardrails.mjs`. Customer vault: see ' +
+          '[[HS-RY2N-91GR-DIAG-fresh-customer-vaults-ship-with-zero]] / customer-vault-local-install-protocol.\n',
+      );
+    }
+  }
+
+  return { rules };
+}
+
+/**
+ * All rules whose `surfaces` include the given surface (e.g. "userpromptsubmit").
+ * Optionally narrow by severity. Order-preserving; never throws.
+ */
+export function rulesForSurface(guardrails, surface, severity = null) {
+  const rules = guardrails && Array.isArray(guardrails.rules) ? guardrails.rules : [];
+  return rules.filter(
+    (r) =>
+      r &&
+      Array.isArray(r.surfaces) &&
+      r.surfaces.includes(surface) &&
+      (severity == null || r.severity === severity),
+  );
+}
+
+/**
+ * Compile a rule's pattern strings to case-insensitive RegExp. Any individual
+ * pattern that fails to compile is skipped (logged) rather than throwing — a single
+ * malformed pattern must not disarm the whole hook.
+ */
+export function compilePatterns(rule) {
+  const patterns = rule && Array.isArray(rule.patterns) ? rule.patterns : [];
+  const compiled = [];
+  for (const p of patterns) {
+    try {
+      compiled.push(new RegExp(p, 'i'));
+    } catch {
+      process.stderr.write(
+        `[guardrail-loader] rule "${rule?.rule}" has an uncompilable pattern; skipping it: ${p}\n`,
+      );
+    }
+  }
+  return compiled;
+}
+
+/**
+ * Read a boolean leaf at a dotted `config_key` (e.g.
+ * "agent_behaviors.research_before_decision.enabled") from .heyspex/config.yaml,
+ * using a dependency-free, indentation-scoped scan (generalized from the original
+ * single-rule reader in the now-retired research-trigger.mjs shim, HS-IYU1). Semantics
+ * match the Tier-1 contract:
+ * the behavior is ON unless the leaf is explicitly `false`; absent / unreadable /
+ * malformed / no config_key all default to ON, so a rule works out of the box and
+ * only an explicit opt-out silences it.
+ *
+ * `repoRoot` is the directory holding `.heyspex/config.yaml`; it defaults to the
+ * VAULT root (see the two-roots note at the top of this file), not DEFAULT_REPO_ROOT.
+ */
+export function isConfigKeyEnabled(configKey, repoRoot = defaultConfigRoot()) {
+  if (!configKey || typeof configKey !== 'string') return true; // no toggle → enabled
+  const segments = configKey.split('.').filter(Boolean);
+  if (segments.length === 0) return true;
+
+  let raw;
+  try {
+    raw = fs.readFileSync(path.join(repoRoot, '.heyspex', 'config.yaml'), 'utf8');
+  } catch {
+    return true; // no config file → default enabled
+  }
+
+  // Maintain the current key path via an indent stack. For each non-blank,
+  // non-comment `key:` line, pop stack frames whose indent is >= this line's, then
+  // push this key. When the path matches the target, read the leaf value.
+  const stack = []; // { key, indent }
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const m = trimmed.match(/^([A-Za-z0-9_]+)\s*:(.*)$/);
+    if (!m) continue; // list items / flow content — irrelevant to a scalar leaf path
+    const indent = line.length - line.trimStart().length;
+    while (stack.length && stack[stack.length - 1].indent >= indent) stack.pop();
+    stack.push({ key: m[1], indent });
+    const pathHere = stack.map((f) => f.key);
+    if (pathHere.length === segments.length && pathHere.every((k, i) => k === segments[i])) {
+      // Reached the leaf — ON unless explicitly false.
+      return m[2].trim().toLowerCase() !== 'false';
+    }
+  }
+  return true; // path absent → default enabled
+}
+
+// Back-compat / ergonomic wrapper: enabled-check straight off a rule object.
+// `repoRoot` defaults to the vault (config) root, same as isConfigKeyEnabled.
+export function isRuleEnabled(rule, repoRoot = defaultConfigRoot()) {
+  return isConfigKeyEnabled(rule && rule.configKey, repoRoot);
+}
+
+/**
+ * Read the RAW scalar value at a dotted `configKey` from .heyspex/config.yaml,
+ * returning the trimmed string after the colon, or `undefined` when the path is
+ * absent / the file is unreadable. Unlike isConfigKeyEnabled (which collapses to a
+ * boolean with an enabled-by-default bias), this preserves the three-state
+ * distinction the confirm-mode resolver needs: explicit value vs. absent/inherit.
+ * Dependency-free indent-scoped scan, mirroring isConfigKeyEnabled. FAIL-SAFE.
+ * `repoRoot` defaults to the vault (config) root — see the two-roots note above.
+ */
+export function readConfigLeafRaw(configKey, repoRoot = defaultConfigRoot()) {
+  if (!configKey || typeof configKey !== 'string') return undefined;
+  const segments = configKey.split('.').filter(Boolean);
+  if (segments.length === 0) return undefined;
+
+  let raw;
+  try {
+    raw = fs.readFileSync(path.join(repoRoot, '.heyspex', 'config.yaml'), 'utf8');
+  } catch {
+    return undefined;
+  }
+
+  const stack = []; // { key, indent }
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const m = trimmed.match(/^([A-Za-z0-9_]+)\s*:(.*)$/);
+    if (!m) continue;
+    const indent = line.length - line.trimStart().length;
+    while (stack.length && stack[stack.length - 1].indent >= indent) stack.pop();
+    stack.push({ key: m[1], indent });
+    const pathHere = stack.map((f) => f.key);
+    if (pathHere.length === segments.length && pathHere.every((k, i) => k === segments[i])) {
+      return m[2].trim();
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the CONFIRM MODE for an autonomous agent behavior — the two-layer
+ * permission model the owner specified (2026-07-11):
+ *   'auto' = act immediately, user can undo/discard afterward   (forgiveness)
+ *   'ask'  = ask the user for confirmation before acting        (permission)
+ *
+ * Resolution order (per-behavior override wins over the global default):
+ *   1. agent_behaviors.<behaviorKey>.ask_first
+ *        true|yes|ask  → 'ask'   ·  false|no|auto → 'auto'  ·  null/absent → inherit
+ *   2. (inherit) global agent_behaviors.ask_forgiveness_not_permission
+ *        true|yes|absent → 'auto' (forgiveness — the owner's default)
+ *        false|no        → 'ask'
+ *
+ * So EVERY behavior honors the one global "ask forgiveness, not permission" switch
+ * unless it opts out with its own ask_first. FAIL-SAFE: any unreadable config →
+ * 'auto' (the stated default). Shared here so any behavior hook resolves it identically.
+ * `repoRoot` defaults to the vault (config) root — see the two-roots note above.
+ */
+export function resolveConfirmMode(behaviorKey, repoRoot = defaultConfigRoot()) {
+  if (behaviorKey && typeof behaviorKey === 'string') {
+    const per = readConfigLeafRaw(`agent_behaviors.${behaviorKey}.ask_first`, repoRoot);
+    if (per !== undefined) {
+      const v = per.toLowerCase();
+      if (v === 'true' || v === 'yes' || v === 'ask') return 'ask';
+      if (v === 'false' || v === 'no' || v === 'auto') return 'auto';
+      // 'null' / '' / anything else → fall through to the global default (inherit)
+    }
+  }
+  const global = readConfigLeafRaw('agent_behaviors.ask_forgiveness_not_permission', repoRoot);
+  if (global !== undefined) {
+    const g = global.toLowerCase();
+    if (g === 'false' || g === 'no') return 'ask'; // forgiveness OFF → ask first
+  }
+  return 'auto'; // forgiveness ON / absent → act, don't ask
+}
+
+/**
+ * Path/filename-shape evaluator for a `naming`-payload rule (the `id-suffix-shape`
+ * rule, lifted from enforce-vault-naming.mjs's old hand-coded validatePath). Given a
+ * compiled rule carrying
+ *   naming: { managed: [{ dir, kind, pattern, example }], slugOnlyDirs: [...] }
+ * and a repo-relative POSIX path, returns null when the path is fine, or a violation
+ * descriptor { relPath, dir, kind, requiredPattern, example } when it breaks the rule.
+ * The caller formats the human message and decides the exit code.
+ *
+ * Lives in the loader (not the hook) so the future pre-commit / server consumers share
+ * one rule module — GHKO §6.2 "one rule module, many surfaces". FAIL-SAFE: a malformed
+ * rule, an uncompilable pattern, or any unexpected shape resolves to null (allow), never
+ * throws — a broken rule must never strand the agent.
+ */
+// --- Vocabulary rules (the glossary / naughty-list family, [[HS-PROTO-terminology-governance]]) ---
+//
+// A `kind: vocabulary` rule carries `vocabulary: { terms: [{word, fix, nounOnly?,
+// caseSensitive?}], allow: [...] }`, compiled from the doc table by build-guardrails.mjs
+// (the doc IS the source of truth). The runtime merges a gitignored, per-user override
+// at LOAD time (not compile time) so personal preferences never enter the committed
+// registry, and the Stop hook + server gate apply the identical resolved list.
+
+function escapeRegexLiteral(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Strip the parts of a message that are NOT prose — code spans, fenced code blocks,
+// [[wikilinks]], URLs, and blockquote lines — so a banned word quoted/defined/in-code
+// is never flagged. To refer to a banned word AS a word, wrap it in backticks.
+export function proseOnly(text) {
+  return String(text)
+    .replace(/```[\s\S]*?```/g, ' ') // fenced code blocks
+    .replace(/`[^`]*`/g, ' ') // inline code
+    .replace(/\[\[[^\]]*\]\]/g, ' ') // [[wikilinks]]
+    .replace(/https?:\/\/\S+/g, ' ') // bare URLs
+    .replace(/^\s{0,3}>.*$/gm, ' '); // blockquote lines
+}
+
+/**
+ * Resolve a vocabulary rule's effective term list by merging the compiled (vendor-
+ * default) terms with the per-user `.heyspex/terminology.local.json` override
+ * ({ add, allow, remove }). User wins: `allow`/`remove` drop a default term, `add`
+ * appends a personal one. FAIL-SAFE: a missing/corrupt override → defaults only.
+ * Returns { terms: [{word, fix, nounOnly?, caseSensitive?}], allow: Set<string> }.
+ */
+export function resolveVocabulary(rule, repoRoot = DEFAULT_REPO_ROOT) {
+  const v = rule && rule.vocabulary ? rule.vocabulary : {};
+  let terms = Array.isArray(v.terms) ? v.terms.slice() : [];
+  const allow = new Set((Array.isArray(v.allow) ? v.allow : []).map((s) => String(s).toLowerCase()));
+
+  try {
+    const raw = fs.readFileSync(path.join(repoRoot, '.heyspex', 'terminology.local.json'), 'utf8');
+    const cfg = JSON.parse(raw);
+    for (const w of cfg?.allow ?? []) allow.add(String(w).toLowerCase());
+    const remove = new Set((cfg?.remove ?? []).map((w) => String(w).toLowerCase()));
+    if (remove.size) terms = terms.filter((t) => !remove.has(String(t.word).toLowerCase()));
+    for (const w of cfg?.add ?? []) {
+      const word = String(w).trim();
+      if (word && !terms.some((t) => String(t.word).toLowerCase() === word.toLowerCase())) {
+        terms.push({ word, fix: 'plain literal language (user-added)' });
+      }
+    }
+  } catch {
+    // no override / unreadable → defaults only
+  }
+
+  // `allow` (default keep-list + user allow) suppresses any matching term.
+  terms = terms.filter((t) => !allow.has(String(t.word).toLowerCase()));
+  return { terms, allow };
+}
+
+/** Longest match window carried on a hit — enough to judge, small enough to log. */
+export const MATCH_CONTEXT_MAX_CHARS = 200;
+
+/**
+ * A bounded window of prose around a match, for the audit row
+ * ([[HS-N71O-P3XQ-DIAG-six-new-qc-gates-fail-cold-verification]] item 10).
+ *
+ * Prefers the sentence the match sits in; falls back to a character window when
+ * the sentence is longer than the cap or has no obvious boundaries. Whitespace is
+ * collapsed so a row stays one line. A reviewer reading the log needs to tell a
+ * false positive ("ladder", the owner's own term in the confidence-ladder method)
+ * from a real hit, and the word alone cannot do that.
+ */
+export function matchContextAround(prose, index, matchLength, maxChars = MATCH_CONTEXT_MAX_CHARS) {
+  try {
+    if (typeof prose !== 'string' || index < 0) return '';
+    // Sentence bounds around the match, then trimmed to the cap around the match
+    // itself so a long sentence still shows the word rather than its opening.
+    let start = prose.lastIndexOf('.', index) + 1;
+    const nextStop = prose.indexOf('.', index + matchLength);
+    let end = nextStop === -1 ? prose.length : nextStop + 1;
+    if (end - start > maxChars) {
+      const slack = Math.max(0, Math.floor((maxChars - matchLength) / 2));
+      start = Math.max(0, index - slack);
+      end = Math.min(prose.length, index + matchLength + slack);
+    }
+    return prose.slice(start, end).replace(/\s+/g, ' ').trim().slice(0, maxChars);
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Scan `text` for a vocabulary rule's banned terms, returning hits
+ * [{word, fix, context}]. `context` is a bounded window of the prose the term
+ * matched in — see `matchContextAround`.
+ * Prose-only (code/quotes excluded); word-boundary match; case-insensitive unless the
+ * term is `caseSensitive` (abbreviations like "AC"). FAIL-SAFE: any error → [] (allow).
+ */
+export function vocabularyViolations(rule, text, repoRoot = DEFAULT_REPO_ROOT) {
+  try {
+    if (typeof text !== 'string' || !text) return [];
+    const { terms } = resolveVocabulary(rule, repoRoot);
+    if (!terms.length) return [];
+    const prose = proseOnly(text);
+    const hits = [];
+    for (const t of terms) {
+      const w = escapeRegexLiteral(t.word);
+      // (?<![\w-]) … (?![\w-]) is a word boundary that also excludes hyphenated
+      // compounds, so a noun-only ban on "grain" never matches "fine-grained".
+      const re = new RegExp(`(?<![\\w-])${w}(?![\\w-])`, t.caseSensitive ? '' : 'i');
+      const m = re.exec(prose);
+      if (m) {
+        hits.push({
+          word: t.word,
+          fix: t.fix,
+          context: matchContextAround(prose, m.index, m[0].length),
+        });
+      }
+    }
+    return hits;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * @param {object} [opts]
+ * @param {boolean} [opts.requireNew] Apply the managed entry's strict
+ *   `newFilePattern` (file key REQUIRED — owner ruling 2026-07-10) instead of the
+ *   lenient `pattern`. Callers pass true when the path is being CREATED (the
+ *   target does not exist yet); existing/legacy files are validated leniently,
+ *   honoring the no-backfill ruling. Entries without a `newFilePattern` fall back
+ *   to `pattern`.
+ */
+export function namingViolation(rule, relPath, opts = {}) {
+  try {
+    if (!rule || typeof relPath !== 'string') return null;
+    const naming = rule.naming;
+    if (!naming || !Array.isArray(naming.managed)) return null;
+    if (!relPath.startsWith('specs/')) return null;
+    // Only .md files are spec entities; .json/.yaml/etc under specs/ are not.
+    if (!relPath.endsWith('.md')) return null;
+
+    // POSIX dirname/basename (relPath is already POSIX-normalized by the caller).
+    const lastSlash = relPath.lastIndexOf('/');
+    const dir = lastSlash === -1 ? '' : relPath.slice(0, lastSlash);
+    const basename = lastSlash === -1 ? relPath : relPath.slice(lastSlash + 1);
+
+    // Slug-only zones: any kebab-case .md is allowed through.
+    const slugOnly = Array.isArray(naming.slugOnlyDirs) ? naming.slugOnlyDirs : [];
+    for (const z of slugOnly) {
+      if (dir === z || dir.startsWith(z + '/')) return null;
+    }
+
+    // Find the managed rule for this directory. A file can match BOTH a parent dir
+    // and a more-specific subdir (e.g. specs/agents AND specs/agents/golden-cases);
+    // the MOST-SPECIFIC match (longest `r.dir`) must win, else the parent rule's
+    // pattern shadows the child's. A plain `.find()` returns registry order, which
+    // mis-validates a golden-case file against the AGENT pattern when specs/agents is
+    // listed first.
+    let m = null;
+    for (const r of naming.managed) {
+      if (!r || typeof r.dir !== 'string') continue;
+      if (dir === r.dir || dir.startsWith(r.dir + '/')) {
+        if (!m || r.dir.length > m.dir.length) m = r;
+      }
+    }
+    if (!m) return null; // unmanaged subdir under specs/ — don't block
+
+    const strictNew = opts.requireNew === true && typeof m.newFilePattern === 'string';
+    const activePattern = strictNew ? m.newFilePattern : m.pattern;
+    let re;
+    try {
+      re = new RegExp(activePattern);
+    } catch {
+      return null; // uncompilable pattern → fail-safe allow
+    }
+    if (re.test(basename)) return null; // matches the required shape → fine
+
+    return {
+      relPath,
+      dir: m.dir,
+      kind: m.kind ?? null,
+      requiredPattern: activePattern,
+      example: m.example ?? null,
+      strictNew,
+    };
+  } catch {
+    return null; // any unexpected error → fail-safe allow
+  }
+}