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

package/src/cli/commands/audit.ts

@@ -30,7 +30,7 @@ function render(r: AuditReport): void {
   L('');
   L(`  Quality score (business-weighted): ${r.score.overall}/10   [Viewpoint Gate: ${r.gateStatus}]`);
   L(`  Intent: focus=${r.intent.focus} · depth threshold ${r.depth.threshold.toFixed(2)} (${r.intent.source})`);
-  L(`  Provenance: sungen ${r.provenance.sungenVersion} · catalog ${r.provenance.catalogHash}  (same here on every machine → same score)`);
+  L(`  Provenance: sungen ${r.provenance.sungenVersion} · catalog ${r.provenance.catalogHash} · rules ${r.provenance.rulesHash}  (same rules on every machine → same score)`);
   // Print the axes the score was ACTUALLY built from — a fixed five-line block omitted a flow's
   // `flowCoverage`, `specFR` and `atomicLedger` while showing `balance`, which a contract flow
   // does not score on.

package/src/cli/commands/contract-derive-command.ts

@@ -2,14 +2,17 @@
  * `sungen contract derive --screen <u> [--grep <re>] [--json]` (DOS-14.8, phase 08): free tests'
  * traces → `features/<u>.free.feature`, every scenario `@free @proposed`, deterministic, no LLM.
  *
- *   exit 0  written, unchanged, nothing to derive, or a mobile project (not supported yet)
- *   exit 1  refused (a secret or a machine path would have been written — nothing was), or an error
+ *   exit 0  written, unchanged, every scenario already approved, or a mobile project (not supported yet)
+ *   exit 1  nothing to derive (no admissible trace — each skipped test says why, #932), refused (a
+ *           secret or a machine path would have been written — nothing was), refused because two
+ *           recorded tests claim one id (#962 — both named, nothing written), or an error
  */
 import type { Command } from 'commander';
 import * as path from 'path';
-import { deriveFreeFeature, DeriveResult } from '../../contract/derive-free-feature';
+import { deriveFreeFeature, DeriveResult, nothingDerived } from '../../contract/derive-free-feature';
 import { registeredTraceResolver } from '../../contract/resolve-unit-trace-identities';
 import { resolveContractUnit } from '../../contract/contract-units';
+import { withProjectInvocation } from '../project-sungen-invocation';
 
 function print(r: DeriveResult, unit: string): void {
   const L = console.log;
@@ -18,20 +21,29 @@ function print(r: DeriveResult, unit: string): void {
   L(`━━━ Contract derive: ${unit} — free tests' traces → ${rel} ━━━`);
   L('');
   if (r.note) L(`  ⚠ ${r.note}`);
+  for (const w of r.warnings ?? []) L(`  ⚠ ${w}`);
   for (const s of r.scenarios) L(`  + ${s.title}  (${s.steps} steps${s.low ? `, ${s.low} low identity` : ''}${s.opaque ? `, ${s.opaque} opaque` : ''})`);
   for (const s of r.skipped) L(`  - ${s.id}  skipped: ${s.reason}`);
-  if (r.refused?.length) {
+  if (r.duplicateIds?.length) {
+    L("  ✗ Refused — nothing was written. One ID names one test: keeping one would silently drop the other's contract.");
+    for (const d of r.duplicateIds) {
+      L(`    ${d.tests.length} recorded tests claim ${d.id}:`);
+      for (const t of d.tests) L(`      ${t}`);
+      if (d.staleRecords?.length) L(`    If that test is gone, delete ${d.staleRecords.join(', ')} — an older run's record (free tests now record under test-results-free/).`);
+    }
+    L("    Give each test its own ID (its title's leading ID, or its @tag), run the free tests again with trace on, then derive.");
+  } else if (r.refused?.length) {
     L(`  ✗ Refused — nothing was written. ${r.refused.length} likely secret(s) / machine path(s):`);
     for (const h of r.refused) L(`      ${h.where} — ${h.reason}`);
     L('    Move the value into test-data (or an env overlay) and use it from there, then derive again.');
   } else if (r.written) {
     L(`  ✓ Wrote ${rel}. Review the steps (they ARE the contract), then QA approves on a terminal:`);
-    L(`    sungen contract approve --screen ${unit}`);
+    L(`    ${withProjectInvocation(`sungen contract approve --screen ${unit}`, process.cwd())}`);
     L('  After approval, re-run the free tests (trace: "on") — a trace older than the contract proves nothing.');
   } else if (r.scenarios.length) {
     L(`  = ${rel} is already up to date.`);
-  } else if (!r.note) {
-    L(`  = Nothing to derive: no admissible trace of a test for ${unit} (try --grep).`);
+  } else if (nothingDerived(r)) {
+    L(`  ✗ Nothing to derive: no admissible trace of a test for ${unit}${r.skipped.length ? ' (each skipped test above says why)' : ' (try --grep)'}.`);
   }
   L('');
 }
@@ -51,7 +63,7 @@ export function registerDeriveCommand(contract: Command): void {
           projectRoot: process.cwd(), unit, grep: options.grep ? String(options.grep) : undefined, resolver: registeredTraceResolver() ?? null,
         });
         if (options.json) console.log(JSON.stringify(r, null, 2)); else print(r, unit.name);
-        process.exit(r.refused?.length ? 1 : 0);
+        process.exit(r.refused?.length || r.duplicateIds?.length || nothingDerived(r) ? 1 : 0);
       } catch (error) {
         console.error('Error:', error instanceof Error ? error.message : error);
         process.exit(1);

package/src/cli/commands/contract.ts

@@ -4,6 +4,9 @@
  *   approve --screen <u> [--scenario <id>] [--reason <text>]
  *       a human types a confirmation on a TTY; writes contracts.lock.yaml + a contract-approval
  *       decision. No TTY → refused with the exact command (exit 1).
+ *   approve --screen <u> --scenario <id> --accept-opaque [--reason <text>]
+ *       the same human act for the reviewed opaque trace steps of one approved free / impl:code
+ *       scenario (#923): bound to each step as it reads now (accept-opaque-steps.ts).
  *   check --screen <u> [--trace] [--json]
  *       rebuilds the verdict from .feature + lock + git HEAD + recorded traces (never from a report),
  *       writes .sungen/reports/<slug>-contract.json as output (secret-scanned first). Exit 2 on a hard
@@ -17,6 +20,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { approveContract } from '../../contract/approve-contract';
 import { buildContractVerdict, ContractVerdict } from '../../contract/build-contract-verdict';
+import { LOW_IDENTITY_FINDING } from '../../contract/classify-trace-conformance';
 import { contractReportPath, writeContractReport } from '../../contract/contract-report-file';
 import { HARD_CLASSES, REVIEW_CLASSES } from '../../contract/contract-schema';
 import { processIO } from '../../decisions/human-confirmation';
@@ -24,6 +28,7 @@ import { resolveContractUnit } from '../../contract/contract-units';
 import { secretScanHits } from '../../contract/field-semantic-redaction';
 import { resolveUnitTraceIdentities } from '../../contract/resolve-unit-trace-identities';
 import { registerDeriveCommand } from './contract-derive-command';
+import { withProjectInvocationInText } from '../project-sungen-invocation';
 
 const MARK: Record<string, string> = {
   match: '✓', strengthened: '↑', proposed: '+', 'hash-changed': '⚖', 'oracle-weakened': '✗', 'target-changed': '✗', 'assertion-lost': '✗',
@@ -31,10 +36,17 @@ const MARK: Record<string, string> = {
 };
 /** `contract check` judges traces with a generous deadline (the guard path keeps ~3 s). */
 const CHECK_TRACE_BUDGET_MS = 120_000;
-const UNPROVEN_HINT = "    → free / impl:code tests need trace: 'on' and the sungen run-record reporter, then a fresh run (see `sungen contract derive`).";
+const UNPROVEN_HINT = "    → free / impl:code tests need their own config (outputDir 'test-results-free', trace: 'on', the sungen run-record reporter), then a fresh run (see `sungen contract derive`).";
 
-function printVerdict(v: ContractVerdict, reportFile: string): void {
-  const L = console.log;
+/** The command that recompiles a unit's spec — `sungen generate --screen|--flow|--api <unit>`. */
+function generateCommand(unit: { name: string; dir: string }): string {
+  const kind = path.relative(path.join(process.cwd(), 'qa'), unit.dir).split(path.sep)[0];
+  return `sungen generate --${kind === 'flows' ? 'flow' : kind === 'api' ? 'api' : 'screen'} ${unit.name}`;
+}
+
+function printVerdict(v: ContractVerdict, reportFile: string, generate: string): void {
+  // The approve / --accept-opaque / generate lines as this project runs sungen (#963).
+  const L = (line: string): void => console.log(withProjectInvocationInText(line, process.cwd()));
   const head = v.verdict === 'pass' ? '✓ PASS' : v.verdict === 'review'
     ? '⚖ REVIEW — changed, not weaker. Exit 0 here, but review blocks `sungen delivery` until QA re-approves' : '✗ FAIL';
   L('');
@@ -64,7 +76,19 @@ function printVerdict(v: ContractVerdict, reportFile: string): void {
       : onlyUnproven ? "  → Re-run the free / impl:code tests with trace: 'on', then check again."
         : '  → Restore the approved checks in the .feature — or, if the change is intended, QA approves it on a terminal:');
   }
-  if (v.verdict !== 'pass' && !v.uncommitted.length && !onlyUnproven) L(`    sungen contract approve --screen ${v.unit}`);
+  // An opaque step is not cleared by re-approving (#923): QA reviews it, then accepts it as it reads now.
+  const acceptable = blocking.filter((s) => s.class === 'opaque' && s.trace?.opaque?.some((o) => !o.accepted)
+    && !s.findings.some((f) => f.detail.startsWith(LOW_IDENTITY_FINDING)));
+  if (v.verdict !== 'pass' && !v.uncommitted.length && !onlyUnproven && acceptable.length < blocking.length) L(`    sungen contract approve --screen ${v.unit}`);
+  for (const s of acceptable) {
+    L(`  → ${s.id}: QA reviews each opaque step above (verbatim, file:line); to accept them as they read now, on a terminal:`);
+    L(`    sungen contract approve --screen ${v.unit} --scenario ${s.id} --accept-opaque`);
+  }
+  // A weakened compiled scenario also leaves its spec out of step (#943): name the command that fixes the drift.
+  // (A free / impl:code scenario carries a trace summary; its test is hand-written, never regenerated.)
+  if (v.verdict === 'fail' && !v.uncommitted.length && v.scenarios.some((s) => !s.trace && HARD_CLASSES.has(s.class))) {
+    L(`  → After fixing the scenario, run \`${generate}\`: until the compiled spec is regenerated, \`sungen script-check\` reports drift.`);
+  }
   L(`  Report: ${path.relative(process.cwd(), reportFile)}`);
   L('');
 }
@@ -85,15 +109,25 @@ export function registerContractCommand(program: Command): void {
     .option('-s, --screen <name>', 'Screen / flow / api unit name')
     .option('--scenario <id>', 'Approve one scenario only (its ID, e.g. VP-LOGIN-001)')
     .option('--reason <text>', 'Why (recorded in the contract-approval decision)')
+    .option('--accept-opaque', 'With --scenario: accept the reviewed opaque trace step(s) of one approved free / impl:code scenario')
     .action(async (options) => {
       try {
         const unit = unitOrThrow(options.screen);
-        const r = await approveContract({ projectRoot: process.cwd(), unit: unit.name, scenario: options.scenario, reason: options.reason, io: processIO() });
+        const r = await approveContract({
+          projectRoot: process.cwd(), unit: unit.name, scenario: options.scenario, reason: options.reason, acceptOpaque: options.acceptOpaque === true, io: processIO(),
+        });
         if (r.status === 'nothing-to-approve') { console.log(`\n= Nothing to approve: every chosen scenario of ${unit.name} already matches its approved lock entry.\n`); return; }
+        if (r.status === 'nothing-to-accept') { console.log(`\n= Nothing to accept: every opaque step of ${options.scenario} is already accepted as it reads now.\n`); return; }
+        if (r.status === 'accepted') {
+          console.log(`\n✓ Accepted ${r.accepted?.length ?? 0} opaque step(s) of ${options.scenario} → ${path.relative(process.cwd(), r.lockPath)} (decision ${r.decisionId})`);
+          console.log('  Commit the lock and the decision through review, then re-run the free test with its trace: a trace older than the lock proves nothing.\n');
+          return;
+        }
         console.log(`\n✓ Approved ${r.approved.length} scenario(s)${r.removed.length ? `, removed ${r.removed.length}` : ''} → ${path.relative(process.cwd(), r.lockPath)} (decision ${r.decisionId})`);
         console.log('  Commit the lock and the decision through review: until they are in git HEAD, `sungen contract check` reports contract.lock-uncommitted.\n');
       } catch (error) {
-        console.error('Error:', error instanceof Error ? error.message : error);
+        // A refusal names the command a human runs instead: as this project runs sungen (#963).
+        console.error('Error:', error instanceof Error ? withProjectInvocationInText(error.message, process.cwd()) : error);
         process.exit(1);
       }
     });
@@ -116,7 +150,7 @@ export function registerContractCommand(program: Command): void {
         if (hits.length) throw new Error(`Refused to write the contract report — likely secret(s): ${hits.map((h) => `${h.where} ${h.reason}`).join('; ')}`);
         const file = writeContractReport(process.cwd(), verdict);
         if (options.json) console.log(JSON.stringify(verdict, null, 2));
-        else printVerdict(verdict, file);
+        else printVerdict(verdict, file, generateCommand(unit));
         process.exit(verdict.exitCode);
       } catch (error) {
         // Unreadable = not run (DOS-14.0): an earlier report must not outlive the inputs it judged.

package/src/cli/commands/delivery.ts

@@ -17,6 +17,7 @@ import { mergeFeatureAndSpec } from '../../exporters/scenario-merger';
 import {
   buildTestCaseRows,
   buildSummary,
+  deliverableBasename,
   renderCsv,
   writeCsv,
 } from '../../exporters/csv-exporter';
@@ -41,11 +42,16 @@ import { MatrixFinding } from '../../exporters/matrix/types';
 import { applyManualCarry, ManualCarryReport, PriorManualResults, readPriorManualResults } from '../../exporters/matrix/carry-manual-results';
 import { formatTestOutcome, resultTotals } from '../../exporters/matrix/result-totals';
 import { readCapabilities } from '../../harness/capability';
+import { splitFeatureBlocks } from '../../contract/free-feature-blocks';
 import { processIO } from '../../decisions/human-confirmation';
 import { DeliveryDecisionGate } from '../../harness/gates/delivery-decision-gate';
 import { runDeliveryDecisionStep } from '../../harness/gates/delivery-decision-step';
 import { deliverableGateOverrides, InRunAcceptance } from '../../harness/gates/gate-override-report';
 import { ChecklistUnit, renderChecklist, unitChecklist } from '../../harness/gates/delivery-checklist';
+import { withProjectInvocationInText } from '../project-sungen-invocation';
+import { freeRunCommand, freeRunHasResults, generatedSubdir, plainRunCommand } from '../run-command-hints';
+import { isHandWritten } from '../../harness/parse';
+import { FREE_RUN_DIR } from '../../contract/trace/trace-run-record';
 
 const COLOR = {
   reset: '\x1b[0m',
@@ -101,14 +107,30 @@ function makeTarget(screen: string, featureBaseName: string, kind: UnitKind): De
 }
 
 /**
- * List all `.feature` files inside a screen/flow/api unit as separate targets.
- * Returns empty array when the directory has no features yet.
+ * A derived `*.free.feature` none of whose scenarios QA has approved yet (every one still `@proposed`):
+ * a proposal, not a delivery unit — counted as one, it ended in "Not exported" (#939). Approving a
+ * scenario drops its tag (`contract approve`), and from then on the file is a unit like any other.
+ */
+function proposalOnly(featureFile: string): boolean {
+  if (!featureFile.endsWith('.free.feature')) return false;
+  try {
+    // No scenario block at all (empty, or not Gherkin) is not a proposal: it stays listed and the preflight names it.
+    const blocks = splitFeatureBlocks(fs.readFileSync(featureFile, 'utf8'));
+    return blocks.length > 0 && blocks.every((b) => b.proposed);
+  } catch {
+    return false;   // unreadable: listed, so the preflight names the problem
+  }
+}
+
+/**
+ * List all `.feature` files inside a screen/flow/api unit as separate targets — a proposal-only
+ * free feature excepted. Returns empty array when the directory has no features yet.
  */
 function listFeatureTargets(cwd: string, screen: string, kind: UnitKind): DeliveryTarget[] {
   const featuresDir = path.join(cwd, 'qa', qaParent(kind), screen, 'features');
   if (!fs.existsSync(featuresDir)) return [];
   return fs.readdirSync(featuresDir)
-    .filter((f) => f.endsWith('.feature'))
+    .filter((f) => f.endsWith('.feature') && !proposalOnly(path.join(featuresDir, f)))
     .map((f) => makeTarget(screen, f.slice(0, -'.feature'.length), kind))
     .sort((a, b) => a.featureBaseName.localeCompare(b.featureBaseName));
 }
@@ -169,8 +191,7 @@ function qaDir(cwd: string, target: DeliveryTarget): string {
 // dashboard snapshot builder loads the identical contract (shared + unit merge).
 
 function generatedDir(cwd: string, target: DeliveryTarget): string {
-  const sub = target.kind === 'flow' ? path.join('flows', target.screen) : target.kind === 'api' ? path.join('api', target.screen) : target.screen;
-  return path.join(cwd, 'specs', 'generated', sub);
+  return path.join(cwd, generatedSubdir(target.kind, target.screen));
 }
 
 // ----------------------------------------------------------------------------
@@ -233,6 +254,9 @@ export function runPreflight(cwd: string, target: DeliveryTarget): PreflightChec
   const selectorsFile = path.join(base, 'selectors', `${target.featureBaseName}.yaml`);
   const specFile = path.join(genBase, `${target.featureBaseName}.spec.ts`);
   const resultsFile = resolveResultsPath(cwd, target);
+  // A derived `*.free.feature` is implemented by hand-written tests (DOS-14.8): no selectors, never compiled,
+  // run with the project's free-test config into its own outputDir — so its hints are that run's (#964).
+  const free = isHandWritten([], featureFile);
 
   const featureOk = checkFeatureReal(featureFile);
   // test-data is only REQUIRED when the feature actually references a
@@ -243,9 +267,9 @@ export function runPreflight(cwd: string, target: DeliveryTarget): PreflightChec
     ? checkTestDataHasVars(testDataFile)
     : true;
   // API units have no DOM → no selectors; the catalog (apis.yaml) is the contract. N/A, not missing.
-  const selectorsOk = target.kind === 'api' ? true : checkSelectorsHasEntries(selectorsFile, target.featureBaseName);
-  const specOk = fs.existsSync(specFile);
-  const resultsOk = resultsFile !== null;
+  const selectorsOk = target.kind === 'api' || free ? true : checkSelectorsHasEntries(selectorsFile, target.featureBaseName);
+  const specOk = free || fs.existsSync(specFile);
+  const resultsOk = free ? freeRunHasResults(cwd) : resultsFile !== null;
 
   const label = target.isFlow ? `flow/${target.featureBaseName}` : target.featureBaseName;
   const missing: string[] = [];
@@ -267,13 +291,15 @@ export function runPreflight(cwd: string, target: DeliveryTarget): PreflightChec
     missing.push(`compiled .spec.ts missing (optional — needed to run): ${path.relative(cwd, specFile)}`);
     suggestions.push(`sungen generate --${target.kind === 'flow' ? 'flow' : target.kind === 'api' ? 'api' : 'screen'} ${target.screen}`);
   }
-  if (!resultsOk) {
+  if (!resultsOk && free) {
+    missing.push(`free-test results missing (optional): ${FREE_RUN_DIR}/`);
+    suggestions.push(freeRunCommand(cwd));
+  } else if (!resultsOk) {
     const env = process.env.SUNGEN_ENV;
     const envSuffix = env ? `.${env}` : '';
     missing.push(`test-result${envSuffix}.json missing (optional)`);
     const genRel = path.relative(cwd, genBase);
-    const envPrefix = env ? `SUNGEN_ENV=${env} ` : '';
-    suggestions.push(`${envPrefix}PLAYWRIGHT_JSON_OUTPUT_NAME=${genRel}/${target.featureBaseName}-test-result.json npx playwright test ${genRel}/${target.featureBaseName}.spec.ts`);
+    suggestions.push(plainRunCommand(genRel, target.featureBaseName, env));
   }
 
   return {
@@ -711,6 +737,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)})`);
@@ -729,11 +757,13 @@ async function exportMatrixTarget(
   // counted, so this line, the workbook's totals and the summary table all agree (#891). A file
   // that cannot be read is reported where it matters — when it would be overwritten.
   const format = opts.format ?? 'xlsx';
+  // A draft (DRAFT banner) is written to its own `…-testcases.DRAFT.<ext>`, never onto the official file (#965).
+  const draft = model.manifest.approvalState === 'draft';
   let prior: PriorManualResults | null = null;
   let priorError: Error | null = null;
   try { prior = await readPriorManualResults(deliverableXlsxPath(cwd, paths.unit)); }
-  // A CSV-only export overwrites no workbook, so an unreadable one only means "nothing to carry".
-  catch (e) { if (format !== 'csv') priorError = e as Error; }
+  // A CSV-only export or a draft overwrites no official workbook, so an unreadable one only means "nothing to carry".
+  catch (e) { if (format !== 'csv' && !draft) priorError = e as Error; }
   applyManualCarry(model, prior);
   model.gateOverrides = deliverableGateOverrides(decisions?.overridesFor(qaDir(cwd, target)) ?? [], hasReview(model.findings), decisions?.acceptedInRun);
 
@@ -783,6 +813,9 @@ async function exportMatrixTarget(
   const failed = model.items.reduce((a, i) => a + i.resultCounts.failed, 0);
   const written = [xlsxPath, csvPath].filter((p): p is string => !!p).map((p) => path.relative(cwd, p));
   for (const rel of written) log(`  ${COLOR.green}→ ${rel}${COLOR.reset}`);
+  if (draft) {
+    log(`  ${COLOR.yellow}draft only — not a deliverable:${COLOR.reset} it carries the DRAFT banner, and the official ${deliverableBasename(paths.unit)} file was neither written nor changed.`);
+  }
   if (manualCarry) printManualCarry(manualCarry);
   return {
     label: paths.label,
@@ -910,7 +943,8 @@ async function printDeliveryChecklist(cwd: string, targets: DeliveryTarget[], ac
   const rows: Array<{ label: string; boxes: Awaited<ReturnType<typeof unitChecklist>> }> = [];
   for (const u of units.values()) rows.push({ label: u.label, boxes: await unitChecklist(cwd, u, accepted) });
   log('');
-  for (const line of renderChecklist(rows)) log(line);
+  // Each box's fix command as this project runs sungen (#963).
+  for (const line of renderChecklist(rows)) log(withProjectInvocationInText(line, cwd));
 }
 
 // ----------------------------------------------------------------------------
@@ -929,7 +963,7 @@ export function registerDeliveryCommand(program: Command): void {
     .option('--full', 'Alias of --legacy')
     .option('--check', 'Matrix gates only — validate the delivery map, write nothing')
     .option('--approve [ids]', 'Approve proposed groups (all, or a comma-separated id list) + stamp fingerprints')
-    .option('--preview', 'Render the matrix despite review-required findings (DRAFT watermark)')
+    .option('--preview', 'Render the matrix despite review-required findings — a DRAFT (watermarked) written to <unit>-testcases.DRAFT.*, never onto the official file')
     .option('--format <format>', 'Matrix output format: xlsx (default) | csv | both', 'xlsx')
     .option('--accept-in-run', 'Deliver despite gate-overrides/waivers/approvals recorded during the run (decision.in-run) — a human confirms on a terminal')
     .action(async (names: string[], options: {
@@ -1023,7 +1057,8 @@ export function registerDeliveryCommand(program: Command): void {
         }
         if (options.approve === undefined) {
           const gate = await runDeliveryDecisionStep({
-            projectRoot: cwd, acceptInRun: !!options.acceptInRun, io: processIO(), log,
+            // The accept-in-run command and its refusal as this project runs sungen (#963).
+            projectRoot: cwd, acceptInRun: !!options.acceptInRun, io: processIO(), log: (line) => log(withProjectInvocationInText(line, cwd)),
             // --preview / --check soften only the matrix export; --legacy has no draft mode, so it always needs one.
             requireTrustedAudit: !!(options.legacy || options.full) || (!options.preview && !options.check),
             refs: toExport.map((t) => ({ label: t.isFlow ? `flow/${t.featureBaseName}` : t.featureBaseName, unitName: t.screen, unitDir: qaDir(cwd, t), resultsPath: resolveResultsPath(cwd, t) })),
@@ -1095,9 +1130,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/gate.ts

@@ -3,6 +3,7 @@ import * as path from 'path';
 import * as fs from 'fs';
 import { runGate, renderGate, GatePhase } from '../../harness/journey';
 import { findUnitDir } from '../resolve-unit';
+import { withProjectInvocationInText } from '../project-sungen-invocation';
 
 
 const PHASES: GatePhase[] = ['create', 'run', 'deliver'];
@@ -24,7 +25,7 @@ export function registerGateCommand(program: Command): void {
 
         const verdict = runGate(process.cwd(), name, phase);
         if (options.json) console.log(JSON.stringify(verdict, null, 2));
-        else console.log(renderGate(verdict));
+        else console.log(withProjectInvocationInText(renderGate(verdict), process.cwd()));   // waive / sign-off hints as the project runs sungen (#963)
 
         // Exit 2 on HALT — usable in CI / the orchestration loop to block the next phase.
         process.exit(verdict.status === 'halt' ? 2 : 0);

package/src/cli/commands/generate.ts

@@ -8,6 +8,7 @@ import { capabilityRegistry } from '../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 import { readCapabilities, writeCapabilities, driverMeta, loadDriverCatalog } from '../../harness/capability';
 import { isHandWritten } from '../../harness/parse';
+import { generatedSubdir, plainRunCommand } from '../run-command-hints';
 
 /**
  * Find .feature files recursively in a directory
@@ -255,8 +256,18 @@ export function registerGenerateCommand(program: Command): void {
           if (shown.length < ddWarnings.length) console.log(`   … and ${ddWarnings.length - shown.length} more (run with -v to list all)`);
         }
 
-        const nextStep = platform === 'mobile' ? 'npm run test:mobile' : 'npx playwright test --ui';
-        console.log(`Next step: ${nextStep}\n`);
+        // Never the interactive `--ui` (#939): an agent cannot drive it, and run-test is what records the results.
+        const unit = screenName || flowName || apiName;
+        const nextStep = platform === 'mobile' ? 'npm run test:mobile' : unit ? `/sungen:run-test ${unit}` : 'npx playwright test';
+        console.log(`Next step: ${nextStep}`);
+        // The plain run writes each feature's results where `sungen next` and `sungen delivery` read them (#964) —
+        // a bare `npx playwright test` wrote them to the config's default file, which neither reads.
+        if (platform !== 'mobile' && unit) {
+          const genRel = generatedSubdir(apiName ? 'api' : flowName ? 'flow' : 'screen', unit);
+          console.log('   or the plain run — it writes the results file `sungen next` and `sungen delivery` read:');
+          for (const f of featureFiles) console.log(`     ${plainRunCommand(genRel, path.basename(f, '.feature'))}`);
+        }
+        console.log('');
       } catch (error) {
         console.error('Error:', error instanceof Error ? error.message : error);
         process.exit(1);

package/src/cli/commands/journey.ts

@@ -1,10 +1,11 @@
 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';
+import { withProjectInvocationInText } from '../project-sungen-invocation';
 
 const collect = (value: string, previous: string[]): string[] => [...previous, value];
 
@@ -22,7 +23,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 +64,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');
@@ -77,12 +78,13 @@ export function registerJourneyCommand(program: Command): void {
           console.log(JSON.stringify(report, null, 2));
         } else {
           console.log('');
-          console.log(board);
+          console.log(withProjectInvocationInText(board, process.cwd()));
           console.log(`  Board: ${written ? path.relative(process.cwd(), written) : '(not written — read-only checkout)'}`);
           console.log('');
         }
       } catch (error) {
-        console.error('Error:', error instanceof Error ? error.message : error);
+        // A refusal names the command a human runs instead: as this project runs sungen (#963).
+        console.error('Error:', error instanceof Error ? withProjectInvocationInText(error.message, process.cwd()) : error);
         process.exit(1);
       }
     });

package/src/cli/commands/next.ts

@@ -9,8 +9,13 @@
  *   sungen next <unit> --case <id>    one test case: its state, and its steps after the blocking
  *                                     unit steps before them (OES-10.3)
  *   --json                            the same, machine-readable; steps add nodeId, granularity,
- *                                     testCase?, gates?; every older field is kept. stdout is the
- *                                     payload alone (#660, #836)
+ *                                     testCase?, gates?; the unit adds `results` (#942) and
+ *                                     `humanActions: [{command, reason, kind, rendered}]` (#954) —
+ *                                     `command` canonical, `rendered` as this project runs it (#963),
+ *                                     and `humanActionsHeldBy[Command]` when a blocking step holds them (#966);
+ *                                     every older field is kept. stdout is the payload alone (#660, #836)
+ * The text names the run the results come from and warns when they are older than the suite (#942),
+ * and ends with "Waiting for you": every pending human-only command, with why (#954).
  */
 import { Command } from 'commander';
 import * as fs from 'fs';
@@ -18,8 +23,13 @@ import * as path from 'path';
 import { CLI_GIT_TIMEOUT_MS, headSnapshot } from '../../contract/contract-git';
 import { testCaseStatusLabel } from '../../graph/test-case-satisfied';
 import { testCaseStates } from '../../graph/test-case-states';
+import { describeResultsRun } from '../../graph/unit-results-freshness';
 import { deriveSteps, NextStep, readUnitState, UnitState } from '../../harness/next-step';
 import { resolveUnit, resolveUnitCandidates, AmbiguousUnitError } from '../resolve-unit';
+import { withProjectInvocation, withProjectInvocationInText } from '../project-sungen-invocation';
+import { waitingForYouLines } from '../waiting-for-you-block';
+import { caseTriageLines } from '../case-triage-hint';
+import { testCaseNeed } from '../../graph/test-case-satisfied';
 
 /** 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 +45,25 @@ function allUnits(cwd: string): Array<{ name: string; kind: UnitState['kind']; d
   return out;
 }
 
-function renderSteps(steps: NextStep[]): void {
+/** Steps as text, each `sungen …` command — the reason's too (#963) — 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(`     ${st.because}`);
+    console.log(`  ${mark} ${withProjectInvocationInText(st.command, cwd)}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}`);
+    console.log(`     ${withProjectInvocationInText(st.because, cwd)}`);
   }
 }
 
-function render(s: UnitState): void {
+/**
+ * `--json`: each human action keeps its canonical `command` and adds `rendered` — the line a human runs in
+ * this project (`npx sungen …` with a local install; an instruction unchanged), as the text shows it (#963).
+ */
+function withRenderedHumanActions(s: UnitState, cwd: string): UnitState {
+  if (!s.humanActions) return s;
+  return { ...s, humanActions: s.humanActions.map((a) => ({ ...a, rendered: a.instruction ? a.command : withProjectInvocation(a.command, cwd) })) };
+}
+
+function render(s: UnitState, cwd: string): void {
   const L = console.log;
   L('');
   L(`━━━ Next steps: ${s.unit} (${s.kind}) ━━━`);
@@ -57,10 +77,16 @@ function render(s: UnitState): void {
   ].filter(Boolean);
   L(`  state: ${held.length ? held.join(' · ') : '(nothing yet)'}`);
   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}`);
+  else if (s.auditNotCounted) L(`  audit: ${s.auditNotCounted.state === 'stale' ? 'stale' : 'not trusted'} — ${withProjectInvocationInText(s.auditNotCounted.reason, cwd)}`);
+  if (s.results) {
+    L(`  results: ${s.results.files.length} file${s.results.files.length === 1 ? '' : 's'}, ${describeResultsRun(s.results)}`);
+    if (s.results.warning) L(`  ⚠ ${s.results.warning}`);
+  }
   L('');
-  renderSteps(s.steps);
+  renderSteps(s.steps, cwd);
   L('');
+  const waiting = waitingForYouLines(s.humanActions, cwd, s.humanActionsHeldBy, s.humanActionsHeldByCommand);
+  if (waiting.length) { for (const line of waiting) L(line); L(''); }
 }
 
 /** `--case <id>`: the case's state and its frontier. Exits 1 when the case cannot be found. */
@@ -84,13 +110,15 @@ function caseView(s: UnitState, cwd: string, unitDir: string, id: string, json:
   L('');
   L(`  test case: ${tc.title}${tc.unstableId ? '   (no VP-id — this id changes when the title does)' : ''}`);
   L(`  where:     ${tc.file}#L${tc.lines[0]}-L${tc.lines[1]}`);
-  L(`  status:    ${testCaseStatusLabel(tc)} · result ${tc.result}${tc.mocked && tc.result === 'passed' ? ' (mocked)' : ''}${tc.stale ? ` · stale: ${tc.stale}` : ''}${tc.triage ? ` · triage ${tc.triage.class}` : ''}`);
+  L(`  status:    ${testCaseStatusLabel(tc)} · result ${tc.result}${tc.mocked && tc.result === 'passed' ? ' (mocked)' : ''}${tc.stale ? ` · stale: ${tc.stale}` : ''}${tc.triage ? ` · triage ${tc.triage.class}${tc.triage.ruleId === 'manual' ? ` (by hand, ${tc.triage.decision})` : ''}` : ''}`);
   if (tc.contract) L(`  contract:  ${tc.contract.class}${tc.contract.uncommitted ? ' · lock entry not committed' : ''}${tc.contract.lowIdentity ? ' · low target identity' : ''}`);
   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)}`);
+  // "needs triage" names how to classify the red, even while a unit step holds its own step back (#966).
+  if (testCaseNeed(tc) === 'triage') for (const line of caseTriageLines(s, tc, steps, cwd)) L(line);
   L('');
 }
 
@@ -128,10 +156,11 @@ export function registerNextCommand(program: Command): void {
           });
         }
         if (o.json) {
-          console.log(JSON.stringify(states.length === 1 ? states[0] : states, null, 2));
+          const out = states.map((s) => withRenderedHumanActions(s, cwd));
+          console.log(JSON.stringify(out.length === 1 ? out[0] : out, 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);