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

package/src/cli/commands/delivery.ts

@@ -711,6 +711,8 @@ async function exportMatrixTarget(
   }
 
   const { model, mapMissing, mapErrors } = loadMatrixModel(paths);
+  // An audit that is untrusted or FAILs never yields an official deliverable: --preview renders a DRAFT (#935).
+  if (model && decisions?.auditDraft(qaDir(cwd, target))) model.manifest.approvalState = 'draft';
 
   if (mapMissing) {
     log(`${COLOR.yellow}${paths.label}: no delivery map${COLOR.reset} (${path.relative(cwd, paths.mapFile)})`);
@@ -1095,9 +1097,12 @@ export function registerDeliveryCommand(program: Command): void {
           // an approval are the normal state of a live project. Preflight skips are
           // not counted here: reaching this point in an explicit scope means
           // --continue-on-missing was passed, which IS the opt-in to tolerate them.
-          const failed = explicitScope
+          // --check reports like its checklist: an audit box that does not hold is a non-zero exit (#935).
+          const auditFails = (decisions?.untrustedAudits.length ?? 0) + (decisions?.failingAudits.length ?? 0);
+          if (options.check && auditFails) log(`${COLOR.red}✗ --check: ${auditFails} unit(s) whose audit does not pass — see the audit box above.${COLOR.reset}`);
+          const failed = (explicitScope
             ? notExported.length > 0
-            : matrixSummaries.length === 0;
+            : matrixSummaries.length === 0) || (!!options.check && auditFails > 0);
           if (failed) process.exit(1);
           return;
         }

package/src/cli/commands/journey.ts

@@ -1,9 +1,9 @@
 import { Command } from 'commander';
 import * as path from 'path';
-import { runJourney, signoff, renderJourneyBoard, rollupJourney, renderRollupBoard, writeJourneyFileBestEffort } from '../../harness/journey';
+import { runJourney, renderJourneyBoard, rollupJourney, renderRollupBoard, writeJourneyFileBestEffort } from '../../harness/journey';
 import { reportSlug } from '../../harness/unit-paths';
 import { findUnitDir } from '../resolve-unit';
-import { answerPendingMigration, decideWithConfirmation, DECIDE_KINDS, waiveWithConfirmation } from '../../decisions/confirmed-decision-commands';
+import { answerPendingMigration, decideWithConfirmation, DECIDE_KINDS, signoffWithConfirmation, waiveWithConfirmation } from '../../decisions/confirmed-decision-commands';
 import { processIO } from '../../decisions/human-confirmation';
 
 const collect = (value: string, previous: string[]): string[] => [...previous, value];
@@ -22,7 +22,7 @@ export function registerJourneyCommand(program: Command): void {
     .option('--payload <json>', 'Kind-specific fields as a JSON object, e.g. a gate-override\'s {"rule","severity","scope"} (with --decide)')
     .option('--visibility <v>', 'internal (default, never exported) | client (with --decide)')
     .option('--supersedes <id>', 'The decision this one replaces — the old entry is never edited (with --decide)')
-    .option('--signoff', 'Sign off the review queue — the single human gate (allowed only when every other obligation is satisfied/waived)')
+    .option('--signoff', 'Sign off the review queue — the single human gate (allowed only when every other obligation is satisfied/waived); a human types a confirmation on a TTY')
     .option('--by <name>', 'Who is signing off (recorded with --signoff)')
     .option('--json', 'Output the raw JSON report')
     .action(async (options) => {
@@ -63,7 +63,7 @@ export function registerJourneyCommand(program: Command): void {
         const report = options.waive
           ? await waiveWithConfirmation({ projectRoot: process.cwd(), unit: name, obligation: options.waive, reason: options.reason || '', io })
           : options.signoff
-            ? signoff(process.cwd(), name, options.by)
+            ? await signoffWithConfirmation({ projectRoot: process.cwd(), unit: name, by: options.by, io })
             : runJourney(process.cwd(), name);
 
         const outDir = path.join(process.cwd(), '.sungen', 'journey');

package/src/cli/commands/next.ts

@@ -20,6 +20,7 @@ import { testCaseStatusLabel } from '../../graph/test-case-satisfied';
 import { testCaseStates } from '../../graph/test-case-states';
 import { deriveSteps, NextStep, readUnitState, UnitState } from '../../harness/next-step';
 import { resolveUnit, resolveUnitCandidates, AmbiguousUnitError } from '../resolve-unit';
+import { withProjectInvocation } from '../project-sungen-invocation';
 
 /** Every unit the project holds, so `sungen next` with no argument still answers. */
 function allUnits(cwd: string): Array<{ name: string; kind: UnitState['kind']; dir: string }> {
@@ -35,15 +36,16 @@ function allUnits(cwd: string): Array<{ name: string; kind: UnitState['kind']; d
   return out;
 }
 
-function renderSteps(steps: NextStep[]): void {
+/** Steps as text, each `sungen …` command as this project runs it (#939); `--json` keeps them canonical. */
+function renderSteps(steps: NextStep[], cwd: string): void {
   for (const st of steps) {
     const mark = st.kind === 'blocked' ? '⛔' : st.kind === 'optional' ? '○' : st.kind === 'decide' ? '⚖' : '→';
-    console.log(`  ${mark} ${st.command}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}`);
+    console.log(`  ${mark} ${withProjectInvocation(st.command, cwd)}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}`);
     console.log(`     ${st.because}`);
   }
 }
 
-function render(s: UnitState): void {
+function render(s: UnitState, cwd: string): void {
   const L = console.log;
   L('');
   L(`━━━ Next steps: ${s.unit} (${s.kind}) ━━━`);
@@ -59,7 +61,7 @@ function render(s: UnitState): void {
   if (s.audit) L(`  audit: ${s.audit.overall}/10 [${s.audit.gateStatus}] · ${s.audit.findings.length} finding(s)`);
   else if (s.auditNotCounted) L(`  audit: ${s.auditNotCounted.state === 'stale' ? 'stale' : 'not trusted'} — ${s.auditNotCounted.reason}`);
   L('');
-  renderSteps(s.steps);
+  renderSteps(s.steps, cwd);
   L('');
 }
 
@@ -89,7 +91,7 @@ function caseView(s: UnitState, cwd: string, unitDir: string, id: string, json:
   if (tc.anchors.length) L(`  anchors:   ${tc.anchors.map((a) => `${a.anchor} (${a.change})`).join(', ')}`);
   for (const f of tc.findings) L(`  finding:   ${f.code} [${f.confidence.label} ${f.confidence.score}] ${f.citation}`);
   L('');
-  if (steps.length) renderSteps(steps);
+  if (steps.length) renderSteps(steps, cwd);
   else L(`  ✓ nothing to do for this test case — ${testCaseStatusLabel(tc)}`);
   L('');
 }
@@ -131,7 +133,7 @@ export function registerNextCommand(program: Command): void {
           console.log(JSON.stringify(states.length === 1 ? states[0] : states, null, 2));
           return;
         }
-        for (const s of states) render(s);
+        for (const s of states) render(s, cwd);
       } catch (e) {
         console.error(`Error: ${e instanceof Error ? e.message : e}`);
         process.exit(1);

package/src/cli/index.ts

@@ -56,7 +56,7 @@ async function main() {
   // process exit (not postAction) because several commands exit with a MEANINGFUL code that skips
   // commander's hooks (`depth-lint` → 2). It points at `sungen next` instead of restating a step,
   // so it cannot drift from the project state. A failure prints it on stderr after the error;
-  // `--json`/`--grep` keep it off stdout (#836); `next` and `hook` never print one. The line and
+  // `--json`/`--grep` keep it off stdout (#836); `hook` never prints one, `next` only when it fails (#937). The line and
   // those rules live in the hook core (src/hooks/hand-back-core.ts) — this file only wires it.
   const handBack = attachCliHandBack(process.argv, process.cwd());
   const program = new Command();

package/src/cli/project-sungen-invocation.ts

@@ -0,0 +1,39 @@
+/**
+ * How a hint names sungen inside a project (#939, items 1–2).
+ *
+ * A project that installs its own sungen (`npm i -D @sun-asterisk/sungen`) runs it with `npx sungen`;
+ * a bare `sungen` is whatever global install the machine has — in the field test an older 3.2.24-beta
+ * beside the project's 3.3.0-alpha. And `sungen update` without a flag switches to the stable
+ * channel, so on an alpha or beta install the update hint must keep the channel it runs on.
+ *
+ *   sungenInvocation(root)          'npx sungen' when <root>/node_modules/@sun-asterisk/sungen exists, else 'sungen'
+ *   withProjectInvocation(cmd, root) a canonical `sungen …` command as this project runs it
+ *   updateCommand(root, version?)   `<invocation> update` plus `--alpha` / `--beta` (`--tag <id>` for another prerelease)
+ *
+ * Only the project root itself is looked at — where `npm i` puts a QA project's install — so a
+ * monorepo checkout above a fixture does not turn its hints into `npx`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getPackageVersion } from '../exporters/package-info';
+
+export function sungenInvocation(projectRoot: string): string {
+  return fs.existsSync(path.join(projectRoot, 'node_modules', '@sun-asterisk', 'sungen', 'package.json')) ? 'npx sungen' : 'sungen';
+}
+
+/** `sungen audit --screen x` → `npx sungen audit --screen x` in a project with its own install; anything else unchanged. */
+export function withProjectInvocation(command: string, projectRoot: string): string {
+  const inv = sungenInvocation(projectRoot);
+  return inv !== 'sungen' && /^sungen\b/.test(command) ? `${inv}${command.slice('sungen'.length)}` : command;
+}
+
+/** The `sungen update` flag that keeps the channel of `version` (its prerelease id); '' for stable. */
+export function updateChannelFlag(version: string = getPackageVersion()): string {
+  const id = version.match(/^\d+\.\d+\.\d+-([0-9A-Za-z-]+)/)?.[1];
+  if (!id) return '';
+  return id === 'alpha' || id === 'beta' ? ` --${id}` : ` --tag ${id}`;
+}
+
+export function updateCommand(projectRoot: string, version: string = getPackageVersion()): string {
+  return `${sungenInvocation(projectRoot)} update${updateChannelFlag(version)}`;
+}

package/src/contract/derive-free-feature.ts

@@ -35,7 +35,8 @@ export interface DeriveResult {
   file: string;
   written: boolean;
   scenarios: Array<{ id: string; title: string; steps: number; low: number; opaque: number }>;
-  skipped: Array<{ id: string; reason: string }>;
+  /** `approved: true` — skipped because QA already approved it (derive never rewrites one), not for want of a trace. */
+  skipped: Array<{ id: string; reason: string; approved?: true }>;
   refused?: SecretHit[];
   note?: string;
 }
@@ -58,6 +59,15 @@ function semanticHits(text: string, label: string): SecretHit[] {
   } finally { fs.rmSync(dir, { recursive: true, force: true }); }
 }
 
+/**
+ * Nothing was derived and nothing explains it away: no test of the unit left an admissible trace
+ * (#932). Not when the scenarios are approved (derive leaves those alone by design), up to date,
+ * refused, or the project is mobile (`note`).
+ */
+export function nothingDerived(r: DeriveResult): boolean {
+  return !r.note && !r.refused?.length && r.scenarios.length === 0 && !r.skipped.some((s) => s.approved);
+}
+
 export async function deriveFreeFeature(i: DeriveInput): Promise<DeriveResult> {
   const unitBase = path.basename(i.unit.name);
   const file = path.join(i.unit.dir, 'features', `${unitBase}.free.feature`);
@@ -79,7 +89,7 @@ export async function deriveFreeFeature(i: DeriveInput): Promise<DeriveResult> {
   for (const id of [...byId.keys()].sort((a, b) => a.localeCompare(b, 'en'))) {
     const runs = admissible(byId.get(id)!);
     if (!runs.length) { result.skipped.push({ id, reason: byId.get(id)![0].reason ?? 'no admissible trace' }); continue; }
-    if (kept.some((b) => b.id === id && !b.proposed)) { result.skipped.push({ id, reason: 'approved — derive never rewrites an approved scenario; use `sungen contract check --trace`' }); continue; }
+    if (kept.some((b) => b.id === id && !b.proposed)) { result.skipped.push({ id, reason: 'approved — derive never rewrites an approved scenario; use `sungen contract check --trace`', approved: true }); continue; }
     const secrets = new Set<string>();
     const rendered = runs.map((r) => {
       const steps = traceIntentSteps(r.trace!);

package/src/contract/trace/collect-trace-evidence.ts

@@ -34,7 +34,7 @@ export interface ScenarioEvidence { runs: Map<string, TraceRun[]>; problems: str
 
 /** The reason a run is not judged once the verdict's deadline has passed (fail closed). */
 export const OVER_BUDGET = 'verdict budget exceeded; run `sungen contract check`';
-const NO_RECORD = "no sungen run record under test-results/ — run the free tests with trace: 'on' and the sungen run-record reporter";
+const NO_RECORD = "no sungen run record under test-results-free/ (or test-results/) — run the free tests with their own config: outputDir 'test-results-free', trace: 'on' and the sungen run-record reporter";
 
 /** The real path of `file` when it is a regular file INSIDE the project (symlinks resolved); else null. */
 export function insideProject(projectRoot: string, file: string): string | null {

package/src/contract/trace/test-step-join.ts

@@ -1,7 +1,8 @@
 /**
  * Join the test runner's steps (test.trace) with the browser calls (<N>-trace.trace) — phase 07
- * criterion 2, proven 114/114 on a real app. A library call's `stepId` is the runner step's
- * `callId`; walking the runner's `parentId` chain says where the call ran:
+ * criterion 2, proven 114/114 on a real app. Up to format 9 a library call's `stepId` is the runner
+ * step's `callId`; from format 10 (Playwright 1.64) the two share ONE id and `stepId` is gone, so the
+ * call's own `callId` is the step. Walking the runner's `parentId` chain says where the call ran:
  *
  *   body       the test function itself, with the path of enclosing `test.step` titles
  *   hook       a user `beforeEach` / `afterEach` (stage setup | teardown)
@@ -26,7 +27,7 @@ export type CallPhase =
   | { phase: 'unjoined' };
 
 export interface JoinedCall {
-  part: string; callId: string; callNumber: number; class: string; method: string;
+  part: string; callId: string; class: string; method: string;
   params: Record<string, unknown>; stepId?: string; where: CallPhase; failed: boolean; startTime: number;
 }
 
@@ -90,9 +91,9 @@ export function joinCalls(trace: ParsedTrace): { steps: Map<string, RunnerStep>;
     for (const e of part.events) {
       if (e.type !== 'before') continue;
       const callId = str(e.callId);
-      const stepId = str(e.stepId) || undefined;
+      const stepId = str(e.stepId) || (part.version >= 10 ? callId : '') || undefined;
       calls.push({
-        part: part.name, callId, callNumber: Number(callId.replace(/^call@/, '')) || 0, class: str(e.class), method: str(e.method),
+        part: part.name, callId, class: str(e.class), method: str(e.method),
         params: (e.params && typeof e.params === 'object' ? e.params : {}) as Record<string, unknown>,
         stepId, where: stepId ? classifyStep(steps, stepId) : { phase: 'unjoined' }, failed: failed.has(callId), startTime: Number(e.startTime) || 0,
       });

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

@@ -5,7 +5,7 @@
  *   test.trace            the test runner's steps (test.step, hooks, fixtures, expect, pw:api)
  *   <N>-trace.trace       a library part: the browser calls, frame snapshots, logs
  *   <N>-trace.network     resources (stylesheets inlined into a replayed snapshot come from here)
- *   <N>-trace.stacks      call number → source frames (`file:line` of an opaque step)
+ *   <N>-trace.stacks      call id → source frames (`file:line` of an opaque step)
  *   resources/<sha1>      resource bodies
  *
  * Every part that has a header (test.trace and each library part) must declare a supported version;
@@ -18,7 +18,12 @@ import { SUPPORTED_TRACE_VERSIONS, traceZipLimits, TraceRejected, TraceZipLimits
 
 export type TraceEvent = { type: string } & Record<string, unknown>;
 export interface StackFrame { file: string; line: number; column: number }
-export interface LibraryPart { name: string; events: TraceEvent[]; network: TraceEvent[]; stacks: Map<number, StackFrame[]> }
+/**
+ * One library part. `version` is its declared format (already accepted by the gate); `stacks` is
+ * keyed by call id — v8/v9 wrote a call NUMBER (`11` → `call@11`, Playwright's legacy id), v10 the
+ * call id itself, which it shares with the runner step (`ulgt@50`).
+ */
+export interface LibraryPart { name: string; version: number; events: TraceEvent[]; network: TraceEvent[]; stacks: Map<string, StackFrame[]> }
 
 export interface ParsedTrace {
   label: string;
@@ -56,19 +61,21 @@ function parseJsonl(zip: ZipArchive, name: string): TraceEvent[] {
   return out;
 }
 
-function parseStacks(zip: ZipArchive, name: string): Map<number, StackFrame[]> {
-  const out = new Map<number, StackFrame[]>();
+function parseStacks(zip: ZipArchive, name: string): Map<string, StackFrame[]> {
+  const out = new Map<string, StackFrame[]>();
   if (!zip.has(name)) return out;
   let doc: { files?: unknown; stacks?: unknown };
   try { doc = JSON.parse(zip.readText(name)); } catch { throw new TraceRejected('trace.malformed', `${name} is not JSON`); }
   const files = Array.isArray(doc.files) ? doc.files.map(String) : [];
   for (const row of Array.isArray(doc.stacks) ? doc.stacks : []) {
-    if (!Array.isArray(row) || typeof row[0] !== 'number' || !Array.isArray(row[1])) continue;
+    if (!Array.isArray(row) || !Array.isArray(row[1])) continue;
+    const id = typeof row[0] === 'number' ? `call@${row[0]}` : row[0];
+    if (typeof id !== 'string' || !CALL_ID.test(id)) continue;
     const frames = (row[1] as unknown[]).filter(Array.isArray).map((f) => {
       const [fileIdx, line, column] = f as number[];
       return { file: files[fileIdx] ?? '', line: Number(line) || 0, column: Number(column) || 0 };
     });
-    out.set(row[0], frames);
+    out.set(id, frames);
   }
   return out;
 }
@@ -81,9 +88,12 @@ export function readTraceBuffer(buf: Buffer, label: string, limits: TraceZipLimi
   const runner = parseJsonl(zip, 'test.trace');
   const library: LibraryPart[] = zip.names().filter((n) => /^\d+-trace\.trace$/.test(n)).sort().map((n) => {
     const base = n.replace(/\.trace$/, '');
+    const events = parseJsonl(zip, n);
+    const version = headerOf(events)?.version;
     return {
       name: n,
-      events: parseJsonl(zip, n),
+      version: typeof version === 'number' ? version : NaN, // a non-number is refused just below
+      events,
       network: zip.has(`${base}.network`) ? parseJsonl(zip, `${base}.network`) : [],
       stacks: parseStacks(zip, `${base}.stacks`),
     };

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

@@ -4,9 +4,10 @@
  * 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.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -31,13 +32,18 @@ const ATTEMPT = new Set(['testId', 'file', 'title', 'retry', 'status', 'startTim
 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 {

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/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/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/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/graph/evaluate-graph.ts

@@ -4,7 +4,9 @@
  *
  *   open       active ∧ ¬satisfied (a test-case node is open when at least one case is)
  *   frontier   open ∧ (every `requires` satisfied ∨ ¬blocking)
- *   cut        an open blocking node ends the walk — nothing ranked after it is offered
+ *   cut        an open blocking node ends the walk — nothing ranked after it is offered, except a
+ *              node's instances that `surfacesPastCut` (a hard contract verdict, #940), which follow
+ *              the cutting step and never cut themselves
  *
  * `--case <id>` (`testCase` option): the frontier is that case's test-case nodes plus the blocking
  * unit nodes before them; non-blocking unit advice is left to the unit view. A `caseOnly` test-case
@@ -41,22 +43,24 @@ export function evaluateGraph(
   const ordered = [...nodes].sort((a, b) => a.rank - b.rank);
   const open = new Set<string>();
   const out: NextStep[] = [];
+  let cut = false;
   for (const node of ordered) {
     if (!node.appliesTo.includes(s.kind) || (node.granularity === 'test-case' && node.caseOnly && !opts.testCase)) continue;
+    if (cut && !node.surfacesPastCut) continue;
     let step: NextStep | null = null;
     if (node.granularity === 'unit') {
-      if (!node.active(s) || node.satisfied(s)) continue;
+      if (!node.active(s) || node.satisfied(s) || (cut && !node.surfacesPastCut!(s))) continue;
       if (!opts.testCase || node.blocking) step = withMeta(node, node.step(s));
     } else {
-      const cases = openCases(node, s, tcStates, opts.testCase);
+      const cases = openCases(node, s, tcStates, opts.testCase).filter((tc) => !cut || node.surfacesPastCut!(s, tc));
       if (!cases.length) continue;
       const single = Boolean(opts.testCase);
       step = withMeta(node, node.step(s, cases, single), single ? cases[0].id : undefined);
     }
     open.add(node.id);
     const ready = node.requires.every((r) => !open.has(r));
-    if (step && (ready || !node.blocking)) out.push(step);
-    if (node.blocking) break;
+    if (step && (cut || ready || !node.blocking)) out.push(step);
+    if (node.blocking && !cut) cut = true;
   }
   return out;
 }

package/src/graph/node-decl.ts

@@ -42,6 +42,11 @@ export interface UnitNodeDecl extends NodeDeclBase {
   active(s: UnitState): boolean;
   satisfied(s: UnitState): boolean;
   step(s: UnitState): StepCore;
+  /**
+   * Offered even when a blocking node ranked before it cut the walk — only while this holds (#940: a
+   * hard contract verdict must not hide behind a stale or failing audit). It never cuts by itself.
+   */
+  surfacesPastCut?(s: UnitState): boolean;
 }
 
 export interface TestCaseNodeDecl extends NodeDeclBase {
@@ -55,6 +60,8 @@ export interface TestCaseNodeDecl extends NodeDeclBase {
   satisfied(s: UnitState, tc: TestCaseState): boolean;
   /** One step for `cases` (all open at this node): a unit-level fold, or exactly one case when `single`. */
   step(s: UnitState, cases: TestCaseState[], single: boolean): StepCore;
+  /** The cases offered even past a cut (see UnitNodeDecl.surfacesPastCut). */
+  surfacesPastCut?(s: UnitState, tc: TestCaseState): boolean;
 }
 
 export type NodeDecl = UnitNodeDecl | TestCaseNodeDecl;

package/src/graph/nodes/test-case-contract-nodes.ts

@@ -11,7 +11,9 @@
  *   tc.conformance       its trace is in review: a `low` target identity  do       contract check --trace
  *                        · its final attempt did not pass (inconclusive)  do       run-test --ids
  *                        · a step no code can compare (opaque)            decide   contract check
- * Exempt cases (DOS-11.2) open nothing. A proposed case (never approved) asks nothing of its own: a
+ * tc.contract-check (a weaker / retargeted / lost check, or an uncommitted lock entry) and tc.unproven
+ * are hard verdicts: they are offered past a stale or failing audit (the cut at unit.audit-stale /
+ * unit.gate-fail), #940; tc.contract-approve (changed, not weaker) is review and waits behind it. Exempt cases (DOS-11.2) open nothing. A proposed case (never approved) asks nothing of its own: a
  * compiled test without a lock is never blocked, and the unit view offers the approval.
  */
 import { ALL_KINDS, StepCore, TestCaseNodeDecl } from '../node-decl';
@@ -29,13 +31,14 @@ const withDetail = (cases: TestCaseState[]): string =>
 const check = (s: UnitState, trace = false): string => `sungen contract check --screen ${s.unit}${trace ? ' --trace' : ''}`;
 
 function contractNode(id: string, rank: number, title: string, actor: TestCaseNodeDecl['actor'], gates: string[], caseOnly: boolean,
-  active: (tc: TestCaseState) => boolean, step: Step): TestCaseNodeDecl {
+  active: (tc: TestCaseState) => boolean, step: Step, hard?: (tc: TestCaseState) => boolean): TestCaseNodeDecl {
   return {
     id, title, actor, granularity: 'test-case', appliesTo: ALL_KINDS, blocking: false, rank, gates, step,
     requires: caseOnly ? ['unit.gate-fail'] : ['unit.run'], produces: ['contracts.lock.yaml', 'decisions/<id>.yaml'],
     ...(caseOnly ? { caseOnly: true as const } : {}),
     active: (_s, tc) => active(tc),
     satisfied: (_s, tc) => exemptionOf(tc) !== null,
+    ...(hard ? { surfacesPastCut: (_s: UnitState, tc: TestCaseState) => hard(tc) } : {}),
   };
 }
 
@@ -60,10 +63,12 @@ export const TEST_CASE_CONTRACT_NODES: readonly TestCaseNodeDecl[] = [
     (tc) => Boolean(tc.contract?.uncommitted) || HARD_LADDER.has(classOf(tc) ?? ''),
     (s, [c]) => ({ kind: 'blocked', command: check(s), because: c.contract?.uncommitted
       ? `its lock entry is not what QA approved and committed (contract.lock-uncommitted) — \`sungen next ${s.unit}\` names the repair; \`sungen delivery\` is blocked until then`
-      : `this case breaks its approved contract (${c.contract?.class}${c.contract?.detail ? `: ${c.contract.detail}` : ''}) — restore the approved check (in the .feature, or in the hand-written test of a free / impl:code case), or a QA approves the change on a terminal (\`sungen contract approve --screen ${s.unit} --scenario ${c.id}\`). \`sungen delivery\` is blocked until then; never weaken an expected value to go green` })),
+      : `this case breaks its approved contract (${c.contract?.class}${c.contract?.detail ? `: ${c.contract.detail}` : ''}) — restore the approved check (in the .feature, or in the hand-written test of a free / impl:code case), or a QA approves the change on a terminal (\`sungen contract approve --screen ${s.unit} --scenario ${c.id}\`). \`sungen delivery\` is blocked until then; never weaken an expected value to go green` }),
+    (tc) => Boolean(tc.contract?.uncommitted) || HARD_LADDER.has(classOf(tc) ?? '')),
   contractNode('tc.unproven', 136, 'Prove the approved free cases with a trace', 'ai', ['contract.unproven'], false,
     (tc) => classOf(tc) === 'unproven',
-    (s, cases) => ({ kind: 'do', command: `/sungen:run-test ${s.unit}${idsArg(cases)}`, because: `${cases.length} approved free / impl:code test case(s) have no trace that proves them (${withDetail(cases)}) — run them again with trace: 'on' and the sungen run-record reporter (run-test Phase 4 does), then \`${check(s, true)}\`. Until then \`sungen contract check\` fails (contract.unproven) and \`sungen delivery\` is blocked; re-approving or editing the .feature cannot prove them` })),
+    (s, cases) => ({ kind: 'do', command: `/sungen:run-test ${s.unit}${idsArg(cases)}`, because: `${cases.length} approved free / impl:code test case(s) have no trace that proves them (${withDetail(cases)}) — run them again with trace: 'on' and the sungen run-record reporter (run-test Phase 4 does), then \`${check(s, true)}\`. Until then \`sungen contract check\` fails (contract.unproven) and \`sungen delivery\` is blocked; re-approving or editing the .feature cannot prove them` }),
+    (tc) => classOf(tc) === 'unproven'),
   contractNode('tc.conformance', 138, 'Settle the traces in review', 'ai', ['contract.opaque-step', 'contract.inconclusive'], false,
     (tc) => classOf(tc) === 'opaque' || classOf(tc) === 'inconclusive', conformanceStep),
 ];

package/src/graph/nodes/unit-contract-node.ts

@@ -3,7 +3,8 @@
  * verdict `sungen contract check` and the delivery guard rebuild (buildContractVerdict), so the three
  * never disagree. Always `decide`: an agent presents it and never approves its own edit.
  *
- *   unit.contract-approve  (rank 105, after the audit gate, before the first run)
+ *   unit.contract-approve  (rank 105, after the audit gate, before the first run; a hard verdict —
+ *                          hard or uncommitted — is offered past a stale or failing audit too, #940)
  *     error        the verdict could not be built → check it on a terminal
  *     uncommitted  by kind: tampered → re-approve or restore · untracked → commit after review ·
  *                  edited → review and commit, or `git checkout --` the lock · unverified → commit the
@@ -66,6 +67,12 @@ export const UNIT_CONTRACT_NODES: readonly UnitNodeDecl[] = [
     active: (s) => Boolean(s.contract),
     satisfied: nothingToDecide,
     step: contractStep,
+    // A hard verdict must not wait behind a re-audit (#940): the audit's PASS says nothing about it —
+    // a broken approved check, or a lock that is not what QA approved and committed (contract.lock-
+    // uncommitted, hard in `contract check`; the step names that repair first). What stays behind the
+    // cut: a changed-not-weaker contract (review — QA re-approves after the design is fixed) and a
+    // verdict that could not be built (not a verdict; `contract check` names the error).
+    surfacesPastCut: (s) => !s.contract!.error && (s.contract!.uncommitted > 0 || s.contract!.hard > 0),
   },
   {
     id: 'unit.contract-proposed', title: 'Approve the Test Contract', actor: 'human', granularity: 'unit',

package/src/graph/nodes/unit-design-nodes.ts

@@ -10,6 +10,7 @@
  *   6 unit.flow-inventory    a flow contract without `flows:` → add it, re-audit
  */
 import { ALL_KINDS, UnitNodeDecl, unitKindDir } from '../node-decl';
+import { updateChannelFlag } from '../../cli/project-sungen-invocation';
 
 const design = (unit: string): string => `/sungen:create-test ${unit}`;
 
@@ -34,7 +35,7 @@ export const UNIT_DESIGN_NODES: readonly UnitNodeDecl[] = [
     satisfied: (s) => !s.assetsDrift,
     step: (s) => ({
       kind: 'do',
-      command: 'sungen update',
+      command: `sungen update${updateChannelFlag(s.assetsDrift!.runningVersion)}`,   // keep the channel (#939)
       because: `this project's AI commands/skills were written by sungen ${s.assetsDrift!.recordedVersion} and you are running ${s.assetsDrift!.runningVersion} — upgrading the package does NOT refresh them, so any rule added since ${s.assetsDrift!.recordedVersion} is not in effect for the next run`,
     }),
   },

package/src/harness/catalog/gate-rules.yaml

@@ -535,8 +535,8 @@ rules:
     stage: deliver
     severity: error
     kind: soft
-    rationale: "Pre-delivery halt: everything automated plus the single human sign-off must be satisfied or waived with a reason."
-    fix: "Close the open obligations and sign off, or waive with a reason."
+    rationale: "Pre-delivery halt: everything automated must be satisfied or waived with a reason, plus the single human sign-off, which is given (sungen journey --signoff), never waived."
+    fix: "Close or waive the open obligations, then a human signs off: sungen journey --screen <unit> --signoff --by <name>."
     since: "<=3.2.34"
     offAllowed: false