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

package/src/contract/trace/trace-zip-limits.ts

@@ -0,0 +1,77 @@
+/**
+ * Limits for reading an untrusted Playwright trace.zip (DOS-14.7), and the one error every trace
+ * refusal raises. A trace is attacker-shaped input: a report can point at any file, and a zip can
+ * claim small sizes and inflate to gigabytes, so every number below is checked BEFORE inflating and
+ * again WHILE inflating (the inflater is capped at the declared size).
+ *
+ *   file size           20 MB        a real trace is ~0.6 MB per attempt, max 1.3 MB measured (phase 07)
+ *   entries            10 000
+ *   one entry           16 MB uncompressed
+ *   all entries         64 MB uncompressed   (each raisable by env: traceZipLimits)
+ *   ratio              100 : 1 per entry (a bomb is ~1000 : 1)
+ *
+ * An entry NAME is a key and nothing else: names with `..`, a leading `/`, a drive letter, a
+ * backslash or a NUL are refused outright rather than "sanitized", because nothing legitimate in a
+ * trace looks like that.
+ */
+export interface TraceZipLimits {
+  maxZipBytes: number;
+  maxEntries: number;
+  maxEntryBytes: number;
+  maxTotalBytes: number;
+  maxRatio: number;
+}
+
+const MB = 1024 * 1024;
+
+export const TRACE_ZIP_LIMITS: Readonly<TraceZipLimits> = Object.freeze({
+  maxZipBytes: 20 * MB,
+  maxEntries: 10_000,
+  maxEntryBytes: 16 * MB,
+  maxTotalBytes: 64 * MB,
+  maxRatio: 100,
+});
+
+/**
+ * The limits in force: the defaults, each raisable by env for unusually large traces —
+ * `SUNGEN_TRACE_MAX_ZIP_MB`, `SUNGEN_TRACE_MAX_ENTRY_MB`, `SUNGEN_TRACE_MAX_TOTAL_MB` (positive numbers;
+ * anything else is ignored, so a typo can never turn a cap into zero or infinity).
+ */
+export function traceZipLimits(env: Record<string, string | undefined> = process.env): TraceZipLimits {
+  const mb = (name: string, fallback: number): number => {
+    const v = Number(env[name]);
+    return Number.isFinite(v) && v > 0 && v <= 4096 ? Math.floor(v * MB) : fallback;
+  };
+  return {
+    ...TRACE_ZIP_LIMITS,
+    maxZipBytes: mb('SUNGEN_TRACE_MAX_ZIP_MB', TRACE_ZIP_LIMITS.maxZipBytes),
+    maxEntryBytes: mb('SUNGEN_TRACE_MAX_ENTRY_MB', TRACE_ZIP_LIMITS.maxEntryBytes),
+    maxTotalBytes: mb('SUNGEN_TRACE_MAX_TOTAL_MB', TRACE_ZIP_LIMITS.maxTotalBytes),
+  };
+}
+
+/**
+ * Trace format versions this reader was verified against: 8 = Playwright 1.57, 9 = 1.63, 10 = 1.64
+ * (one shared call id for a library call and its runner step; stacks keyed by that id). Anything
+ * else — a newer format included — is refused until it has been checked the same way.
+ */
+export const SUPPORTED_TRACE_VERSIONS: ReadonlySet<number> = new Set([8, 9, 10]);
+
+export type TraceRejectCode =
+  | 'zip.too-large' | 'zip.too-many-entries' | 'zip.entry-too-large' | 'zip.total-too-large' | 'zip.ratio'
+  | 'zip.entry-name' | 'zip.malformed' | 'zip.unsupported' | 'trace.version-unsupported' | 'trace.malformed';
+
+/** A trace that was refused before anything in it was trusted. `code` is stable; `message` names the cause. */
+export class TraceRejected extends Error {
+  constructor(public readonly code: TraceRejectCode, message: string) {
+    super(`${code}: ${message}`);
+    this.name = 'TraceRejected';
+  }
+}
+
+const BAD_NAME = /(^|[\\/])\.\.([\\/]|$)|^[\\/]|^[A-Za-z]:|\\|\0/;
+
+/** Refuse an entry name that could ever be mistaken for a path outside the archive. */
+export function assertSafeEntryName(name: string): void {
+  if (!name || BAD_NAME.test(name)) throw new TraceRejected('zip.entry-name', `refused entry name ${JSON.stringify(name.slice(0, 80))}`);
+}

package/src/contract/trace/trace-zip-reader.ts

@@ -0,0 +1,127 @@
+/**
+ * A synchronous, limit-enforcing zip reader for trace.zip files (DOS-14.7) on Node's own zlib —
+ * no dependency, and synchronous so the contract verdict (and the Claude Code guard that rebuilds
+ * it) stays a plain function.
+ *
+ * Only what a Playwright trace needs is accepted: STORE or DEFLATE entries, no encryption, no
+ * ZIP64, no duplicate names. Sizes come from the central directory and are checked against
+ * TRACE_ZIP_LIMITS before anything is inflated; inflation itself is capped at the declared size and
+ * the CRC is verified, so a header that lies is caught while reading, not after. Entry names are
+ * map keys — nothing here ever touches the filesystem.
+ */
+import * as zlib from 'zlib';
+import { assertSafeEntryName, TRACE_ZIP_LIMITS, TraceRejected, TraceZipLimits } from './trace-zip-limits';
+
+interface Entry { name: string; method: number; compressed: number; size: number; crc: number; localOffset: number }
+
+export interface ZipArchive {
+  names(): string[];
+  has(name: string): boolean;
+  readBuffer(name: string): Buffer;
+  readText(name: string): string;
+}
+
+const EOCD = 0x06054b50;
+const CENTRAL = 0x02014b50;
+const LOCAL = 0x04034b50;
+/** Below this, a high ratio is just a small repetitive file; the per-entry and total caps still apply. */
+const RATIO_FLOOR_BYTES = 64 * 1024;
+
+const malformed = (why: string): TraceRejected => new TraceRejected('zip.malformed', why);
+
+const CRC_TABLE = (() => {
+  const t = new Int32Array(256);
+  for (let n = 0; n < 256; n++) { let c = n; for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; t[n] = c; }
+  return t;
+})();
+function crc32(buf: Buffer): number {
+  let c = -1;
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ -1) >>> 0;
+}
+
+function findEocd(buf: Buffer): number {
+  const stop = Math.max(0, buf.length - 22 - 0xffff);
+  for (let i = buf.length - 22; i >= stop; i--) if (buf.readUInt32LE(i) === EOCD) return i;
+  throw malformed('no end-of-central-directory record (not a zip)');
+}
+
+function readEntries(buf: Buffer, limits: TraceZipLimits): Map<string, Entry> {
+  const eocd = findEocd(buf);
+  const count = buf.readUInt16LE(eocd + 10);
+  const cdOffset = buf.readUInt32LE(eocd + 16);
+  if (count === 0xffff || cdOffset === 0xffffffff) throw new TraceRejected('zip.unsupported', 'ZIP64 archives are not read');
+  if (count > limits.maxEntries) throw new TraceRejected('zip.too-many-entries', `${count} entries > ${limits.maxEntries}`);
+  const entries = new Map<string, Entry>();
+  let at = cdOffset;
+  let total = 0;
+  for (let i = 0; i < count; i++) {
+    if (buf.readUInt32LE(at) !== CENTRAL) throw malformed(`central directory entry ${i} has a bad signature`);
+    const flags = buf.readUInt16LE(at + 8);
+    const method = buf.readUInt16LE(at + 10);
+    const crc = buf.readUInt32LE(at + 16);
+    const compressed = buf.readUInt32LE(at + 20);
+    const size = buf.readUInt32LE(at + 24);
+    const nameLen = buf.readUInt16LE(at + 28);
+    const name = buf.toString('utf8', at + 46, at + 46 + nameLen);
+    const localOffset = buf.readUInt32LE(at + 42);
+    at += 46 + nameLen + buf.readUInt16LE(at + 30) + buf.readUInt16LE(at + 32);
+    assertSafeEntryName(name.replace(/\/$/, '') || name);
+    if (flags & 1) throw new TraceRejected('zip.unsupported', `${name} is encrypted`);
+    if (method !== 0 && method !== 8) throw new TraceRejected('zip.unsupported', `${name} uses compression method ${method}`);
+    if (compressed === 0xffffffff || size === 0xffffffff) throw new TraceRejected('zip.unsupported', `${name} needs ZIP64`);
+    if (name.endsWith('/')) continue;
+    if (entries.has(name)) throw malformed(`duplicate entry ${name}`);
+    if (size > limits.maxEntryBytes) throw new TraceRejected('zip.entry-too-large', `${name}: ${size} B > ${limits.maxEntryBytes}`);
+    if (size >= RATIO_FLOOR_BYTES && compressed > 0 && size / compressed > limits.maxRatio) {
+      throw new TraceRejected('zip.ratio', `${name}: ratio ${(size / compressed).toFixed(0)}:1 > ${limits.maxRatio}:1`);
+    }
+    if (size >= RATIO_FLOOR_BYTES && compressed === 0) throw new TraceRejected('zip.ratio', `${name}: ${size} B from 0 compressed bytes`);
+    total += size;
+    if (total > limits.maxTotalBytes) throw new TraceRejected('zip.total-too-large', `more than ${limits.maxTotalBytes} B uncompressed`);
+    entries.set(name, { name, method, compressed, size, crc, localOffset });
+  }
+  return entries;
+}
+
+function inflate(buf: Buffer, e: Entry): Buffer {
+  if (buf.readUInt32LE(e.localOffset) !== LOCAL) throw malformed(`${e.name}: bad local header`);
+  const start = e.localOffset + 30 + buf.readUInt16LE(e.localOffset + 26) + buf.readUInt16LE(e.localOffset + 28);
+  const data = buf.subarray(start, start + e.compressed);
+  if (data.length !== e.compressed) throw malformed(`${e.name}: truncated data`);
+  let out: Buffer;
+  if (e.method === 0) out = data;
+  else {
+    try { out = zlib.inflateRawSync(data, { maxOutputLength: Math.max(1, e.size) }); } catch (err) {
+      throw malformed(`${e.name}: inflates past its declared ${e.size} B or is corrupt (${(err as Error).message.split('\n')[0]})`);
+    }
+  }
+  if (out.length !== e.size) throw malformed(`${e.name}: ${out.length} B, header says ${e.size} B`);
+  if (crc32(out) !== e.crc) throw malformed(`${e.name}: CRC mismatch`);
+  return out;
+}
+
+/** Open a zip held in memory. Throws TraceRejected for anything outside the limits or the format. */
+export function openZip(buf: Buffer, limits: TraceZipLimits = TRACE_ZIP_LIMITS): ZipArchive {
+  if (buf.length > limits.maxZipBytes) throw new TraceRejected('zip.too-large', `${buf.length} B > ${limits.maxZipBytes}`);
+  if (buf.length < 22) throw malformed('too short to be a zip');
+  let entries: Map<string, Entry>;
+  try { entries = readEntries(buf, limits); } catch (e) {
+    if (e instanceof TraceRejected) throw e;
+    throw malformed(`unreadable zip structure (${(e as Error).message.split('\n')[0]})`);
+  }
+  const readBuffer = (name: string): Buffer => {
+    const e = entries.get(name);
+    if (!e) throw malformed(`no entry ${name}`);
+    try { return inflate(buf, e); } catch (err) {
+      if (err instanceof TraceRejected) throw err;
+      throw malformed(`${name}: ${(err as Error).message.split('\n')[0]}`);
+    }
+  };
+  return {
+    names: () => [...entries.keys()],
+    has: (name) => entries.has(name),
+    readBuffer,
+    readText: (name) => readBuffer(name).toString('utf8'),
+  };
+}

package/src/contract/verify-approval-decisions.ts

@@ -0,0 +1,64 @@
+/**
+ * Every approved lock entry must be vouched for by its decision (DOS-13.2, DOS-14.4, review M1):
+ * `qa/<kind>/<unit>/decisions/<decisionId>.yaml`, COMMITTED in git HEAD (outside git: on disk),
+ * intact (schema, id = content, entry_hash = entry), of kind `contract-approval`, whose payload lists
+ * this scenario at this hash — with exactly the opaque steps the entry says QA accepted (#923) — and
+ * whose `valid_from` is the entry's `approvedAt`. A lock line copied from elsewhere, re-pointed at
+ * another decision, backdated, or given an acceptance nobody recorded fails here — `unverified`,
+ * reported under contract.lock-uncommitted (hard).
+ *
+ * Only entries that are otherwise identical to HEAD are checked: an entry already added, changed or
+ * tampered is a hard finding on its own.
+ */
+import * as path from 'path';
+import { computeDecisionId, computeEntryHash } from '../decisions/decision-identity';
+import { DecisionEntry, storedEntryErrors } from '../decisions/decision-schema';
+import { safeYamlParse } from '../utils/safe-yaml-parse';
+import { HeadSnapshot, headFileText, posixRel, readTextOrNull } from './contract-git';
+import { sameJson } from './contract-hash';
+import { ContractLock, isHumanApproved, LockEntry } from './contract-schema';
+import type { UncommittedEntry } from './lock-vs-git-head';
+
+type Loaded = { entry: DecisionEntry } | { problem: string };
+
+function loadDecision(projectRoot: string, unitDir: string, id: string, snap: HeadSnapshot): Loaded {
+  const file = path.join(unitDir, 'decisions', `${id}.yaml`);
+  const rel = posixRel(projectRoot, file);
+  const working = readTextOrNull(file);
+  const text = snap.blobs === null ? working : headFileText(snap, rel, working);
+  if (text === null) return { problem: snap.blobs === null ? `decision ${id} does not exist` : `decision ${id} is not in git HEAD (not committed through review)` };
+  let raw: unknown;
+  try { raw = safeYamlParse(text, rel); } catch (e) { return { problem: `decision ${id} is unreadable: ${e instanceof Error ? e.message : e}` }; }
+  const errors = storedEntryErrors(raw);
+  if (errors.length) return { problem: `decision ${id} is invalid: ${errors[0]}` };
+  const entry = raw as DecisionEntry;
+  const scope = posixRel(path.join(projectRoot, 'qa'), unitDir);
+  if (entry.id !== id || computeDecisionId(entry, scope) !== id) return { problem: `decision ${id} does not hash to its id in ${scope}` };
+  if (computeEntryHash(entry) !== entry.entry_hash) return { problem: `decision ${id} was altered (entry_hash)` };
+  return { entry };
+}
+
+function mismatch(scenario: string, lockEntry: LockEntry, d: DecisionEntry): string | null {
+  if (d.kind !== 'contract-approval') return `decision ${d.id} is a ${d.kind}, not a contract-approval`;
+  const listed = Array.isArray(d.payload?.scenarios) ? d.payload!.scenarios as Array<{ id?: unknown; hash?: unknown; acceptedOpaque?: unknown }> : [];
+  const item = listed.find((s) => s && s.id === scenario && s.hash === lockEntry.hash);
+  if (!item) return `decision ${d.id} does not approve ${scenario} at hash ${lockEntry.hash}`;
+  if (!sameJson(item.acceptedOpaque ?? [], lockEntry.acceptedOpaque ?? [])) return `decision ${d.id} does not accept the opaque step(s) the lock entry of ${scenario} lists (acceptedOpaque)`;
+  if (Date.parse(lockEntry.approvedAt) !== Date.parse(d.valid_from)) return `approvedAt ${lockEntry.approvedAt} is not decision ${d.id}'s valid_from ${d.valid_from}`;
+  return null;
+}
+
+export function unverifiedApprovals(
+  projectRoot: string, unitDir: string, lock: ContractLock | null, skip: ReadonlySet<string>, snap: HeadSnapshot,
+): UncommittedEntry[] {
+  const cache = new Map<string, Loaded>();
+  const out: UncommittedEntry[] = [];
+  for (const [id, entry] of Object.entries(lock?.scenarios ?? {})) {
+    if (!isHumanApproved(entry) || skip.has(id)) continue;
+    if (!cache.has(entry.decisionId)) cache.set(entry.decisionId, loadDecision(projectRoot, unitDir, entry.decisionId, snap));
+    const loaded = cache.get(entry.decisionId)!;
+    const problem = 'problem' in loaded ? loaded.problem : mismatch(id, entry, loaded.entry);
+    if (problem) out.push({ id, change: 'unverified', detail: problem });
+  }
+  return out;
+}

package/src/decisions/append-decision.ts

@@ -0,0 +1,35 @@
+/**
+ * Append one decision: one file per entry, named by its content id, created exclusively
+ * (DOS-13.1, red-team #13). The file appears complete or not at all (createFileExclusive), so two
+ * writers can race freely: same content → same name → the second sees "already recorded"; different
+ * content → different names → both land. Nothing is sequential, so nothing can collide.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { createFileExclusive } from './exclusive-file-create';
+import { DecisionDraft, DecisionEntry, draftErrors } from './decision-schema';
+import { sealDecision } from './decision-identity';
+import { decisionsDirFor, serializeDecision, verifyDecisionFile } from './decision-file';
+
+export interface AppendResult { status: 'created' | 'already-recorded'; entry: DecisionEntry; path: string }
+
+export class DecisionConflictError extends Error {
+  constructor(public readonly path: string, detail: string) {
+    super(`${path} already exists but does not verify (${detail}). Restore it from git; record a new entry instead.`);
+    this.name = 'DecisionConflictError';
+  }
+}
+
+export function appendDecision(projectRoot: string, scope: string, draft: DecisionDraft): AppendResult {
+  const errors = draftErrors(draft as unknown as Record<string, unknown>);
+  if (errors.length) throw new Error(`invalid decision: ${errors.join('; ')}`);
+  const dir = decisionsDirFor(projectRoot, scope);
+  const entry = sealDecision(draft, scope);
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, `${entry.id}.yaml`);
+  if (createFileExclusive(file, serializeDecision(entry))) return { status: 'created', entry, path: file };
+
+  const existing = verifyDecisionFile(file, scope);
+  if (existing.entry) return { status: 'already-recorded', entry: existing.entry, path: file };
+  throw new DecisionConflictError(file, `${existing.problem?.code}: ${existing.problem?.message}`);
+}

package/src/decisions/confirmed-decision-commands.ts

@@ -0,0 +1,149 @@
+/**
+ * The journey CLI's human-gated actions (DOS-13.4), with the terminal passed in so the exact code the
+ * CLI runs on process.stdin/stderr is the code a test drives with a simulated TTY.
+ *
+ *   waive      `sungen journey --screen <u> --waive <OB> --reason …`                         phrase: the obligation id
+ *   signoff    `sungen journey --screen <u> --signoff [--by <name>]`                          phrase: SIGN-OFF (review W3)
+ *   decide     `sungen journey [--screen <u>] --decide <kind> --text … --reason … [--anchor …]` phrase: the kind
+ *   migration  a leftover write-ahead sentinel → REVERT or KEEP                                 (takumi T6)
+ *
+ * Everything that can be validated is validated BEFORE the prompt, so a human never confirms
+ * something that is then rejected — for a gate-override that includes the override rules (OES-11.3:
+ * soft rule, warning|info|off, `off` only where allowed, one unit or a glob in one kind, reason ≥ 15).
+ * `humanAccepted: true` is added to a gate-override's payload only AFTER the typed confirmation
+ * (takumi T5: present means effective) and can never be supplied through --payload.
+ * Without a TTY each refuses and prints the exact command.
+ */
+import * as path from 'path';
+import { assertNoPendingMigration, pendingMigrationState, PendingMigration, readPendingMigration, resolvePendingMigration, sentinelPath } from '../basis/migration-sentinel';
+import { parseAnchorId } from '../basis/anchor-grammar';
+import { assertCanSignOff, assertWaivable, JourneyReport, runJourney, signoff, signoffSigner, waive } from '../harness/journey';
+import { reportSlug } from '../harness/unit-paths';
+import { appendDecision, AppendResult } from './append-decision';
+import { PROJECT_SCOPE, unitDecisionScope } from './decision-file';
+import { DecisionDraft, DecisionKind, draftErrors, JsonValue } from './decision-schema';
+import { gitUserName } from './decision-source';
+import { askMigrationChoice, ConfirmationIO, formatCommand, requireInteractive, requireTypedConfirmation } from './human-confirmation';
+import { readDecisions } from './read-decisions';
+import { overridePayloadErrors } from '../harness/gates/gate-override-validation';
+
+export interface WaiveInput { projectRoot: string; unit: string; obligation: string; reason: string; io: ConfirmationIO }
+
+export async function waiveWithConfirmation(i: WaiveInput): Promise<JourneyReport> {
+  if (!i.reason || !i.reason.trim()) throw new Error('A reason is required to waive (anti-amnesia: a waiver must record WHY). Use --reason "...".');
+  assertWaivable(runJourney(i.projectRoot, i.unit), i.unit, i.obligation);
+  await requireTypedConfirmation({
+    what: `waive ${i.obligation} for ${i.unit}`,
+    phrase: i.obligation,
+    command: formatCommand(['sungen', 'journey', '--screen', i.unit, '--waive', i.obligation, '--reason', i.reason]),
+    summary: [`reason: ${i.reason.trim()}`, `recorded by: ${gitUserName(i.projectRoot)}`, 'it stops counting as soon as the audit changes (re-decide then)'],
+    io: i.io,
+  });
+  return waive(i.projectRoot, i.unit, i.obligation, i.reason);
+}
+
+export interface SignoffInput { projectRoot: string; unit: string; by?: string; io: ConfirmationIO }
+
+/**
+ * The single human gate (DOS §3.4, S5), typed by a person on a terminal: the gate suggests it, so an
+ * agent must not be able to give it. Refused before the prompt when the board cannot be signed off.
+ */
+export async function signoffWithConfirmation(i: SignoffInput): Promise<JourneyReport> {
+  const what = `sign off ${i.unit} (the single human gate before delivery)`;
+  const command = formatCommand(['sungen', 'journey', '--screen', i.unit, '--signoff', ...(i.by ? ['--by', i.by] : [])]);
+  requireInteractive(i.io, what, command);   // before the board is read: a refused sign-off writes nothing
+  const { signer, gitUser } = signoffSigner(i.projectRoot, i.unit, i.by);   // nobody to name → refused, no prompt
+  const before = runJourney(i.projectRoot, i.unit);
+  assertCanSignOff(before);
+  await requireTypedConfirmation({
+    what, phrase: 'SIGN-OFF', command,
+    summary: [`by: ${signer}${signer !== gitUser ? ` (recorded by git user ${gitUser})` : ''}`, `${before.needsYou.length} item(s) in the review queue — you have reviewed them`, 'it goes stale as soon as the audit changes (sign off again then)'],
+    io: i.io,
+  });
+  return signoff(i.projectRoot, i.unit, i.by);
+}
+
+/** Kinds `--decide` records. The others have a command of their own that computes their payload. */
+export const DECIDE_KINDS: readonly DecisionKind[] = ['gate-override', 'clarification'];
+const OWN_COMMAND: Partial<Record<DecisionKind, string>> = {
+  waiver: 'use `sungen journey --screen <unit> --waive <OB-id> --reason "..."`',
+  'contract-approval': 'it is recorded by `sungen contract approve`',
+  'viewpoint-acceptance': 'it is recorded by `sungen audit --accept-viewpoint`',
+};
+
+export interface DecideInput {
+  projectRoot: string; unit?: string; kind: string; text?: string; reason?: string; anchors?: string[];
+  payload?: string; visibility?: string; supersedes?: string; io: ConfirmationIO;
+}
+
+function decideDraft(i: DecideInput): { scope: string; draft: DecisionDraft } {
+  const kind = i.kind as DecisionKind;
+  if (!DECIDE_KINDS.includes(kind)) {
+    throw new Error(`--decide ${i.kind}: ${OWN_COMMAND[kind] ?? `kind must be one of ${DECIDE_KINDS.join(', ')}`}.`);
+  }
+  const errors: string[] = [];
+  const anchors = i.anchors ?? [];
+  for (const a of anchors) if (!parseAnchorId(a)) errors.push(`--anchor "${a}" is not a spec anchor (SPEC-ID#A-2, SPEC-ID#A-2/val or sec-<slug>)`);
+  let payload: Record<string, JsonValue> | undefined;
+  if (i.payload !== undefined) {
+    try {
+      const p = JSON.parse(i.payload);
+      if (p && typeof p === 'object' && !Array.isArray(p)) payload = p; else errors.push('--payload must be a JSON object');
+    } catch { errors.push('--payload is not valid JSON'); }
+  }
+  const scope = i.unit ? unitDecisionScope(i.projectRoot, i.unit) : PROJECT_SCOPE;
+  if (!scope) errors.push(`--screen ${i.unit} does not name exactly one unit under qa/screens, qa/flows or qa/api`);
+  if (kind === 'gate-override') {
+    if (payload && 'humanAccepted' in payload) errors.push('--payload must not carry humanAccepted — the terminal confirmation sets it');
+    else if (!payload) errors.push('--payload is required for a gate-override: {"rule","severity","scope"}');
+    else if (scope) errors.push(...overridePayloadErrors(payload, i.reason ?? '', scope).map((e) => `gate-override: ${e}`));
+  }
+  if (scope && i.supersedes && !readDecisions(i.projectRoot, scope).entries.some((e) => e.id === i.supersedes)) {
+    errors.push(`--supersedes ${i.supersedes} names no decision in ${scope === PROJECT_SCOPE ? 'qa/decisions' : `qa/${scope}/decisions`}`);
+  }
+  const draft = {
+    kind, anchors, text: i.text ?? '', reason: i.reason ?? '', ...(payload ? { payload } : {}),
+    source: { by: gitUserName(i.projectRoot), where: 'cli' }, valid_from: new Date().toISOString(),
+    ...(i.supersedes ? { supersedes: i.supersedes } : {}), visibility: (i.visibility ?? 'internal') as DecisionDraft['visibility'],
+  };
+  errors.push(...draftErrors(draft as unknown as Record<string, unknown>).map((e) => e.replace(/^text /, '--text ').replace(/^reason /, '--reason ')));
+  if (errors.length) throw new Error(`Cannot record the decision:\n  - ${errors.join('\n  - ')}`);
+  return { scope, draft };
+}
+
+export async function decideWithConfirmation(i: DecideInput): Promise<AppendResult> {
+  const { scope, draft } = decideDraft(i);
+  const argv = ['sungen', 'journey', ...(i.unit ? ['--screen', i.unit] : []), '--decide', draft.kind, '--text', draft.text, '--reason', draft.reason,
+    ...draft.anchors.flatMap((a) => ['--anchor', a]), ...(i.payload !== undefined ? ['--payload', i.payload] : []),
+    ...(draft.visibility !== 'internal' ? ['--visibility', draft.visibility] : []), ...(draft.supersedes ? ['--supersedes', draft.supersedes] : [])];
+  await requireTypedConfirmation({
+    what: `record a ${draft.kind} decision in ${scope === PROJECT_SCOPE ? 'qa/decisions' : `qa/${scope}/decisions`}`,
+    phrase: draft.kind,
+    command: formatCommand(argv),
+    summary: [`text: ${draft.text}`, `reason: ${draft.reason}`, ...(draft.anchors.length ? [`anchors: ${draft.anchors.join(', ')}`] : []),
+      ...(draft.payload ? [`payload: ${JSON.stringify(draft.payload)}`] : []), `visibility: ${draft.visibility}`, `recorded by: ${draft.source.by}`],
+    io: i.io,
+  });
+  // Present means effective (T5): only now, after a human typed the phrase, is the override accepted.
+  const confirmed = draft.kind === 'gate-override' ? { ...draft, payload: { ...draft.payload, humanAccepted: true } } : draft;
+  return appendDecision(i.projectRoot, scope, confirmed);
+}
+
+function assertNotInProgress(projectRoot: string, slug: string, pending: PendingMigration & { readable: boolean }): void {
+  if (pendingMigrationState(pending) === 'in-progress') assertNoPendingMigration(projectRoot, slug);   // throws MigrationInProgressError
+}
+
+/** A sentinel left by a killed migration: ask REVERT/KEEP on a TTY, refuse without one. null = none pending. */
+export async function answerPendingMigration(projectRoot: string, unit: string, io: ConfirmationIO): Promise<string[] | null> {
+  const slug = reportSlug(unit);
+  const pending = readPendingMigration(projectRoot, slug);
+  if (!pending) return null;
+  assertNotInProgress(projectRoot, slug, pending);   // another run migrating now: "retry", never a prompt
+  const files = pending.files.map((f) => `    ${f.existed ? 'restore' : 'remove '} ${f.path}`).join('\n');
+  const choice = await askMigrationChoice({
+    detail: `An interrupted migration left ${path.relative(projectRoot, sentinelPath(projectRoot, slug))} (started ${pending.startedAt}: ${pending.reason}).\n${files}`,
+    command: formatCommand(['sungen', 'journey', '--screen', unit]),
+    io,
+  });
+  return resolvePendingMigration(projectRoot, slug, choice);
+}

package/src/decisions/decision-file.ts

@@ -0,0 +1,93 @@
+/**
+ * Where decisions live and how one file reads and writes (DOS-13.1, DOS-3.9).
+ *
+ *   project scope   qa/decisions/<id>.yaml
+ *   unit scope      qa/<kind>/<unit>/decisions/<id>.yaml     scope = `<kind>/<unit>` (e.g. `screens/login`)
+ *
+ * The scope is not stored in the entry: it is where the file lives, and it is part of the id, so a
+ * file moved to another unit no longer matches its own id.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { stringify } from 'yaml';
+import { resolveUnitCandidates } from '../cli/resolve-unit';
+import { safeYamlParse } from '../utils/safe-yaml-parse';
+import { DecisionEntry, storedEntryErrors } from './decision-schema';
+import { computeDecisionId, computeEntryHash } from './decision-identity';
+
+export const PROJECT_SCOPE = 'project';
+/** A decision file's path (`/`-separated, relative to the project): `…/decisions/<name>.yaml`. One test for every reader. */
+export const DECISION_FILE_PATH = /(^|\/)decisions\/[^/]+\.yaml$/;
+const UNIT_SCOPE_RE = /^(?:(?:screens|flows|api)\/(?!\.\.?$)[^/\\]+|api\/flows\/(?!\.\.?$)[^/\\]+)$/;
+
+export function isValidScope(scope: string): boolean {
+  return scope === PROJECT_SCOPE || UNIT_SCOPE_RE.test(scope);
+}
+
+export function decisionsDirFor(projectRoot: string, scope: string): string {
+  if (!isValidScope(scope)) throw new Error(`invalid decision scope "${scope}" (project, or <screens|flows|api>/<unit>)`);
+  return scope === PROJECT_SCOPE
+    ? path.join(projectRoot, 'qa', 'decisions')
+    : path.join(projectRoot, 'qa', ...scope.split('/'), 'decisions');
+}
+
+/** The unit scope for a unit name, or null when the name matches no unit or more than one. */
+export function unitDecisionScope(projectRoot: string, unit: string): string | null {
+  const found = resolveUnitCandidates(unit, projectRoot);
+  if (found.length !== 1) return null;
+  const scope = path.relative(path.join(projectRoot, 'qa'), found[0].dir).split(path.sep).join('/');
+  return isValidScope(scope) ? scope : null;
+}
+
+/** Every decisions directory that exists, with its scope. */
+export function listDecisionDirs(projectRoot: string): { scope: string; dir: string }[] {
+  const qa = path.join(projectRoot, 'qa');
+  const out: { scope: string; dir: string }[] = [];
+  const add = (scope: string): void => {
+    const dir = decisionsDirFor(projectRoot, scope);
+    if (fs.existsSync(dir)) out.push({ scope, dir });
+  };
+  add(PROJECT_SCOPE);
+  const units = (rel: string): string[] => {
+    try {
+      return fs.readdirSync(path.join(qa, rel), { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+    } catch { return []; }
+  };
+  for (const kind of ['screens', 'flows', 'api']) {
+    for (const u of units(kind)) if (!(kind === 'api' && u === 'flows')) add(`${kind}/${u}`);
+  }
+  for (const u of units('api/flows')) add(`api/flows/${u}`);
+  return out;
+}
+
+export function serializeDecision(entry: DecisionEntry): string {
+  const head = '# Sungen decision — append-only. To change it, record a new entry with `supersedes`.\n';
+  return head + stringify(entry, { schema: 'core', lineWidth: 0 });
+}
+
+/** `untrusted`: legacy approval state that differs from git HEAD (viewpoint-baseline adapter). */
+export type DecisionProblemCode = 'unreadable' | 'invalid' | 'id-mismatch' | 'hash-mismatch' | 'untrusted';
+export interface DecisionProblem { path: string; code: DecisionProblemCode; message: string }
+
+/**
+ * Read one decision file and verify it against itself: schema, file name = id, id = content
+ * (else `id-mismatch` → decision.id-reuse), entry_hash = entry (else `hash-mismatch` → decision.mutated).
+ * Never throws — a bad file is a problem, and the caller decides what that means.
+ */
+export function verifyDecisionFile(file: string, scope: string): { entry?: DecisionEntry; problem?: DecisionProblem } {
+  const fail = (code: DecisionProblemCode, message: string) => ({ problem: { path: file, code, message } });
+  let raw: unknown;
+  try {
+    raw = safeYamlParse(fs.readFileSync(file, 'utf8'), file);
+  } catch (err) {
+    return fail('unreadable', err instanceof Error ? err.message : String(err));
+  }
+  const errors = storedEntryErrors(raw);
+  if (errors.length) return fail('invalid', errors.join('; '));
+  const entry = raw as DecisionEntry;
+  if (path.basename(file) !== `${entry.id}.yaml`) return fail('id-mismatch', `file name does not match its id ${entry.id}`);
+  const id = computeDecisionId(entry, scope);
+  if (id !== entry.id) return fail('id-mismatch', `stored id ${entry.id} but the content (in scope ${scope}) hashes to ${id}`);
+  if (computeEntryHash(entry) !== entry.entry_hash) return fail('hash-mismatch', 'entry_hash no longer matches the entry');
+  return { entry };
+}

package/src/decisions/decision-identity.ts

@@ -0,0 +1,73 @@
+/**
+ * Decision identity (DOS-13.2). Two hashes answer two different questions:
+ *
+ *   id         = `D-` + first 16 hex of sha256(normalized content)
+ *                content = {kind, scope, anchors (sorted), text, reason, payload, supersedes, visibility,
+ *                evidence_hash}; excludes valid_from, source, id, entry_hash
+ *                → "what was decided, where": re-recording it later, by anyone, yields the same id
+ *   entry_hash = full sha256 of the whole stored entry in canonical form (id, valid_from, source included)
+ *                → "was this file altered": changing any field, even the date, breaks it
+ *
+ * Canonical form: keys sorted, strings NFC with LF line ends and trimmed, absent fields omitted
+ * (`null` in the id content so its key set is fixed). The stored entry IS the normalized form, so a
+ * hash over the parsed file equals a hash over what was sealed.
+ */
+import { createHash } from 'crypto';
+import { DecisionDraft, DecisionEntry, JsonValue } from './decision-schema';
+
+const normText = (s: string): string => s.normalize('NFC').replace(/\r\n?/g, '\n').trim();
+
+export function canonicalize(v: unknown): unknown {
+  if (typeof v === 'string') return normText(v);
+  if (Array.isArray(v)) return v.map(canonicalize);
+  if (v && typeof v === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const k of Object.keys(v).sort()) {
+      const x = (v as Record<string, unknown>)[k];
+      if (x !== undefined) out[k] = canonicalize(x);
+    }
+    return out;
+  }
+  return v;
+}
+
+export const canonicalJson = (v: unknown): string => JSON.stringify(canonicalize(v));
+const sha256 = (s: string): string => createHash('sha256').update(s).digest('hex');
+
+/** The draft as it is stored: normalized strings, sorted anchors, absent optionals dropped. */
+export function normalizeDraft(d: DecisionDraft): DecisionDraft {
+  const out: DecisionDraft = {
+    kind: d.kind,
+    anchors: d.anchors.map(normText).sort(),
+    text: normText(d.text),
+    reason: normText(d.reason),
+    ...(d.payload !== undefined ? { payload: canonicalize(d.payload) as Record<string, JsonValue> } : {}),
+    source: { by: normText(d.source.by), where: normText(d.source.where) },
+    valid_from: normText(d.valid_from),
+    ...(d.supersedes !== undefined ? { supersedes: normText(d.supersedes) } : {}),
+    visibility: d.visibility,
+    ...(d.evidence_hash !== undefined ? { evidence_hash: normText(d.evidence_hash) } : {}),
+  };
+  return out;
+}
+
+export function computeDecisionId(d: DecisionDraft, scope: string): string {
+  const n = normalizeDraft(d);
+  const content = {
+    kind: n.kind, scope, anchors: n.anchors, text: n.text, reason: n.reason, payload: n.payload ?? null,
+    supersedes: n.supersedes ?? null, visibility: n.visibility, evidence_hash: n.evidence_hash ?? null,
+  };
+  return `D-${sha256(canonicalJson(content)).slice(0, 16)}`;
+}
+
+export function computeEntryHash(entry: Omit<DecisionEntry, 'entry_hash'> & { entry_hash?: string }): string {
+  const { entry_hash: _ignored, ...rest } = entry;
+  return sha256(canonicalJson(rest));
+}
+
+/** Normalize a draft and give it its id and entry_hash, fields in storage order. */
+export function sealDecision(d: DecisionDraft, scope: string): DecisionEntry {
+  const n = normalizeDraft(d);
+  const withId = { id: computeDecisionId(n, scope), ...n };
+  return { ...withId, entry_hash: computeEntryHash(withId) };
+}