@sun-asterisk/sungen 3.2.35 → 3.3.0-alpha.10

package/src/decisions/decision-integrity-check.ts

@@ -0,0 +1,61 @@
+/**
+ * Append-only integrity of the decision layer (DOS-13.3). Emits the catalog's hard rules — it does
+ * not define severity; phase 04's resolver decides what a finding blocks.
+ *
+ *   decision.id-reuse   stored id ≠ id of the content (edited text, renamed file, moved to another scope)
+ *   decision.mutated    entry_hash ≠ entry, an unreadable entry, or an entry in `git show HEAD:` that
+ *                       was edited or deleted in the working tree — the only check a careful forger
+ *                       who recomputes both hashes cannot pass
+ *
+ * Outside git (or with no commit yet) the HEAD comparison is skipped; it never throws.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { safeYamlParse } from '../utils/safe-yaml-parse';
+import { canonicalJson } from './decision-identity';
+import { DECISION_FILE_PATH, listDecisionDirs, verifyDecisionFile } from './decision-file';
+import { gitOutput as git } from './git-head-trust';
+
+export const DECISION_INTEGRITY_RULES = { idReuse: 'decision.id-reuse', mutated: 'decision.mutated' } as const;
+export type DecisionIntegrityRule = typeof DECISION_INTEGRITY_RULES[keyof typeof DECISION_INTEGRITY_RULES];
+export interface DecisionFinding { rule: DecisionIntegrityRule; path: string; message: string }
+
+
+/** Same meaning, whatever the line endings or YAML layout: compare the parsed entries canonically. */
+function sameEntry(a: string, b: string): boolean {
+  try {
+    return canonicalJson(safeYamlParse(a)) === canonicalJson(safeYamlParse(b));
+  } catch {
+    return a.replace(/\r\n?/g, '\n') === b.replace(/\r\n?/g, '\n');
+  }
+}
+
+export function checkDecisionIntegrity(projectRoot: string): DecisionFinding[] {
+  const out = new Map<string, DecisionFinding>();
+  const add = (rule: DecisionIntegrityRule, abs: string, message: string): void => {
+    const rel = path.relative(projectRoot, abs).split(path.sep).join('/');
+    if (!out.has(`${rule} ${rel}`)) out.set(`${rule} ${rel}`, { rule, path: rel, message });
+  };
+
+  for (const { scope, dir } of listDecisionDirs(projectRoot)) {
+    let names: string[] = [];
+    try { names = fs.readdirSync(dir).filter((f) => f.endsWith('.yaml')); } catch { continue; }
+    for (const name of names) {
+      const file = path.join(dir, name);
+      const v = verifyDecisionFile(file, scope);
+      if (!v.problem) continue;
+      add(v.problem.code === 'id-mismatch' ? DECISION_INTEGRITY_RULES.idReuse : DECISION_INTEGRITY_RULES.mutated, file, v.problem.message);
+    }
+  }
+
+  const listed = git(projectRoot, ['ls-tree', '-r', '-z', '--name-only', 'HEAD', '--', 'qa']);
+  for (const rel of (listed ?? '').split('\0').filter((p) => DECISION_FILE_PATH.test(p))) {
+    const abs = path.join(projectRoot, ...rel.split('/'));
+    if (!fs.existsSync(abs)) { add(DECISION_INTEGRITY_RULES.mutated, abs, 'committed entry was deleted (append-only: supersede it instead)'); continue; }
+    const head = git(projectRoot, ['show', `HEAD:./${rel}`]);
+    if (head !== null && !sameEntry(head, fs.readFileSync(abs, 'utf8'))) {
+      add(DECISION_INTEGRITY_RULES.mutated, abs, 'committed entry was edited (append-only: record a superseding entry instead)');
+    }
+  }
+  return [...out.values()];
+}

package/src/decisions/decision-schema.ts

@@ -0,0 +1,77 @@
+/**
+ * Decision entry schema (DOS-13.2).
+ *
+ * `{id, kind, anchors[], text, reason, payload?, source:{by, where}, valid_from, supersedes?,
+ *   visibility: internal|client, evidence_hash?, entry_hash}`
+ *
+ * Validation is strict both ways: a draft is checked before it is written, and a stored entry is
+ * checked when read — an unknown key (a stored `superseded_by`, say) makes the entry invalid, because
+ * a field outside the id's content could carry meaning the id does not vouch for.
+ */
+/** `triage-classification`: a red classified by hand, `sungen triage --case --as` (#928, graph/manual-triage-decisions.ts). */
+export const DECISION_KINDS = ['waiver', 'gate-override', 'contract-approval', 'viewpoint-acceptance', 'clarification', 'triage-classification'] as const;
+export type DecisionKind = typeof DECISION_KINDS[number];
+export type DecisionVisibility = 'internal' | 'client';
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+export interface DecisionSource { by: string; where: string }
+
+export interface DecisionDraft {
+  kind: DecisionKind;
+  anchors: string[];
+  text: string;
+  reason: string;
+  payload?: Record<string, JsonValue>;
+  source: DecisionSource;
+  valid_from: string;
+  supersedes?: string;
+  visibility: DecisionVisibility;
+  evidence_hash?: string;
+}
+
+export interface DecisionEntry extends DecisionDraft { id: string; entry_hash: string }
+
+export const DECISION_ID_RE = /^D-[0-9a-f]{16}$/;
+const ENTRY_HASH_RE = /^[0-9a-f]{64}$/;
+const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
+const STORED_KEYS = new Set(['id', 'kind', 'anchors', 'text', 'reason', 'payload', 'source', 'valid_from', 'supersedes', 'visibility', 'evidence_hash', 'entry_hash']);
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const nonEmpty = (v: unknown): boolean => typeof v === 'string' && v.trim().length > 0;
+
+function isJson(v: unknown, depth = 0): boolean {
+  if (depth > 20) return false;
+  if (v === null || typeof v === 'string' || typeof v === 'boolean') return true;
+  if (typeof v === 'number') return Number.isFinite(v);
+  if (Array.isArray(v)) return v.every((x) => isJson(x, depth + 1));
+  return isObject(v) && Object.values(v).every((x) => isJson(x, depth + 1));
+}
+
+/** Errors in a draft (empty = valid). Shared by the write boundary and the stored-entry check. */
+export function draftErrors(d: Record<string, unknown>): string[] {
+  const e: string[] = [];
+  if (!DECISION_KINDS.includes(d.kind as DecisionKind)) e.push(`kind must be one of ${DECISION_KINDS.join('|')}`);
+  if (!Array.isArray(d.anchors) || !d.anchors.every(nonEmpty)) e.push('anchors must be a list of non-empty strings');
+  if (!nonEmpty(d.text)) e.push('text is required');
+  if (!nonEmpty(d.reason)) e.push('reason is required');
+  if (d.payload !== undefined && !(isObject(d.payload) && isJson(d.payload))) e.push('payload must be a JSON object');
+  const src = d.source;
+  if (!isObject(src) || typeof src.by !== 'string' || !nonEmpty(src.where) || Object.keys(src).some((k) => k !== 'by' && k !== 'where')) {
+    e.push('source must be {by, where}');
+  }
+  if (typeof d.valid_from !== 'string' || !ISO_RE.test(d.valid_from) || Number.isNaN(Date.parse(d.valid_from))) e.push('valid_from must be an ISO-8601 timestamp');
+  if (d.supersedes !== undefined && (typeof d.supersedes !== 'string' || !DECISION_ID_RE.test(d.supersedes))) e.push('supersedes must be a decision id D-<16 hex>');
+  if (d.visibility !== 'internal' && d.visibility !== 'client') e.push('visibility must be internal|client');
+  if (d.evidence_hash !== undefined && typeof d.evidence_hash !== 'string') e.push('evidence_hash must be a string');
+  return e;
+}
+
+/** A stored entry: the draft rules plus id, entry_hash and no unknown keys. */
+export function storedEntryErrors(raw: unknown): string[] {
+  if (!isObject(raw)) return ['not a mapping'];
+  const e = draftErrors(raw);
+  for (const k of Object.keys(raw)) if (!STORED_KEYS.has(k)) e.push(`unknown key "${k}"`);
+  if (typeof raw.id !== 'string' || !DECISION_ID_RE.test(raw.id)) e.push('id must be D-<16 hex>');
+  if (typeof raw.entry_hash !== 'string' || !ENTRY_HASH_RE.test(raw.entry_hash)) e.push('entry_hash must be 64 hex');
+  return e;
+}

package/src/decisions/decision-source.ts

@@ -0,0 +1,14 @@
+/**
+ * Who recorded a decision: `git config user.name` — a name, never the email (DOS-13.2, security
+ * considerations). Best-effort: no git, no name → 'unknown'.
+ */
+import { execFileSync } from 'child_process';
+
+export function gitUserName(cwd: string): string {
+  try {
+    const name = execFileSync('git', ['config', 'user.name'], { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).toString('utf8').trim();
+    return name || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}

package/src/decisions/exclusive-file-create.ts

@@ -0,0 +1,42 @@
+/**
+ * Create a file only if its name is free, and never leave it half-written (red-team #13).
+ *
+ * The bytes go to a private tmp file opened with O_EXCL, are fsynced, then hard-linked to the final
+ * name. `link` fails with EEXIST when the name is taken, so the final file appears complete or not at
+ * all. On a filesystem without hard links an O_EXCL create of the final name keeps the exclusivity.
+ * Used for decision entries (same content → same name → "already recorded") and for the migration
+ * sentinel (two migrations of one unit cannot both believe they hold it).
+ */
+import { randomBytes } from 'crypto';
+import * as fs from 'fs';
+
+const NO_HARD_LINKS = new Set(['EPERM', 'ENOTSUP', 'EOPNOTSUPP', 'ENOSYS', 'EXDEV']);
+
+/** true = created, false = the name was already taken. Any other failure throws. */
+export function createFileExclusive(file: string, text: string): boolean {
+  const tmp = `${file}.tmp-${process.pid}-${randomBytes(6).toString('hex')}`;
+  const fd = fs.openSync(tmp, 'wx');
+  try {
+    fs.writeFileSync(fd, text);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  try {
+    fs.linkSync(tmp, file);
+    return true;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code ?? '';
+    if (code === 'EEXIST') return false;
+    if (!NO_HARD_LINKS.has(code)) throw err;
+    try {
+      fs.writeFileSync(file, text, { flag: 'wx' });
+      return true;
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code === 'EEXIST') return false;
+      throw e;
+    }
+  } finally {
+    fs.rmSync(tmp, { force: true });
+  }
+}

package/src/decisions/git-head-trust.ts

@@ -0,0 +1,76 @@
+/**
+ * What git HEAD says — the trust anchor for agent-writable state (red-team #3, review H1).
+ *
+ * `.sungen/` files are written by the CLI and, without the guard, by any agent. A record in them is
+ * trusted only where it equals its committed version: a commit went through review, a local edit
+ * did not. Outside git, or for a file git does not track, nothing is trusted. Never throws.
+ */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+
+/** stdout of a git command run in `cwd`, or null when git fails (no repo, no HEAD, untracked path…). */
+export function gitOutput(cwd: string, args: string[]): string | null {
+  try {
+    return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024, timeout: 30000 }).toString('utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The text of each `<rev>:<path>` spec, read by ONE `git cat-file --batch` in `cwd` (`./path` is relative
+ * to it): null where git holds no such file; null for the whole call when git fails.
+ */
+export function gitFileTexts(cwd: string, specs: string[]): Array<string | null> | null {
+  if (specs.length === 0) return [];
+  if (specs.some((s) => /[\r\n]/.test(s))) return null;
+  let out: Buffer;
+  try {
+    out = execFileSync('git', ['cat-file', '--batch'], { cwd, input: `${specs.join('\n')}\n`, stdio: ['pipe', 'pipe', 'ignore'], maxBuffer: 256 * 1024 * 1024, timeout: 60000 });
+  } catch {
+    return null;
+  }
+  // Each answer: `<oid> <type> <size>\n<content>\n`, or `<spec> missing\n` (also `ambiguous`).
+  const texts: Array<string | null> = [];
+  let at = 0;
+  for (let i = 0; i < specs.length; i++) {
+    const eol = out.indexOf(0x0a, at);
+    if (eol < 0) return null;
+    const header = out.subarray(at, eol).toString('utf8').split(' ');
+    at = eol + 1;
+    if (header.length !== 3 || !/^\d+$/.test(header[2])) { texts.push(null); continue; }
+    const size = Number(header[2]);
+    texts.push(header[1] === 'blob' ? out.subarray(at, at + size).toString('utf8') : null);
+    at += size + 1;
+  }
+  return texts;
+}
+
+/**
+ * Whether `cwd` is in a shallow clone. git < 2.15 does not know `--is-shallow-repository` and echoes it
+ * back, so only an exact `true` / `false` is an answer; otherwise the `shallow` file in the git directory
+ * (common dir, or the git dir) decides, and when not even that can be found the clone is taken as shallow
+ * — its history is then unknown, which fails closed for the callers that ask.
+ */
+export function isShallowRepository(cwd: string): boolean {
+  const answer = gitOutput(cwd, ['rev-parse', '--is-shallow-repository'])?.trim();
+  if (answer === 'true' || answer === 'false') return answer === 'true';
+  const dirs = ['--git-common-dir', '--git-dir'].map((flag) => gitOutput(cwd, ['rev-parse', flag])?.trim())
+    .filter((d): d is string => !!d && !d.startsWith('-'));
+  return dirs.length === 0 || dirs.some((d) => fs.existsSync(path.join(path.resolve(cwd, d), 'shallow')));
+}
+
+/** The committed text of `abs` (a file inside `projectRoot`), or null when git HEAD has no such file. */
+export function committedText(projectRoot: string, abs: string): string | null {
+  const rel = path.relative(projectRoot, abs).split(path.sep).join('/');
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null;
+  return gitOutput(projectRoot, ['show', `HEAD:./${rel}`]);
+}
+
+/** The committed JSON of `abs`, or null (absent from HEAD, or not JSON). */
+export function committedJson(projectRoot: string, abs: string): unknown {
+  const text = committedText(projectRoot, abs);
+  if (text === null) return null;
+  try { return JSON.parse(text.replace(/^/, '')); } catch { return null; }
+}

package/src/decisions/human-confirmation.ts

@@ -0,0 +1,119 @@
+/**
+ * Typed human confirmation (DOS-13.4, red-team #3; review phase 03 M5).
+ *
+ * `journey --waive`, `journey --decide`, `delivery --accept-in-run` record or accept decisions that
+ * relax a gate, so a person must type a confirmation on a terminal:
+ *   - no TTY (an agent's shell, a pipe, CI) → refuse and print the exact command for a human to run;
+ *     piped stdin is not a TTY, so piping the phrase in never counts
+ *   - the prompt and the answer go through the controlling terminal (`/dev/tty`), not stdin/stderr,
+ *     so a redirected or wrapped stream neither sees nor answers it
+ *   - the phrase carries a NONCE drawn per prompt, so an answer cannot be scripted from the refusal
+ *     message: the printed command never contains it (it does not exist until the prompt is shown)
+ * This is a hard floor under Claude Code (the PreToolUse guard also denies agent writes to
+ * qa/**\/decisions/**) and a soft barrier elsewhere; git-HEAD comparison and the in-run rule remain.
+ */
+import { randomBytes } from 'crypto';
+import * as fs from 'fs';
+import * as readline from 'readline';
+import * as tty from 'tty';
+
+export interface ConfirmationIO {
+  input: NodeJS.ReadableStream & { isTTY?: boolean };
+  output: NodeJS.WritableStream;
+  /** The CLI's real terminal: prompt on `/dev/tty` (opened only when a confirmation is asked). */
+  controllingTerminal?: boolean;
+}
+
+export class HumanConfirmationRefused extends Error {
+  constructor(message: string, public readonly command?: string) {
+    super(message);
+    this.name = 'HumanConfirmationRefused';
+  }
+}
+
+/** The CLI's streams: stdin decides whether a human is there; the prompt itself uses /dev/tty. */
+export const processIO = (): ConfirmationIO => ({ input: process.stdin, output: process.stderr, controllingTerminal: true });
+export const isInteractive = (io: ConfirmationIO): boolean => io.input.isTTY === true;
+
+export function shellQuote(arg: string): string {
+  return /^[A-Za-z0-9_./:=@%+-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+export const formatCommand = (argv: string[]): string => argv.map(shellQuote).join(' ');
+
+interface Terminal { input: NodeJS.ReadableStream; output: NodeJS.WritableStream; close(): void }
+
+/** The terminal to talk to a human on, or null when there is none. */
+function openTerminal(io: ConfirmationIO): Terminal | null {
+  if (!isInteractive(io)) return null;
+  if (!io.controllingTerminal || process.platform === 'win32') return { input: io.input, output: io.output, close: () => undefined };
+  let rfd = -1;
+  let wfd = -1;
+  try {
+    rfd = fs.openSync('/dev/tty', 'r');
+    wfd = fs.openSync('/dev/tty', 'w');
+    const input = new tty.ReadStream(rfd);
+    const output = new tty.WriteStream(wfd);
+    return { input, output, close: () => { input.destroy(); output.destroy(); } };
+  } catch {
+    for (const fd of [rfd, wfd]) if (fd >= 0) { try { fs.closeSync(fd); } catch { /* already closed */ } }
+    return null;   // no controlling terminal: not a human at a keyboard
+  }
+}
+
+/** One line from the human, or null on EOF. */
+function askLine(t: Terminal, prompt: string): Promise<string | null> {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: t.input, output: t.output, terminal: false });
+    let settled = false;
+    const done = (v: string | null): void => { if (!settled) { settled = true; resolve(v); rl.close(); } };
+    rl.on('close', () => done(null));
+    rl.question(prompt, (answer) => done(answer));
+  });
+}
+
+function refuseWithoutTty(what: string, command: string): HumanConfirmationRefused {
+  return new HumanConfirmationRefused(
+    `Refused: ${what} needs a human at a terminal to type a confirmation, and this run has no TTY.\n`
+    + `  Nothing was recorded. Run this yourself in a terminal:\n    ${command}`,
+    command,
+  );
+}
+
+/** Refuse up front, before any state is read or written, when no human is at a terminal. */
+export function requireInteractive(io: ConfirmationIO, what: string, command: string): void {
+  if (!isInteractive(io)) throw refuseWithoutTty(what, command);
+}
+
+/** A fresh, hard-to-guess suffix for one prompt. */
+export const confirmationNonce = (): string => randomBytes(3).toString('hex').toUpperCase();
+
+export async function requireTypedConfirmation(opts: {
+  what: string; phrase: string; command: string; summary: string[]; io: ConfirmationIO;
+}): Promise<void> {
+  const t = openTerminal(opts.io);
+  if (!t) throw refuseWithoutTty(opts.what, opts.command);
+  try {
+    const expected = `${opts.phrase} ${confirmationNonce()}`;
+    t.output.write(`\nAbout to ${opts.what}:\n${opts.summary.map((l) => `  ${l}`).join('\n')}\n`);
+    const answer = await askLine(t, `Type "${expected}" to confirm (anything else cancels): `);
+    if ((answer ?? '').trim() !== expected) {
+      throw new HumanConfirmationRefused(`Cancelled: the confirmation did not match the phrase shown. Nothing was recorded.`, opts.command);
+    }
+  } finally {
+    t.close();
+  }
+}
+
+/** A leftover write-ahead sentinel: the human answers REVERT or KEEP. Never answered for them. */
+export async function askMigrationChoice(opts: { detail: string; command: string; io: ConfirmationIO }): Promise<'REVERT' | 'KEEP'> {
+  const t = openTerminal(opts.io);
+  if (!t) throw refuseWithoutTty('answering an interrupted migration (REVERT or KEEP)', opts.command);
+  try {
+    t.output.write(`\n${opts.detail}\n`);
+    const answer = ((await askLine(t, 'Type REVERT (restore every file it lists) or KEEP (keep the new files): ')) ?? '').trim().toUpperCase();
+    if (answer === 'REVERT' || answer === 'KEEP') return answer;
+    throw new HumanConfirmationRefused('Cancelled: answer REVERT or KEEP. Nothing was changed.', opts.command);
+  } finally {
+    t.close();
+  }
+}

package/src/decisions/legacy-waiver-migration.ts

@@ -0,0 +1,146 @@
+/**
+ * Waivers move from `.sungen/journey/<slug>.state.json` into the decision layer (DOS-13.5, red-team
+ * #2) — without laundering an agent-forged waiver into a hash-valid decision (review H1).
+ *
+ * The state file is agent-writable, so a legacy waiver is TRUSTED only when its record equals the
+ * one committed in git HEAD (a commit went through review; a local edit did not). Per obligation,
+ * with L = the legacy waiver and D = the decision in force:
+ *   L same as D                 → nothing to do (same reason against the same evidence)
+ *   L untrusted                 → not imported, not counted; needs-you says UNTRUSTED and how to confirm it
+ *   L trusted, no D             → import L (`where: migrated`, idempotent by content id)
+ *   L trusted, newer than D     → import L superseding D — an `at` in the future never counts as newer
+ *   L trusted, not newer than D → D wins; the dual-write corrects the legacy file
+ * The import runs ONCE per unit: when nothing untrusted remains, a marker is written and from then on
+ * the legacy file is only a dual-write target (so the previous CLI still reads the waivers), never a source.
+ *
+ * plan is read-only, so the board is the same whether or not the writes succeed. commit writes under
+ * the write-ahead sentinel; only an unwritable checkout is tolerated silently — a conflict is raised.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { withMigrationSentinel } from '../basis/migration-sentinel';
+import { appendDecision, AppendResult } from './append-decision';
+import { canonicalJson, computeDecisionId } from './decision-identity';
+import { decisionsDirFor, unitDecisionScope } from './decision-file';
+import { DecisionDraft } from './decision-schema';
+import { gitUserName } from './decision-source';
+import { committedJson } from './git-head-trust';
+import { formatCommand } from './human-confirmation';
+import { readDecisions } from './read-decisions';
+import { asLegacyWaiver, effectiveWaiverEntries, isLegacyWaiver, LegacyWaiver, sameWaiver, waiverDraft } from './waiver-decisions';
+
+export interface UntrustedWaiver { obligation: string; waiver: LegacyWaiver }
+
+export interface WaiverSyncPlan {
+  scope: string | null;
+  /** obligation → waiver in force (legacy shape): what the board counts. */
+  waivers: Record<string, LegacyWaiver>;
+  untrusted: UntrustedWaiver[];
+  /** What the dual-write puts back in the legacy file: legacy key order, unknown records kept verbatim. */
+  stateWaivers: Record<string, unknown>;
+  imports: DecisionDraft[];
+  /** Write the import marker on commit: nothing untrusted is left to decide. */
+  markDone: boolean;
+}
+
+export const importMarkerPath = (projectRoot: string, slug: string): string =>
+  path.join(projectRoot, '.sungen', 'migrations', `${slug}.waivers-imported.json`);
+
+const asRecord = (v: unknown): Record<string, unknown> => (v && typeof v === 'object' && !Array.isArray(v) ? v as Record<string, unknown> : {});
+const newer = (w: LegacyWaiver, validFrom: string): boolean => {
+  const at = Date.parse(w.at);
+  return at > Date.parse(validFrom) && at <= Date.now();
+};
+
+export function planWaiverSync(projectRoot: string, unit: string, slug: string, statePath: string, legacy: unknown): WaiverSyncPlan {
+  const legacyWaivers = asRecord(legacy);
+  const scope = unitDecisionScope(projectRoot, unit);
+  const inForce = scope ? effectiveWaiverEntries(readDecisions(projectRoot, scope, { kind: 'waiver' }).entries) : new Map();
+  const stateWaivers: Record<string, unknown> = { ...legacyWaivers };
+  const waivers: Record<string, LegacyWaiver> = {};
+  const untrusted: UntrustedWaiver[] = [];
+  const imports: DecisionDraft[] = [];
+
+  if (scope && fs.existsSync(importMarkerPath(projectRoot, slug))) {
+    for (const [ob, d] of inForce) stateWaivers[ob] = waivers[ob] = asLegacyWaiver(d);
+    return { scope, waivers, untrusted, stateWaivers, imports, markDone: false };
+  }
+
+  const head = asRecord(asRecord(committedJson(projectRoot, statePath)).waivers);
+  for (const [ob, w] of Object.entries(legacyWaivers)) {
+    if (!isLegacyWaiver(w)) continue;                                 // unreadable record: kept in the file, never counted
+    const d = inForce.get(ob);
+    if (d && sameWaiver(asLegacyWaiver(d), w)) { waivers[ob] = w; continue; }
+    if (!(ob in head) || canonicalJson(head[ob]) !== canonicalJson(w)) { untrusted.push({ obligation: ob, waiver: w }); continue; }
+    if (d && !newer(w, d.valid_from)) { stateWaivers[ob] = waivers[ob] = asLegacyWaiver(d); continue; }
+    if (scope) imports.push(waiverDraft(ob, w, { by: 'unknown', where: 'migrated' }, d?.id));
+    waivers[ob] = w;
+  }
+  for (const [ob, d] of inForce) if (!(ob in waivers)) stateWaivers[ob] = waivers[ob] = asLegacyWaiver(d);
+  return { scope, waivers, untrusted, stateWaivers, imports, markDone: !!scope && untrusted.length === 0 };
+}
+
+/** The command a human types to give (or confirm) a waiver — the board's line and `sungen next`'s "Waiting for you" (#954). */
+export const waiveCommand = (unit: string, obligation: string, reason: string): string =>
+  formatCommand(['sungen', 'journey', '--screen', unit, '--waive', obligation, '--reason', reason]);
+
+/** The needs-you line for a waiver that is not in git HEAD: not counted, and how a human confirms it. */
+export function untrustedWaiverText(unit: string, slug: string, title: string, u: UntrustedWaiver): string {
+  const confirm = waiveCommand(unit, u.obligation, u.waiver.reason);
+  return `⚠️ Waiver on "${title}" is UNTRUSTED — not counted (decision.in-run: it is in .sungen/journey/${slug}.state.json `
+    + `but not in git HEAD). If it is yours, confirm it on a terminal: ${confirm}`;
+}
+
+const UNWRITABLE = new Set(['EACCES', 'EROFS', 'ENOSPC', 'EPERM']);
+
+function writeFile(file: string, text: string): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text, 'utf-8');
+}
+
+/**
+ * Persist a plan: imports, the dual-written legacy file, the import marker. Returns false when the
+ * checkout cannot be written (read-only, full disk); any other failure — a decision that does not
+ * verify, a migration in progress or interrupted — is raised, never swallowed.
+ */
+export function commitWaiverSync(projectRoot: string, unit: string, slug: string, plan: WaiverSyncPlan, statePath: string, stateText: string): boolean {
+  const marker = importMarkerPath(projectRoot, slug);
+  const writeMarker = plan.markDone && !fs.existsSync(marker);
+  const markerText = (ids: string[]) => `${JSON.stringify({ schema: 1, unit, importedAt: new Date().toISOString(), imported: ids }, null, 2)}\n`;
+  try {
+    if (!plan.scope || plan.imports.length === 0) {
+      writeFile(statePath, stateText);
+      if (writeMarker) writeFile(marker, markerText([]));
+      return true;
+    }
+    const scope = plan.scope;
+    const dir = decisionsDirFor(projectRoot, scope);
+    const targets = plan.imports.map((d) => path.join(dir, `${computeDecisionId(d, scope)}.yaml`));
+    withMigrationSentinel(projectRoot, unit, slug, `import ${plan.imports.length} legacy waiver(s) into the decision layer`,
+      [statePath, ...(writeMarker ? [marker] : []), ...targets], () => {
+        const ids = plan.imports.map((d) => appendDecision(projectRoot, scope, d).entry.id);
+        writeFile(statePath, stateText);
+        if (writeMarker) writeFile(marker, markerText(ids));
+      });
+    return true;
+  } catch (err) {
+    if (UNWRITABLE.has((err as NodeJS.ErrnoException)?.code ?? '')) return false;
+    throw err;
+  }
+}
+
+/**
+ * Record a waiver given now on the CLI; supersedes the waiver in force for that obligation, if any.
+ * The same waiver again records nothing — unless the one in force was imported (`where: migrated`):
+ * re-confirming it on a terminal is how a human vouches for a migrated waiver its legacy record cannot
+ * (decision.in-run), so it always writes the `cli` decision that supersedes it (#925).
+ */
+export function recordWaiver(projectRoot: string, unit: string, obligation: string, w: LegacyWaiver): AppendResult {
+  const scope = unitDecisionScope(projectRoot, unit);
+  if (!scope) throw new Error(`Cannot record a waiver: "${unit}" does not name exactly one unit under qa/screens, qa/flows or qa/api.`);
+  const current = effectiveWaiverEntries(readDecisions(projectRoot, scope, { kind: 'waiver' }).entries).get(obligation);
+  if (current && current.source?.where !== 'migrated' && sameWaiver(asLegacyWaiver(current), w)) {
+    return { status: 'already-recorded', entry: current, path: current.path };
+  }
+  return appendDecision(projectRoot, scope, waiverDraft(obligation, w, { by: gitUserName(projectRoot), where: 'cli' }, current?.id));
+}

package/src/decisions/read-decisions.ts

@@ -0,0 +1,61 @@
+/**
+ * Read the decisions of one scope (DOS-13.1 – 13.3). Best-effort by contract: a missing directory
+ * reads as empty, a bad file becomes a `problem` — a read-only or half-broken checkout never throws.
+ *
+ * Only entries that verify against themselves take effect; an entry whose content no longer matches
+ * its id, or whose entry_hash no longer matches the entry, is reported and ignored (trust nothing
+ * written). Computed on read, never stored:
+ *   - `superseded_by` — the latest visible entry that names this one in `supersedes`
+ *   - `stale`         — with `auditHash` given: `evidence_hash ≠ auditHash` (the waiver rule, DOS-13.5)
+ * `asOf` hides entries whose `valid_from` is later, so a later superseder does not supersede yet.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { DecisionEntry, DecisionKind } from './decision-schema';
+import { DecisionProblem, decisionsDirFor, verifyDecisionFile } from './decision-file';
+
+export interface ReadDecision extends DecisionEntry {
+  scope: string;
+  path: string;
+  superseded_by?: string;
+  stale?: boolean;
+}
+
+export interface ReadDecisionsOptions { asOf?: string; auditHash?: string; kind?: DecisionKind }
+export interface ReadDecisionsResult { entries: ReadDecision[]; problems: DecisionProblem[] }
+
+const byTime = (a: DecisionEntry, b: DecisionEntry): number =>
+  Date.parse(a.valid_from) - Date.parse(b.valid_from) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
+export function readDecisions(projectRoot: string, scope: string, opts: ReadDecisionsOptions = {}): ReadDecisionsResult {
+  const problems: DecisionProblem[] = [];
+  let dir: string;
+  let names: string[];
+  try {
+    dir = decisionsDirFor(projectRoot, scope);
+    names = fs.readdirSync(dir).filter((f) => f.endsWith('.yaml')).sort();
+  } catch {
+    return { entries: [], problems };
+  }
+
+  const cutoff = opts.asOf ? Date.parse(opts.asOf) : Infinity;
+  const entries: ReadDecision[] = [];
+  for (const name of names) {
+    const file = path.join(dir, name);
+    const v = verifyDecisionFile(file, scope);
+    if (v.problem) { problems.push(v.problem); continue; }
+    if (Date.parse(v.entry.valid_from) > cutoff) continue;
+    entries.push({ ...v.entry, scope, path: file });
+  }
+  entries.sort(byTime);
+
+  const byId = new Map(entries.map((e) => [e.id, e]));
+  for (const e of entries) {
+    const target = e.supersedes ? byId.get(e.supersedes) : undefined;
+    if (target) target.superseded_by = e.id;   // ascending time: the latest superseder wins
+  }
+  if (opts.auditHash !== undefined) {
+    for (const e of entries) if (e.evidence_hash !== undefined) e.stale = e.evidence_hash !== opts.auditHash;
+  }
+  return { entries: opts.kind ? entries.filter((e) => e.kind === opts.kind) : entries, problems };
+}