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

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';
@@ -31,9 +35,15 @@ 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 {
+/** 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 {
   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';
@@ -64,7 +74,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,11 +107,20 @@ 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) {
@@ -116,7 +147,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

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

package/src/cli/commands/journey.ts

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

package/src/cli/commands/next.ts

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

package/src/cli/index.ts

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

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

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

package/src/contract/accept-opaque-steps.ts

@@ -0,0 +1,114 @@
+/**
+ * `sungen contract approve --screen <u> --scenario <id> --accept-opaque` — a QA accepts the reviewed
+ * opaque steps of ONE approved free / impl:code scenario (#923). An opaque step (a check on a JS value,
+ * an API request, an evaluate) is never compared by code, so without this an approved test that has one
+ * stays in review for good: re-approving changes nothing and contract.opaque-step allows no override.
+ * In order, like `approve` (approve-contract.ts), so a human never confirms something then refused:
+ *
+ *   1. the scenario must be approved AS IT READS NOW — its lock entry human-approved, intact, at the
+ *      current hash, and vouched for by its decision — else: approve it first
+ *   2. its verdict is rebuilt (buildContractVerdict, as `contract check`): the opaque steps must be the
+ *      ONLY thing holding it; anything else (changed, unproven, inconclusive, a `low` identity…) refuses
+ *      with its own fix. Every opaque step already accepted → nothing to accept, no prompt
+ *   3. each opaque step is shown verbatim with its file:line; on a TTY the human types the scenario id
+ *      and a one-time code — without one: refused with the exact command (an agent never runs this)
+ *   4. everything is read AGAIN: if the trace, the feature or the lock moved meanwhile → refused
+ *   5. a contract-approval decision records the scenario at its hash WITH the accepted steps (step + sha)
+ *      and the lock entry points at it (record-contract-approval.ts)
+ *
+ * The acceptance is bound to each step's sha (opaqueStepSha): a change to an accepted step, or a new
+ * approval of the scenario, brings it back to review.
+ *
+ * Trust boundary: the TTY confirmation guards this command, not the files. A lock entry AND a matching
+ * decision forged together and committed through review are trusted like any approval — git review
+ * is that boundary, here as for `approve`.
+ */
+import { gitUserName } from '../decisions/decision-source';
+import { formatCommand, requireTypedConfirmation } from '../decisions/human-confirmation';
+import type { ApproveInput, ApproveResult } from './approve-contract';
+import { buildContractVerdict } from './build-contract-verdict';
+import { LOW_IDENTITY_FINDING } from './classify-trace-conformance';
+import { canonicalJson } from './contract-hash';
+import { ContractScenario, isHumanApproved, OpaqueStep } from './contract-schema';
+import { resolveContractUnit } from './contract-units';
+import { lockPathFor, ReadLock, readLockFile } from './contracts-lock-file';
+import { loadContractScenarios } from './normalize-feature-steps';
+import { recordOpaqueAcceptance } from './record-contract-approval';
+import { unverifiedApprovals } from './verify-approval-decisions';
+
+/** Accepting reads the traces with `contract check`'s generous deadline, never the guard's ~3 s. */
+const ACCEPT_TRACE_BUDGET_MS = 120_000;
+/** Findings that never hold a scenario back may stand beside the opaque steps. */
+const HARMLESS = new Set(['strengthened', 'nondeterministic']);
+
+interface Plan { unitDir: string; unit: string; scenario: ContractScenario; lock: ReadLock; decisionId: string; opaque: OpaqueStep[]; fingerprint: string }
+
+const isLow = (detail: string): boolean => detail.startsWith(LOW_IDENTITY_FINDING);
+
+function plan(i: ApproveInput, id: string): Plan {
+  const unit = resolveContractUnit(i.projectRoot, i.unit);
+  const lock = readLockFile(lockPathFor(unit.dir));
+  const matches = loadContractScenarios(unit.dir, unit.name).filter((s) => s.id === id);
+  if (!matches.length) throw new Error(`--scenario ${id} names no scenario of ${i.unit}`);
+  if (matches.length > 1) throw new Error(`Refused: scenario id ${id} is used by ${matches.length} scenarios — an acceptance must name exactly one. Give each its own ID.`);
+  const sc = matches[0];
+  if (sc.implementation === 'compiled') throw new Error(`Refused: ${id} is compiled — only a free / impl:code test has trace steps to accept.`);
+  const entry = lock?.scenarios[id];
+  if (!lock || !isHumanApproved(entry) || lock.tampered.includes(id) || entry.hash !== sc.hash) {
+    throw new Error(`Refused: ${id} is not approved as it reads now — approve it first (\`sungen contract approve --screen ${i.unit} --scenario ${id}\`), re-run it with a trace, then accept its opaque steps.`);
+  }
+  // The entry an acceptance re-points must be QA's own: its decision (on disk) vouches for it as it is.
+  const [unvouched] = unverifiedApprovals(i.projectRoot, unit.dir, { schema: lock.schema, scenarios: { [id]: entry } }, new Set(), { root: i.projectRoot, timeoutMs: 0, blobs: null });
+  if (unvouched) throw new Error(`Refused: the lock entry of ${id} is not vouched for by its decision (${unvouched.detail}) — restore the lock from git, or approve the scenario again.`);
+
+  const v = buildContractVerdict(i.projectRoot, unit, { traceBudgetMs: ACCEPT_TRACE_BUDGET_MS });
+  const bad = v.uncommitted.find((u) => u.id === id && (u.change === 'tampered' || u.change === 'unverified'));
+  if (bad) throw new Error(`Refused: the lock entry of ${id} is ${bad.change} (${bad.detail}) — restore it from git before accepting anything.`);
+  const r = v.scenarios.find((s) => s.id === id);
+  const blocking = (r?.findings ?? []).filter((f) => !HARMLESS.has(f.class) && !(f.class === 'opaque' && !isLow(f.detail)));
+  if (blocking.length) {
+    const fix = blocking.some((f) => isLow(f.detail))
+      ? `run \`sungen contract check --screen ${i.unit} --trace\` (a real browser resolves the identity) first`
+      : `settle that first — \`sungen contract check --screen ${i.unit}\` names the fix`;
+    throw new Error(`Refused: accepting clears only opaque steps, and ${id} is also held by: ${blocking.map((f) => `${f.class}${f.step ? ` (step ${f.step})` : ''} — ${f.detail}`).join('; ')}. ${fix[0].toUpperCase()}${fix.slice(1)}.`);
+  }
+  const opaque = r?.trace?.opaque ?? [];
+  if (!opaque.length) throw new Error(`Refused: the trace of ${id} has no opaque step — nothing to accept (${r?.class ?? 'not judged'}).`);
+  return { unitDir: unit.dir, unit: unit.name, scenario: sc, lock, decisionId: entry.decisionId, opaque, fingerprint: canonicalJson({ lock, hash: sc.hash, opaque }) };
+}
+
+const describe = (o: OpaqueStep): string =>
+  `${o.accepted ? '=' : '◐'} step ${o.step}  opaque ${o.kind === 'assert' ? 'check' : 'step'} "${o.verbatim}"${o.where ? ` at ${o.where}` : ''}`
+  + `${o.replaces ? ` — replaces approved ${o.replaces}` : ''}${o.accepted ? '  (accepted before)' : ''}`;
+
+export async function acceptOpaqueSteps(i: ApproveInput): Promise<ApproveResult> {
+  const id = i.scenario;
+  if (!id) throw new Error('--accept-opaque needs --scenario <id>: an acceptance names the one scenario whose opaque steps QA reviewed');
+  const before = plan(i, id);
+  const lockPath = lockPathFor(before.unitDir);
+  if (before.opaque.every((o) => o.accepted)) return { status: 'nothing-to-accept', lockPath, approved: [], removed: [] };
+
+  const pending = before.opaque.filter((o) => !o.accepted);
+  await requireTypedConfirmation({
+    what: `accept ${pending.length} reviewed opaque step(s) of ${id} (${i.unit}) — steps sungen cannot compare, so they are never checked by code`,
+    phrase: id,
+    command: formatCommand(['sungen', 'contract', 'approve', '--screen', i.unit, '--scenario', id, '--accept-opaque', ...(i.reason ? ['--reason', i.reason] : [])]),
+    summary: [
+      ...before.opaque.map(describe),
+      `bound to each step as it reads now: a change to it, or a new approval of ${id}, brings it back to review`,
+      `${id} stays approved at hash ${before.scenario.hash}; its lock entry moves from decision ${before.decisionId} to the new one`,
+      `recorded by: ${gitUserName(i.projectRoot)}`,
+    ],
+    io: i.io,
+  });
+
+  const after = plan(i, id);
+  if (after.fingerprint !== before.fingerprint) {
+    throw new Error('Refused: the trace, the feature or the lock changed while you were confirming — nothing was written. Run the command again and review the new summary.');
+  }
+  const { decisionId } = recordOpaqueAcceptance({
+    projectRoot: i.projectRoot, unitDir: after.unitDir, unit: after.unit, scenario: after.scenario, reason: i.reason, lock: after.lock,
+    accepted: after.opaque.map((o) => ({ step: o.step, sha: o.sha })),
+  });
+  return { status: 'accepted', lockPath, decisionId, approved: [id], removed: [], accepted: after.opaque };
+}

package/src/contract/approve-contract.ts

@@ -11,25 +11,31 @@
  *   5. read everything AGAIN: if the feature or the lock moved while the human was reading, what
  *      they confirmed is not what would be written — refuse (L5)
  *   6. record the decision and the lock (record-contract-approval.ts)
+ *
+ * `--accept-opaque` (with `--scenario`) is the other human act of this command: accepting the reviewed
+ * opaque trace steps of one approved free / impl:code scenario — accept-opaque-steps.ts (#923).
  */
 import { ConfirmationIO, formatCommand, requireTypedConfirmation } from '../decisions/human-confirmation';
 import { gitUserName } from '../decisions/decision-source';
 import { classifyScenario } from './classify-contract-change';
 import { canonicalJson } from './contract-hash';
-import { ContractScenario, isHumanApproved } from './contract-schema';
+import { acceptOpaqueSteps } from './accept-opaque-steps';
+import { ContractScenario, isHumanApproved, OpaqueStep } from './contract-schema';
 import { resolveContractUnit } from './contract-units';
 import { lockPathFor, ReadLock, readLockFile } from './contracts-lock-file';
 import { dropProposedTags } from './free-feature-blocks';
 import { contractFeatureFiles, loadContractScenarios } from './normalize-feature-steps';
 import { ApprovalWrite, checkApprovalSecrets, recordContractApproval } from './record-contract-approval';
 
-export interface ApproveInput { projectRoot: string; unit: string; scenario?: string; reason?: string; io: ConfirmationIO }
+export interface ApproveInput { projectRoot: string; unit: string; scenario?: string; reason?: string; io: ConfirmationIO; acceptOpaque?: boolean }
 export interface ApproveResult {
-  status: 'approved' | 'nothing-to-approve';
+  status: 'approved' | 'nothing-to-approve' | 'accepted' | 'nothing-to-accept';
   lockPath: string;
   decisionId?: string;
   approved: string[];
   removed: string[];
+  /** `--accept-opaque`: the scenario's opaque steps, all accepted by the new decision. */
+  accepted?: OpaqueStep[];
 }
 
 interface Plan { write: ApprovalWrite; lock: ReadLock | null; fingerprint: string }
@@ -62,6 +68,7 @@ function describe(sc: ContractScenario, lock: ReadLock | null): string {
 }
 
 export async function approveContract(i: ApproveInput): Promise<ApproveResult> {
+  if (i.acceptOpaque) return acceptOpaqueSteps(i);
   const before = plan(i);
   const { approve, removed } = before.write;
   const lockPath = lockPathFor(before.write.unitDir);

package/src/contract/build-contract-verdict.ts

@@ -9,7 +9,7 @@
  *           (added · changed · removed vs HEAD, tampered, unverified), or an APPROVED free /
  *           impl:code scenario with no admissible trace (unproven, also past the deadline) exit 2
  *   review  any hash-changed (changed, not weaker — QA re-approves), opaque (a check no code
- *           can compare, or a target identity that is only `low`), or inconclusive (an
+ *           can compare and QA has not accepted, or a target identity that is only `low`), or inconclusive (an
  *           approved free scenario's final attempt did not pass); blocks delivery         exit 0
  *   pass    only match / strengthened / proposed / nondeterministic                       exit 0
  *
@@ -64,7 +64,7 @@ function withTrace(results: ScenarioResult[], outcomes: Map<string, TraceOutcome
     const o = outcomes.get(r.id);
     if (!o) return r;
     const cls = severityOf(o.class) > severityOf(r.class) ? o.class : r.class;
-    return { ...r, class: cls, findings: [...r.findings, ...o.findings], trace: { hashes: o.hashes, runs: o.runs } };
+    return { ...r, class: cls, findings: [...r.findings, ...o.findings], trace: { hashes: o.hashes, runs: o.runs, ...(o.opaque.length ? { opaque: o.opaque } : {}) } };
   });
 }
 

package/src/contract/build-trace-conformance.ts

@@ -38,11 +38,16 @@ const sha = (s: string | Buffer): string => createHash('sha256').update(s).diges
 const why = (e: unknown): string => (e instanceof Error ? e.message : String(e)).split('\n')[0].slice(0, 300);
 
 export const MOBILE_NOT_SUPPORTED = 'trace conformance is web-only: free / impl:code scenarios of a mobile project are not supported yet (not judged)';
-/** The guard path's deadline for the trace part of one unit's verdict (override: SUNGEN_TRACE_VERDICT_BUDGET_MS). */
+/** The Claude Code guard's deadline for the trace part of one unit's verdict (its hook has ~5 s in all). */
+export const GUARD_TRACE_BUDGET_MS = 3_000;
+/** The default deadline (`next`, the guard) — override: SUNGEN_TRACE_VERDICT_BUDGET_MS. */
 export function defaultTraceBudgetMs(env: Record<string, string | undefined> = process.env): number {
   const v = Number(env.SUNGEN_TRACE_VERDICT_BUDGET_MS);
-  return Number.isFinite(v) && v > 0 ? v : 3_000;
+  return Number.isFinite(v) && v > 0 ? v : GUARD_TRACE_BUDGET_MS;
 }
+/** Inside the guard path the override may only SHORTEN the deadline (#926): the hook cannot wait longer. */
+export const guardTraceBudgetMs = (env: Record<string, string | undefined> = process.env): number =>
+  Math.min(defaultTraceBudgetMs(env), GUARD_TRACE_BUDGET_MS);
 
 export function traceConformanceForUnit(
   projectRoot: string, unit: { name: string; dir: string }, current: ContractScenario[], lock: ContractLock | null,
@@ -61,7 +66,7 @@ export function traceConformanceForUnit(
   let setupError = '';
   try {
     const notBefore = Math.max(mtimeMs(lockPathFor(unit.dir)), ...contractFeatureFiles(unit.dir, unit.name).map(mtimeMs));
-    evidence = collectScenarioEvidence(projectRoot, new Set(traced.map((s) => s.id)), notBefore, deadline);
+    evidence = collectScenarioEvidence(projectRoot, new Set(traced.map((s) => s.id)), notBefore, deadline, new Map(traced.map((s) => [s.id, s.source.name])));
     index = loadTestDataIndex(unit.dir, unit.name);
   } catch (e) { setupError = `trace conformance could not run: ${why(e)}`; }
   const { cache, problem } = readIdentityCache(projectRoot);

package/src/contract/classify-contract-change.ts

@@ -14,12 +14,12 @@
  * still `hash-changed`: equal hashes are the only road to `match`.
  */
 import { sameJson } from './contract-hash';
-import { ContractScenario, ContractStep, FindingClass, LadderClass, LockEntry, RULE_OF, ScenarioClass, TraceClass } from './contract-schema';
+import { ContractScenario, ContractStep, FindingClass, LadderClass, LockEntry, OpaqueStep, RULE_OF, ScenarioClass, TraceClass } from './contract-schema';
 import { compareAsserts } from './oracle-strength';
 
 export interface ContractFinding { class: FindingClass; rule?: string; detail: string; step?: number }
-/** What a free / impl:code scenario's traces fingerprinted to (DOS-14.6) — output only. */
-export interface TraceSummary { hashes: string[]; runs: string[] }
+/** What a free / impl:code scenario's traces fingerprinted to (DOS-14.6), and their opaque steps (#923) — output only. */
+export interface TraceSummary { hashes: string[]; runs: string[]; opaque?: OpaqueStep[] }
 export interface ScenarioResult { id: string; class: ScenarioClass; findings: ContractFinding[]; file?: string; trace?: TraceSummary }
 
 const SEVERITY: Record<ScenarioClass, number> = {