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

package/src/cli/commands/triage.ts

@@ -1,15 +1,44 @@
 import { Command } from 'commander';
 import * as path from 'path';
 import { resolveUnit } from '../resolve-unit';
+import { withProjectInvocation, withProjectInvocationInText } from '../project-sungen-invocation';
+import { processIO } from '../../decisions/human-confirmation';
+import { manualClassifications } from '../../graph/manual-triage-decisions';
+import { testCaseStates } from '../../graph/test-case-states';
 import { triageUnit, writeTriageReport } from '../../harness/triage-unit';
+import { classifyRedCase } from '../../harness/triage-manual-classification';
 import type { TriageClass } from '../../harness/triage';
 
 /** Display order: what needs a decision first, green last. */
 const ORDER: TriageClass[] = ['product-candidate', 'unclassified', 'test-defect', 'environment', 'blocked-capability', 'known-defect', 'flaky'];
 
+interface TriageOptions { screen?: string; api?: string; area?: string; json?: boolean; case?: string; as?: string; reason?: string }
+
+/** The classifications by hand in force for the unit (they win over the automatic class of the same red). */
+function printManual(cwd: string, unitDir: string, name: string): void {
+  const inForce = testCaseStates(cwd, name, { unitDir, auditFindings: [] }).filter((c) => c.triage?.ruleId === 'manual');
+  if (!inForce.length) return;
+  const why = new Map(manualClassifications(cwd, unitDir).map((m) => [m.decision, m]));
+  console.log(`\n  classified by hand (${inForce.length}) — these win over the automatic class`);
+  for (const c of inForce) {
+    const m = why.get(c.triage!.decision ?? '');
+    console.log(`    • ${c.id} → ${c.triage!.class}${m ? ` (${m.decision}, by ${m.by}): ${m.reason}` : ''}`);
+  }
+}
+
+/** `--case <id> --as <class> --reason "…"`: record one classification by hand (harness/triage-manual-classification.ts). */
+async function classifyByHand(cwd: string, name: string, o: TriageOptions): Promise<void> {
+  if (!o.case || !o.as) throw new Error(o.as ? '--as needs --case <id>' : '--case needs --as product|test-defect|environment and --reason "…"');
+  const r = await classifyRedCase({ projectRoot: cwd, unit: name, caseId: o.case, as: o.as, reason: o.reason, io: processIO() });
+  if (o.json) { console.log(JSON.stringify({ status: r.status, caseId: r.caseId, class: r.class, path: path.relative(cwd, r.path), entry: r.entry }, null, 2)); return; }
+  console.log(`\n${r.status === 'created' ? '✓ Recorded' : '= Already recorded'} ${r.entry.id}: ${r.caseId} → ${r.class} (classified by hand) → ${path.relative(cwd, r.path)}`);
+  console.log('  It holds until the case runs again. Commit it through review with the run it judged.\n');
+}
+
 /**
  * `sungen triage` — classify every red or flaky scenario of the latest run (see harness/triage.ts).
- * Reports, never gates: always exits 0 once the unit is found.
+ * Reports, never gates: always exits 0 once the unit is found. With `--case --as` it records one
+ * classification by hand instead (exit 1 when refused or invalid).
  */
 export function registerTriageCommand(program: Command): void {
   program
@@ -18,14 +47,18 @@ export function registerTriageCommand(program: Command): void {
     .option('-s, --screen <name>', 'Screen or flow name')
     .option('--api <name>', 'API-first area or api flow (qa/api/<name>)')
     .option('--area <name>', 'Alias of --api')
+    .option('--case <id>', 'Classify one red test case by hand (its VP-id) — with --as and --reason')
+    .option('--as <class>', 'product (anyone may record it) | test-defect | environment (test-defect and environment: a human types a confirmation on a TTY)')
+    .option('--reason <text>', 'Why the red is that class (mandatory with --as)')
     .option('--json', 'Output the raw JSON report')
-    .action((o: { screen?: string; api?: string; area?: string; json?: boolean }) => {
+    .action(async (o: TriageOptions) => {
       try {
         const name = o.screen || o.api || o.area;
         if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
         const cwd = process.cwd();
         const unit = resolveUnit(name, cwd);
         if (!unit) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
+        if (o.case || o.as) { await classifyByHand(cwd, name, o); return; }
 
         const report = triageUnit(cwd, unit);
         if (report.resultFiles.length === 0) {
@@ -48,9 +81,14 @@ export function registerTriageCommand(program: Command): void {
             L(`      ${r.ruleId}: ${r.evidence}`);
           }
         }
+        printManual(cwd, unit.dir, name);
+        if (report.rows.some((r) => r.class === 'unclassified')) {
+          L(`\n  Unclassified: read the evidence (trace, error), then classify by hand:\n    ${withProjectInvocation(`sungen triage --${unit.kind === 'api' ? 'api' : 'screen'} ${name} --case <id> --as product|test-defect|environment --reason "…"`, cwd)}`);
+        }
         L(`\n  Report: ${path.relative(cwd, saved)}\n`);
       } catch (error) {
-        console.error('Error:', error instanceof Error ? error.message : error);
+        // A refusal names the command a human runs instead: as this project runs sungen (#963).
+        console.error('Error:', error instanceof Error ? withProjectInvocationInText(error.message, process.cwd()) : error);
         process.exitCode = 1;
       }
     });

package/src/cli/commands/update.ts

@@ -26,7 +26,9 @@ import { syncProjectSungenDeps } from '../../orchestrator/project-deps-sync';
  *
  * The public `--skip-npm-install` flag is still available for users who
  * already installed the binary by other means (CI pipelines, corporate
- * mirror, manual download) and only want to refresh the project AI assets.
+ * mirror, manual download). It skips only step 1: the project sync still
+ * re-pins package.json (security overrides included) and runs `npm install`
+ * there — `--skip-project` skips that (#939).
  */
 
 const SKIP_NPM_ENV = 'SUNGEN_UPDATE_SKIP_NPM';
@@ -70,9 +72,11 @@ export function registerUpdateCommand(program: Command): void {
       '--tag <dist-tag>',
       'Install a specific npm dist-tag (e.g. latest, beta, alpha, next). Overrides --beta / --alpha.',
     )
+    // #939: it skips only the GLOBAL install — the project is still synced, so the help says so.
     .option(
       '--skip-npm-install',
-      'Skip the global npm install step (refresh project AI assets only)',
+      'Skip the global npm install step. The project is still synced: its sungen packages are re-pinned in package.json '
+        + '(security `overrides` included) and `npm install` runs in the project — add --skip-project to skip that too',
       false,
     )
     .option(

package/src/cli/index.ts

@@ -45,6 +45,7 @@ import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 import { warnAssetsDrift } from '../orchestrator/assets-drift';
 import { attachCliHandBack } from '../hooks/hand-back-core';
+import { attachJsonErrorOnExit, commandSupportsJson } from './json-error-on-exit';
 import { registerHookCommand } from '../hooks/hook-cli-command';
 
 // Read version from package.json so `--version` never drifts from the released version.
@@ -56,10 +57,12 @@ 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();
+  // #939: a failed `--json` command prints {"error":{code,message}} on stdout (json-error-on-exit.ts).
+  const jsonErrors = attachJsonErrorOnExit(process.argv, (args) => commandSupportsJson(program, args));
 
   program
     .name('sungen')
@@ -130,6 +133,7 @@ registerSetupMobileEnvCommand(program);
   // The action knows its unit and output mode; the hand-back default above is refined here.
   program.hook('preAction', (_thisCommand, actionCommand) => {
     handBack.onAction(actionCommand.name(), actionCommand.opts() as Record<string, unknown>, actionCommand.args);
+    jsonErrors.onAction();
   });
 
   await program.parseAsync(process.argv);

package/src/cli/json-error-on-exit.ts

@@ -0,0 +1,72 @@
+/**
+ * `--json` failures speak JSON too (#939 item 7). A command that supports `--json` and fails used to
+ * print its error on stderr and NOTHING on stdout, so a caller parsing stdout got an empty string. Now,
+ * when such a command exits non-zero without having written stdout, the exit prints one object:
+ *
+ *   {"error":{"code":"command-failed" | "usage-error","message":"<the error it printed>"}}
+ *
+ *   command-failed  the action ran and failed (`next nope --json`)
+ *   usage-error     commander refused the arguments before any action ran (`audit --json --bogus`)
+ * The human error stays on stderr, unchanged. A command that printed its own JSON keeps it, whatever
+ * its exit code (`contract check --json` exits 2 with the verdict); a command without `--json` is never
+ * touched — commander's own "unknown option '--json'" is its usage error, not a JSON caller's.
+ * Like the hand-back, it hangs off process exit: commands exit from inside their actions.
+ */
+import type { Command } from 'commander';
+
+export type JsonErrorCode = 'command-failed' | 'usage-error';
+export interface JsonError { error: { code: JsonErrorCode; message: string } }
+
+const ANSI = /\u001b\[[0-9;]*m/g;
+const ERROR_LINE = /^(?:Error|error|Fatal error|❌[^:]*):\s*/;
+const MAX_CAPTURE = 64 * 1024;
+
+/** The error object for what the command printed on stderr: from its first error line on, the hand-back dropped. */
+export function jsonErrorPayload(stderr: string, actionRan: boolean, exitCode: number): JsonError {
+  const lines = stderr.replace(ANSI, '').split('\n').map((l) => l.trimEnd()).filter((l) => l && !/^Next: /.test(l));
+  const at = lines.findIndex((l) => ERROR_LINE.test(l));
+  const picked = at >= 0 ? lines.slice(at) : lines.slice(-1);
+  const message = picked.join('\n').replace(ERROR_LINE, '').trim() || `exited with code ${exitCode}`;
+  return { error: { code: actionRan ? 'command-failed' : 'usage-error', message } };
+}
+
+/** The (sub)command `args` name, walked down from `program`, defines `--json`. */
+export function commandSupportsJson(program: Command, args: string[]): boolean {
+  let cmd: Command = program;
+  for (const a of args) {
+    if (a.startsWith('-')) continue;
+    const sub = cmd.commands.find((c) => c.name() === a || c.aliases().includes(a));
+    if (!sub) break;
+    cmd = sub;
+  }
+  return cmd !== program && cmd.options.some((o) => o.long === '--json');
+}
+
+/**
+ * Wire it to process exit for `argv` (a no-op without `--json`). `supportsJson` is asked at exit, once
+ * every command is registered; `onAction` marks that an action ran (a failure then is not a usage error).
+ */
+export function attachJsonErrorOnExit(argv: string[], supportsJson: (args: string[]) => boolean): { onAction: () => void } {
+  const args = argv.slice(2);
+  if (!args.includes('--json')) return { onAction: () => undefined };
+  let wroteStdout = false;
+  let stderr = '';
+  let actionRan = false;
+  const writeOut = process.stdout.write.bind(process.stdout);
+  const writeErr = process.stderr.write.bind(process.stderr);
+  process.stdout.write = ((chunk: unknown, ...rest: unknown[]) => {
+    if (String(chunk).length) wroteStdout = true;
+    return (writeOut as (...a: unknown[]) => boolean)(chunk, ...rest);
+  }) as typeof process.stdout.write;
+  process.stderr.write = ((chunk: unknown, ...rest: unknown[]) => {
+    if (stderr.length < MAX_CAPTURE) stderr += String(chunk);
+    return (writeErr as (...a: unknown[]) => boolean)(chunk, ...rest);
+  }) as typeof process.stderr.write;
+  process.on('exit', (code) => {
+    try {
+      if (code === 0 || wroteStdout || !supportsJson(args)) return;
+      writeOut(`${JSON.stringify(jsonErrorPayload(stderr, actionRan, code))}\n`);
+    } catch { /* the exit code is the contract; this object is a courtesy */ }
+  });
+  return { onAction: () => { actionRan = true; } };
+}

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

@@ -0,0 +1,59 @@
+/**
+ * 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
+ *   withProjectInvocationInText(text, root)
+ *                                   every `sungen …` command inside printed text (a refusal, a hint, a
+ *                                   step's reason) as this project runs it (#963); prose mentions stay
+ *   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;
+}
+
+/**
+ * A `sungen` that starts a command inside text: at the start of a line (after indentation), after a
+ * backtick or `(`, after ": ", "run " or "then " — and followed by a subcommand or an option. A prose
+ * mention ("written by sungen 3.3.0", "an older sungen", "sungen: …") is none of these.
+ */
+const COMMAND_IN_TEXT = /(^[ \t]*|[`(]|:[ \t]+|\b(?:[Rr]un|then)[ \t]+)sungen(?= [a-z-])/gm;
+
+/**
+ * Printed text (a refusal, a hint, a step's reason) with every `sungen …` command in it as this project
+ * runs sungen (#963): the human-only commands a QA copies from a refusal must run the project's own
+ * install, not an older global one. Text for machines (`--json`) stays canonical; this is for the screen.
+ */
+export function withProjectInvocationInText(text: string, projectRoot: string): string {
+  const inv = sungenInvocation(projectRoot);
+  return inv === 'sungen' ? text : text.replace(COMMAND_IN_TEXT, (_m, before: string) => `${before}${inv}`);
+}
+
+/** 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/cli/run-command-hints.ts

@@ -0,0 +1,47 @@
+/**
+ * The run commands sungen suggests, each writing its results where the reader that asks for them
+ * looks (#964). A hint whose results nobody reads leaves a passing run invisible: the plain
+ * `npx playwright test` wrote `test-result.json` at the project root, which `sungen next` never reads.
+ *
+ *   generatedSubdir(kind, unit)      `specs/generated/<unit>` · `…/flows/<flow>` · `…/api/<area>` — where
+ *                                    `generate` writes a unit's specs and `next` / `delivery` read its results
+ *   plainRunCommand(genRel, feature) one compiled feature's spec with the JSON reporter pointed at
+ *                                    `<genRel>/<feature>-test-result.json` (graph/unit-artifact-probes RESULT_FILE)
+ *   freeRunCommand(cwd)              hand-written @free / impl:code tests: the project's free-test config, which
+ *                                    writes into its own outputDir `test-results-free/` (#941)
+ *   freeRunHasResults(cwd)           that run left its results (or a sungen run record) there
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { FREE_RUN_DIR } from '../contract/trace/trace-run-record';
+
+export type RunUnitKind = 'screen' | 'flow' | 'api';
+
+export function generatedSubdir(kind: RunUnitKind, unit: string): string {
+  return path.posix.join('specs', 'generated', ...(kind === 'flow' ? ['flows'] : kind === 'api' ? ['api'] : []), unit);
+}
+
+/** `[SUNGEN_ENV=<env> ]PLAYWRIGHT_JSON_OUTPUT_NAME=<genRel>/<feature>-test-result.json npx playwright test <genRel>/<feature>.spec.ts` */
+export function plainRunCommand(genRel: string, featureBaseName: string, env?: string): string {
+  return `${env ? `SUNGEN_ENV=${env} ` : ''}PLAYWRIGHT_JSON_OUTPUT_NAME=${genRel}/${featureBaseName}-test-result.json npx playwright test ${genRel}/${featureBaseName}.spec.ts`;
+}
+
+const FREE_CONFIG = /^playwright\.free\.config\.(?:ts|mts|cts|js|mjs|cjs)$/;
+
+/** The free run: `npx playwright test -c <playwright.free.config.*>` when the project has one, else what that config holds. */
+export function freeRunCommand(cwd: string): string {
+  let config: string | undefined;
+  try { config = fs.readdirSync(cwd).find((f) => FREE_CONFIG.test(f)); } catch { /* no project dir: the generic form */ }
+  return config
+    ? `npx playwright test -c ${config}`
+    : `run the hand-written tests with the project's free-test config (outputDir '${FREE_RUN_DIR}', trace: 'on', the sungen run-record reporter — "Free tests" in the sungen docs)`;
+}
+
+/** The free run left its JSON results or a sungen run record in `test-results-free/`. */
+export function freeRunHasResults(cwd: string): boolean {
+  try {
+    return fs.readdirSync(path.join(cwd, FREE_RUN_DIR)).some((f) => f === 'results.json' || /^sungen-run-record.*\.json$/.test(f));
+  } catch {
+    return false;   // never run
+  }
+}

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

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

package/src/contract/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

@@ -12,17 +12,17 @@
  * Bounded (review H4, M2): a deadline (`budgetMs`; the guard's default is ~3 s) — a scenario not
  * judged in time is `unproven` when approved, a warning while proposed: fail CLOSED. An input that
  * cannot be read while judging (test-data, a trace) makes that scenario unproven with its reason,
- * never a thrown verdict. A trace older than the unit's newest `.feature` / lock is refused (stale).
+ * never a thrown verdict. A trace older than the unit's `.feature` / lock is refused (stale) — judged
+ * by their content, so a touch or a fresh clone stales nothing (#967, trace/trace-freshness.ts).
  */
 import { createHash } from 'crypto';
 import * as fs from 'fs';
 import { readCapabilities } from '../harness/capability';
 import { classifyTraceRuns, notJudged, TraceOutcome } from './classify-trace-conformance';
 import { ContractLock, ContractScenario, isHumanApproved, LockEntry } from './contract-schema';
-import { lockPathFor } from './contracts-lock-file';
 import { loadTestDataIndex, TestDataIndex } from './data-normalize';
-import { contractFeatureFiles } from './normalize-feature-steps';
 import { renderTraceSteps, RenderedStep } from './render-free-gherkin';
+import { unitContract } from './trace/trace-freshness';
 import { collectScenarioEvidence, OVER_BUDGET, ScenarioEvidence, TraceRun } from './trace/collect-trace-evidence';
 
 export { OVER_BUDGET } from './trace/collect-trace-evidence';
@@ -33,16 +33,20 @@ import { traceIntentSteps } from './trace/trace-steps';
 
 export interface UnitTraceConformance { outcomes: Map<string, TraceOutcome>; warnings: string[]; inputs: unknown }
 
-const mtimeMs = (f: string): number => { try { return fs.statSync(f).mtimeMs; } catch { return 0; } };
 const sha = (s: string | Buffer): string => createHash('sha256').update(s).digest('hex');
 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,
@@ -60,8 +64,7 @@ export function traceConformanceForUnit(
   let index: TestDataIndex = { byValue: new Map() };
   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)), unitContract(projectRoot, unit), 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> = {