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

package/src/cli/commands/contract.ts

@@ -0,0 +1,164 @@
+/**
+ * `sungen contract approve | check` — the Test Contract (DOS-14, phase 06a).
+ *
+ *   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
+ *       finding, 0 on pass or review, 1 on an error (unknown unit, untrusted lock, unparseable feature).
+ *       `--trace` first asks driver-ui (a real browser) for the target identities of free / impl:code
+ *       traces; without it the cached answers are used (DOS-14.5, 14.6).
+ *   derive --screen <u> [--grep <re>]   → contract-derive-command.ts (DOS-14.8)
+ */
+import { Command } from 'commander';
+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';
+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': '✗',
+  opaque: '◐', nondeterministic: '≈', inconclusive: '?', unproven: '✗',
+};
+/** `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 their own config (outputDir 'test-results-free', trace: 'on', the sungen run-record reporter), then a fresh run (see `sungen contract derive`).";
+
+/** 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('');
+  L(`━━━ Contract check: ${v.unit} — Gherkin vs the approved lock ━━━`);
+  L('');
+  L(`  verdict: ${head}`);
+  const matched = v.scenarios.filter((s) => s.class === 'match').length;
+  for (const s of v.scenarios.filter((x) => x.class !== 'match')) {
+    L(`  ${MARK[s.class] ?? '?'} ${s.id}  ${s.class}${s.class === 'proposed' ? ' (no approved entry — does not block)' : ''}`);
+    for (const f of s.findings) L(`      ${f.rule ? `[${f.rule}] ` : ''}${f.step ? `step ${f.step}: ` : ''}${f.detail}`);
+    if (s.trace?.hashes.length) L(`      trace: ${[...new Set(s.trace.hashes)].join(', ')} (${s.trace.runs.length} run(s))`);
+    if (s.class === 'unproven') L(UNPROVEN_HINT);
+  }
+  if (matched) L(`  ✓ ${matched} scenario(s) match the approved contract`);
+  const issue = (u: ContractVerdict['uncommitted'][number]): string =>
+    u.change === 'tampered' || u.change === 'unverified' ? `lock entry ${u.change}: ${u.detail}` : `lock entry ${u.change} and not committed`;
+  for (const u of v.uncommitted.slice(0, 10)) L(`  ✗ ${u.id}  ${issue(u)}  [contract.lock-uncommitted]`);
+  if (v.uncommitted.length > 10) L(`  ✗ … and ${v.uncommitted.length - 10} more lock entries that are not what QA approved and committed`);
+  for (const w of v.warnings) L(`  ⚠ ${w}`);
+  L('');
+  // Only missing / refused traces: re-approving cannot help, a fresh traced run can.
+  const blocking = v.scenarios.filter((s) => HARD_CLASSES.has(s.class) || REVIEW_CLASSES.has(s.class));
+  const onlyUnproven = blocking.length > 0 && blocking.every((s) => s.class === 'unproven');
+  if (v.verdict === 'fail') {
+    L(v.uncommitted.length
+      ? '  → Commit the approval (lock + decision) through review, or restore the lock from git (`git checkout -- <lock>`).'
+      : 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:');
+  }
+  // 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('');
+}
+
+function unitOrThrow(name: string | undefined): { name: string; dir: string } {
+  if (!name) throw new Error('Provide --screen <name>');
+  return resolveContractUnit(process.cwd(), name);
+}
+
+export function registerContractCommand(program: Command): void {
+  const contract = program
+    .command('contract')
+    .description('Test Contract (DOS-14): the Gherkin QA approved is the contract — lock it (TTY) and check the .feature was not weakened');
+
+  contract
+    .command('approve')
+    .description('Lock the current Gherkin as the approved contract — a human types a confirmation on a TTY')
+    .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, 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) {
+        // 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);
+      }
+    });
+
+  contract
+    .command('check')
+    .description('Compare the .feature with the approved lock on the strength ladder, and the lock with git HEAD')
+    .option('-s, --screen <name>', 'Screen / flow / api unit name')
+    .option('--trace', 'Resolve free / impl:code trace target identities with @sungen/driver-ui (a real browser) first')
+    .option('--json', 'Output the verdict as JSON')
+    .action(async (options) => {
+      let unit: { name: string; dir: string } | undefined;
+      try {
+        unit = unitOrThrow(options.screen);
+        const notes = options.trace ? await resolveUnitTraceIdentities(process.cwd(), unit) : [];
+        // The CLI may take its time; the guard (contractBlockers) keeps the ~3 s default.
+        const verdict = buildContractVerdict(process.cwd(), unit, { traceBudgetMs: CHECK_TRACE_BUDGET_MS });
+        verdict.warnings.push(...notes);
+        const hits = secretScanHits(JSON.stringify(verdict, null, 2), `${unit.name}-contract.json`);
+        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, generateCommand(unit));
+        process.exit(verdict.exitCode);
+      } catch (error) {
+        // Unreadable = not run (DOS-14.0): an earlier report must not outlive the inputs it judged.
+        if (unit) fs.rmSync(contractReportPath(process.cwd(), unit.name), { force: true });
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+
+  registerDeriveCommand(contract);
+}

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,6 +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',
@@ -96,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));
 }
@@ -164,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));
 }
 
 // ----------------------------------------------------------------------------
@@ -228,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
@@ -238,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[] = [];
@@ -262,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 {
@@ -660,7 +691,7 @@ export function matrixPathsFor(cwd: string, target: DeliveryTarget): MatrixTarge
 }
 
 function printFindings(findings: MatrixFinding[]): void {
-  const icon = { error: `${COLOR.red}✗`, review: `${COLOR.yellow}⚠`, warning: `${COLOR.gray}·` } as const;
+  const icon = { error: `${COLOR.red}✗`, review: `${COLOR.yellow}⚠`, warning: `${COLOR.gray}·`, info: `${COLOR.gray}i` } as const;
   for (const f of findings) {
     log(`  ${icon[f.severity]} [Gate ${f.gate}]${COLOR.reset} ${f.ref ? `${f.ref}: ` : ''}${f.message}`);
   }
@@ -685,9 +716,11 @@ async function exportMatrixTarget(
   target: DeliveryTarget,
   opts: { check?: boolean; preview?: boolean; format?: MatrixFormat },
   env: EnvironmentInfo,
+  decisions?: DeliveryDecisionGate,
 ): Promise<MatrixRunSummary | 'skipped' | null> {
   const paths = matrixPathsFor(cwd, target);
   paths.runEnv = matrixRunEnv(cwd, target, env, paths);
+  paths.gateRules = decisions?.rulesFor(qaDir(cwd, target));   // the unit's gate-overrides apply to its matrix gates
 
   // A feature whose scenarios are ALL @exploration probes has nothing to deliver —
   // skip it quietly (no map required) instead of demanding a reviewed grouping for
@@ -704,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)})`);
@@ -722,12 +757,15 @@ 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);
 
   log(`${COLOR.bold}${paths.label}${COLOR.reset} — ${model.manifest.itemCount} delivery item(s), ${model.manifest.variantCount} coverage variant(s), review: ${model.manifest.approvalState} (design), test outcome: ${formatTestOutcome(resultTotals(model.items))}`);
   {
@@ -775,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,
@@ -892,6 +933,20 @@ function printSummaryTable(summaries: ScreenSummary[]): void {
   }
 }
 
+/** T6: one checklist block per delivered unit, each box from what its command says now (delivery-checklist.ts). */
+async function printDeliveryChecklist(cwd: string, targets: DeliveryTarget[], accepted?: InRunAcceptance): Promise<void> {
+  const units = new Map<string, ChecklistUnit>();
+  for (const t of targets) {
+    const dir = qaDir(cwd, t);
+    if (!units.has(dir)) units.set(dir, { label: t.isFlow ? `flow/${t.screen}` : t.screen, unitName: t.screen, unitDir: dir, kind: t.kind, resultsPath: resolveResultsPath(cwd, t) });
+  }
+  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('');
+  // Each box's fix command as this project runs sungen (#963).
+  for (const line of renderChecklist(rows)) log(withProjectInvocationInText(line, cwd));
+}
+
 // ----------------------------------------------------------------------------
 // Command registration
 // ----------------------------------------------------------------------------
@@ -908,12 +963,13 @@ 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: {
       skipPreflight?: boolean; continueOnMissing?: boolean; env?: string;
       legacy?: boolean; full?: boolean; check?: boolean; approve?: boolean | string; preview?: boolean;
-      format?: string;
+      format?: string; acceptInRun?: boolean;
     }) => {
       try {
         // Same effect as running with SUNGEN_ENV=<env> — result-file resolution,
@@ -990,6 +1046,31 @@ export function registerDeliveryCommand(program: Command): void {
           .reduce<SecretScanResult>((a, r) => ({ hits: [...a.hits, ...r.hits], unscanned: [...a.unscanned, ...r.unscanned] }), { hits: [], unscanned: [] });
         for (const line of formatSecretScan(secretScan)) log(line);
 
+        // OES-11.3–11.5: decisions that do not verify, rejected overrides, a stale audit and in-run
+        // decisions stop the delivery before anything is written (approval only stamps the map).
+        let decisions: DeliveryDecisionGate | undefined;
+        // --approve only stamps a matrix map. With --legacy / --full it would skip this gate and
+        // fall through to the export, so the combination is refused before anything is written.
+        if (options.approve !== undefined && (options.legacy || options.full)) {
+          console.error(`${COLOR.red}--approve applies to the matrix deliverable only${COLOR.reset} — it cannot be combined with --legacy / --full`);
+          process.exit(1);
+        }
+        if (options.approve === undefined) {
+          const gate = await runDeliveryDecisionStep({
+            // 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) })),
+            argv: ['sungen', 'delivery', ...(names ?? []), ...(options.env ? ['--env', options.env] : []), ...(options.legacy || options.full ? ['--legacy'] : [])],
+          });
+          if (!gate) {
+            await printDeliveryChecklist(cwd, toExport);
+            process.exit(1);
+          }
+          decisions = gate;
+        }
+
         // 3. Export
         const legacy = options.legacy || options.full;
         if (!legacy) {
@@ -1035,21 +1116,26 @@ export function registerDeliveryCommand(program: Command): void {
           for (const target of toExport) {
             const s = await exportMatrixTarget(cwd, target, {
               check: options.check, preview: options.preview, format: format as MatrixFormat,
-            }, env);
+            }, env, decisions);
             if (s === 'skipped') continue; // all-@exploration feature — neither exported nor a failure
             if (s) matrixSummaries.push(s);
             else notExported.push(target.isFlow ? `flow/${target.featureBaseName}` : target.featureBaseName);
           }
           if (matrixSummaries.length > 0 && !options.check) printMatrixSummaryTable(matrixSummaries);
+          for (const line of decisions?.summaryLines() ?? []) log(line);
           printSkipSummary(skipped, notExported);
+          await printDeliveryChecklist(cwd, toExport, decisions?.acceptedInRun);
           // A named target that produced nothing is a failure. A sweep is a failure
           // only when it produced nothing at all — units still waiting for a map or
           // 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;
         }
@@ -1064,6 +1150,7 @@ export function registerDeliveryCommand(program: Command): void {
         // 4. Summary
         printSummaryTable(summaries);
         printSkipSummary(skipped, []);
+        await printDeliveryChecklist(cwd, toExport, decisions?.acceptedInRun);
         // Same rule as the matrix path: every attempted target in an explicit scope
         // must have produced a file; a sweep only fails when nothing was written.
         if (explicitScope ? summaries.length < toExport.length : summaries.length === 0) process.exit(1);

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

@@ -7,6 +7,8 @@ import { scanTestDataSecrets, formatSecretScan, type SecretScanResult } from '..
 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
@@ -20,7 +22,8 @@ function findFeatureFiles(dir: string): string[] {
     const fullPath = path.join(dir, entry.name);
     if (entry.isDirectory()) {
       files.push(...findFeatureFiles(fullPath));
-    } else if (entry.isFile() && entry.name.endsWith('.feature')) {
+    } else if (entry.isFile() && entry.name.endsWith('.feature') && !isHandWritten([], fullPath)) {
+      // A derived `*.free.feature` is a contract for hand-written tests — never compiled (DOS-14.8).
       files.push(fullPath);
     }
   }
@@ -253,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,13 @@
 import { Command } from 'commander';
 import * as path from 'path';
-import * as fs from 'fs';
-import { runJourney, waive, signoff, renderJourneyBoard, rollupJourney, renderRollupBoard } 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, 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];
 
 export function registerJourneyCommand(program: Command): void {
   program
@@ -12,22 +15,41 @@ export function registerJourneyCommand(program: Command): void {
     .description('Durable "you are here" board (#381): obligations + what-to-review + next, synthesised read-only from the audit report + ledger already on disk.')
     .option('-s, --screen <name>', 'Screen / flow / api unit name')
     .option('--all', 'Roll up every unit (screens + flows + api) into one board — the serial review surface for multi-unit fan-out')
-    .option('--waive <obligation>', 'Waive an obligation (e.g. OB-coverage) — requires --reason')
-    .option('--reason <text>', 'The reason a waived obligation is acceptable (mandatory with --waive)')
-    .option('--signoff', 'Sign off the review queue — the single human gate (allowed only when every other obligation is satisfied/waived)')
+    .option('--waive <obligation>', 'Waive an obligation (e.g. OB-coverage) — requires --reason; a human types a confirmation on a TTY')
+    .option('--reason <text>', 'Why: mandatory with --waive and --decide')
+    .option('--decide <kind>', `Record a decision (${DECIDE_KINDS.join(' | ')}) in qa/decisions/, or the unit's with --screen — a human types a confirmation on a TTY`)
+    .option('--text <text>', 'What was decided (with --decide)')
+    .option('--anchor <id>', 'Spec anchor the decision is about, e.g. SPEC-AUTH-001#A-2 (repeatable, with --decide)', collect, [])
+    .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); 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((options) => {
+    .action(async (options) => {
+      const io = processIO();
       try {
+        if (options.decide) {
+          if (options.screen && !findUnitDir(options.screen)) throw new Error(`Not found: qa/screens/${options.screen}, qa/flows/${options.screen}, or qa/api/${options.screen}`);
+          const r = await decideWithConfirmation({
+            projectRoot: process.cwd(), unit: options.screen, kind: options.decide, text: options.text, reason: options.reason,
+            anchors: options.anchor, payload: options.payload, visibility: options.visibility, supersedes: options.supersedes, io,
+          });
+          if (options.json) { console.log(JSON.stringify({ status: r.status, path: path.relative(process.cwd(), r.path), entry: r.entry }, null, 2)); return; }
+          console.log(`\n${r.status === 'created' ? '✓ Recorded' : '= Already recorded'} ${r.entry.id} → ${path.relative(process.cwd(), r.path)}`);
+          console.log('  Commit it through review: a decision not yet in git HEAD is flagged at delivery (decision.in-run).\n');
+          return;
+        }
+
         if (options.all) {
           const rows = rollupJourney(process.cwd());
           const board = renderRollupBoard(rows);
           const outDir = path.join(process.cwd(), '.sungen', 'journey');
-          fs.mkdirSync(outDir, { recursive: true });
-          fs.writeFileSync(path.join(outDir, '_rollup.json'), JSON.stringify(rows, null, 2), 'utf-8');
-          fs.writeFileSync(path.join(outDir, '_rollup.board.md'), board, 'utf-8');
+          // Derived files: a read-only checkout still gets the board (DOS-13.3).
+          writeJourneyFileBestEffort(path.join(outDir, '_rollup.json'), JSON.stringify(rows, null, 2));
+          const written = writeJourneyFileBestEffort(path.join(outDir, '_rollup.board.md'), board);
           if (options.json) console.log(JSON.stringify(rows, null, 2));
-          else { console.log(''); console.log(board); console.log(`  Board: ${path.relative(process.cwd(), path.join(outDir, '_rollup.board.md'))}`); console.log(''); }
+          else { console.log(''); console.log(board); console.log(`  Board: ${written ? path.relative(process.cwd(), written) : '(not written — read-only checkout)'}`); console.log(''); }
           return;
         }
 
@@ -35,29 +57,34 @@ export function registerJourneyCommand(program: Command): void {
         if (!name) throw new Error('Provide --screen <name> (or --all for the roll-up)');
         if (!findUnitDir(name)) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
 
+        // A migration killed half-way (T6): a human answers REVERT or KEEP before anything else runs.
+        const restored = await answerPendingMigration(process.cwd(), name, io);
+        if (restored) io.output.write(`  Interrupted migration resolved${restored.length ? ` — restored ${restored.length} file(s)` : ' — kept the new files'}.\n`);
+
         const report = options.waive
-          ? waive(process.cwd(), name, options.waive, options.reason || '')
+          ? 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');
-        fs.mkdirSync(outDir, { recursive: true });
         const slug = reportSlug(name);
-        fs.writeFileSync(path.join(outDir, `${slug}.json`), JSON.stringify(report, null, 2), 'utf-8');
+        // Derived files: a read-only checkout still gets the board (DOS-13.3).
+        writeJourneyFileBestEffort(path.join(outDir, `${slug}.json`), JSON.stringify(report, null, 2));
         const board = renderJourneyBoard(report);
-        fs.writeFileSync(path.join(outDir, `${slug}.board.md`), board, 'utf-8');
+        const written = writeJourneyFileBestEffort(path.join(outDir, `${slug}.board.md`), board);
 
         if (options.json) {
           console.log(JSON.stringify(report, null, 2));
         } else {
           console.log('');
-          console.log(board);
-          console.log(`  Board: ${path.relative(process.cwd(), path.join(outDir, `${slug}.board.md`))}`);
+          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);
       }
     });