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

package/src/contract/trace/trace-freshness.ts

@@ -0,0 +1,110 @@
+/**
+ * Is a trace newer than the contract it is asked to prove? (DOS-14.6: a trace older than the
+ * `.feature` or the lock is refused.) Judged by CONTENT, never by file time alone (#967): a `touch`,
+ * a checkout or a fresh clone changes no byte, so it stales nothing; an edit after the run always does.
+ *
+ *   schema 2 record   the reporter hashed every `.feature` and `contracts.lock.yaml` under `qa/` when
+ *                     the run started. Each of the unit's contract files must hash NOW to what the run
+ *                     saw: one that changed since, or did not exist yet, is newer than the trace → stale
+ *   schema 1 record   an older reporter recorded no content, so the files are dated against the run's
+ *                     start (the record's `startedAt`): one last written before it is older than the run;
+ *                     one written after it still is when git holds it unchanged and the commit that last
+ *                     changed it is an ancestor of HEAD committed before the run started (its bytes ARE
+ *                     that commit's). Anything else — edited, uncommitted, untracked, committed after the
+ *                     run started, no git, git failed or slow — is stale: fail closed.
+ *
+ * Limit of the schema-1 path: a commit time is what the committer's clock (or GIT_COMMITTER_DATE) said,
+ * so a backdated commit passes the time check — time-based checks cannot see through that. Schema 2
+ * compares content and retires this path: re-running the free tests once with the current reporter is
+ * the remedy.
+ */
+import { execFileSync } from 'child_process';
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { lockPathFor } from '../contracts-lock-file';
+import { contractFeatureFiles } from '../normalize-feature-steps';
+import type { RunRecord } from './trace-run-record';
+
+interface ContractFile { rel: string; sha: string; mtimeMs: number }
+interface LastCommit { sha: string; ms: number }
+/** A unit's contract as it is NOW — its `.feature` files and lock, read once per verdict. */
+export interface UnitContract {
+  projectRoot: string;
+  files: ContractFile[];
+  /** Schema 1 only, asked of git at most once: project path → the last commit that changed each file git holds unchanged. */
+  committed?: Map<string, LastCommit> | null;
+  /** Schema 1 only: commit → is it an ancestor of HEAD (asked once per commit). */
+  ancestors?: Map<string, boolean>;
+}
+
+/** Inside the Claude Code guard too: a slow git leaves a schema-1 trace stale rather than the hook waiting. */
+const GIT_TIMEOUT_MS = 2_000;
+const posix = (p: string): string => p.split(path.sep).join('/');
+
+export function unitContract(projectRoot: string, unit: { name: string; dir: string }): UnitContract {
+  const root = path.resolve(projectRoot);
+  const lock = path.resolve(lockPathFor(unit.dir));
+  const files = [...(fs.existsSync(lock) ? [lock] : []), ...contractFeatureFiles(unit.dir, unit.name)].map((abs) => {
+    let sha = 'unreadable';   // never equal to a recorded sha256: an unreadable contract file is stale
+    let mtimeMs = Number.POSITIVE_INFINITY;
+    try { sha = createHash('sha256').update(fs.readFileSync(abs)).digest('hex'); mtimeMs = fs.statSync(abs).mtimeMs; } catch { /* stale */ }
+    return { rel: posix(path.relative(root, abs)), sha, mtimeMs };
+  });
+  return { projectRoot: root, files };
+}
+
+function git(cwd: string, args: string[]): string | null {
+  try { return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 }).toString('utf8'); } catch { return null; }
+}
+
+/**
+ * Each contract file git holds unchanged → the last commit (first-parent history, merges included)
+ * that changed it, with its committer time. Two git calls for the whole unit; null when git cannot say.
+ * Paths are passed as literal pathspecs: no glob or `:(magic)` reading of a unit's file names.
+ */
+function committedTimes(c: UnitContract): Map<string, LastCommit> | null {
+  if (c.committed !== undefined) return c.committed;
+  const rels = c.files.map((f) => f.rel);
+  const changed = git(c.projectRoot, ['--literal-pathspecs', 'diff', '--name-only', '--relative', '-z', 'HEAD', '--', ...rels]);
+  const log = git(c.projectRoot, ['-c', 'core.quotePath=false', '--literal-pathspecs', 'log', '--first-parent', '-m', '-n', '500', '--format=%x01%H %ct', '--name-only', '--relative', '--', ...rels]);
+  if (changed === null || log === null) return (c.committed = null);
+  const dirty = new Set(changed.split('\0').filter(Boolean));
+  const times = new Map<string, LastCommit>();
+  let at: LastCommit | null = null;
+  for (const raw of log.split('\n')) {
+    const line = raw.trim();
+    if (raw.startsWith('\x01')) {
+      const [sha, ct] = raw.slice(1).trim().split(' ');
+      at = /^[0-9a-f]{40,64}$/.test(sha ?? '') && Number(ct) > 0 ? { sha, ms: Number(ct) * 1000 } : null;
+    } else if (line && at && !times.has(line) && !dirty.has(line)) times.set(line, at);
+  }
+  return (c.committed = times);
+}
+
+/** Is `sha` an ancestor of HEAD? First-parent history says so already; asserted, never assumed. */
+function isAncestorOfHead(c: UnitContract, sha: string): boolean {
+  if (!c.ancestors) c.ancestors = new Map();
+  if (!c.ancestors.has(sha)) c.ancestors.set(sha, git(c.projectRoot, ['merge-base', '--is-ancestor', sha, 'HEAD']) !== null);
+  return c.ancestors.get(sha)!;
+}
+
+/** Why a trace bound to `record` is older than the unit's contract — null when it is not. */
+export function staleReason(c: UnitContract, record: RunRecord): string | null {
+  if (record.contract) {
+    const f = c.files.find((x) => record.contract![x.rel] !== x.sha);
+    if (!f) return null;
+    const why = record.contract[f.rel] === undefined ? 'it did not exist when the run started' : 'its content changed after the run';
+    return `the trace is older than ${f.rel}: ${why} (stale) — re-run the test`;
+  }
+  const runStart = Date.parse(record.startedAt);   // unreadable → nothing is "before the run": stale
+  const late = c.files.filter((f) => !(f.mtimeMs <= runStart));
+  if (!late.length) return null;
+  const committed = committedTimes(c);
+  const vouched = (rel: string): boolean => {
+    const last = committed?.get(rel);
+    return !!last && last.ms <= runStart && isAncestorOfHead(c, last.sha);
+  };
+  const f = late.find((x) => !vouched(x.rel));
+  return f ? `the trace is older than ${f.rel}: it was written after the run, and no commit from before the run holds its bytes (stale) — re-run the test` : null;
+}

package/src/contract/trace/trace-identity-resolution.ts

@@ -51,13 +51,16 @@ export function identityRequestsFor(trace: ParsedTrace): TraceIdentityRequest[]
 }
 
 /** Ask the driver about every not-yet-cached target of these traces; rewrite the cache. */
-export async function resolveWithDriver(projectRoot: string, traces: ParsedTrace[], resolver: TraceIdentityResolver): Promise<{ asked: number; resolver: string; blockedRequests: number }> {
+/** `keys`: every target of the given traces (cached or asked) — what the caller reports on. */
+export async function resolveWithDriver(projectRoot: string, traces: ParsedTrace[], resolver: TraceIdentityResolver): Promise<{ asked: number; resolver: string; blockedRequests: number; keys: string[] }> {
   const { cache } = readIdentityCache(projectRoot);
   // The cache is project-wide (every unit's traces): answers are only ever ADDED, never pruned here.
   const keep = new Map<string, CachedIdentity>(cache.entries);
+  const all = traces.flatMap(identityRequestsFor);
+  const keys = [...new Set(all.map((req) => req.key))];
   const requests = new Map<string, TraceIdentityRequest>();
-  for (const req of traces.flatMap(identityRequestsFor)) if (!keep.has(req.key)) requests.set(req.key, req);
-  if (!requests.size) return { asked: 0, resolver: cache.resolver, blockedRequests: 0 };
+  for (const req of all) if (!keep.has(req.key)) requests.set(req.key, req);
+  if (!requests.size) return { asked: 0, resolver: cache.resolver, blockedRequests: 0, keys };
   const answer = await resolver({ requests: [...requests.values()] });
   if (!answer || !Array.isArray(answer.results)) throw new Error('the trace identity resolver returned no results');
   if (!TRUSTED_RESOLVER.test(String(answer.resolver)) || typeof answer.browser !== 'string' || !answer.browser) {
@@ -70,5 +73,5 @@ export async function resolveWithDriver(projectRoot: string, traces: ParsedTrace
     keep.set(key, { ...rest, browser: answer.browser.slice(0, 100) });
   }
   writeIdentityCache(projectRoot, answer.resolver, keep);
-  return { asked: requests.size, resolver: String(answer.resolver), blockedRequests: Number(answer.blockedRequests) || 0 };
+  return { asked: requests.size, resolver: String(answer.resolver), blockedRequests: Number(answer.blockedRequests) || 0, keys };
 }

package/src/contract/trace/trace-run-record.ts

@@ -4,9 +4,14 @@
  * the code that produced it live, so an unknown key, a wrong type or a malformed hash means the
  * record is not trusted at all (every trace it would vouch for is unbound).
  *
- * Found by convention: `<project>/test-results/sungen-run-record*.json` (one per run or shard).
- * Playwright wipes `test-results/` at the start of every run, so a record and its traces share a
- * lifetime.
+ * Found by convention: `<project>/test-results-free/sungen-run-record*.json` — the free-test config's
+ * own outputDir (#941) — or `<project>/test-results/sungen-run-record*.json` (one per run or shard).
+ * Playwright wipes its outputDir at the start of every run, so a record and its traces share a
+ * lifetime; the free run has its own so the compiled suite's next run cannot delete its traces.
+ *
+ * Schema 2 (#967) adds `contract`: the sha256 of every `.feature` and `contracts.lock.yaml` under `qa/`
+ * when the run started — what trace freshness compares by content. Schema 1 (an older reporter) has
+ * none; its traces are dated instead (trace-freshness.ts).
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -23,21 +28,29 @@ export interface RunRecord {
   shard: string | null;
   report: string | null;
   specs: Record<string, string>;
+  /** Schema 2: project path → sha256 of each contract file at run start. null: schema 1 (no content recorded). */
+  contract: Record<string, string> | null;
   attempts: RunRecordAttempt[];
 }
 
-const TOP = new Set(['schema', 'tool', 'runId', 'startedAt', 'playwrightVersion', 'shard', 'report', 'specs', 'attempts']);
+const TOP_V1: ReadonlySet<string> = new Set(['schema', 'tool', 'runId', 'startedAt', 'playwrightVersion', 'shard', 'report', 'specs', 'attempts']);
+const TOP_V2: ReadonlySet<string> = new Set([...TOP_V1, 'contract']);
 const ATTEMPT = new Set(['testId', 'file', 'title', 'retry', 'status', 'startTime', 'duration', 'trace']);
 const SHA = /^[0-9a-f]{64}$/;
 const isObj = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
 
-export const RUN_RECORD_DIR = 'test-results';
+/** The free / impl:code run's own outputDir (the documented free-test config); compiled runs clear `test-results/`. */
+export const FREE_RUN_DIR = 'test-results-free';
+/** Where run records are read, in this order: the free run's dir, then Playwright's default (older configs). */
+export const RUN_RECORD_DIRS: readonly string[] = [FREE_RUN_DIR, 'test-results'];
 
 export function findRunRecords(projectRoot: string): string[] {
-  const dir = path.join(projectRoot, RUN_RECORD_DIR);
-  let names: string[];
-  try { names = fs.readdirSync(dir); } catch { return []; }
-  return names.filter((n) => /^sungen-run-record(?:\.[A-Za-z0-9._-]+)?\.json$/.test(n)).sort().map((n) => path.join(dir, n));
+  return RUN_RECORD_DIRS.flatMap((rel) => {
+    const dir = path.join(projectRoot, rel);
+    let names: string[];
+    try { names = fs.readdirSync(dir); } catch { return []; }
+    return names.filter((n) => /^sungen-run-record(?:\.[A-Za-z0-9._-]+)?\.json$/.test(n)).sort().map((n) => path.join(dir, n));
+  });
 }
 
 function attemptOf(raw: unknown, i: number): RunRecordAttempt {
@@ -54,21 +67,30 @@ function attemptOf(raw: unknown, i: number): RunRecordAttempt {
   return { testId, file, title, retry: retry as number, status, startTime, duration, trace: trace as RunRecordAttempt['trace'] };
 }
 
-/** Read and check one record; throws an Error naming what is wrong. */
-export function readRunRecord(file: string): RunRecord {
+/** Read and check one record (`text`: its bytes, already read once by the caller); throws an Error naming what is wrong. */
+export function readRunRecord(file: string, text?: string): RunRecord {
   let raw: unknown;
-  try { raw = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (e) { throw new Error(`not readable JSON (${(e as Error).message.split('\n')[0]})`); }
+  try { raw = JSON.parse(text ?? fs.readFileSync(file, 'utf8')); } catch (e) { throw new Error(`not readable JSON (${(e as Error).message.split('\n')[0]})`); }
   if (!isObj(raw)) throw new Error('not an object');
-  const extra = Object.keys(raw).find((k) => !TOP.has(k));
+  if (raw.tool === 'sungen-trace-run-record' && typeof raw.schema === 'number' && raw.schema > 2) {
+    // A newer driver-ui wrote it (mixed versions): say what to upgrade, not just "not a record".
+    throw new Error(`record schema ${raw.schema} is newer than this sungen — upgrade @sun-asterisk/sungen (core before or together with driver-ui)`);
+  }
+  const keys = raw.schema === 2 ? TOP_V2 : raw.schema === 1 ? TOP_V1 : null;
+  if (!keys || raw.tool !== 'sungen-trace-run-record') throw new Error('not a sungen run record (schema 1 or 2)');
+  const extra = Object.keys(raw).find((k) => !keys.has(k));
   if (extra) throw new Error(`unknown key "${extra}"`);
-  if (raw.schema !== 1 || raw.tool !== 'sungen-trace-run-record') throw new Error('not a sungen run record (schema 1)');
   if (typeof raw.runId !== 'string' || !raw.runId || typeof raw.startedAt !== 'string' || typeof raw.playwrightVersion !== 'string') throw new Error('runId, startedAt and playwrightVersion must be strings');
   if (raw.shard !== null && typeof raw.shard !== 'string') throw new Error('shard must be a string or null');
   if (raw.report !== null && typeof raw.report !== 'string') throw new Error('report must be a string or null');
   if (!isObj(raw.specs) || !Object.values(raw.specs).every((v) => typeof v === 'string' && (v === '' || SHA.test(v)))) throw new Error('specs must map files to sha256');
+  if (raw.schema === 2 && !(isObj(raw.contract) && Object.values(raw.contract).every((v) => typeof v === 'string' && SHA.test(v)))) {
+    throw new Error('contract must map contract files to sha256 (schema 2)');
+  }
   if (!Array.isArray(raw.attempts)) throw new Error('attempts must be a list');
   return {
     file, runId: raw.runId, startedAt: raw.startedAt, playwrightVersion: raw.playwrightVersion, shard: raw.shard as string | null,
-    report: raw.report as string | null, specs: raw.specs as Record<string, string>, attempts: raw.attempts.map(attemptOf),
+    report: raw.report as string | null, specs: raw.specs as Record<string, string>,
+    contract: raw.schema === 2 ? raw.contract as Record<string, string> : null, attempts: raw.attempts.map(attemptOf),
   };
 }

package/src/contract/trace/trace-steps.ts

@@ -70,7 +70,7 @@ export function traceIntentSteps(trace: ParsedTrace): IntentStep[] {
     const runner = c.stepId ? steps.get(c.stepId) : undefined;
     out.push({
       kind, method: c.method, callId: c.callId, params: c.params, group: groupOf(steps, c.stepId),
-      location: firstFrame(runner?.stack) ?? firstFrame(stacks.get(c.part)?.get(c.callNumber)),
+      location: firstFrame(runner?.stack) ?? firstFrame(stacks.get(c.part)?.get(c.callId)),
       ...(verbatim ? { verbatim } : {}), startTime: c.startTime,
     });
   }

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

@@ -50,8 +50,12 @@ export function traceZipLimits(env: Record<string, string | undefined> = process
   };
 }
 
-/** Trace format versions this reader was verified against: 8 = Playwright 1.57, 9 = 1.63. */
-export const SUPPORTED_TRACE_VERSIONS: ReadonlySet<number> = new Set([8, 9]);
+/**
+ * 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'

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

@@ -2,9 +2,10 @@
  * 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, and whose `valid_from` is the entry's `approvedAt`. A lock line copied
- * from elsewhere, re-pointed at another decision, or backdated fails here — `unverified`, reported
- * under contract.lock-uncommitted (hard).
+ * 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.
@@ -14,6 +15,7 @@ import { computeDecisionId, computeEntryHash } from '../decisions/decision-ident
 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';
 
@@ -38,8 +40,10 @@ function loadDecision(projectRoot: string, unitDir: string, id: string, snap: He
 
 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 }> : [];
-  if (!listed.some((s) => s && s.id === scenario && s.hash === lockEntry.hash)) return `decision ${d.id} does not approve ${scenario} at hash ${lockEntry.hash}`;
+  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;
 }

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

@@ -3,6 +3,7 @@
  * 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)
  *
@@ -16,13 +17,13 @@
 import * as path from 'path';
 import { assertNoPendingMigration, pendingMigrationState, PendingMigration, readPendingMigration, resolvePendingMigration, sentinelPath } from '../basis/migration-sentinel';
 import { parseAnchorId } from '../basis/anchor-grammar';
-import { JourneyReport, runJourney, waive } from '../harness/journey';
+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, requireTypedConfirmation } from './human-confirmation';
+import { askMigrationChoice, ConfirmationIO, formatCommand, requireInteractive, requireTypedConfirmation } from './human-confirmation';
 import { readDecisions } from './read-decisions';
 import { overridePayloadErrors } from '../harness/gates/gate-override-validation';
 
@@ -30,8 +31,7 @@ export interface WaiveInput { projectRoot: string; unit: string; obligation: str
 
 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 "...".');
-  const valid = runJourney(i.projectRoot, i.unit).obligations.map((o) => o.id);
-  if (!valid.includes(i.obligation)) throw new Error(`Unknown obligation "${i.obligation}". Valid: ${valid.join(', ')}`);
+  assertWaivable(runJourney(i.projectRoot, i.unit), i.unit, i.obligation);
   await requireTypedConfirmation({
     what: `waive ${i.obligation} for ${i.unit}`,
     phrase: i.obligation,
@@ -42,6 +42,27 @@ export async function waiveWithConfirmation(i: WaiveInput): Promise<JourneyRepor
   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>> = {

package/src/decisions/decision-schema.ts

@@ -8,7 +8,8 @@
  * 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.
  */
-export const DECISION_KINDS = ['waiver', 'gate-override', 'contract-approval', 'viewpoint-acceptance', 'clarification'] as const;
+/** `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 };

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

@@ -6,6 +6,7 @@
  * 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…). */
@@ -17,6 +18,49 @@ export function gitOutput(cwd: string, args: string[]): string | 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('/');

package/src/decisions/human-confirmation.ts

@@ -79,6 +79,11 @@ function refuseWithoutTty(what: string, command: string): HumanConfirmationRefus
   );
 }
 
+/** 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();
 

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

@@ -80,9 +80,13 @@ export function planWaiverSync(projectRoot: string, unit: string, slug: string,
   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 = formatCommand(['sungen', 'journey', '--screen', unit, '--waive', u.obligation, '--reason', u.waiver.reason]);
+  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}`;
 }
@@ -125,11 +129,18 @@ export function commitWaiverSync(projectRoot: string, unit: string, slug: string
   }
 }
 
-/** Record a waiver given now on the CLI; supersedes the waiver in force for that obligation, if any. */
+/**
+ * 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 && sameWaiver(asLegacyWaiver(current), w)) return { status: 'already-recorded', entry: current, path: current.path };
+  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/exporters/csv-exporter.ts

@@ -439,12 +439,12 @@ export function renderCsv(summary: ScreenSummary, rows: TestCaseRow[], specLink:
  * multi-locale delivery aggregator. Pass an empty string to force the
  * base (no suffix) variant.
  */
-export function writeCsv(cwd: string, screen: string, csvContent: string, locale?: string | null): string {
+export function writeCsv(cwd: string, screen: string, csvContent: string, locale?: string | null, opts: DeliverableFileOptions = {}): string {
   const outDir = path.join(cwd, 'qa', 'deliverables');
   if (!fs.existsSync(outDir)) {
     fs.mkdirSync(outDir, { recursive: true });
   }
-  const outPath = path.join(outDir, `${deliverableBasename(screen, locale)}.csv`);
+  const outPath = path.join(outDir, `${deliverableBasename(screen, locale, opts)}.csv`);
   fs.writeFileSync(outPath, csvContent, 'utf-8');
   return outPath;
 }
@@ -455,8 +455,16 @@ export function writeCsv(cwd: string, screen: string, csvContent: string, locale
  * locale is given (or `SUNGEN_ENV` is set and no explicit override). Pass
  * `null` / empty string to force the base variant.
  */
-export function deliverableBasename(screen: string, locale?: string | null): string {
+export function deliverableBasename(screen: string, locale?: string | null, opts: DeliverableFileOptions = {}): string {
   const effective = locale !== undefined ? locale : process.env.SUNGEN_ENV;
-  return effective ? `${screen}-testcases.${effective}` : `${screen}-testcases`;
+  return `${effective ? `${screen}-testcases.${effective}` : `${screen}-testcases`}${opts.draft ? DRAFT_MARK : ''}`;
 }
 
+/**
+ * A DRAFT render (a watermarked `--preview`) is written beside the official deliverable, never onto it
+ * (#965): `<screen>-testcases[.env].DRAFT.<ext>`. Readers of `qa/deliverables/` skip it (isDraftDeliverable).
+ */
+export interface DeliverableFileOptions { draft?: boolean }
+export const DRAFT_MARK = '.DRAFT';
+export const isDraftDeliverable = (fileName: string): boolean => /\.DRAFT\.[^.]+$/.test(fileName);
+

package/src/exporters/matrix/export.ts

@@ -169,7 +169,12 @@ export function approveMatrix(paths: MatrixTargetPaths, groupIds?: string[]): {
 
 export type MatrixFormat = 'xlsx' | 'csv' | 'both';
 
-/** Render + write the requested format(s). Caller has already enforced the gate policy. */
+/**
+ * Render + write the requested format(s). Caller has already enforced the gate policy. A draft (the
+ * matrix is not approved for official delivery: it carries the DRAFT banner) goes to its own
+ * `…-testcases.DRAFT.<ext>` and never overwrites the official file (#965); the tester's Manual results
+ * are still carried from the official workbook when it can be read.
+ */
 export async function writeMatrixDeliverables(
   paths: MatrixTargetPaths,
   model: MatrixModel,
@@ -179,23 +184,25 @@ export async function writeMatrixDeliverables(
 ): Promise<{ csvPath?: string; xlsxPath?: string; manualCarry?: ManualCarryReport }> {
   const out: { csvPath?: string; xlsxPath?: string; manualCarry?: ManualCarryReport } = {};
   const xlsx = format === 'xlsx' || format === 'both';
+  const draft = model.manifest.approvalState === 'draft';
   // Read the workbook about to be overwritten BEFORE writing anything, so the tester's Manual
   // results survive (#756) and a refusal leaves no half-written target behind.
   // A CSV-only export overwrites no workbook, so an unreadable one is no reason to refuse it — but a
   // readable one still holds the Manual results the CSV should show.
+  // A draft overwrites nothing official either, so an unreadable official workbook is no reason to refuse it.
   const prior = priorRead !== undefined ? priorRead
-    : xlsx ? await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit))
+    : xlsx && !draft ? await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit))
       : await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit)).catch(() => null);
   // Into the model first: the CSV, every cached total and roll-up, and the caller's summary
   // all read it (#891).
   applyManualCarry(model, prior);
   if (format === 'csv' || format === 'both') {
-    out.csvPath = writeCsv(paths.cwd, paths.unit, renderMatrixCsv(model));
+    out.csvPath = writeCsv(paths.cwd, paths.unit, renderMatrixCsv(model), undefined, { draft });
   }
   if (xlsx) {
     const wb = renderMatrixXlsx(model, getPackageVersion());
     out.manualCarry = carryManualResults(wb, model, prior);
-    out.xlsxPath = await writeXlsx(paths.cwd, paths.unit, wb);
+    out.xlsxPath = await writeXlsx(paths.cwd, paths.unit, wb, undefined, { draft });
   }
   return out;
 }

package/src/exporters/matrix/xlsx-cells.ts

@@ -49,7 +49,7 @@ export function draftBanner(ws: ExcelJS.Worksheet, model: MatrixModel): void {
   if (model.manifest.approvalState !== 'draft') return;
   ws.mergeCells('A5:H5');
   const c = ws.getCell('A5');
-  c.value = 'DRAFT — NOT APPROVED FOR OFFICIAL DELIVERY (review-required findings or proposed groups remain)';
+  c.value = 'DRAFT — NOT APPROVED FOR OFFICIAL DELIVERY (review-required findings, proposed groups, or an audit that does not pass)';
   c.font = { bold: true, size: 11, name: ARIAL_FONT, color: { argb: 'FFFFFFFF' } };
   c.fill = { type: 'pattern', pattern: 'solid', fgColor: DRAFT_RED };
   c.alignment = { horizontal: 'center', vertical: 'middle' };

package/src/exporters/xlsx-exporter.ts

@@ -18,7 +18,7 @@ import ExcelJS from 'exceljs';
 import JSZip from 'jszip';
 import { ApiCatalogEntry, ApiDetailRow, ScreenSummary, TestCaseRow } from './types';
 import { getPackageVersion } from './package-info';
-import { deliverableBasename } from './csv-exporter';
+import { deliverableBasename, DeliverableFileOptions } from './csv-exporter';
 import {
   extractApiCallOrder,
   extractCasesDataset,
@@ -114,8 +114,8 @@ export function buildApiDetailRows(
  * to force the base (no suffix) variant.
  */
 /** Where `writeXlsx` puts a unit's workbook — shared so a reader targets the identical file. */
-export function deliverableXlsxPath(cwd: string, screen: string, locale?: string | null): string {
-  return path.join(cwd, 'qa', 'deliverables', `${deliverableBasename(screen, locale)}.xlsx`);
+export function deliverableXlsxPath(cwd: string, screen: string, locale?: string | null, opts: DeliverableFileOptions = {}): string {
+  return path.join(cwd, 'qa', 'deliverables', `${deliverableBasename(screen, locale, opts)}.xlsx`);
 }
 
 export async function writeXlsx(
@@ -123,8 +123,9 @@ export async function writeXlsx(
   screen: string,
   wb: ExcelJS.Workbook,
   locale?: string | null,
+  opts: DeliverableFileOptions = {},
 ): Promise<string> {
-  const outPath = deliverableXlsxPath(cwd, screen, locale);
+  const outPath = deliverableXlsxPath(cwd, screen, locale, opts);
   const outDir = path.dirname(outPath);
   if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
   const buffer = await wb.xlsx.writeBuffer();