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

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

@@ -0,0 +1,61 @@
+/**
+ * `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, 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), or an error
+ */
+import type { Command } from 'commander';
+import * as path from 'path';
+import { deriveFreeFeature, DeriveResult, nothingDerived } from '../../contract/derive-free-feature';
+import { registeredTraceResolver } from '../../contract/resolve-unit-trace-identities';
+import { resolveContractUnit } from '../../contract/contract-units';
+
+function print(r: DeriveResult, unit: string): void {
+  const L = console.log;
+  const rel = path.relative(process.cwd(), r.file);
+  L('');
+  L(`━━━ Contract derive: ${unit} — free tests' traces → ${rel} ━━━`);
+  L('');
+  if (r.note) L(`  ⚠ ${r.note}`);
+  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) {
+    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('  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 (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('');
+}
+
+export function registerDeriveCommand(contract: Command): void {
+  contract
+    .command('derive')
+    .description("Write features/<unit>.free.feature (@free @proposed) from the free tests' traces — deterministic, no LLM")
+    .option('-s, --screen <name>', 'Screen / flow / api unit name')
+    .option('--grep <regex>', 'Which tests, matched against "<id> <title> <file>" (default: tests whose file is named after the unit)')
+    .option('--json', 'Output the result as JSON')
+    .action(async (options) => {
+      try {
+        if (!options.screen) throw new Error('Provide --screen <name>');
+        const unit = resolveContractUnit(process.cwd(), String(options.screen));
+        const r = await deriveFreeFeature({
+          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 || nothingDerived(r) ? 1 : 0);
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/contract.ts

@@ -0,0 +1,130 @@
+/**
+ * `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).
+ *   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 { 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';
+
+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`).";
+
+function printVerdict(v: ContractVerdict, reportFile: string): void {
+  const L = console.log;
+  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:');
+  }
+  if (v.verdict !== 'pass' && !v.uncommitted.length && !onlyUnproven) L(`    sungen contract approve --screen ${v.unit}`);
+  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)')
+    .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() });
+        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; }
+        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);
+        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);
+        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/defect.ts

@@ -0,0 +1,49 @@
+import { Command } from 'commander';
+import { resolveUnit } from '../resolve-unit';
+import { draftDefects } from '../../harness/defect-draft';
+import { readDefects } from '../../harness/defects';
+
+/**
+ * `sungen defect draft|list` — defect records under qa/defects/ (see harness/defects.ts).
+ * `draft` writes one record per product-candidate row of the unit's last `sungen triage`.
+ */
+export function registerDefectCommand(program: Command): void {
+  const defect = program.command('defect').description('Draft and list defect records (qa/defects/DEF-NNN-*.md) from red scenarios');
+
+  defect
+    .command('draft')
+    .description('Draft a defect record for each product-candidate row of the last `sungen triage`')
+    .option('-s, --screen <name>', 'Screen or flow name')
+    .option('--api <name>', 'API-first area or api flow (qa/api/<name>)')
+    .option('--scenario <title|id>', 'Only the scenario whose title contains this text, or that carries this VP id')
+    .option('--json', 'Output raw JSON')
+    .action((o: { screen?: string; api?: string; scenario?: string; json?: boolean }) => {
+      try {
+        const name = o.screen || o.api;
+        if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
+        const unit = resolveUnit(name, process.cwd());
+        if (!unit) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
+        const r = draftDefects(process.cwd(), unit, { scenario: o.scenario });
+        if (o.json) { console.log(JSON.stringify(r, null, 2)); return; }
+        if (r.missingTriage) { console.log(`\n  ${name}: no triage yet — run \`sungen triage --screen ${name}\` after the tests.\n`); return; }
+        for (const f of r.written) console.log(`  ✎ ${f}`);
+        for (const s of r.skipped) console.log(`  ○ already recorded as ${s.id}: ${s.scenario}`);
+        if (!r.written.length && !r.skipped.length) console.log(`  ✓ ${name}: no product-candidate rows to draft.`);
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+      }
+    });
+
+  defect
+    .command('list')
+    .description('List defect records (id, severity, status, units, scenario count)')
+    .option('--status <status>', 'Only records with this status (open, fixed, verified, closed, wont-fix)')
+    .option('--json', 'Output raw JSON')
+    .action((o: { status?: string; json?: boolean }) => {
+      const rows = readDefects(process.cwd()).filter((r) => !o.status || r.status === o.status);
+      if (o.json) { console.log(JSON.stringify(rows, null, 2)); return; }
+      if (!rows.length) { console.log('  (no defect records)'); return; }
+      for (const r of rows) console.log(`  ${r.id}  ${r.severity.padEnd(8)} ${r.status.padEnd(9)} ${r.units.join(',')}  ${r.scenarios.length} scenario(s)  ${r.title}`);
+    });
+}

package/src/cli/commands/delivery.ts

@@ -7,7 +7,7 @@ import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
 import { parse as parseYaml } from 'yaml';
-import { parseFeatureMetadata } from '../../exporters/feature-parser';
+import { isHookScenario, parseFeatureMetadata } from '../../exporters/feature-parser';
 import { parseSpecFile } from '../../exporters/spec-parser';
 import { loadTestData } from '../../exporters/test-data-resolver';
 import { loadSelectorKeyMap } from '../../exporters/selector-key-resolver';
@@ -20,7 +20,7 @@ import {
   renderCsv,
   writeCsv,
 } from '../../exporters/csv-exporter';
-import { renderXlsxMultiSheet, writeXlsx, buildApiDetailRows, addApiDetailSheet } from '../../exporters/xlsx-exporter';
+import { renderXlsxMultiSheet, writeXlsx, buildApiDetailRows, addApiDetailSheet, deliverableXlsxPath } from '../../exporters/xlsx-exporter';
 import { loadApiCatalog } from '../../exporters/api-catalog-loader';
 import { resolveApiEnvironment } from '../../exporters/api-environment';
 import { getEnvironment, platformOfResultFile, RunEnvironment } from '../../exporters/run-environment';
@@ -38,9 +38,14 @@ import {
   hasReview,
 } from '../../exporters/matrix/export';
 import { MatrixFinding } from '../../exporters/matrix/types';
-import { ManualCarryReport } from '../../exporters/matrix/carry-manual-results';
+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 { 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';
 
 const COLOR = {
   reset: '\x1b[0m',
@@ -85,6 +90,12 @@ export interface DeliveryTarget {
   isFlow: boolean;
 }
 
+/** The command that regenerates a target's unit — flag by kind, the unit (not feature) name. */
+function generateCommandFor(target: DeliveryTarget): string {
+  const flag = target.kind === 'flow' ? '--flow' : target.kind === 'api' ? '--api' : '--screen';
+  return `sungen generate ${flag} ${target.screen}`;
+}
+
 function makeTarget(screen: string, featureBaseName: string, kind: UnitKind): DeliveryTarget {
   return { screen, featureBaseName, name: featureBaseName, kind, isFlow: kind === 'flow' };
 }
@@ -464,6 +475,7 @@ async function exportTarget(
       if (isMobileProject(cwd)) removeBaseDeliverables(cwd, target.featureBaseName);
       const rows = buildTestCaseRows({
         screen: label,
+        generateCommand: generateCommandFor(target),
         featureName: feature.featureName,
         // OS-precise env column: a mobile dual-id Path resolves to just the
         // android package / ios bundle id for SUNGEN_ENV=android|ios.
@@ -522,6 +534,7 @@ async function exportTarget(
         for (const variant of osVariants) {
           const variantRows = buildTestCaseRows({
             screen: label,
+            generateCommand: generateCommandFor(target),
             featureName: feature.featureName,
             featurePath: resolvePlatformAppId(featurePath, variant.locale), // OS-precise app id
             merged,
@@ -574,6 +587,7 @@ async function exportTarget(
       const variantResults = variant.resultsPath ? loadPlaywrightReport(variant.resultsPath) : null;
       const variantRows = buildTestCaseRows({
         screen: label,
+        generateCommand: generateCommandFor(target),
         featureName: feature.featureName,
         // No-op for web (URL Path); for a mobile fall-through (a no-suffix result
         // json) this collapses the dual-id to the android package so the combined
@@ -651,7 +665,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}`);
   }
@@ -676,23 +690,29 @@ 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
   // probes that are, by contract, outside the official suite.
   {
     const featureMeta = parseFeatureMetadata(paths.featureFile);
-    const deliverable = featureMeta.scenarios.filter((s) => !s.tags.some((t) => /^@exploration\b/i.test(t)));
-    if (featureMeta.scenarios.length > 0 && deliverable.length === 0) {
-      log(`${COLOR.gray}${paths.label}: nothing to deliver — all ${featureMeta.scenarios.length} scenario(s) are @exploration probes (outside the official suite).${COLOR.reset}`);
+    // Hooks are setup/teardown, never test cases — they neither need nor make a deliverable (#880).
+    const scenarios = featureMeta.scenarios.filter((s) => !isHookScenario(s));
+    const deliverable = scenarios.filter((s) => !s.tags.some((t) => /^@exploration\b/i.test(t)));
+    if (scenarios.length > 0 && deliverable.length === 0) {
+      log(`${COLOR.gray}${paths.label}: nothing to deliver — all ${scenarios.length} scenario(s) are @exploration probes (outside the official suite).${COLOR.reset}`);
       return 'skipped';
     }
   }
 
   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)})`);
@@ -707,6 +727,18 @@ async function exportMatrixTarget(
     return null;
   }
 
+  // The tester's recorded Manual results are part of the outcome: read them BEFORE anything is
+  // 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';
+  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; }
+  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))}`);
   {
     const mocked = model.items.flatMap((it) => it.variants.filter((v) => v.mocked));
@@ -741,7 +773,8 @@ async function exportMatrixTarget(
 
   let deliverables: Awaited<ReturnType<typeof writeMatrixDeliverables>>;
   try {
-    deliverables = await writeMatrixDeliverables(paths, model, opts.format ?? 'xlsx');
+    if (priorError) throw priorError;
+    deliverables = await writeMatrixDeliverables(paths, model, format, prior);
   } catch (e) {
     // The existing workbook could not be read, so writing would destroy its Manual results.
     log(`  ${COLOR.red}not written:${COLOR.reset} ${(e as Error).message}`);
@@ -869,6 +902,19 @@ 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('');
+  for (const line of renderChecklist(rows)) log(line);
+}
+
 // ----------------------------------------------------------------------------
 // Command registration
 // ----------------------------------------------------------------------------
@@ -887,10 +933,11 @@ export function registerDeliveryCommand(program: Command): void {
     .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('--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,
@@ -967,6 +1014,30 @@ 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({
+            projectRoot: cwd, acceptInRun: !!options.acceptInRun, io: processIO(), log,
+            // --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) {
@@ -981,9 +1052,9 @@ export function registerDeliveryCommand(program: Command): void {
               // Same contract as the export path: an all-@exploration feature has no
               // deliverable variants, so there is no map to approve — skip, not an error.
               {
-                const featureMeta = parseFeatureMetadata(paths.featureFile);
-                if (featureMeta.scenarios.length > 0
-                  && featureMeta.scenarios.every((s) => s.tags.some((t) => /^@exploration\b/i.test(t)))) {
+                const scenarios = parseFeatureMetadata(paths.featureFile).scenarios.filter((s) => !isHookScenario(s));
+                if (scenarios.length > 0
+                  && scenarios.every((s) => s.tags.some((t) => /^@exploration\b/i.test(t)))) {
                   log(`${COLOR.gray}${paths.label}: nothing to approve — all scenario(s) are @exploration probes.${COLOR.reset}`);
                   continue;
                 }
@@ -1012,21 +1083,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;
         }
@@ -1041,6 +1117,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/generate.ts

@@ -7,6 +7,7 @@ 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';
 
 /**
  * Find .feature files recursively in a directory
@@ -20,7 +21,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);
     }
   }

package/src/cli/commands/journey.ts

@@ -1,10 +1,12 @@
 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';
 
+const collect = (value: string, previous: string[]): string[] => [...previous, value];
 
 export function registerJourneyCommand(program: Command): void {
   program
@@ -12,22 +14,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,25 +56,29 @@ 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(`  Board: ${written ? path.relative(process.cwd(), written) : '(not written — read-only checkout)'}`);
           console.log('');
         }
       } catch (error) {