@sun-asterisk/sungen 3.2.34 → 3.3.0-alpha.2

package/src/harness/viewpoint-ledger.ts

@@ -12,6 +12,7 @@ import * as fs from 'fs';
 import { NON_DECLARATION_SECTION, PRIORITY_WORDS, ScenarioInfo } from './parse';
 import { readViewpointText } from './read-text';
 import { keywordHit } from './keyword-match';
+import { countedAssertions } from './counted-assertions';
 
 export interface LedgerItem { id?: string; text: string; covered: boolean }
 
@@ -238,8 +239,7 @@ export function viewpointLedger(viewpointPath: string, scenarios: ScenarioInfo[]
         const n = claimedCount(item.text);
         const auto = carriers.filter((s) => !s.manual);
         if (n !== null && auto.length > 0 && !auto.some((s) => /\bsee all\b/.test(s.stepsText))) {
-          const asserted = Math.max(...auto.map((s) =>
-            (s.stepsText.match(/\bsee \[[^\]]+\][^|]*?\b(?:with|contains) \{\{/g) ?? []).length));
+          const asserted = Math.max(...auto.map((s) => countedAssertions(s.stepsText)));
           if (asserted > 0 && asserted < n) partial.push({ id: item.id, text: item.text, claimed: n, asserted });
         }
       }

package/src/hooks/bash-write-targets.ts

@@ -0,0 +1,109 @@
+/**
+ * The files a Bash command line WRITES through the three forms the pre-tool guard covers (P0.1):
+ * output redirection (`>`, `>>`, `>|`, `&>`, `2>`…), `tee`, and in-place `sed -i`.
+ *
+ * A floor, not a shell interpreter: quotes, escapes, `;`/`&&`/`||`/`|` and a leading `cd` are
+ * understood; anything else that can write a file (`cp`, a script, `python -c`) is out of scope by
+ * design. The command string is untrusted — it is only tokenized here, never executed.
+ */
+import * as path from 'path';
+
+type Tok = { kind: 'word'; value: string } | { kind: 'sep' } | { kind: 'redir'; writes: boolean };
+
+/** Commands that run another command: the real one is the next word. */
+const WRAPPERS = new Set(['sudo', 'env', 'command', 'nohup', 'time', 'exec', 'nice']);
+const ASSIGNMENT = /^[A-Za-z_]\w*=/;
+
+function tokenize(cmd: string): Tok[] {
+  const toks: Tok[] = [];
+  let word = '';
+  let inWord = false;
+  const flush = (): void => { if (inWord) toks.push({ kind: 'word', value: word }); word = ''; inWord = false; };
+  for (let i = 0; i < cmd.length;) {
+    const ch = cmd[i];
+    if (ch === "'") {
+      const end = cmd.indexOf("'", i + 1);
+      word += cmd.slice(i + 1, end < 0 ? cmd.length : end); inWord = true; i = end < 0 ? cmd.length : end + 1;
+    } else if (ch === '"') {
+      let j = i + 1;
+      for (; j < cmd.length && cmd[j] !== '"'; j++) { if (cmd[j] === '\\' && j + 1 < cmd.length) j++; word += cmd[j]; }
+      inWord = true; i = j + 1;
+    } else if (ch === '\\' && i + 1 < cmd.length) {
+      word += cmd[i + 1]; inWord = true; i += 2;
+    } else if (ch === ' ' || ch === '\t') {
+      flush(); i++;
+    } else if ('\n;|()'.includes(ch) || (ch === '&' && cmd[i + 1] !== '>')) {
+      flush(); toks.push({ kind: 'sep' }); i += (ch === '|' || ch === '&') && cmd[i + 1] === ch ? 2 : 1;
+    } else if (ch === '>' || (ch === '&' && cmd[i + 1] === '>')) {
+      if (ch === '>' && inWord && /^\d+$/.test(word)) { word = ''; inWord = false; } else flush(); // `2>`: an fd, not a word
+      i += ch === '&' ? 2 : 1;
+      if (cmd[i] === '>' || cmd[i] === '|') i++;
+      if (cmd[i] === '&') { i++; toks.push({ kind: 'redir', writes: false }); } // `>&2`: an fd dup
+      else toks.push({ kind: 'redir', writes: true });
+    } else if (ch === '<') {
+      flush(); i++;
+      while (cmd[i] === '<') i++;
+      toks.push({ kind: 'redir', writes: false });
+    } else {
+      word += ch; inWord = true; i++;
+    }
+  }
+  flush();
+  return toks;
+}
+
+const isInPlaceFlag = (a: string): boolean => a === '--in-place' || a.startsWith('--in-place=') || /^-[a-zA-Z]*i/.test(a);
+
+/** One simple command of a Bash line (`a | b && c` is three). */
+export interface BashSegment {
+  /** The command name (basename, after env assignments and wrappers like `sudo`), or ''. */
+  cmd: string;
+  /** Its arguments, and every redirection target, as written. */
+  words: string[];
+  /** The directory it runs in — a preceding `cd` in the same line is followed. */
+  dir: string;
+  /** Absolute paths it writes via redirection, `tee` or `sed -i`. */
+  writes: string[];
+}
+
+export function bashSegments(command: string, cwd: string): BashSegment[] {
+  const out: BashSegment[] = [];
+  const toks = tokenize(command);
+  let dir = cwd;
+  let seg: string[] = [];
+  let redirected: string[] = [];
+  let writes: string[] = [];
+  const endSegment = (): void => {
+    let k = 0;
+    while (k < seg.length && (ASSIGNMENT.test(seg[k]) || WRAPPERS.has(seg[k]))) k++;
+    const cmd = path.basename(seg[k] ?? '');
+    const args = seg.slice(k + 1).filter((a) => a !== '');
+    if (cmd === 'tee') writes.push(...args.filter((a) => !a.startsWith('-')).map((a) => path.resolve(dir, a)));
+    else if ((cmd === 'sed' || cmd === 'gsed') && args.some(isInPlaceFlag)) {
+      writes.push(...args.filter((a) => !a.startsWith('-')).map((a) => path.resolve(dir, a)));
+    }
+    if (cmd || redirected.length) out.push({ cmd, words: [...args, ...redirected], dir, writes });
+    if (cmd === 'cd' && args.length === 1 && !/^[-~]/.test(args[0])) dir = path.resolve(dir, args[0]);
+    seg = []; redirected = []; writes = [];
+  };
+  for (let t = 0; t < toks.length; t++) {
+    const tok = toks[t];
+    if (tok.kind === 'sep') { endSegment(); continue; }
+    if (tok.kind === 'redir') {
+      const target = toks[t + 1];
+      if (target?.kind !== 'word') continue;
+      t++;
+      redirected.push(target.value);
+      if (tok.writes && target.value && target.value !== '/dev/null' && target.value !== '-') writes.push(path.resolve(dir, target.value));
+      continue;
+    }
+    seg.push(tok.value);
+  }
+  endSegment();
+  return out;
+}
+
+/** Absolute paths the command writes via redirection, `tee` or `sed -i`, resolved against `cwd`. */
+export function bashWriteTargets(command: string, cwd: string): string[] {
+  return bashSegments(command, cwd).flatMap((s) => s.writes);
+}

package/src/hooks/claude-hook-entry.ts

@@ -0,0 +1,85 @@
+/**
+ * Claude Code → sungen hook bridge (P0.1). Three ways in, one behaviour:
+ *
+ *   node dist/hooks/claude-hook-entry.js <hook>        executed directly (`require.main` branch)
+ *   .claude/hooks/sungen-hook.cjs <hook>               the project launcher `require`s this, calls main
+ *   sungen hook <hook>                                  the hidden CLI command (debugging, dev checkouts)
+ *
+ * Reads the event JSON on stdin, runs the hook through `runHook` (toggles + fail-open), and prints
+ * the Claude Code JSON on stdout. Exit code is ALWAYS 0 and anything unexpected prints `{}`: a hook
+ * error must never block or derail a session. The payload is untrusted — it is parsed as JSON and
+ * read field by field, never executed.
+ */
+import * as path from 'path';
+import { ClaudeHookEvent, HookContext, HookInput, runHook, runHookOnUnreadableInput, toClaudeStdout } from './hook-result-contract';
+import { loadHook } from './hook-registry';
+import { hooksKilled } from './hook-toggles';
+
+/**
+ * Payloads above this are not parsed. Not a free pass either: a hook declares what an unreadable
+ * payload means (`onUnreadableInput`) — the guard asks, the advisory hooks stay quiet.
+ */
+const MAX_PAYLOAD_BYTES = 5 * 1024 * 1024;
+/** A hook whose stdin never closes still answers (as a no-op) well inside its timeout. */
+const STDIN_TIMEOUT_MS = 2000;
+
+export function parsePayload(raw: string): HookInput {
+  try {
+    const v: unknown = JSON.parse(raw);
+    return v && typeof v === 'object' && !Array.isArray(v) ? (v as HookInput) : {};
+  } catch { return {}; }
+}
+
+export function contextFor(input: HookInput, env: Record<string, string | undefined>): HookContext {
+  const cwd = typeof input.cwd === 'string' && path.isAbsolute(input.cwd) ? input.cwd : env.CLAUDE_PROJECT_DIR || process.cwd();
+  return { env, cwd };
+}
+
+/**
+ * What to print for this hook and raw payload — pure apart from the hook's own reads. `oversize`
+ * means the payload was too large to read at all.
+ */
+export function dispatch(hookName: string, raw: string, env: Record<string, string | undefined>, oversize = false): string {
+  if (hooksKilled(env)) return '{}';
+  const hook = loadHook(hookName);
+  if (!hook) return '{}';
+  if (oversize) return toClaudeStdout(hook.meta.events[0], runHookOnUnreadableInput(hook, contextFor({}, env)));
+  const input = parsePayload(raw);
+  const event = typeof input.hook_event_name === 'string' ? input.hook_event_name : hook.meta.events[0];
+  if (!hook.meta.events.includes(event as ClaudeHookEvent)) return '{}';
+  return toClaudeStdout(event, runHook(hook, input, contextFor(input, env)));
+}
+
+function readStdin(): Promise<{ raw: string; oversize: boolean }> {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) { resolve({ raw: '', oversize: false }); return; }
+    let size = 0;
+    const chunks: Buffer[] = [];
+    const done = (raw: string, oversize = false): void => {
+      clearTimeout(timer); process.stdin.removeAllListeners(); process.stdin.destroy(); resolve({ raw, oversize });
+    };
+    const timer = setTimeout(() => done(''), STDIN_TIMEOUT_MS);
+    process.stdin.on('data', (c: Buffer) => {
+      size += c.length;
+      if (size > MAX_PAYLOAD_BYTES) done('', true); else chunks.push(c);
+    });
+    process.stdin.on('end', () => done(Buffer.concat(chunks).toString('utf8')));
+    process.stdin.on('error', () => done(''));
+  });
+}
+
+/** Run one hook end to end. Resolves once stdout has flushed; never rejects. */
+export async function main(hookName: string = process.argv[2] ?? ''): Promise<void> {
+  let out = '{}';
+  try {
+    const { raw, oversize } = await readStdin();
+    out = dispatch(hookName, raw, process.env, oversize);
+  } catch { out = '{}'; }
+  await new Promise<void>((resolve) => process.stdout.write(`${out}\n`, () => resolve()));
+  process.exitCode = 0;
+}
+
+if (require.main === module) {
+  // Exit explicitly once flushed: a stray handle must not keep a hook alive into its timeout.
+  void main().then(() => process.exit(0), () => process.exit(0));
+}

package/src/hooks/claude-transcript-turn.ts

@@ -0,0 +1,96 @@
+/**
+ * What happened in the turn that just ended, read from the tail of Claude Code's transcript.
+ *
+ * The Stop hook must not nag every turn of every conversation in a sungen project — only a turn
+ * that ran sungen work and then ended without handing back. The transcript (JSONL) answers both:
+ * walk back from its end to the human prompt that opened the turn, noting sungen activity and any
+ * AskUserQuestion that came after it.
+ *
+ * The transcript is untrusted data: each line is JSON-parsed and inspected as strings. Nothing in
+ * it is ever executed.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface TurnSummary {
+  /** The turn ran sungen: a `/sungen:` prompt, a Bash call running `sungen`, a sungen skill. */
+  sungenActivity: boolean;
+  /** An AskUserQuestion came AFTER the last sungen activity — the turn already handed back. */
+  askedAfter: boolean;
+  /** The last unit a sungen call named (`--screen x`, `/sungen:create-test x`). */
+  lastUnit?: string;
+}
+
+/** Enough for any realistic turn; a transcript can be many MB and the hook has a time budget. */
+const TAIL_BYTES = 512 * 1024;
+const SUNGEN_BASH = /(?:^|[\s;&|(])(?:\S*\/)?sungen(?:\.js)?\s+[a-z]/;
+const UNIT_FLAG = /--(?:screen|flow|area|api)[= ]([\w.-]+(?:\/[\w.-]+)?)/g;
+/** `/sungen:<cmd>` typed, or as Claude Code records it; the unit argument is optional. */
+const SLASH = /\/sungen:[a-z-]+(?:(?:<\/command-name>[\s\S]*?<command-args>|[ \t]+)([\w.-]+))?/;
+
+type Block = { type?: unknown; name?: unknown; input?: unknown; text?: unknown };
+type Entry = { type?: unknown; isMeta?: unknown; message?: { role?: unknown; content?: unknown } };
+
+function readTail(file: string): string[] {
+  const fd = fs.openSync(file, 'r');
+  try {
+    const size = fs.fstatSync(fd).size;
+    const start = Math.max(0, size - TAIL_BYTES);
+    const buf = Buffer.alloc(size - start);
+    // Only the bytes actually read: a transcript truncated between fstat and read must not leave
+    // zero-filled garbage at the end of the buffer.
+    const read = fs.readSync(fd, buf, 0, buf.length, start);
+    const lines = buf.subarray(0, read).toString('utf8').split('\n');
+    return start > 0 ? lines.slice(1) : lines; // the first line of a cut tail is partial
+  } finally { fs.closeSync(fd); }
+}
+
+const lastUnitIn = (s: string): string | undefined => [...s.matchAll(UNIT_FLAG)].pop()?.[1];
+
+/** The human prompt's text, or null when this user entry is a tool result or injected meta. */
+function promptText(e: Entry): string | null {
+  if (e.type !== 'user' || e.isMeta === true || e.message?.role !== 'user') return null;
+  const c = e.message.content;
+  if (typeof c === 'string') return c;
+  if (!Array.isArray(c)) return null;
+  const text = (c as Block[]).filter((b) => b?.type === 'text' && typeof b.text === 'string').map((b) => b.text as string);
+  return text.length ? text.join('\n') : null;
+}
+
+/** Summarize the last turn, or null when the transcript cannot be read (callers fail open). */
+export function summarizeTurn(transcriptPath: unknown): TurnSummary | null {
+  if (typeof transcriptPath !== 'string' || !path.isAbsolute(transcriptPath)) return null;
+  let lines: string[];
+  try { lines = readTail(transcriptPath); } catch { return null; }
+
+  const turn: TurnSummary = { sungenActivity: false, askedAfter: false };
+  // Walking backwards, the first unit seen is the most recently named one.
+  const sawSungen = (unit?: string): void => {
+    turn.lastUnit ??= unit;
+    turn.sungenActivity = true;
+  };
+  for (let i = lines.length - 1; i >= 0; i--) {
+    let e: Entry;
+    try { e = JSON.parse(lines[i]) as Entry; } catch { continue; }
+    if (!e || typeof e !== 'object') continue;
+    const prompt = promptText(e);
+    if (prompt !== null) {
+      const m = prompt.match(SLASH);
+      if (m) sawSungen(m[1]);
+      break; // the turn starts here
+    }
+    if (e.type !== 'assistant' || !Array.isArray(e.message?.content)) continue;
+    const blocks = e.message!.content as Block[];
+    for (let j = blocks.length - 1; j >= 0; j--) {
+      const b = blocks[j];
+      if (b?.type !== 'tool_use' || !b.input || typeof b.input !== 'object') continue;
+      const input = b.input as Record<string, unknown>;
+      if (b.name === 'AskUserQuestion') { if (!turn.sungenActivity) turn.askedAfter = true; continue; }
+      const cmd = typeof input.command === 'string' ? input.command : '';
+      if (b.name === 'Bash' && SUNGEN_BASH.test(cmd)) sawSungen(lastUnitIn(cmd));
+      else if (b.name === 'SlashCommand' && cmd.includes('/sungen:')) sawSungen(cmd.match(SLASH)?.[1]);
+      else if (b.name === 'Skill' && typeof input.skill === 'string' && input.skill.startsWith('sungen')) sawSungen();
+    }
+  }
+  return turn;
+}

package/src/hooks/guard-delivery-contract-rule.ts

@@ -0,0 +1,110 @@
+/**
+ * Guard rule `delivery-contract-verdict` (phase 06, OES-12.3, DOS-14.4, takumi T4): Claude Code may
+ * not run `sungen delivery` while a delivered unit's Test Contract verdict is not `pass`.
+ *
+ *   - the verdict is REBUILT from .feature + lock + git HEAD (buildContractVerdict); the report file
+ *     is never read, so a hand-edited "pass" there is ignored
+ *   - which units: those `delivery` itself would deliver (contract-units.ts) — every candidate of an
+ *     ambiguous name, api flows included; bare `delivery`, a runner (`npx`, `pnpm dlx`, `tsx`, `node`…)
+ *     whose sungen cannot be named, or a `bash -c` / `eval` wrapper → every unit
+ *   - recognized: `sungen`, `sungen.js`, `@scope/sungen@1.2.3`, `sungen@latest`; `delivery --check`
+ *     (writes nothing) is allowed; a unit with no lock in the tree or in HEAD is skipped
+ *   - git runs with a ≈3 s timeout (the hook's own budget is 5 s); git failing while a lock exists,
+ *     or any other read error, → `ask` (onError), never a silent pass
+ *   - the command is only tokenized, never executed; unit names are matched against directories
+ *
+ * The contract module loads only when a command mentions both `sungen` (or a runner) and `delivery`,
+ * so every other Edit/Write/Bash call pays nothing for this rule.
+ */
+import * as path from 'path';
+import type { HookResult } from './hook-result-contract';
+import { bashSegments } from './bash-write-targets';
+import type { GuardRule } from './guard-rules';
+import { findSungenRoot } from './sungen-project-root';
+
+const SUNGEN = /^sungen(?:\.js)?(?:@[^/]*)?$/;
+const RUNNERS = new Set(['npx', 'pnpm', 'yarn', 'bunx', 'bun', 'npm', 'tsx', 'ts-node', 'node', 'deno']);
+/** delivery options that take a value (commander would consume the next word). */
+const VALUE_OPTS = new Set(['--env', '--format', '--approve']);
+const READ_ONLY_OPTS = new Set(['--check', '--help', '-h']);
+const WRAPPED = /\b(?:bash|sh|zsh|dash|eval|xargs)\b/;
+const MENTION = /\bsungen\b[^\n]*\bdelivery\b/;
+const GUARD_GIT_TIMEOUT_MS = 3_000;
+
+interface Invocation { dir: string; names: string[] }
+
+function namesAfter(args: string[]): string[] {
+  const names: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    if (VALUE_OPTS.has(args[i])) { i++; continue; }
+    if (!args[i].startsWith('-')) names.push(args[i]);
+  }
+  return names;
+}
+
+/**
+ * Where `delivery` sits as sungen's subcommand, or -1. Only options, and a word that may be an
+ * option's value (`--env staging`), may precede it — so `sungen --env x delivery` is caught while
+ * `sungen add --screen delivery` (a unit named delivery) is not a delivery call.
+ */
+function deliverySubcommandAt(rest: string[]): number {
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === 'delivery') return i;
+    if (rest[i].startsWith('-')) continue;
+    const prev = rest[i - 1];
+    if (prev && prev.startsWith('--') && !prev.includes('=')) continue;
+    return -1;
+  }
+  return -1;
+}
+
+/** Every `sungen delivery …` the command line would run, with the unit names it passes ([] = every unit). */
+export function deliveryInvocations(command: string, cwd: string): Invocation[] {
+  const out: Invocation[] = [];
+  for (const seg of bashSegments(command, cwd)) {
+    const words = [seg.cmd, ...seg.words];
+    const at = words.findIndex((w) => SUNGEN.test(path.basename(w)));
+    if (at >= 0) {
+      const rest = words.slice(at + 1);
+      const sub = deliverySubcommandAt(rest);
+      if (sub < 0) continue;
+      const args = rest.slice(sub + 1);
+      if (!args.some((a) => READ_ONLY_OPTS.has(a))) out.push({ dir: seg.dir, names: namesAfter(args) });
+    } else if (RUNNERS.has(seg.cmd) && seg.words.includes('delivery') && !seg.words.some((a) => READ_ONLY_OPTS.has(a))) {
+      out.push({ dir: seg.dir, names: [] });   // `tsx src/cli/index.ts delivery`, `node dist/cli/index.js delivery`
+    }
+  }
+  if (!out.length && MENTION.test(command) && WRAPPED.test(command)) out.push({ dir: cwd, names: [] });
+  return out;
+}
+
+function denyFor(blockers: Array<{ unit: string; verdict: string; headline: string }>): HookResult {
+  const lines = blockers.slice(0, 5).map((b) => `\`${b.unit}\` is ${b.verdict}: ${b.headline} — see \`sungen contract check --screen ${b.unit}\``);
+  return {
+    status: 'deny',
+    denyReason: `sungen: delivery is blocked — the Test Contract does not pass.\n${lines.join('\n')}${blockers.length > 5 ? `\n(+${blockers.length - 5} more)` : ''}\n`
+      + 'Restore the approved checks in the .feature, or ask QA to approve the change themselves on a terminal (`sungen contract approve --screen <unit>`). '
+      + 'Do not edit the lock or the report.',
+  };
+}
+
+export const deliveryContractVerdict: GuardRule = {
+  id: 'delivery-contract-verdict',
+  onError: 'ask',
+  check(call) {
+    const cmd = call.tool === 'Bash' ? call.bashCommand : undefined;
+    if (!cmd || !cmd.includes('delivery')) return null;
+    const invocations = deliveryInvocations(cmd, call.cwd);
+    if (!invocations.length) return null;
+    const units = require('../contract/contract-units') as typeof import('../contract/contract-units');
+    const { contractBlockers } = require('../contract/project-contract-blockers') as typeof import('../contract/project-contract-blockers');
+    const blockers: Array<{ unit: string; verdict: string; headline: string }> = [];
+    for (const inv of invocations) {
+      const root = findSungenRoot(inv.dir);
+      if (!root) continue;
+      const targets = inv.names.length ? inv.names.flatMap((n) => units.deliveryUnitsNamed(root, n)) : units.allContractUnits(root);
+      blockers.push(...contractBlockers(root, targets, { gitTimeoutMs: GUARD_GIT_TIMEOUT_MS }));
+    }
+    return blockers.length ? denyFor(blockers) : null;
+  },
+};

package/src/hooks/guard-protected-paths.ts

@@ -0,0 +1,71 @@
+/**
+ * Which paths the pre-tool guard protects, and how (P0.1 + review fixes H2, L5).
+ *
+ *   approval records — DENY an agent write:
+ *     qa/**\/contracts.lock.yaml
+ *     qa/decisions/<id>.yaml                       (project decisions, phase 03)
+ *     qa/<screens|flows|api[/flows]>/<unit>/decisions/<id>.yaml   (unit decisions)
+ *     .sungen/journey/<slug>.state.json            (legacy waivers and their dual-written copy, DOS-13.5)
+ *     .sungen/viewpoint-baseline.json              (the accepted viewpoint declaration)
+ *     — the CLI still writes the last two itself; the guard only judges an agent's tool calls
+ *   trace evidence — DENY an agent write (phase 08; the verdict trusts it only as far as this guard and git review):
+ *     .sungen/trace-identity/**                    (the driver's identity answers — written by the CLI)
+ *     test-results[-free]/sungen-run-record*.json  (run id + test-file hashes — written by the Playwright reporter;
+ *                                                  test-results-free/ is the free run's own outputDir, #941)
+ *   hook control — ASK before an agent write (the agent must not switch its own guard off):
+ *     qa/sungen.config.yaml · .claude/settings.json · .claude/settings.local.json ·
+ *     .claude/hooks/sungen-hook.cjs
+ *
+ * The human path for the hook-control files is editing them by hand, then `sungen update`.
+ * A `decisions/` folder anywhere else (e.g. `requirements/decisions/notes.md`) is not a record.
+ */
+import * as path from 'path';
+import { findSungenRoot } from './sungen-project-root';
+
+const LOCK = /^qa\/(?:.+\/)?contracts\.lock\.yaml$/i;
+const DECISION = /^qa\/(?:(?:screens|flows|api(?:\/flows)?)\/[^/]+\/)?decisions\/[^/]+/i;
+const APPROVAL_STATE = /^\.sungen\/(?:journey\/[^/]+\.state\.json|viewpoint-baseline\.json)$/i;
+/** Trace evidence (phase 08, DOS-14.6): the driver's identity answers and the run records. */
+const TRACE_EVIDENCE = /^(?:\.sungen\/trace-identity\/.+|test-results(?:-free)?\/sungen-run-record(?:\.[A-Za-z0-9._-]+)?\.json)$/i;
+const HOOK_CONTROL = ['qa/sungen.config.yaml', '.claude/settings.json', '.claude/settings.local.json', '.claude/hooks/sungen-hook.cjs'];
+
+/** The same paths as they appear INSIDE a command string (e.g. in `bash -c "…"` or `python -c "…"`). */
+const MENTIONS = [
+  /contracts\.lock\.yaml/i,
+  /(?:^|[^\w.-])qa\/(?:(?:screens|flows|api(?:\/flows)?)\/[^/\s'"]+\/)?decisions\//i,
+  /\.sungen\/(?:journey\/[^/\s'"]+\.state\.json|viewpoint-baseline\.json)/i,
+  /(?:^|[/\s'"=])(?:qa\/sungen\.config\.yaml|\.claude\/settings(?:\.local)?\.json|\.claude\/hooks\/sungen-hook\.cjs)/i,
+  /\.sungen\/trace-identity\//i,
+  /(?:^|[/\s'"=])sungen-run-record(?:\.[A-Za-z0-9._-]+)?\.json/i,
+];
+
+const posix = (p: string): string => p.split(path.sep).join('/');
+
+/** `abs` relative to its sungen project, when it is an approval record (lock, decision, approval state); else null. */
+export function approvalRecordPath(abs: string): string | null {
+  const root = findSungenRoot(path.dirname(abs));
+  if (!root) return null;
+  const rel = posix(path.relative(root, abs));
+  return LOCK.test(rel) || DECISION.test(rel) || APPROVAL_STATE.test(rel) ? rel : null;
+}
+
+/** `abs` relative to its sungen project, when it is a trace evidence store; else null. */
+export function traceEvidencePath(abs: string): string | null {
+  const root = findSungenRoot(path.dirname(abs));
+  if (!root) return null;
+  const rel = posix(path.relative(root, abs));
+  return TRACE_EVIDENCE.test(rel) ? rel : null;
+}
+
+/** The hook-control file `abs` is (as its project-relative name), or null. */
+export function hookControlPath(abs: string): string | null {
+  const p = posix(path.resolve(abs)).toLowerCase();
+  return HOOK_CONTROL.find((rel) => p.endsWith(`/${rel}`)) ?? null;
+}
+
+/** Does this command word name a protected path — as text, or once resolved against `dir`? */
+export function mentionsProtectedPath(word: string, dir: string): boolean {
+  if (MENTIONS.some((re) => re.test(word))) return true;
+  const abs = path.resolve(dir, word);
+  return approvalRecordPath(abs) !== null || traceEvidencePath(abs) !== null || hookControlPath(abs) !== null;
+}

package/src/hooks/guard-rules.ts

@@ -0,0 +1,98 @@
+/**
+ * The pre-tool guard's rules. Each looks at one normalized tool call and returns a decision or
+ * null; pre-tool-guard-hook.ts runs them in order (first deny wins, else first ask).
+ *
+ *   protected-approval-paths  DENY  a precise write (Edit/Write/MultiEdit, or Bash `>`, `tee`,
+ *                                   `sed -i`) to a contract lock, a decision record, approval state or
+ *                                   trace evidence (.sungen/trace-identity, test-results[-free]/sungen-run-record*)
+ *   protected-hook-control    ASK   the same writes to the files that control the hooks, so the
+ *                                   agent cannot switch its own guard off unasked
+ *   bash-protected-mention    ASK   any other Bash segment that names a protected path and does not
+ *                                   start with a read-only command (cp, mv, ln, install, rm,
+ *                                   bash -c, python -c, perl -i…)
+ *
+ * A floor, not a sandbox: a path built at runtime, a symlink, or a script file that writes without
+ * naming the path on the command line is out of reach by design. Each rule only matches strings,
+ * so each fails open (`onError: 'no-op'`); a rule that READS project state must declare `'ask'`.
+ */
+import type { HookContext, HookResult } from './hook-result-contract';
+import { bashSegments } from './bash-write-targets';
+import { approvalRecordPath, hookControlPath, mentionsProtectedPath, traceEvidencePath } from './guard-protected-paths';
+
+/** One tool call, normalized from the untrusted payload. */
+export interface GuardedCall {
+  tool: string;
+  /** Absolute target paths of a file tool (Edit/Write/MultiEdit). */
+  filePaths: string[];
+  bashCommand?: string;
+  cwd: string;
+}
+
+export interface GuardRule {
+  id: string;
+  /** What a throw inside `check` becomes: `ask` for a rule that reads state, `no-op` otherwise. */
+  onError: 'ask' | 'no-op';
+  /** A decision for this call, or null when the rule has nothing to say about it. */
+  check(call: GuardedCall, ctx: HookContext): HookResult | null;
+}
+
+/** The files a call writes precisely: a file tool's target, or Bash's `>` / `tee` / `sed -i` targets. */
+const preciseWrites = (call: GuardedCall): string[] =>
+  call.tool === 'Bash' ? bashSegments(call.bashCommand ?? '', call.cwd).flatMap((s) => s.writes) : call.filePaths;
+
+export const protectedApprovalPaths: GuardRule = {
+  id: 'protected-approval-paths',
+  onError: 'no-op',
+  check(call) {
+    const writes = preciseWrites(call);
+    const rel = writes.map(approvalRecordPath).find((r): r is string => r !== null);
+    if (rel) {
+      return {
+        status: 'deny',
+        denyReason: `sungen: \`${rel}\` is an approval record — contract locks, decisions, waivers and the accepted `
+          + 'viewpoint baseline change only through a human at a terminal, never by an agent edit. If this change is '
+          + 'intended, stop and ask the user to make it themselves.',
+      };
+    }
+    const evidence = writes.map(traceEvidencePath).find((r): r is string => r !== null);
+    return evidence ? {
+      status: 'deny',
+      denyReason: `sungen: \`${evidence}\` is trace evidence — only \`sungen contract check --trace\` / \`contract derive\` `
+        + 'and the Playwright run-record reporter write it. Re-run the free tests or the CLI instead of editing it.',
+    } : null;
+  },
+};
+
+export const protectedHookControl: GuardRule = {
+  id: 'protected-hook-control',
+  onError: 'no-op',
+  check(call) {
+    const rel = preciseWrites(call).map(hookControlPath).find((r): r is string => r !== null);
+    return rel ? {
+      status: 'ask',
+      askReason: `sungen: \`${rel}\` controls sungen's hooks and guard, so an agent does not change it on its own. `
+        + 'Allow only if you asked for exactly this change — the usual path is to edit it by hand, then run `sungen update`.',
+    } : null;
+  },
+};
+
+/** Segments that only read: they may name a protected path freely. */
+const READ_ONLY = new Set(['cat', 'ls', 'head', 'tail', 'grep', 'rg', 'wc', 'diff', 'sungen', 'sungen.js']);
+const GIT_READ_ONLY = new Set(['diff', 'log', 'show', 'status']);
+const isReadOnly = (cmd: string, words: string[]): boolean =>
+  READ_ONLY.has(cmd) || (cmd === 'git' && GIT_READ_ONLY.has(words.find((w) => !w.startsWith('-')) ?? ''));
+
+export const bashProtectedMention: GuardRule = {
+  id: 'bash-protected-mention',
+  onError: 'no-op',
+  check(call) {
+    if (call.tool !== 'Bash' || !call.bashCommand) return null;
+    const seg = bashSegments(call.bashCommand, call.cwd)
+      .find((s) => s.cmd && !isReadOnly(s.cmd, s.words) && s.words.some((w) => mentionsProtectedPath(w, s.dir)));
+    return seg ? {
+      status: 'ask',
+      askReason: `sungen: this \`${seg.cmd}\` command names a contract lock, a decision record, approval state or a hook-control file, `
+        + 'and the guard cannot tell whether it writes it. Allow only if you asked for exactly this.',
+    } : null;
+  },
+};

package/src/hooks/guard-tty-spoof-rule.ts

@@ -0,0 +1,31 @@
+/**
+ * Guard rule `tty-spoof` (phase 06, M5): ASK before an agent runs a human-confirmed sungen command
+ * through a terminal emulator.
+ *
+ * `contract approve`, `journey --waive`, `journey --decide` and `journey --signoff` refuse without a TTY (DOS-13.4), and
+ * an agent's Bash has none — unless it borrows one: `script`, `expect`, `unbuffer`, or a pty from
+ * Python/Perl/zsh. Then the prompt sees a "terminal" and a piped phrase reads as a human typing it.
+ * This rule spots the pair in the raw command (quotes included, so `bash -c "…"` and `expect -c '…'`
+ * are covered) and hands the call to the user. A floor, not a sandbox: a script file that does the
+ * same without naming either on the command line is out of reach by design. String match only, so
+ * it fails open.
+ */
+import type { GuardRule } from './guard-rules';
+
+const TTY_EMULATOR = /\b(?:script|unbuffer|expect|pty|zpty|openpty|forkpty|ptyprocess)\b/i;
+const HUMAN_GATED = /\bsungen\b[\s\S]*?\b(?:contract['",\s]+approve\b|journey\b[\s\S]*?--(?:waive|decide|signoff)\b)/i;
+
+export const ttySpoof: GuardRule = {
+  id: 'tty-spoof',
+  onError: 'no-op',
+  check(call) {
+    const cmd = call.tool === 'Bash' ? call.bashCommand : undefined;
+    if (!cmd || !TTY_EMULATOR.test(cmd) || !HUMAN_GATED.test(cmd)) return null;
+    return {
+      status: 'ask',
+      askReason: 'sungen: this runs a human-confirmed sungen action (`contract approve` / `journey --waive|--decide|--signoff`) through a terminal '
+        + 'emulator (script / expect / unbuffer / pty). Those confirmations exist so a PERSON at a terminal decides — allow only if you '
+        + 'are that person and asked for exactly this; otherwise run the command yourself in your own terminal.',
+    };
+  },
+};