@sun-asterisk/sungen 3.3.0-alpha.6 → 3.3.0-alpha.8

package/src/cli/waiting-for-you-block.ts

@@ -0,0 +1,27 @@
+/**
+ * The "Waiting for you" block (#954) — every pending human-only action of a unit, as ready-to-copy
+ * commands with the reason under each. One renderer for the three places that show it: `sungen next`
+ * (text) and the Stop / SessionStart hook context. Commands — and those inside a reason (#963) — as the
+ * project runs sungen (`npx sungen` with a local install, #939); `--json` keeps `command` canonical in
+ * `humanActions` and adds `rendered`. An instruction (a commit through review, a `git checkout --`) is
+ * marked `✎ … (by hand, not a command)`, never shown as one to copy.
+ */
+import type { HumanAction } from '../graph/human-action';
+import { withProjectInvocation, withProjectInvocationInText } from './project-sungen-invocation';
+
+export const WAITING_FOR_YOU_HEAD = '⏳ Waiting for you — a human runs these in their own terminal (in Claude Code: ! <command>); an agent never runs them:';
+
+/**
+ * The block's lines (indented two spaces), or none when nothing waits for a human and nothing holds the
+ * rest. `heldBy`: the title of the blocking step that cut the frontier — the block is not exhaustive then,
+ * and says what holds the rest, with that step's command (`heldByCommand`) when given (#966). A held
+ * block with no item of its own still says so, rather than vanishing (a QA read "nothing is waiting").
+ */
+export function waitingForYouLines(actions: readonly HumanAction[] | undefined, projectRoot: string, heldBy?: string, heldByCommand?: string): string[] {
+  const holds = heldBy ? `"${heldBy}" clears${heldByCommand ? ` (the step above: ${withProjectInvocationInText(heldByCommand, projectRoot)})` : ''}` : '';
+  if (!actions?.length) return heldBy ? [`  ⏳ Waiting for you: nothing yet — more appear once ${holds}.`] : [];
+  return [`  ${WAITING_FOR_YOU_HEAD}`, ...actions.flatMap((a) => [
+    a.instruction ? `     ✎ ${a.command}   (by hand, not a command)` : `     ${withProjectInvocation(a.command, projectRoot)}`,
+    `       ${withProjectInvocationInText(a.reason, projectRoot)}`,
+  ]), ...(heldBy ? [`     More appear once ${holds}.`] : [])];
+}

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

@@ -22,6 +22,7 @@ import { scrubKnownSecrets, scrubMachinePaths, secretScanHits, SecretHit } from
 import { idOfTitle, splitFeatureBlocks } from './free-feature-blocks';
 import { sensitiveLiteralHits } from './lock-secret-guard';
 import { scenariosOfFeatureFile } from './normalize-feature-steps';
+import { featureFilesFor } from '../harness/unit-paths';
 import { CONTROL_CHARS, freeFeatureText, renderTraceSteps, scenarioBlockText } from './render-free-gherkin';
 import { collectRuns, TraceRun } from './trace/collect-trace-evidence';
 import { readIdentityCache } from './trace/identity-cache';
@@ -39,6 +40,8 @@ export interface DeriveResult {
   skipped: Array<{ id: string; reason: string; approved?: true }>;
   refused?: SecretHit[];
   note?: string;
+  /** A derived id another `.feature` of the unit already uses (#939) — `contract check` and approve would trip on it later. */
+  warnings?: string[];
 }
 
 const MACHINE_PATH = /(?:\/Users|\/home)\/[^/\s"'`]+\/|[A-Za-z]:\\Users\\/;
@@ -59,6 +62,22 @@ function semanticHits(text: string, label: string): SecretHit[] {
   } finally { fs.rmSync(dir, { recursive: true, force: true }); }
 }
 
+/**
+ * The derived ids another `.feature` of the unit already carries (#939): `contract check` reports an id
+ * used twice and approve refuses it, so say it now — when it is still one rename away — not at check.
+ */
+function reusedIdWarnings(unit: { name: string; dir: string }, freeFile: string, ids: string[]): string[] {
+  const owners = new Map<string, string>();
+  for (const f of featureFilesFor(unit.dir, unit.name)) {
+    if (path.resolve(f) === path.resolve(freeFile) || !fs.existsSync(f)) continue;
+    try {
+      for (const sc of scenariosOfFeatureFile(f)) if (!owners.has(sc.id)) owners.set(sc.id, path.basename(f));
+    } catch { /* an unparseable sibling is `contract check`'s to report */ }
+  }
+  return ids.filter((id) => owners.has(id)).map((id) =>
+    `${id} is already the ID of a scenario in ${owners.get(id)} — the derived scenario reuses it; give the free test (its title's leading ID) or that scenario its own ID, or \`sungen contract check\` reports it twice and approval refuses it`);
+}
+
 /**
  * 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,
@@ -108,6 +127,8 @@ export async function deriveFreeFeature(i: DeriveInput): Promise<DeriveResult> {
     result.scenarios.push({ id, title, steps: rendered[0].length, low: rendered[0].filter((s) => s.low).length, opaque: rendered[0].filter((s) => s.opaque).length });
   }
   if (!result.scenarios.length) return result;
+  const reused = reusedIdWarnings(i.unit, file, result.scenarios.map((x) => x.id));
+  if (reused.length) result.warnings = reused;
 
   const text = freeFeatureText(unitBase, [...blocks.values()]);
   const label = path.basename(file);

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}`;
 }

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/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();

package/src/graph/board-human-actions.ts

@@ -0,0 +1,80 @@
+/**
+ * The human-only actions the graph does not hold ("Waiting for you", #954) — asked by the journey
+ * board and the delivery's decision check, read through THEIR functions (never restated here):
+ *
+ *   waive          a waiver the board re-surfaces: stale (the audit changed since) or untrusted (not
+ *                  in git HEAD) — readJourneyHumanAsks, the reconcile `runJourney` commits
+ *   decide         a gate-override that relaxes nothing because no human confirmed it (ineffective) —
+ *                  re-recorded with `journey --decide`, superseding it (loadUnitGateOverrides)
+ *   signoff        every other obligation holds — assertCanSignOff, as `journey --signoff` checks it
+ *   accept-in-run  a decision recorded during the run — evaluateDeliveryDecisions, as `delivery` runs it
+ * The sign-off and accept-in-run only once the frontier was not cut (the unit has run and nothing
+ * blocks before it). Read-only and advisory: whatever cannot be read adds nothing.
+ */
+import { formatCommand } from '../decisions/human-confirmation';
+import { waiveCommand } from '../decisions/legacy-waiver-migration';
+import { evaluateDeliveryDecisions } from '../harness/gates/delivery-decision-gate';
+import { IN_RUN_RULE } from '../harness/gates/in-run-decision-check';
+import { loadUnitGateOverrides, unitScopeOfDir } from '../harness/gates/unit-gate-overrides';
+import { readJourneyHumanAsks, signoffCommand } from '../harness/journey';
+import type { UnitState } from '../harness/next-step';
+import type { HumanAction } from './human-action';
+import { unitResultFiles } from './unit-artifact-probes';
+
+function journeyActions(projectRoot: string, s: UnitState, cut: boolean): HumanAction[] {
+  const asks = readJourneyHumanAsks(projectRoot, s.unit);
+  const out: HumanAction[] = asks.redecide.map((w) => ({
+    kind: 'waive',
+    command: waiveCommand(s.unit, w.obligation, w.reason),
+    reason: w.why === 'stale'
+      ? `the waiver on "${w.title}" is stale — the evidence changed since it was given, so it no longer counts; if it still holds, a human gives it again on a terminal (or repair the obligation)`
+      : `the waiver on "${w.title}" is not in git HEAD (decision.in-run), so it is not counted — if it is yours, confirm it on a terminal`,
+  }));
+  if (!cut && asks.canSignOff && asks.signoff.status !== 'given') {
+    out.push({
+      kind: 'signoff',
+      command: signoffCommand(s.unit),
+      reason: asks.signoff.status === 'stale'
+        ? `the sign-off of ${asks.signoff.at} is stale — the suite changed since; review the queue (\`sungen journey --screen ${s.unit}\`) and sign off again`
+        : `every other obligation is satisfied or waived — the human sign-off is the one gate \`sungen gate --phase deliver\` still waits on; review the queue (\`sungen journey --screen ${s.unit}\`, ${asks.report.needsYou.length} item(s)), then sign`,
+    });
+  }
+  return out;
+}
+
+function unconfirmedOverrides(projectRoot: string, unitDir: string, s: UnitState): HumanAction[] {
+  return loadUnitGateOverrides(projectRoot, unitScopeOfDir(projectRoot, unitDir)).ineffective.map((o) => {
+    const { humanAccepted: _ignored, ...payload } = o.entry.payload ?? {};
+    return {
+      kind: 'decide',
+      command: formatCommand(['sungen', 'journey', '--screen', s.unit, '--decide', 'gate-override', '--text', o.entry.text, '--reason', o.entry.reason,
+        '--payload', JSON.stringify(payload), '--supersedes', o.decisionId]),
+      reason: `the gate-override ${o.decisionId}${o.rule ? ` (${o.rule})` : ''} relaxes nothing: ${o.reason} — if it is meant, a human records it again on a terminal, superseding it`,
+    };
+  });
+}
+
+function inRunActions(projectRoot: string, unitDir: string, s: UnitState): HumanAction[] {
+  const files = unitResultFiles(projectRoot, s.unit);
+  const refs = (files.length ? files : [null]).map((resultsPath) => ({ label: s.unit, unitName: s.unit, unitDir, resultsPath }));
+  const inRun = evaluateDeliveryDecisions(projectRoot, refs).inRun;
+  if (!inRun.length) return [];
+  const which = inRun.slice(0, 3).map((d) => `${d.kind} ${d.id}`).join(', ');
+  return [{
+    kind: 'accept-in-run',
+    command: formatCommand(['sungen', 'delivery', s.unit, '--accept-in-run']),
+    reason: `${inRun.length} decision(s) recorded during the run (${IN_RUN_RULE}): ${which}${inRun.length > 3 ? ', …' : ''} — \`sungen delivery\` refuses them until they are committed through review and the tests re-run, or a human accepts them on a terminal`,
+  }];
+}
+
+/** The board's and the delivery's asks of a human for this unit. `cut`: the frontier stopped at a blocking node. */
+export function boardHumanActions(projectRoot: string, unitDir: string, s: UnitState, cut: boolean): HumanAction[] {
+  const out: HumanAction[] = [];
+  const add = (read: () => HumanAction[]): void => {
+    try { out.push(...read()); } catch { /* advisory: an unreadable board or decision adds nothing */ }
+  };
+  add(() => journeyActions(projectRoot, s, cut));
+  add(() => unconfirmedOverrides(projectRoot, unitDir, s));
+  if (!cut) add(() => inRunActions(projectRoot, unitDir, s));
+  return out;
+}

package/src/graph/evaluate-graph.ts

@@ -11,8 +11,12 @@
  * `--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
  * node speaks only there (its unit-level decision is in the unit view already).
+ *
+ * evaluateHumanActions reads the SAME walk for "Waiting for you" (#954): the human-only actions behind
+ * the offered steps, and whether the walk was cut.
  */
 import type { NextStep, UnitState } from '../harness/next-step';
+import type { HumanAction } from './human-action';
 import type { NodeDecl, StepCore } from './node-decl';
 import type { TestCaseState } from './test-case-state-shape';
 
@@ -37,30 +41,57 @@ function openCases(node: NodeDecl, s: UnitState, tcStates: TestCaseState[] | und
   return tcStates.filter((tc) => (!only || tc.id === only) && node.active(s, tc) && !node.satisfied(s, tc));
 }
 
-export function evaluateGraph(
-  nodes: readonly NodeDecl[], s: UnitState, tcStates?: TestCaseState[], opts: EvaluateOptions = {},
-): NextStep[] {
+/** One offered step and what produced it: the node, and the cases open at it (test-case nodes). */
+interface Offered { node: NodeDecl; step: NextStep; cases: TestCaseState[] }
+
+/** The walk both answers share: the offered steps in rank order, and whether an open blocking node cut it. */
+function walkFrontier(nodes: readonly NodeDecl[], s: UnitState, tcStates: TestCaseState[] | undefined, opts: EvaluateOptions): { offered: Offered[]; cut: boolean; cutBy?: NodeDecl } {
   const ordered = [...nodes].sort((a, b) => a.rank - b.rank);
   const open = new Set<string>();
-  const out: NextStep[] = [];
+  const offered: Offered[] = [];
   let cut = false;
+  let cutBy: NodeDecl | undefined;
   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;
+    let cases: TestCaseState[] = [];
     if (node.granularity === 'unit') {
       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).filter((tc) => !cut || node.surfacesPastCut!(s, tc));
+      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 && (cut || ready || !node.blocking)) out.push(step);
-    if (node.blocking && !cut) cut = true;
+    if (step && (cut || ready || !node.blocking)) offered.push({ node, step, cases });
+    if (node.blocking && !cut) { cut = true; cutBy = node; }
   }
-  return out;
+  return { offered, cut, ...(cutBy ? { cutBy } : {}) };
+}
+
+export function evaluateGraph(
+  nodes: readonly NodeDecl[], s: UnitState, tcStates?: TestCaseState[], opts: EvaluateOptions = {},
+): NextStep[] {
+  return walkFrontier(nodes, s, tcStates, opts).offered.map((o) => o.step);
+}
+
+/**
+ * The HUMAN-ONLY actions of the same frontier ("Waiting for you", #954) — never a second walk with
+ * rules of its own: each offered step's node says what a person runs (its `human` hook), and a decide
+ * step without one is its own command. `cut`: an open blocking node ended the walk, so only what does
+ * not depend on it is offered (a hard verdict that surfaces past the cut), and the board's asks that
+ * need the unit past it (sign-off, accept-in-run) wait; `heldBy` is that node's title and `heldByCommand`
+ * its offered step's command (#966: "More appear once …" names what to run).
+ */
+export function evaluateHumanActions(nodes: readonly NodeDecl[], s: UnitState, tcStates?: TestCaseState[]): { actions: HumanAction[]; cut: boolean; heldBy?: string; heldByCommand?: string } {
+  const { offered, cut, cutBy } = walkFrontier(nodes, s, tcStates, {});
+  const actions = offered.flatMap(({ node, step, cases }) => (node.human
+    ? node.human(s, step, cases)
+    : step.kind === 'decide' ? [{ command: step.command, reason: step.because, kind: 'decide' as const }] : []));
+  const heldByCommand = cutBy ? offered.find((o) => o.node === cutBy)?.step.command : undefined;
+  return { actions, cut, ...(cutBy ? { heldBy: cutBy.title } : {}), ...(heldByCommand ? { heldByCommand } : {}) };
 }

package/src/graph/human-action.ts

@@ -0,0 +1,33 @@
+/**
+ * A HUMAN-ONLY action of a unit — what `sungen next` lists under "Waiting for you" (#954) and `--json`
+ * carries as `humanActions`. An agent presents these and never runs them: they approve, sign, waive,
+ * classify or accept something on a person's behalf, and most refuse without a typed confirmation.
+ *
+ * `command` is canonical (`sungen …`, or a slash command); the text renders it as the project runs
+ * sungen (`npx sungen` with a local install). Placeholders a human fills are quoted (`"<name>"`, `"…"`)
+ * so a copied command never turns into a shell redirection.
+ */
+export type HumanActionKind =
+  | 'contract-approve'   // approve (or re-approve) the Test Contract — `sungen contract approve`
+  | 'accept-opaque'      // accept a reviewed opaque trace step — `contract approve --scenario <id> --accept-opaque`
+  | 'contract-commit'    // commit, or restore, a lock / approval decision through review
+  | 'contract-review'    // read the contract verdict on a terminal (it could not be built)
+  | 'accept-viewpoint'   // accept the changed viewpoint baseline — `sungen audit --accept-viewpoint`
+  | 'defect-draft'       // decide whether a product-defect candidate is a defect — `sungen defect draft`
+  | 'rerun-environment'  // re-run the reds the environment caused, once a human confirms it is up
+  | 'triage-classify'    // classify a red by hand as test-defect / environment — `sungen triage --case --as`
+  | 'signoff'            // the single human gate — `sungen journey --signoff`
+  | 'waive'              // give a waiver again — `sungen journey --waive`
+  | 'decide'             // record a decision — `sungen journey --decide`
+  | 'accept-in-run';     // deliver despite decisions recorded during the run — `sungen delivery --accept-in-run`
+
+export interface HumanAction {
+  command: string;
+  reason: string;
+  kind: HumanActionKind;
+  /**
+   * `command` is an instruction a person carries out by hand (commit through review, restore from git),
+   * not a command line to copy — the block marks it so, and never renders it as one.
+   */
+  instruction?: true;
+}

package/src/graph/node-decl.ts

@@ -11,6 +11,7 @@
  * `sungen next <unit> --case <id>`).
  */
 import type { NextStep, UnitState } from '../harness/next-step';
+import type { HumanAction, HumanActionKind } from './human-action';
 import type { TestCaseState } from './test-case-state-shape';
 
 export type NodeActor = 'ai' | 'human' | 'deterministic';
@@ -35,8 +36,18 @@ interface NodeDeclBase {
   gates: readonly string[];
   /** Artifacts the step produces, for a reader of the graph. */
   produces: readonly string[];
+  /**
+   * The HUMAN-ONLY actions behind an offered step ("Waiting for you", #954): what a person runs, with
+   * why. Without it a `decide` step is one action of kind `decide` and any other step is none. `cases`
+   * are the cases open at a test-case node (none for a unit node).
+   */
+  human?(s: UnitState, step: StepCore, cases: TestCaseState[]): HumanAction[];
 }
 
+/** The `human` hook of a node whose decide step IS the human action: its command and reason, under `kind`. */
+export const humanStep = (kind: HumanActionKind) => (_s: UnitState, step: StepCore): HumanAction[] =>
+  [{ command: step.command, reason: step.because, kind }];
+
 export interface UnitNodeDecl extends NodeDeclBase {
   granularity: 'unit';
   active(s: UnitState): boolean;

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

@@ -16,8 +16,9 @@
  * 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';
+import { ALL_KINDS, humanStep, StepCore, TestCaseNodeDecl } from '../node-decl';
 import type { UnitState } from '../../harness/next-step';
+import type { HumanAction } from '../human-action';
 import type { TestCaseState } from '../test-case-state-shape';
 import { exemptionOf } from '../test-case-satisfied';
 import { idsArg, listed } from './test-case-nodes';
@@ -31,7 +32,7 @@ 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, hard?: (tc: TestCaseState) => boolean): TestCaseNodeDecl {
+  active: (tc: TestCaseState) => boolean, step: Step, hard?: (tc: TestCaseState) => boolean, human?: TestCaseNodeDecl['human']): 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'],
@@ -39,9 +40,23 @@ function contractNode(id: string, rank: number, title: string, actor: TestCaseNo
     active: (_s, tc) => active(tc),
     satisfied: (_s, tc) => exemptionOf(tc) !== null,
     ...(hard ? { surfacesPastCut: (_s: UnitState, tc: TestCaseState) => hard(tc) } : {}),
+    ...(human ? { human } : {}),
   };
 }
 
+/**
+ * An opaque step is cleared by a QA accepting it as it reads now, never by re-approving (#923): one
+ * `--accept-opaque` per case whose only hold is the opaque step. A case held by a `low` identity is
+ * not acceptable yet (`contract check --trace` resolves it first), so it is not offered (#954).
+ */
+function acceptOpaque(s: UnitState, _step: StepCore, cases: TestCaseState[]): HumanAction[] {
+  return cases.filter((c) => classOf(c) === 'opaque' && !c.contract?.lowIdentity).map((c) => ({
+    kind: 'accept-opaque',
+    command: `sungen contract approve --screen ${s.unit} --scenario ${c.id} --accept-opaque`,
+    reason: `${c.id} carries a step sungen cannot compare${c.contract?.detail ? ` (${c.contract.detail})` : ''} — a QA reviews it verbatim with its file:line in \`${check(s)}\`, then accepts it as it reads now; until then the contract is in review and \`sungen delivery\` waits`,
+  }));
+}
+
 const conformanceStep: Step = (s, cases) => {
   const low = cases.filter((c) => c.contract?.lowIdentity);
   if (low.length) {
@@ -57,7 +72,8 @@ const conformanceStep: Step = (s, cases) => {
 export const TEST_CASE_CONTRACT_NODES: readonly TestCaseNodeDecl[] = [
   contractNode('tc.contract-approve', 106, 'Re-approve this changed case', 'human', ['contract.hash-changed'], true,
     (tc) => classOf(tc) === 'hash-changed' && !tc.contract?.uncommitted,
-    (s, [c]) => ({ kind: 'decide', command: `sungen contract approve --screen ${s.unit} --scenario ${c.id}`, because: `this case changed since QA approved it, not weaker${c.contract?.detail ? ` (${c.contract.detail})` : ''} — a QA re-approves this scenario on a terminal; until then review blocks \`sungen delivery\`. An agent presents it and never approves its own edit` })),
+    (s, [c]) => ({ kind: 'decide', command: `sungen contract approve --screen ${s.unit} --scenario ${c.id}`, because: `this case changed since QA approved it, not weaker${c.contract?.detail ? ` (${c.contract.detail})` : ''} — a QA re-approves this scenario on a terminal; until then review blocks \`sungen delivery\`. An agent presents it and never approves its own edit` }),
+    undefined, humanStep('contract-approve')),
   contractNode('tc.contract-check', 107, 'Restore the approved check of this case', 'human',
     ['contract.oracle-weakened', 'contract.target-changed', 'contract.assertion-lost', 'contract.lock-uncommitted'], true,
     (tc) => Boolean(tc.contract?.uncommitted) || HARD_LADDER.has(classOf(tc) ?? ''),
@@ -70,5 +86,5 @@ export const TEST_CASE_CONTRACT_NODES: readonly TestCaseNodeDecl[] = [
     (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),
+    (tc) => classOf(tc) === 'opaque' || classOf(tc) === 'inconclusive', conformanceStep, undefined, acceptOpaque),
 ];

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

@@ -15,8 +15,9 @@
  * the reds the cases account for; unit.triage keeps the rest (unattributedReds), so a red no case
  * explains — an @cases row, a renamed scenario, a nested describe title — still gets a triage step.
  */
-import { ALL_KINDS, StepCore, TestCaseNodeDecl } from '../node-decl';
+import { ALL_KINDS, humanStep, StepCore, TestCaseNodeDecl } from '../node-decl';
 import type { UnitState } from '../../harness/next-step';
+import type { HumanAction } from '../human-action';
 import type { TestCaseState } from '../test-case-state-shape';
 import { exemptionOf, TestCaseNeed, triggerOf } from '../test-case-satisfied';
 
@@ -31,15 +32,28 @@ const withRule = (cases: TestCaseState[]): string =>
   `${cases.slice(0, 3).map((c) => `${c.id}: ${c.triage?.ruleId}`).join('; ')}${cases.length > 3 ? '; …' : ''}`;
 
 function caseNode(id: string, need: TestCaseNeed, rank: number, title: string, actor: TestCaseNodeDecl['actor'],
-  step: (s: UnitState, cases: TestCaseState[], single: boolean) => StepCore, produces: string[]): TestCaseNodeDecl {
+  step: (s: UnitState, cases: TestCaseState[], single: boolean) => StepCore, produces: string[], human?: TestCaseNodeDecl['human']): TestCaseNodeDecl {
   return {
     id, title, actor, granularity: 'test-case', appliesTo: ALL_KINDS, requires: ['unit.run'], blocking: false, rank,
     gates: [], produces, step,
     active: (_s, tc) => triggerOf(tc) === need,
     satisfied: (_s, tc) => exemptionOf(tc) !== null,
+    ...(human ? { human } : {}),
   };
 }
 
+/**
+ * A red triage left unclassified is a human's to classify (#928): test-defect and environment take it
+ * off the product-defect path, so they need a person on a terminal. One action per such case (#954).
+ */
+function classifyByHand(s: UnitState, _step: StepCore, cases: TestCaseState[]): HumanAction[] {
+  return cases.filter((c) => c.triage?.class === 'unclassified').map((c) => ({
+    kind: 'triage-classify',
+    command: `sungen triage ${flag(s)} ${s.unit} --case ${c.id} --as "<test-defect|environment>" --reason "…"`,
+    reason: `${c.id} failed and \`sungen triage\` left it unclassified — read its evidence (trace, error), then classify it: test-defect or environment take it off the product-defect path, so a human types them on a terminal (\`--as product\` anyone may record)`,
+  }));
+}
+
 export const TEST_CASE_NODES: readonly TestCaseNodeDecl[] = [
   caseNode('tc.run', 'run', 131, 'Run the cases that never ran', 'ai', (s, cases) => ({
     kind: 'do',
@@ -58,19 +72,19 @@ export const TEST_CASE_NODES: readonly TestCaseNodeDecl[] = [
       command: `sungen triage ${flag(s)} ${s.unit}`,
       because: `${cases.length} test case(s) failed in the latest run and are not classified yet${left ? ` (${left} left unclassified by the last triage — read its evidence and classify by hand: \`sungen triage ${flag(s)} ${s.unit} --case <id> --as product|test-defect|environment --reason "…"\`; test-defect and environment are a human's call, on a terminal)` : ''} — classify each (known defect, test defect, environment, product candidate) before exporting or extending: an unexplained red in the deliverable is a finding nobody has judged`,
     };
-  }, ['.sungen/triage/<unit>.json']),
+  }, ['.sungen/triage/<unit>.json'], classifyByHand),
   caseNode('tc.product-candidate', 'product-candidate', 134, 'Decide on the product-defect candidates', 'human', (s, cases, single) => ({
     kind: 'decide',
     command: `sungen defect draft ${flag(s)} ${s.unit}${single ? ` --scenario ${cases[0].id}` : ''}`,
     because: `${cases.length} red test case(s) look like a product defect (${listed(cases)}) — the app answered and the answer differs from the oracle. A QA decides whether it is a defect to record; an agent presents it and does not draft it on its own`,
-  }), ['qa/defects/DEF-<n>-<slug>.md']),
+  }), ['qa/defects/DEF-<n>-<slug>.md'], humanStep('defect-draft')),
   // decide, not do: an agent re-running into an environment that is still down gets the same red and
   // the same step again — a loop with no stop. A human confirms the environment first (#928 review W3).
   caseNode('tc.rerun-environment', 'rerun-environment', 139, 'Re-run the cases the environment failed, once it is up', 'human', (s, cases) => ({
     kind: 'decide',
     command: `/sungen:run-test ${s.unit}${idsArg(cases)}`,
     because: `${cases.length} red test case(s) failed on the environment, not the app (${withRule(cases)}) — the run never reached a usable app, so their results say nothing about it yet. A human confirms the app, base URL, network, auth state or device is up, then they are re-run; an agent presents this and does not re-run on its own — into an environment that is still down, the same red comes back`,
-  }), ['specs/generated/<unit>/<unit>-test-result.json']),
+  }), ['specs/generated/<unit>/<unit>-test-result.json'], humanStep('rerun-environment')),
   caseNode('tc.fix-test', 'fix-test', 139.5, 'Fix the tests triaged as test defects', 'ai', (s, cases) => ({
     kind: 'do',
     command: `/sungen:run-test ${s.unit}${idsArg(cases)}`,

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

@@ -8,7 +8,7 @@
  *    9 unit.repair-findings   findings with a known repair → repair + re-audit, names ≤ 4 codes
  *   10 unit.gate-fail         gateStatus FAIL → blocked, cuts
  */
-import { ALL_KINDS, UnitNodeDecl } from '../node-decl';
+import { ALL_KINDS, humanStep, UnitNodeDecl } from '../node-decl';
 import type { UnitState } from '../../harness/next-step';
 
 /** The finding codes worth naming in a next step — each maps to a specific repair. */
@@ -66,6 +66,7 @@ export const UNIT_AUDIT_NODES: readonly UnitNodeDecl[] = [
       command: `sungen audit --screen ${s.unit} --accept-viewpoint`,
       because: 'test-viewpoint.md changed since the accepted baseline, so the ledger and traceability axes are not evidence until a QA confirms the new declaration. A decision, not a step: an agent presents it and does not run it — accepting the yardstick you just wrote makes both axes read 100% by construction',
     }),
+    human: humanStep('accept-viewpoint'),
   },
   {
     id: 'unit.repair-findings', title: 'Repair the named findings', actor: 'ai', granularity: 'unit',

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

@@ -16,8 +16,9 @@
  * A free / impl:code scenario only its TRACE cannot prove — unproven, inconclusive, opaque — is not a
  * unit decision: the case nodes say what proves it (test-case-contract-nodes.ts, phase 09).
  */
-import { ALL_KINDS, StepCore, UnitNodeDecl, unitKindDir } from '../node-decl';
+import { ALL_KINDS, humanStep, StepCore, UnitNodeDecl, unitKindDir } from '../node-decl';
 import type { UnitState } from '../../harness/next-step';
+import type { HumanActionKind } from '../human-action';
 
 const HUMAN_ONLY = 'A QA decision on a terminal: an agent presents it and never approves its own edit';
 const approveCmd = (s: UnitState): string => `sungen contract approve --screen ${s.unit}`;
@@ -50,6 +51,10 @@ function contractStep(s: UnitState): StepCore {
   return { kind: 'decide', command: approveCmd(s), because: `${c.review} approved scenario(s) changed since QA approved them (changed, not weaker) — review blocks \`sungen delivery\` until QA re-approves. ${HUMAN_ONLY}` };
 }
 
+/** What the human does for the step contractStep offered: approve, commit / restore through review, or read the verdict. */
+const contractActionKind = (command: string): HumanActionKind =>
+  command.startsWith('sungen contract approve') ? 'contract-approve' : command.startsWith('sungen contract check') ? 'contract-review' : 'contract-commit';
+
 const CONTRACT_RULES = ['contract.hash-changed', 'contract.oracle-weakened', 'contract.target-changed', 'contract.assertion-lost', 'contract.lock-uncommitted'];
 /** The verdict is a pass and it was built: nothing blocks, nothing to repair. */
 const verdictClean = (s: UnitState): boolean => !s.contract!.error && s.contract!.verdict === 'pass';
@@ -67,6 +72,11 @@ export const UNIT_CONTRACT_NODES: readonly UnitNodeDecl[] = [
     active: (s) => Boolean(s.contract),
     satisfied: nothingToDecide,
     step: contractStep,
+    human: (_s, step) => {
+      const kind = contractActionKind(step.command);
+      // A lock repair is a commit (or `git checkout --`) after review — prose, never a sungen command to copy.
+      return [{ command: step.command, reason: step.because, kind, ...(kind === 'contract-commit' ? { instruction: true as const } : {}) }];
+    },
     // 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
@@ -85,5 +95,6 @@ export const UNIT_CONTRACT_NODES: readonly UnitNodeDecl[] = [
       command: approveCmd(s),
       because: `${s.contract!.proposed} scenario(s) have no approved contract yet — approving locks the checks QA reviewed, so a later edit that weakens one (a healer's included) fails \`sungen contract check\`. ${HUMAN_ONLY}; proposed scenarios do not block`,
     }),
+    human: humanStep('contract-approve'),
   },
 ];

package/src/graph/unit-artifact-probes.ts

@@ -9,6 +9,7 @@ import { parse as parseYaml } from 'yaml';
 import { featureFilesFor } from '../harness/unit-paths';
 import { readTextFile } from '../harness/read-text';
 import { loadPlaywrightReport } from '../exporters/playwright-report-parser';
+import { isDraftDeliverable } from '../exporters/csv-exporter';
 
 /** `<f>-test-result[.<os>][.<env>].json` — a mobile run writes the OS into the name, an env run the env (#868). */
 export const RESULT_FILE = /-test-result(?:\.[^.]+)*\.json$/;
@@ -72,6 +73,7 @@ export function countFailedResults(resultFiles: string[]): number {
 
 export function hasDeliverableFor(projectRoot: string, slug: string): boolean {
   try {
-    return fs.readdirSync(path.join(projectRoot, 'qa', 'deliverables')).some((f) => f.startsWith(`${slug}-`));
+    // A `--preview` DRAFT is not a deliverable (#965).
+    return fs.readdirSync(path.join(projectRoot, 'qa', 'deliverables')).some((f) => f.startsWith(`${slug}-`) && !isDraftDeliverable(f));
   } catch { return false; }                                    // nothing exported yet
 }