heyspex 0.1.0 → 0.2.1

package/spexharness/src/gates/enforce-session-sequence.mjs

@@ -0,0 +1,895 @@
+// spexharness/src/gates/enforce-session-sequence.mjs
+//
+// Engine port of scripts/claude-hooks/enforce-session-sequence.mjs — the
+// Stop-hook L3 SEQUENCING gate ([[HS-EPIC-ZGWR]] AC#4): once a session has
+// flipped a spec to `status: in_review`, the structured handoff
+// (heyspex_record_wip) and a progress checkpoint (heyspex_report_progress)
+// are hard close-out steps. See ./PORTING.md for the recipe this follows and
+// ./env-vault-guard.mjs for the reference port.
+//
+// The original script does NOT export a pure decision function — its logic
+// (`scanTranscript`, `toolUseIsFlip`, `isUnderSpecsTaskOrEpic`,
+// `shouldBlockForReal`, `fireRule`) lives as un-exported helpers inside the
+// file, tangled with `main()`'s stdin read. Per PORTING.md step 1's
+// "otherwise" branch that logic would normally be extracted into the
+// original script itself, but this task's Do-nots forbid touching anything
+// under scripts/claude-hooks/. This port therefore re-derives those helpers
+// (transcript scanning, the in_review flip detector, the interactive-vs-
+// unattended rung check) here, verbatim in behavior, while importing the
+// REAL shared/canonical dependencies unchanged rather than re-deriving them:
+//   - scripts/claude-hooks/_guardrail-loader.mjs — loadGuardrails,
+//     rulesForSurface, isRuleEnabled. This is a dependency-free shared
+//     loader (not one of the twelve hook scripts themselves; no stdin read,
+//     no unconditional main()), so importing it carries no import hazard and
+//     keeps the toggle/reason-text source of truth identical to the
+//     original (the compiled `.heyspex/guardrails.json`, authored from
+//     session-close-protocol.md's `enforcement:` block).
+//   - vendor/heyspex-mcp/vault-resolve.mjs — getActiveConfig(), for the
+//     same optional second vault-root base the original's `vaultRoot()`
+//     helper resolves (specs living in a vault split out from the code
+//     repo). Also dependency-free / no import hazard.
+// Nothing here re-derives the wip/progress reason TEXT or the enable/disable
+// toggle logic — both come from the same compiled registry the original
+// reads, so the two cannot drift on THAT axis; what's re-derived is the
+// transcript-scanning glue, which carries no rule content of its own.
+//
+// IMPORT HAZARD NOTE (why the original script itself is never imported,
+// unlike settings-write-gate.mjs which imports its original lazily):
+// enforce-session-sequence.mjs's `main()` is also unguarded (no
+// `isDirectExecution` check) and also reads stdin unconditionally — but it
+// exports no pure function worth reaching for in the first place (see
+// above), so there is nothing to gain by importing it at all, hazardous or
+// otherwise. It is simply never imported here.
+//
+// Event/field mapping: a Stop hook → the engine's `stop` event point.
+//   stdin.transcript_path   → evt.transcriptPath
+//   stdin.stop_hook_active  → evt.stopHookActive
+// (`events.mjs`'s EVENT_FIELDS documents `stop` as carrying no fields beyond
+// the common ones; createEvent does not validate field names, so a front
+// passes these two straight through.)
+//
+// ---------------------------------------------------------------------------
+// FRONT-AGNOSTIC (wave 6 of [[HS-AZ61-NYPR]]): the session-record path
+// ---------------------------------------------------------------------------
+// The port above reads a CLAUDE CODE TRANSCRIPT, which is the only place a
+// Claude Code session records what it did. Every other front has no such file —
+// so on `hs chat`, an overnight headless seat, a DeepSeek seat or a local-model
+// seat this gate used to short-circuit on `if (!transcriptPath) return allow`,
+// i.e. it registered and then allowed, unconditionally. The rule reached
+// exactly one front.
+//
+// It no longer does. Those fronts DO have a record of what the session did —
+// spexharness/src/session-record.mjs, which spexharness/src/session-lifecycle.mjs
+// hands to every `stop` event as BOTH `evt.sessionRecord` and `ctx.sessionRecord`.
+// Its `toolCalls` array carries `{ name, input, output }` per call in order,
+// which is precisely the information `scanTranscript` digs out of a transcript's
+// assistant `tool_use` blocks: heyspex_submit_for_review (or an Edit/Write/
+// MultiEdit that introduces `status: in_review` under specs/tasks|epics) is the
+// FLIP, heyspex_record_wip is the handoff, heyspex_report_progress is the
+// checkpoint. `scanSessionRecord` below reads exactly those three facts off the
+// record, reusing the SAME `toolUseIsFlip` helper the transcript scan uses — one
+// flip detector, two carriers.
+//
+// Precedence is deliberate and preserves every existing golden: a transcript,
+// when present, still wins. The record path is what runs when there is no
+// transcript, which is every non-Claude-Code front. Both paths feed the identical
+// rule evaluation below (the same two registry rows, the same two rungs, the same
+// reason text), so the two fronts cannot enforce different rules.
+//
+// Decision mapping — the builder brief's own instruction: "map its current
+// `{ decision: 'block', reason }` stdout shape onto the engine's deny
+// decision". The original is actually a TWO-RUNG gate, not a single
+// block/allow switch — HEYSPEX_SESSION_SEQUENCE_INTERACTIVE and
+// CLAUDE_AGENT decide whether an unmet check is a real BLOCK (stdout JSON,
+// `{decision:"block", reason}`) or an interactive WARN-ONLY (empty stdout —
+// the stop is still allowed — with the same reason text only on stderr).
+// The warn-only rung is a third, richer-than-binary outcome the engine has
+// no native slot for either (same shape as `env-vault-guard.mjs`'s "ask" →
+// rewrite mapping): mapped here to `rewrite` with `{ warn: true, reason,
+// rule }` rather than silently downgrading it to a plain `allow` (which
+// would drop the reason text a caller might still want to surface) or
+// upgrading it to `deny` (a real behavior change — the original explicitly
+// does NOT block the stop in this rung). This also gives this one gate
+// natural coverage of all three engine decisions by itself (AC3: allow when
+// nothing is missing or the check doesn't apply, deny on a real block, and
+// rewrite on the warn-only rung) — see ./enforce-session-sequence.test.mjs.
+//
+// AC5 (the blocking case is preserved exactly): a real block's `reason` is
+// `wipRule.inject.trim()` / `progressRule.inject.trim()` — the SAME compiled
+// registry text the original emits, verbatim, not a re-authored string.
+//
+// Env hatches (unchanged):
+//   HEYSPEX_SESSION_SEQUENCE_OFF=1               Hard kill switch (both rungs).
+//   HEYSPEX_SESSION_SEQUENCE_INTERACTIVE=block    Raises the interactive rung to a real block.
+//   CLAUDE_AGENT=true                             Unattended session → real block (unchanged).
+// The rule also honors its registry `configKey`
+// (agent_behaviors.session_wip_before_stop.enabled /
+// agent_behaviors.session_progress_before_stop.enabled) via isRuleEnabled.
+//
+// Not ported HERE: the original's `appendGuardrailEvent(...)` audit-log
+// write on fire, and the loop-guard/no-op fail-safe paths' silence — a gate
+// module stays a pure decision function (AC1: no stdout writes; same
+// spirit, no other observability side effects), matching env-vault-guard.mjs's
+// port. The `rule` field this run() carries on both its `deny` and `rewrite`
+// results exists so a FRONT can restore that same audit trail without
+// re-deriving which rule fired from `reason` text — see
+// spexharness/src/adapters/audit.mjs, called from
+// spexharness/src/adapters/claude-code.mjs's runGateAsHook after this
+// gate's decision comes back.
+//
+// `ctx` contract (all optional; every field defaults to a real fs/env read):
+//   ctx.cwd        - repo root to resolve the guardrail registry + flip-path
+//                     checks from. Defaults to CLAUDE_PROJECT_DIR, else this
+//                     repo's root. When given it is a self-contained fixture
+//                     root and both rules' config toggles are read from it too.
+//   ctx.configRoot - the directory holding `.heyspex/config.yaml` (both rules'
+//                     configKey toggles); 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]]).
+//                     Distinct from ctx.vaultRoot below, which is only the
+//                     flip-path second base and may be a function.
+//   ctx.readFile(path) - reads the transcript file's content, or null if
+//                     unreadable. Defaults to a real fs.readFileSync. Tests
+//                     inject the fixture's transcript text directly instead
+//                     of writing a real file.
+//   ctx.vaultRoot  - string, or a zero-arg function returning one (or
+//                     throwing) — the second base `isUnderSpecsTaskOrEpic`
+//                     checks a flip path against, mirroring the original's
+//                     `vaultRoot()` (getActiveConfig().repoRootAbs, cached
+//                     process-lifetime by vault-resolve.mjs). Defaults to a
+//                     fail-safe-wrapped call to the real getActiveConfig().
+//                     None of this port's own fixtures need it (every fixture
+//                     flip path already resolves under ctx.cwd itself), but
+//                     it is available for a caller/tester that does.
+//   ctx.env        - env var overrides (tests use this instead of mutating
+//                     process.env).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  loadGuardrails,
+  rulesForSurface,
+  isRuleEnabled,
+  vocabularyViolations,
+  compilePatterns,
+  proseOnly,
+  matchContextAround,
+} from '../../../scripts/claude-hooks/_guardrail-loader.mjs';
+import { lastAssistantText } from '../../../scripts/claude-hooks/_transcript-text.mjs';
+import { getActiveConfig } from '../../../vendor/heyspex-mcp/vault-resolve.mjs';
+import { defaultConfigRoot } from '../config-root.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, '..', '..', '..');
+
+const RULE_ID = 'session-wip-before-stop';
+const PROGRESS_RULE_ID = 'session-progress-before-review';
+const STATUS_REVIEW_RE = /^\s*status:\s*in_review\s*$/m;
+const SUBMIT_FOR_REVIEW_RE = /heyspex_submit_for_review/;
+const RECORD_WIP_RE = /heyspex_record_wip/;
+const REPORT_PROGRESS_RE = /heyspex_report_progress/;
+const OFF_ENV = 'HEYSPEX_SESSION_SEQUENCE_OFF';
+const INTERACTIVE_ENV = 'HEYSPEX_SESSION_SEQUENCE_INTERACTIVE';
+
+function defaultReadFile(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function resolveVaultRootAbs(ctx) {
+  if (typeof ctx.vaultRoot === 'string') return ctx.vaultRoot;
+  if (typeof ctx.vaultRoot === 'function') {
+    try {
+      return ctx.vaultRoot();
+    } catch {
+      return null;
+    }
+  }
+  try {
+    return getActiveConfig()?.repoRootAbs ?? null;
+  } catch {
+    return null; // fail-safe: the code-repo base still applies
+  }
+}
+
+// True when a file path resolves under specs/tasks or specs/epics (the spec
+// kinds that carry a reviewable lifecycle). Mirrors the original hook's
+// local helper of the same name (itself mirroring notify-status-flip.mjs).
+function isUnderSpecsTaskOrEpic(filePath, root, vaultRootAbs) {
+  if (typeof filePath !== 'string' || filePath.length === 0) return false;
+  const abs = path.isAbsolute(filePath) ? filePath : path.resolve(root, filePath);
+  const bases = [root];
+  if (vaultRootAbs && vaultRootAbs !== root) bases.push(vaultRootAbs);
+  for (const base of bases) {
+    for (const sub of ['specs/tasks', 'specs/epics']) {
+      const rel = path.relative(path.join(base, sub), abs);
+      if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) return true;
+    }
+  }
+  return false;
+}
+
+// Did THIS Edit/Write/MultiEdit tool_use introduce `status: in_review`?
+// Mirrors the original hook's local helper of the same name.
+function toolUseIsFlip(name, input, root, vaultRootAbs) {
+  if (!input || typeof input !== 'object') return false;
+  if (!isUnderSpecsTaskOrEpic(input.file_path, root, vaultRootAbs)) return false;
+  if (name === 'Edit') {
+    const next = typeof input.new_string === 'string' ? input.new_string : '';
+    const prev = typeof input.old_string === 'string' ? input.old_string : '';
+    return STATUS_REVIEW_RE.test(next) && !STATUS_REVIEW_RE.test(prev);
+  }
+  if (name === 'MultiEdit') {
+    const edits = Array.isArray(input.edits) ? input.edits : [];
+    return edits.some((e) => {
+      const next = typeof e?.new_string === 'string' ? e.new_string : '';
+      const prev = typeof e?.old_string === 'string' ? e.old_string : '';
+      return STATUS_REVIEW_RE.test(next) && !STATUS_REVIEW_RE.test(prev);
+    });
+  }
+  if (name === 'Write') {
+    const content = typeof input.content === 'string' ? input.content : '';
+    return STATUS_REVIEW_RE.test(content);
+  }
+  return false;
+}
+
+// Walk the whole transcript JSONL once, returning whether the session (a)
+// flipped a spec to in_review, (b) called heyspex_record_wip, and (c) called
+// heyspex_report_progress at least once — by scanning every assistant
+// tool_use block. Mirrors the original hook's local helper of the same name,
+// except it takes the transcript's TEXT directly (via ctx.readFile) rather
+// than a path + its own fs.readFileSync call.
+function scanTranscript(raw, root, vaultRootAbs) {
+  const result = { flip: false, wip: false, progress: false };
+  if (typeof raw !== 'string') return result;
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line) continue;
+    let evt;
+    try {
+      evt = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const content = evt?.message?.content;
+    if (!Array.isArray(content)) continue;
+    for (const block of content) {
+      if (!block || block.type !== 'tool_use' || typeof block.name !== 'string') continue;
+      if (RECORD_WIP_RE.test(block.name)) result.wip = true;
+      if (REPORT_PROGRESS_RE.test(block.name)) result.progress = true;
+      if (SUBMIT_FOR_REVIEW_RE.test(block.name)) result.flip = true;
+      if (toolUseIsFlip(block.name, block.input, root, vaultRootAbs)) result.flip = true;
+    }
+    if (result.flip && result.wip && result.progress) break; // nothing left to decide
+  }
+  return result;
+}
+
+/**
+ * The same three facts {@link scanTranscript} extracts, read off a
+ * spexharness/src/session-record.mjs record instead of a Claude Code
+ * transcript — the front-agnostic carrier (see this module's header).
+ *
+ * Only `record.toolCalls` is read: `record.events` carries an event's `point`
+ * and its decision but NOT the tool name (see session-record.mjs's
+ * `recordEvent`), so it cannot answer "was heyspex_record_wip called". The flip
+ * detector is the SAME `toolUseIsFlip` the transcript scan uses, so a
+ * status-flipping Write/Edit/MultiEdit is recognized identically on both paths.
+ *
+ * @param {{ toolCalls?: Array<{ name?: string|null, input?: unknown }> }|null|undefined} record
+ * @param {string} root
+ * @param {string|null} vaultRootAbs
+ * @returns {{ flip: boolean, wip: boolean, progress: boolean }}
+ */
+export function scanSessionRecord(record, root, vaultRootAbs) {
+  const result = { flip: false, wip: false, progress: false };
+  const calls = Array.isArray(record?.toolCalls) ? record.toolCalls : [];
+  for (const call of calls) {
+    const name = typeof call?.name === 'string' ? call.name : '';
+    if (!name) continue;
+    if (RECORD_WIP_RE.test(name)) result.wip = true;
+    if (REPORT_PROGRESS_RE.test(name)) result.progress = true;
+    if (SUBMIT_FOR_REVIEW_RE.test(name)) result.flip = true;
+    if (toolUseIsFlip(name, call?.input, root, vaultRootAbs)) result.flip = true;
+    if (result.flip && result.wip && result.progress) break; // nothing left to decide
+  }
+  return result;
+}
+
+// Real block (unattended, or an interactive session explicitly raised the
+// rung) vs. warn-only (interactive default). Mirrors the original hook's
+// local helper of the same name.
+function shouldBlockForReal(env) {
+  return env.CLAUDE_AGENT === 'true' || env[INTERACTIVE_ENV] === 'block';
+}
+
+// Byte-for-byte the original hook's own interactive-warn stderr banner (its
+// unexported fireRule()'s `else` branch) — kept here rather than left to the
+// adapter's generic warn formatter (spexharness/src/adapters/claude-code.mjs's
+// `warnStderrText`) 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 (
+    `[enforce-session-sequence] warning — ${reason}\n` +
+    '(Interactive session: this only warns. Set HEYSPEX_SESSION_SEQUENCE_INTERACTIVE=block to enforce it here too.)\n'
+  );
+}
+
+/** The session-sequence gate's id — unique across the built-in registry. */
+export const id = 'enforce-session-sequence';
+/** 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 (the unattended/raised rung). */
+export const severity = 'block';
+
+/**
+ * @param {{ point: string, transcriptPath?: string, stopHookActive?: boolean,
+ *            sessionRecord?: object }} evt
+ * @param {{ cwd?: string, readFile?: (p: string) => string | null,
+ *            sessionRecord?: object,
+ *            vaultRoot?: string | (() => string | null),
+ *            env?: Record<string, string | undefined> }} [ctx]
+ *   `sessionRecord` (on either the event or the ctx — session-lifecycle.mjs
+ *   supplies both) is the front-agnostic carrier read when no transcript exists.
+ * @returns {{ decision: 'allow'|'deny'|'rewrite', reason?: string, rewrite?: object }}
+ */
+export function run(evt, ctx = {}) {
+  const env = ctx.env ?? process.env;
+  if (String(env[OFF_ENV] ?? '') === '1') return { decision: 'allow' };
+
+  // Already inside a stop-hook continuation — one reminder is enough; never loop.
+  if (evt?.stopHookActive === true) return { decision: 'allow' };
+
+  // A transcript (Claude Code) or a session record (every other front). With
+  // neither there is nothing to judge — that is the only remaining allow-by-
+  // absence, and it is now a genuinely empty session rather than "this front
+  // isn't Claude Code".
+  const transcriptPath = evt?.transcriptPath;
+  const sessionRecord = evt?.sessionRecord ?? ctx.sessionRecord ?? null;
+  if (!transcriptPath && !sessionRecord) return { decision: 'allow' };
+
+  const root = ctx.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? REPO_ROOT;
+  const configRoot = ctx.configRoot ?? (ctx.cwd ? ctx.cwd : defaultConfigRoot());
+  const readFile = ctx.readFile ?? defaultReadFile;
+
+  const guardrails = loadGuardrails(root);
+  const stopRules = rulesForSurface(guardrails, 'stop');
+
+  // Load both rules independently — toggle + reason text each. Missing/
+  // disabled rule → that check is skipped (fail-open per-rule, matching
+  // every other registry-driven gate in this repo), not a reason to skip the
+  // other check.
+  const wipRule = stopRules.find((r) => r && r.rule === RULE_ID);
+  const progressRule = stopRules.find((r) => r && r.rule === PROGRESS_RULE_ID);
+  if ((!wipRule || !wipRule.inject) && (!progressRule || !progressRule.inject)) {
+    return { decision: 'allow' };
+  }
+
+  const vaultRootAbs = resolveVaultRootAbs(ctx);
+  // Transcript first when there is one (every existing golden is recorded on
+  // this path and must keep matching byte for byte); the session record is the
+  // carrier every other front actually has.
+  const { flip, wip, progress } = transcriptPath
+    ? scanTranscript(readFile(transcriptPath) ?? '', root, vaultRootAbs)
+    : scanSessionRecord(sessionRecord, root, vaultRootAbs);
+  if (!flip) return { decision: 'allow' };
+
+  const forReal = shouldBlockForReal(env);
+
+  // Checked in this order so a turn missing BOTH reports the wip gate first
+  // (the more foundational of the two — no handoff at all vs. an incomplete
+  // checklist) — same ordering as the original.
+  if (wipRule && wipRule.inject && !wip && isRuleEnabled(wipRule, configRoot)) {
+    const reason = wipRule.inject.trim();
+    // `rule` rides at the top level (not just inside `rewrite`) so a caller
+    // observing only the deny branch — e.g. the audit-log writer in
+    // spexharness/src/adapters/audit.mjs — can still name which of the two
+    // rules fired without re-deriving it from `reason` text.
+    return forReal
+      ? { decision: 'deny', reason, rule: RULE_ID }
+      : { decision: 'rewrite', reason, rule: RULE_ID, rewrite: { warn: true, reason, rule: RULE_ID, stderrText: warnStderrText(reason) } };
+  }
+
+  if (progressRule && progressRule.inject && !progress && isRuleEnabled(progressRule, configRoot)) {
+    const reason = progressRule.inject.trim();
+    return forReal
+      ? { decision: 'deny', reason, rule: PROGRESS_RULE_ID }
+      : { decision: 'rewrite', reason, rule: PROGRESS_RULE_ID, rewrite: { warn: true, reason, rule: PROGRESS_RULE_ID, stderrText: warnStderrText(reason) } };
+  }
+
+  return { decision: 'allow' };
+}
+
+export default { id, event, severity, run };
+
+// ---------------------------------------------------------------------------
+// HS-RCIT — the stop-time correction gate (bounded, one-shot).
+//
+// [[HS-Y646-NYPR-EPIC-session-bootstrap-and-stop-for-every]] acceptance
+// criterion 3: "A stop-time violation is rewritten once with the specific
+// correction and the second reply is shown with a flag if it still violates."
+// The epic's "What you will see" says the same in user words: "A reply that
+// breaks a stop-time rule is rewritten once and shown with a one-line note,
+// never silently passed and never looped."
+//
+// This section adds that bounded correction ON TOP of the session-sequence
+// port above — nothing above this line changed shape, so the registry entry
+// (./index.mjs), the golden fixtures and every existing caller of `run()`
+// keep behaving exactly as recorded.
+//
+// The three stop-time rules checked, all read from the SAME compiled
+// registry (`.heyspex/guardrails.json`) the sibling Stop gates read — never a
+// second copy of a word list or a pattern:
+//   1. naughty list          → vocabularyViolations (naughty-list-gate.mjs's source)
+//   2. id display format     → compilePatterns + proseOnly (id-display-format-gate.mjs's source)
+//   3. session sequence      → this module's own run(), given the stop event
+//
+// The bound (never loops): a reply is corrected AT MOST ONCE
+// (STOP_TIME_MAX_REWRITES = 1) and re-checked AT MOST ONCE. If the corrected
+// reply still violates, it is returned UNCHANGED carrying `flagged: true`
+// plus a one-line note — never corrected a second time, never re-checked a
+// third time, and never downgraded to a plain `allow` (which is what
+// "silently passes a violation" would mean). Two loop bounds exist so a
+// misbehaving caller cannot defeat either:
+//   - in-process: enforceStopTimeRules() does the single correction pass
+//     itself and terminates on its own;
+//   - out-of-process (the model does the rewrite between calls): the caller
+//     passes `attempt`, and createStopTimeCorrector() holds that counter for
+//     callers that would otherwise keep passing 0.
+//
+// Decision mapping onto decide.mjs: a clean reply is `allow`; a corrected
+// reply and a flagged reply are BOTH `rewrite` (the caller must show the
+// payload's `reply`, not the one it handed in) — never `deny`, because a
+// stop-time correction shows the answer with its note rather than swallowing
+// it. `deny` stays what the session-sequence rung above uses.
+// ---------------------------------------------------------------------------
+
+/** Break-glass for the whole stop-time correction path (per-rule hatches still apply). */
+export const STOP_TIME_OFF_ENV = 'HEYSPEX_STOP_TIME_OFF';
+/** The bound: a violating reply is corrected at most this many times. Never raise it. */
+export const STOP_TIME_MAX_REWRITES = 1;
+
+const NAUGHTY_RULE_ID = 'naughty-list';
+const ID_DISPLAY_RULE_ID = 'id-display-shape-gate';
+/** The stop-time rule families this gate checks a reply against (acceptance criterion 1). */
+export const STOP_TIME_RULES = Object.freeze([NAUGHTY_RULE_ID, ID_DISPLAY_RULE_ID, 'session-sequence']);
+
+// The same non-prose spans proseOnly() blanks out (code spans, fenced blocks,
+// [[wikilinks]], URLs, blockquotes) — kept as an ordered split rather than a
+// blanking replace so a mechanical correction can rewrite the prose parts and
+// put the protected parts back byte-for-byte.
+const NON_PROSE_RE = /```[\s\S]*?```|`[^`]*`|\[\[[^\]]*\]\]|https?:\/\/\S+|^[ \t]{0,3}>.*$/gm;
+
+function proseSegments(text) {
+  const segments = [];
+  const re = new RegExp(NON_PROSE_RE.source, 'gm');
+  let last = 0;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    if (m.index > last) segments.push({ text: text.slice(last, m.index), prose: true });
+    segments.push({ text: m[0], prose: false });
+    last = m.index + m[0].length;
+    if (m[0].length === 0) re.lastIndex += 1; // guard against a zero-width match spinning
+  }
+  if (last < text.length) segments.push({ text: text.slice(last), prose: true });
+  return segments;
+}
+
+function escapeRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * The literal drop-in a naughty-list term's `fix` offers, when it offers one.
+ * The registry writes fixes as prose, some of which lead with a quoted
+ * replacement ("knob" → `"setting," "parameter," "control"`); those can be
+ * applied mechanically. A fix with no quoted candidate ("seam" → `name what
+ * the boundary or integration actually is`) has no mechanical form — the
+ * correction still names it, but only a real rewriter can clear it, which is
+ * exactly the case that exercises the flagged second-violation path.
+ *
+ * @param {string} fix
+ * @returns {string|null}
+ */
+export function suggestedReplacement(fix) {
+  if (typeof fix !== 'string') return null;
+  const m = /["“]([^"“”]{1,60})["”]/.exec(fix);
+  if (!m) return null;
+  const candidate = m[1].trim().replace(/[,.;:]+$/, '').trim();
+  return candidate.length > 0 ? candidate : null;
+}
+
+function stopTimeRoot(options) {
+  return options.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? REPO_ROOT;
+}
+
+/** Same code-root vs config-root split as run() — see the ctx contract in the header. */
+function stopTimeConfigRoot(options) {
+  return options.configRoot ?? (options.cwd ? options.cwd : defaultConfigRoot());
+}
+
+function naughtyListViolations(reply, root, env, configRoot = root) {
+  if (String(env.HEYSPEX_NAUGHTY_LIST_OFF ?? '') === '1') return [];
+  const rules = rulesForSurface(loadGuardrails(root), 'stop').filter((r) => r && r.kind === 'vocabulary');
+  const found = [];
+  for (const rule of rules) {
+    if (!isRuleEnabled(rule, configRoot)) continue;
+    for (const hit of vocabularyViolations(rule, reply, root)) {
+      found.push({
+        rule: rule.rule ?? NAUGHTY_RULE_ID,
+        kind: 'vocabulary',
+        severity: rule.severity ?? 'block',
+        word: hit.word,
+        fix: hit.fix,
+        context: hit.context,
+        replacement: suggestedReplacement(hit.fix),
+        correction: `"${hit.word}" → ${hit.fix}`,
+      });
+    }
+  }
+  return found;
+}
+
+function idDisplayViolations(reply, root, env, configRoot = root) {
+  if (String(env.HEYSPEX_ID_DISPLAY_GATE_OFF ?? '') === '1') return [];
+  const rule = rulesForSurface(loadGuardrails(root), 'stop').find((r) => r && r.rule === ID_DISPLAY_RULE_ID);
+  if (!rule || !isRuleEnabled(rule, configRoot)) return [];
+  const patterns = compilePatterns(rule);
+  if (!patterns.length) return [];
+  const prose = proseOnly(reply);
+  const found = [];
+  for (const re of patterns) {
+    const m = re.exec(prose);
+    if (!m) continue;
+    const excerpt = matchContextAround(prose, m.index, m[0].length);
+    found.push({
+      rule: ID_DISPLAY_RULE_ID,
+      kind: 'pattern',
+      severity: rule.severity ?? 'warn',
+      excerpt,
+      replacement: null, // no mechanical form: the type must be read off the spec, never guessed
+      correction:
+        `"${excerpt}" → write the id suffixed (HS-OFUB-CVOB-EPIC) or prose-prefixed (Epic: HS-OFUB-CVOB), ` +
+        `never annotated in parentheses`,
+    });
+  }
+  return found;
+}
+
+function sequenceViolations(evt, options) {
+  if (!evt) return [];
+  const result = run(evt, options);
+  if (!result || result.decision === 'allow') return [];
+  const reason = typeof result.reason === 'string' ? result.reason : '';
+  return [
+    {
+      rule: result.rule ?? 'session-sequence',
+      kind: 'sequence',
+      severity: result.decision === 'deny' ? 'block' : 'warn',
+      // The registry's own inject text, verbatim — same words the deny rung
+      // above emits, not a re-authored string.
+      correction: reason,
+      reason,
+    },
+  ];
+}
+
+/**
+ * Check one reply against all three stop-time rule families (acceptance
+ * criterion 1). Pure with respect to the reply: it never modifies it.
+ *
+ * @param {string} reply - the assistant reply about to be shown.
+ * @param {{ cwd?: string, configRoot?: string, env?: Record<string, string|undefined>, event?: object,
+ *           readFile?: (p: string) => string|null, vaultRoot?: string|(() => string|null) }} [options]
+ * @returns {{ violations: Array<object>, checked: string[], off: boolean }}
+ */
+export function checkStopTimeRules(reply, options = {}) {
+  const env = options.env ?? process.env;
+  if (String(env[STOP_TIME_OFF_ENV] ?? '') === '1') {
+    return { violations: [], checked: [], off: true };
+  }
+  const root = stopTimeRoot(options);
+  const configRoot = stopTimeConfigRoot(options);
+  const text = typeof reply === 'string' ? reply : '';
+  const checked = [NAUGHTY_RULE_ID, ID_DISPLAY_RULE_ID];
+  const violations = [
+    ...naughtyListViolations(text, root, env, configRoot),
+    ...idDisplayViolations(text, root, env, configRoot),
+  ];
+  // The sequence rule is transcript state, not reply text — it is only
+  // checkable when the caller hands over the stop event it belongs to.
+  if (options.event) {
+    checked.push('session-sequence');
+    violations.push(...sequenceViolations(options.event, options));
+  }
+  return { violations, checked, off: false };
+}
+
+/**
+ * The SPECIFIC correction for a set of violations — the per-rule fix text,
+ * never a generic "you broke a rule" line.
+ *
+ * @param {Array<object>} violations
+ * @returns {string}
+ */
+export function correctionFor(violations) {
+  const lines = [];
+  const seen = new Set();
+  for (const v of violations ?? []) {
+    const line = `  • ${v.rule}: ${v.correction}`;
+    if (seen.has(line)) continue;
+    seen.add(line);
+    lines.push(line);
+  }
+  if (!lines.length) return '';
+  return `Stop-time correction — rewrite the reply and resend:\n${lines.join('\n')}`;
+}
+
+/**
+ * The one-line note a flagged (still-violating) reply is shown with.
+ *
+ * @param {Array<object>} violations
+ * @returns {string}
+ */
+export function stopTimeFlagNote(violations) {
+  const parts = [];
+  for (const v of violations ?? []) {
+    const label = v.word ? `${v.rule} ("${v.word}")` : v.rule;
+    if (!parts.includes(label)) parts.push(label);
+  }
+  return `[stop-time] shown with a flag — still violates after one correction: ${parts.join(', ')}`;
+}
+
+/**
+ * The default, mechanical correction pass: swap each banned term that carries
+ * a literal replacement candidate, in the PROSE parts of the reply only (a
+ * banned word inside backticks, a wikilink, a URL or a blockquote is exempt,
+ * same as every other stop gate). Violations with no mechanical form are left
+ * alone — deliberately, so they surface on the re-check as a flagged reply
+ * instead of being silently dropped.
+ *
+ * A caller with a real rewriter (a model) passes it as `options.rewrite`
+ * instead; this is the fallback so the gate corrects something on its own.
+ *
+ * Takes the violations as either the second or the third argument, so it can
+ * be handed straight to `options.rewrite` (whose rewriter signature is
+ * `(reply, correction, violations)`) as well as called directly.
+ *
+ * @param {string} reply
+ * @param {Array<object>|string} violations - the violations, or the correction
+ *   text when called in rewriter position (then `alsoViolations` carries them).
+ * @param {Array<object>} [alsoViolations]
+ * @returns {string} the corrected reply (=== the input when nothing was mechanically fixable)
+ */
+export function applyCorrection(reply, violations, alsoViolations) {
+  if (typeof reply !== 'string' || !reply) return typeof reply === 'string' ? reply : '';
+  const list = Array.isArray(violations) ? violations : Array.isArray(alsoViolations) ? alsoViolations : [];
+  const swaps = list.filter((v) => v && v.kind === 'vocabulary' && v.word && v.replacement);
+  if (!swaps.length) return reply;
+  return proseSegments(reply)
+    .map((seg) => {
+      if (!seg.prose) return seg.text;
+      let out = seg.text;
+      for (const swap of swaps) {
+        const re = new RegExp(`(?<![\\w-])${escapeRe(swap.word)}(?![\\w-])`, 'gi');
+        out = out.replace(re, (match) =>
+          /^[A-Z]/.test(match) ? swap.replacement.charAt(0).toUpperCase() + swap.replacement.slice(1) : swap.replacement,
+        );
+      }
+      return out;
+    })
+    .join('');
+}
+
+/**
+ * The stop-time gate itself (acceptance criteria 2, 3 and 4).
+ *
+ * @param {string} reply - the reply about to be shown.
+ * @param {{
+ *   cwd?: string,
+ *   env?: Record<string, string|undefined>,
+ *   event?: object,
+ *   readFile?: (p: string) => string|null,
+ *   vaultRoot?: string|(() => string|null),
+ *   attempt?: number,
+ *   rewrite?: false | ((reply: string, correction: string, violations: Array<object>) => string),
+ * }} [options]
+ *   `attempt` — how many corrections this reply already went through
+ *   upstream; `>= STOP_TIME_MAX_REWRITES` means this IS the second reply, so
+ *   it is flagged rather than corrected again. `rewrite` — a rewriter to run
+ *   the single correction pass with (defaults to {@link applyCorrection});
+ *   pass `false` for verdict-only mode, where the caller performs the rewrite
+ *   between calls and comes back with `attempt: 1`.
+ * @returns {{
+ *   decision: 'allow'|'rewrite',
+ *   reply: string, originalReply: string,
+ *   violations: Array<object>, initialViolations: Array<object>,
+ *   correction: string|null, reason?: string,
+ *   rewritten: boolean, flagged: boolean, needsRewrite: boolean,
+ *   attempts: number, checked: string[],
+ *   flag?: { note: string, rules: string[], violations: Array<object> },
+ *   rewrite?: object,
+ * }}
+ */
+export function enforceStopTimeRules(reply, options = {}) {
+  const original = typeof reply === 'string' ? reply : '';
+  const attemptIn = Number.isInteger(options.attempt) && options.attempt > 0 ? options.attempt : 0;
+  const first = checkStopTimeRules(original, options);
+
+  const clean = (attempts) => ({
+    decision: 'allow',
+    reply: original,
+    originalReply: original,
+    violations: [],
+    initialViolations: first.violations,
+    correction: null,
+    rewritten: false,
+    flagged: false,
+    needsRewrite: false,
+    attempts,
+    checked: first.checked,
+  });
+
+  if (!first.violations.length) return clean(attemptIn);
+
+  const correction = correctionFor(first.violations);
+
+  // `attempts` is the correction budget SPENT overall (never above the
+  // bound); `rewritten` says whether THIS call did the rewriting, so a caller
+  // re-asking about an already-corrected reply never double-counts it.
+  const flaggedVerdict = (shownReply, violations, attempts, rewritten) => {
+    const note = stopTimeFlagNote(violations);
+    const flag = { note, rules: [...new Set(violations.map((v) => v.rule))], violations };
+    return {
+      // Still a rewrite decision, never `allow` — a flagged reply is shown
+      // WITH its note, which is not the same thing as silently passing it.
+      decision: 'rewrite',
+      reply: shownReply,
+      originalReply: original,
+      violations,
+      initialViolations: first.violations,
+      correction,
+      reason: note,
+      rewritten,
+      flagged: true,
+      needsRewrite: false, // the single correction is spent; never ask for another
+      attempts,
+      checked: first.checked,
+      flag,
+      rewrite: { reply: shownReply, correction, violations, flagged: true, note, attempts },
+    };
+  };
+
+  // The reply already went through its one correction upstream: show it
+  // UNCHANGED with the flag. No second correction, no third check.
+  if (attemptIn >= STOP_TIME_MAX_REWRITES) {
+    return flaggedVerdict(original, first.violations, STOP_TIME_MAX_REWRITES, false);
+  }
+
+  // Verdict-only mode: hand the specific correction back and let the caller
+  // do the single rewrite. It must return with `attempt: 1`, which lands on
+  // the flagged branch above if the new reply still violates.
+  if (options.rewrite === false) {
+    return {
+      decision: 'rewrite',
+      reply: original,
+      originalReply: original,
+      violations: first.violations,
+      initialViolations: first.violations,
+      correction,
+      reason: correction,
+      rewritten: false,
+      flagged: false,
+      needsRewrite: true,
+      attempts: 0,
+      checked: first.checked,
+      rewrite: { reply: original, correction, violations: first.violations, flagged: false, needsRewrite: true, attempts: 0 },
+    };
+  }
+
+  const rewriter = typeof options.rewrite === 'function' ? options.rewrite : applyCorrection;
+  let corrected;
+  try {
+    corrected = rewriter(original, correction, first.violations);
+  } catch {
+    corrected = original; // a broken rewriter must not lose the reply
+  }
+  if (typeof corrected !== 'string') corrected = original;
+
+  // Exactly one re-check. Whatever it says, this call terminates here.
+  const second = checkStopTimeRules(corrected, options);
+  if (second.violations.length) {
+    return flaggedVerdict(corrected, second.violations, STOP_TIME_MAX_REWRITES, true);
+  }
+
+  return {
+    decision: 'rewrite',
+    reply: corrected,
+    originalReply: original,
+    violations: [],
+    initialViolations: first.violations,
+    correction,
+    reason: correction,
+    rewritten: true,
+    flagged: false,
+    needsRewrite: false,
+    attempts: STOP_TIME_MAX_REWRITES,
+    checked: first.checked,
+    rewrite: { reply: corrected, correction, violations: [], flagged: false, note: null, attempts: STOP_TIME_MAX_REWRITES },
+  };
+}
+
+/**
+ * A session-scoped holder of the one-correction budget, for the
+ * out-of-process shape where the caller (not this module) does the rewriting
+ * and could otherwise keep asking forever. It carries the attempt counter so
+ * a caller that always passes `attempt: 0` still gets exactly one correction
+ * and a flag after that.
+ *
+ * @param {object} [baseOptions] - the options every review() call inherits.
+ * @returns {{ attempts: number, done: boolean, review: (reply: string, extra?: object) => object }}
+ */
+export function createStopTimeCorrector(baseOptions = {}) {
+  let attempts = 0;
+  let done = false;
+
+  return {
+    get attempts() {
+      return attempts;
+    },
+    get done() {
+      return done;
+    },
+    review(reply, extra = {}) {
+      const verdict = enforceStopTimeRules(reply, { ...baseOptions, ...extra, attempt: attempts });
+      if (verdict.rewritten || verdict.needsRewrite) {
+        attempts = Math.min(STOP_TIME_MAX_REWRITES, attempts + 1);
+      }
+      if (verdict.decision === 'allow' || verdict.flagged) done = true;
+      return verdict;
+    },
+  };
+}
+
+/**
+ * decide.mjs-shaped adapter, so a front can register the stop-time gate
+ * alongside the other stop gates. The reply comes from `ctx.reply` when the
+ * front already holds it, else from the transcript's last assistant text (the
+ * same reader naughty-list-gate.mjs and id-display-format-gate.mjs use).
+ *
+ * @param {{ point: string, transcriptPath?: string, stopHookActive?: boolean }} evt
+ * @param {object} [ctx] - the same option bag {@link enforceStopTimeRules} takes.
+ * @returns {{ decision: 'allow'|'rewrite', reason?: string, rewrite?: object, verdict: object }}
+ */
+export function runStopTime(evt, ctx = {}) {
+  const reply =
+    typeof ctx.reply === 'string'
+      ? ctx.reply
+      : evt?.transcriptPath
+        ? (lastAssistantText(evt.transcriptPath) ?? '')
+        : '';
+  const verdict = enforceStopTimeRules(reply, { ...ctx, event: evt });
+  if (verdict.decision === 'allow') return { decision: 'allow', verdict };
+  return { decision: 'rewrite', reason: verdict.reason, rewrite: verdict.rewrite, verdict };
+}
+
+/**
+ * The stop-time correction gate as a registry.mjs gate object. Kept as a
+ * named export rather than registered in ./index.mjs — that file's twelve-gate
+ * set is asserted by fixtures/goldens.test.mjs and index.test.mjs, so a front
+ * that wants this gate registers it itself.
+ */
+export const stopTimeGate = {
+  id: 'stop-time-correction',
+  event: 'stop',
+  severity: 'block',
+  run: runStopTime,
+};