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

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

@@ -7,26 +7,43 @@
  *               with that step — identically (fine), weaker (hard), stronger (strengthened), changed
  *               (review); an approved check with no group or no check in its group → assertion-lost
  *   overlays    a step whose target identity is `low` → opaque (review, never match, red-team #4);
- *               an opaque step → opaque with its verbatim text and file:line (contract.opaque-step)
+ *               an opaque step → opaque with its verbatim text and file:line (contract.opaque-step) —
+ *               unless the approved entry lists it as accepted by QA at its sha (#923, opaqueStepSha):
+ *               then a note, not a finding. impl:code: a test.step whose only candidates are opaque is
+ *               left to the overlay (judged on the ladder it could only read "changed"), which names the
+ *               approved step the opaque one replaces
  *   runs        no admissible trace → unproven (all inconclusive → inconclusive) when APPROVED, a
  *               warning while proposed (M5, M6); a trace refused beside an admissible one → a warning;
  *               several admissible traces that fingerprint differently → nondeterministic (worst wins)
  */
 import { classifyScenario, ContractFinding, finding, ScenarioResult, severityOf } from './classify-contract-change';
-import { sameJson } from './contract-hash';
-import type { ContractStep, Implementation, LockEntry, ScenarioClass } from './contract-schema';
+import { canonicalJson, sameJson, sha256Hex } from './contract-hash';
+import type { AcceptedOpaqueStep, ContractStep, Implementation, LockEntry, OpaqueStep, ScenarioClass } from './contract-schema';
 import { compareAsserts } from './oracle-strength';
+import { clip, RenderedStep } from './render-free-gherkin';
 import type { TraceRun } from './trace/collect-trace-evidence';
 import type { TraceFingerprint } from './trace/trace-fingerprint';
 
-/** `warnings` never change the verdict: a not-yet-approved scenario's trace problems, unused traces. */
-export interface TraceOutcome { class: ScenarioClass; findings: ContractFinding[]; hashes: string[]; runs: string[]; warnings: string[] }
+/**
+ * `warnings` never change the verdict: a not-yet-approved scenario's trace problems, unused traces, an
+ * accepted opaque step. `opaque`: every opaque step of the admissible traces, accepted or not.
+ */
+export interface TraceOutcome { class: ScenarioClass; findings: ContractFinding[]; hashes: string[]; runs: string[]; warnings: string[]; opaque: OpaqueStep[] }
 
 /** What an unjudgeable scenario becomes: hard when QA locked it (approved), a warning while it is proposed. */
 export function notJudged(id: string, approved: boolean, cls: 'unproven' | 'inconclusive', reasons: string[]): TraceOutcome {
   return approved
-    ? { class: cls, findings: reasons.map((r) => finding(cls, r)), hashes: [], runs: [], warnings: [] }
-    : { class: 'proposed', findings: [], hashes: [], runs: [], warnings: reasons.map((r) => `${id} (not approved yet, so a warning): ${r}`) };
+    ? { class: cls, findings: reasons.map((r) => finding(cls, r)), hashes: [], runs: [], warnings: [], opaque: [] }
+    : { class: 'proposed', findings: [], hashes: [], runs: [], warnings: reasons.map((r) => `${id} (not approved yet, so a warning): ${r}`), opaque: [] };
+}
+
+/**
+ * The sha a QA acceptance binds to (#923): the opaque step as rendered — its verbatim line or request,
+ * check or step, the `test.step` it sits in — and as normalized, with the implementation path. Any
+ * change to the step gives another sha, so the old acceptance no longer covers it.
+ */
+export function opaqueStepSha(implementation: Implementation, r: RenderedStep, step: ContractStep | undefined): string {
+  return sha256Hex(canonicalJson({ implementation, kind: r.kind, group: r.group ?? null, verbatim: r.opaque?.verbatim ?? null, step: step ?? null })).slice(0, 16);
 }
 
 /** How a low target identity opens its finding — `next` reads it to offer `contract check --trace`. */
@@ -35,19 +52,41 @@ export const LOW_IDENTITY_FINDING = 'target identity is low';
 const worstOf = (findings: ContractFinding[], start: ScenarioClass = 'match'): ScenarioClass =>
   findings.reduce<ScenarioClass>((acc, f) => (severityOf(f.class as ScenarioClass) > severityOf(acc) ? f.class as ScenarioClass : acc), start);
 
-function overlays(fp: TraceFingerprint, used?: Set<number>): ContractFinding[] {
-  const out: ContractFinding[] = [];
+type Judged = { findings: ContractFinding[]; opaque: OpaqueStep[] };
+
+/** An approved step as a reader sees it: `see [My Account] heading with text "My Account"`. */
+function approvedStepText(s: ContractStep): string {
+  const refs = [s.target?.ref, ...(s.target?.also ?? [])].filter((r): r is string => r !== undefined);
+  const values = (s.kind === 'assert' ? s.expected : s.value)?.split(' | ') ?? [];
+  let r = 0;
+  let v = 0;
+  return s.verb.replace(/\[\]/g, () => `[${refs[r++] ?? ''}]`).replace(/\{\}/g, () => (v < values.length ? `"${values[v++]}"` : '{}'));
+}
+
+function overlays(
+  fp: TraceFingerprint, implementation: Implementation, accepted: readonly AcceptedOpaqueStep[], used?: Set<number>, replaces?: ReadonlyMap<number, string>,
+): Judged {
+  const findings: ContractFinding[] = [];
+  const opaque: OpaqueStep[] = [];
   fp.rendered.forEach((r, i) => {
     if (used && !used.has(i)) return;
-    if (r.opaque) out.push(finding('opaque', `"${r.opaque.verbatim}"${r.opaque.where ? ` at ${r.opaque.where}` : ''} — ${r.kind === 'assert' ? 'a check' : 'a step'} sungen cannot compare; QA reviews it`, i + 1));
-    else if (r.low) out.push(finding('opaque', `${LOW_IDENTITY_FINDING} (${r.low}) — cannot prove "${r.sentence}" acts on the approved element`, i + 1));
+    if (r.opaque) {
+      const sha = opaqueStepSha(implementation, r, fp.steps[i]);
+      const isAccepted = accepted.some((a) => a.step === i + 1 && a.sha === sha);
+      const instead = replaces?.get(i);
+      opaque.push({ step: i + 1, sha, kind: r.kind, verbatim: r.opaque.verbatim, ...(r.opaque.where ? { where: r.opaque.where } : {}), ...(instead ? { replaces: instead } : {}), accepted: isAccepted });
+      if (!isAccepted) {
+        findings.push(finding('opaque', `"${r.opaque.verbatim}"${r.opaque.where ? ` at ${r.opaque.where}` : ''} — ${r.kind === 'assert' ? 'a check' : 'a step'} sungen cannot compare; QA reviews it${instead ? ` — replaces approved ${instead}` : ''}`, i + 1));
+      }
+    } else if (r.low) findings.push(finding('opaque', `${LOW_IDENTITY_FINDING} (${r.low}) — cannot prove "${r.sentence}" acts on the approved element`, i + 1));
   });
-  return out;
+  return { findings, opaque };
 }
 
-function implCodeFindings(entry: LockEntry, fp: TraceFingerprint): { findings: ContractFinding[]; used: Set<number> } {
+function implCodeFindings(entry: LockEntry, fp: TraceFingerprint): { findings: ContractFinding[]; used: Set<number>; replaces: Map<number, string> } {
   const findings: ContractFinding[] = [];
   const used = new Set<number>();
+  const replaces = new Map<number, string>();
   const taken = new Set<number>();
   entry.steps.forEach((locked, i) => {
     const g = fp.groups.findIndex((x, gi) => !taken.has(gi) && sameJson(x.titleStep, locked));
@@ -68,6 +107,13 @@ function implCodeFindings(entry: LockEntry, fp: TraceFingerprint): { findings: C
       return;
     }
     candidates.forEach((m) => used.add(m));
+    // Only steps sungen cannot compare implement this approved step: the overlay sends them to QA's
+    // review (#923), naming the approved step. On the ladder they could only read "changed", which
+    // re-approving never clears.
+    if (candidates.every((m) => fp.rendered[m].opaque)) {
+      for (const m of candidates) replaces.set(m, `step ${i + 1} "${clip(approvedStepText(locked))}"`);
+      return;
+    }
     if (locked.kind === 'action') { findings.push(finding('hash-changed', `the code for "${locked.verb}" does something else: "${fp.rendered[candidates[0]].sentence}"`, i + 1)); return; }
     const judged = candidates.map((m) => compareAsserts(locked, fp.steps[m] as ContractStep));
     const rank = (k: string): number => (k === 'oracle-weakened' ? 0 : k === 'review' ? 1 : 2);
@@ -75,18 +121,21 @@ function implCodeFindings(entry: LockEntry, fp: TraceFingerprint): { findings: C
     findings.push(finding(best.class === 'review' ? 'hash-changed' : best.class, best.detail, i + 1));
   });
   fp.groups.forEach((g, gi) => { if (!taken.has(gi)) findings.push(finding('hash-changed', `test.step "${g.title}" implements no approved step`)); });
-  return { findings, used };
+  return { findings, used, replaces };
 }
 
-function classifyOne(id: string, implementation: Implementation, entry: LockEntry, fp: TraceFingerprint): ContractFinding[] {
+function classifyOne(id: string, implementation: Implementation, entry: LockEntry, fp: TraceFingerprint): Judged {
+  const accepted = entry.acceptedOpaque ?? [];
   if (implementation === 'impl:code') {
-    const { findings, used } = implCodeFindings(entry, fp);
-    return [...findings, ...overlays(fp, used)];
+    const { findings, used, replaces } = implCodeFindings(entry, fp);
+    const o = overlays(fp, implementation, accepted, used, replaces);
+    return { findings: [...findings, ...o.findings], opaque: o.opaque };
   }
   const ladder: ScenarioResult = classifyScenario(id, entry, {
     id, implementation, steps: fp.steps, hash: fp.hash, source: { file: '', name: id, hasId: true, lines: [], outline: false },
   });
-  return [...ladder.findings, ...overlays(fp)];
+  const o = overlays(fp, implementation, accepted);
+  return { findings: [...ladder.findings, ...o.findings], opaque: o.opaque };
 }
 
 const runLabel = (r: TraceRun): string => `${r.record?.runId ?? '?'}#${r.result?.retry ?? '?'}`;
@@ -104,13 +153,18 @@ export function classifyTraceRuns(
   }
   // A trace that may not speak, beside one that may: the admissible one judges, the other is a warning.
   const warnings = others.map((r) => `${id}: another trace of this scenario was not used — ${r.reason ?? r.status}`);
-  if (!entry) return { class: 'proposed', findings: [], hashes, runs: labels, warnings };
+  if (!entry) return { class: 'proposed', findings: [], hashes, runs: labels, warnings, opaque: [] };
   const perRun = admissible.map((r) => classifyOne(id, implementation, entry, fingerprints.get(r)!));
-  const findings = perRun.flat();
-  let cls = worstOf(perRun.flat());
+  const findings = perRun.flatMap((p) => p.findings);
+  const opaque = [...new Map(perRun.flatMap((p) => p.opaque).map((o) => [`${o.step}:${o.sha}`, o] as const)).values()]
+    .sort((a, b) => a.step - b.step || a.sha.localeCompare(b.sha));
+  for (const o of opaque.filter((x) => x.accepted)) {
+    warnings.push(`${id}: step ${o.step} — opaque ${o.kind === 'assert' ? 'check' : 'step'} "${clip(o.verbatim)}" accepted by QA (decision ${entry.decisionId}), not compared`);
+  }
+  let cls = worstOf(findings);
   if (new Set(hashes).size > 1) {
     findings.push(finding('nondeterministic', `${new Set(hashes).size} different fingerprints across ${admissible.length} runs — the runs took different branches`));
     if (severityOf(cls) <= severityOf('strengthened')) cls = 'nondeterministic';
   }
-  return { class: cls, findings, hashes, runs: labels, warnings };
+  return { class: cls, findings, hashes, runs: labels, warnings, opaque };
 }

package/src/contract/contract-schema.ts

@@ -3,7 +3,7 @@
  *
  *   step   {kind: action|assert, verb, target?:{ref, also?, parent?, nth?}, value?, matcher?, expected?, negated?, table?}
  *   lock   qa/<kind>/<unit>/contracts.lock.yaml → {schema: 1, scenarios: {<scenario id>: LockEntry}}
- *   entry  {hash, steps, implementation, approvedAt, decisionId, humanApproved?}
+ *   entry  {hash, steps, implementation, approvedAt, decisionId, humanApproved?, acceptedOpaque?}
  *
  * A stored entry is checked the way the decision layer checks its records: a wrong type or an
  * UNKNOWN key is an error, because a field outside the hash could carry meaning the hash does not
@@ -49,6 +49,9 @@ export interface ContractScenario {
   source: { file: string; name: string; hasId: boolean; lines: number[]; outline: boolean };
 }
 
+/** A reviewed opaque trace step QA accepted (#923): its 1-based position in the trace's steps and its sha (opaqueStepSha). */
+export interface AcceptedOpaqueStep { step: number; sha: string }
+
 export interface LockEntry {
   hash: string;
   steps: ContractStep[];
@@ -56,8 +59,16 @@ export interface LockEntry {
   approvedAt: string;
   decisionId: string;
   humanApproved?: true;
+  /** Opaque trace steps a QA accepted on a terminal (`contract approve --accept-opaque`) — vouched for by `decisionId`. */
+  acceptedOpaque?: AcceptedOpaqueStep[];
 }
 
+/**
+ * One opaque step of a scenario's trace(s), as `contract check` reports it and `--accept-opaque` shows it.
+ * `replaces` (impl:code): the approved step it stands in for — `step 5 "see [Title] heading"`.
+ */
+export interface OpaqueStep { step: number; sha: string; kind: 'action' | 'assert'; verbatim: string; where?: string; replaces?: string; accepted: boolean }
+
 export const LOCK_SCHEMA = 1;
 export interface ContractLock { schema: typeof LOCK_SCHEMA; scenarios: Record<string, LockEntry> }
 
@@ -88,8 +99,10 @@ export const RULE_OF: Readonly<Partial<Record<FindingClass, string>>> = {
 
 const STEP_KEYS = new Set(['kind', 'verb', 'target', 'value', 'matcher', 'expected', 'negated', 'table']);
 const TARGET_KEYS = new Set(['ref', 'also', 'parent', 'nth']);
-const ENTRY_KEYS = new Set(['hash', 'steps', 'implementation', 'approvedAt', 'decisionId', 'humanApproved']);
+const ENTRY_KEYS = new Set(['hash', 'steps', 'implementation', 'approvedAt', 'decisionId', 'humanApproved', 'acceptedOpaque']);
+const ACCEPTED_KEYS = new Set(['step', 'sha']);
 const HASH_RE = /^[0-9a-f]{12}$/;
+export const OPAQUE_SHA_RE = /^[0-9a-f]{16}$/;
 
 const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
 const isStringList = (v: unknown): v is string[] => Array.isArray(v) && v.every((x) => typeof x === 'string');
@@ -118,6 +131,18 @@ export function stepErrors(s: unknown, at: string): string[] {
   return e;
 }
 
+function acceptedOpaqueErrors(v: unknown, at: string): string[] {
+  if (!Array.isArray(v) || !v.length) return [`${at}: acceptedOpaque must be a non-empty list`];
+  return v.flatMap((a, i) => {
+    const where = `${at} acceptedOpaque ${i + 1}`;
+    if (!isObject(a)) return [`${where}: not a mapping`];
+    const e = unknownKeys(a, ACCEPTED_KEYS, where);
+    if (!(Number.isInteger(a.step) && (a.step as number) > 0)) e.push(`${where}: step must be a positive integer`);
+    if (typeof a.sha !== 'string' || !OPAQUE_SHA_RE.test(a.sha)) e.push(`${where}: sha must be 16 hex characters`);
+    return e;
+  });
+}
+
 /** Errors in one stored lock entry (empty = well-formed). The hash itself is checked by the reader. */
 export function lockEntryErrors(raw: unknown, id: string): string[] {
   const at = `scenario ${id}`;
@@ -128,6 +153,10 @@ export function lockEntryErrors(raw: unknown, id: string): string[] {
   if (typeof raw.approvedAt !== 'string' || Number.isNaN(Date.parse(raw.approvedAt))) e.push(`${at}: approvedAt must be an ISO-8601 timestamp`);
   if (typeof raw.decisionId !== 'string' || !DECISION_ID_RE.test(raw.decisionId)) e.push(`${at}: decisionId must be D-<16 hex>`);
   if (raw.humanApproved !== undefined && raw.humanApproved !== true) e.push(`${at}: humanApproved is either true or absent`);
+  if (raw.acceptedOpaque !== undefined) {
+    e.push(...acceptedOpaqueErrors(raw.acceptedOpaque, at));
+    if (raw.humanApproved !== true) e.push(`${at}: acceptedOpaque needs humanApproved: true`);
+  }
   if (!Array.isArray(raw.steps)) e.push(`${at}: steps must be a list`);
   else raw.steps.forEach((s, i) => e.push(...stepErrors(s, `${at} step ${i + 1}`)));
   return e;

package/src/contract/contracts-lock-file.ts

@@ -80,6 +80,7 @@ export function serializeLock(lock: ContractLock): string {
     scenarios[id] = {
       hash: e.hash, implementation: e.implementation, approvedAt: e.approvedAt, decisionId: e.decisionId,
       ...(e.humanApproved === true ? { humanApproved: true as const } : {}),
+      ...(e.acceptedOpaque?.length ? { acceptedOpaque: e.acceptedOpaque.map((a) => ({ step: a.step, sha: a.sha })) } : {}),
       steps: e.steps.map(orderedStep),
     };
   }

package/src/contract/derive-free-feature.ts

@@ -8,6 +8,8 @@
  *   identities    asked of the registered `traceIdentity` resolver (driver-ui) when one is given,
  *                 otherwise the cache, otherwise core's heuristic — `# identity low` marks those steps
  *   approved      a scenario QA already approved (no `@proposed`) is never rewritten
+ *   one id, one   two recorded tests claiming one id (#962) refuse the derive — both named with
+ *   test          file:line, NOTHING written for the unit: keeping one would drop the other's contract
  *   safety        redaction by field meaning, machine paths scrubbed, then the secret scanner and the
  *                 semantic credential check over the exact text: any hit → NOTHING is written
  */
@@ -22,8 +24,10 @@ import { scrubKnownSecrets, scrubMachinePaths, secretScanHits, SecretHit } from
 import { idOfTitle, splitFeatureBlocks } from './free-feature-blocks';
 import { sensitiveLiteralHits } from './lock-secret-guard';
 import { scenariosOfFeatureFile } from './normalize-feature-steps';
+import { featureFilesFor } from '../harness/unit-paths';
 import { CONTROL_CHARS, freeFeatureText, renderTraceSteps, scenarioBlockText } from './render-free-gherkin';
 import { collectRuns, TraceRun } from './trace/collect-trace-evidence';
+import { idsClaimedByTwoTests } from './trace/scenario-id-claims';
 import { readIdentityCache } from './trace/identity-cache';
 import type { TraceIdentityResolver } from './trace/target-identity';
 import { identitiesFor, resolveWithDriver } from './trace/trace-identity-resolution';
@@ -35,9 +39,17 @@ export interface DeriveResult {
   file: string;
   written: boolean;
   scenarios: Array<{ id: string; title: string; steps: number; low: number; opaque: number }>;
-  skipped: Array<{ id: string; reason: string }>;
+  /** `approved: true` — skipped because QA already approved it (derive never rewrites one), not for want of a trace. */
+  skipped: Array<{ id: string; reason: string; approved?: true }>;
   refused?: SecretHit[];
+  /**
+   * Ids two or more recorded tests claim (#962), each test as `file:line "title" (run record <path>)` —
+   * nothing was written. `staleRecords`: older test-results/ records that are a claim's only source.
+   */
+  duplicateIds?: Array<{ id: string; tests: string[]; staleRecords?: string[] }>;
   note?: string;
+  /** A derived id another `.feature` of the unit already uses (#939) — `contract check` and approve would trip on it later. */
+  warnings?: string[];
 }
 
 const MACHINE_PATH = /(?:\/Users|\/home)\/[^/\s"'`]+\/|[A-Za-z]:\\Users\\/;
@@ -58,13 +70,42 @@ function semanticHits(text: string, label: string): SecretHit[] {
   } finally { fs.rmSync(dir, { recursive: true, force: true }); }
 }
 
+/**
+ * The derived ids another `.feature` of the unit already carries (#939): `contract check` reports an id
+ * used twice and approve refuses it, so say it now — when it is still one rename away — not at check.
+ */
+function reusedIdWarnings(unit: { name: string; dir: string }, freeFile: string, ids: string[]): string[] {
+  const owners = new Map<string, string>();
+  for (const f of featureFilesFor(unit.dir, unit.name)) {
+    if (path.resolve(f) === path.resolve(freeFile) || !fs.existsSync(f)) continue;
+    try {
+      for (const sc of scenariosOfFeatureFile(f)) if (!owners.has(sc.id)) owners.set(sc.id, path.basename(f));
+    } catch { /* an unparseable sibling is `contract check`'s to report */ }
+  }
+  return ids.filter((id) => owners.has(id)).map((id) =>
+    `${id} is already the ID of a scenario in ${owners.get(id)} — the derived scenario reuses it; give the free test (its title's leading ID, or its @tag) or that scenario its own ID, or \`sungen contract check\` reports it twice and approval refuses it`);
+}
+
+/**
+ * Nothing was derived and nothing explains it away: no test of the unit left an admissible trace
+ * (#932). Not when the scenarios are approved (derive leaves those alone by design), up to date,
+ * refused, or the project is mobile (`note`).
+ */
+export function nothingDerived(r: DeriveResult): boolean {
+  return !r.note && !r.refused?.length && !r.duplicateIds?.length && r.scenarios.length === 0 && !r.skipped.some((s) => s.approved);
+}
+
 export async function deriveFreeFeature(i: DeriveInput): Promise<DeriveResult> {
   const unitBase = path.basename(i.unit.name);
   const file = path.join(i.unit.dir, 'features', `${unitBase}.free.feature`);
   const result: DeriveResult = { file, written: false, scenarios: [], skipped: [] };
   if ((readCapabilities(i.projectRoot).platform ?? '').toLowerCase() === 'mobile') return { ...result, note: MOBILE_NOT_SUPPORTED };
   const grep = i.grep ? new RegExp(i.grep, 'i') : null;
-  const found = collectRuns(i.projectRoot, (id, t) => (grep ? grep.test(`${id} ${t.title} ${t.file}`) : belongsToUnit(t.file, unitBase.toLowerCase())), 0);
+  const found = collectRuns(i.projectRoot, (id, t) => (grep ? grep.test(`${id} ${t.title} ${t.file}`) : belongsToUnit(t.file, unitBase.toLowerCase())), null);
+  const claimed = idsClaimedByTwoTests(i.projectRoot, found.runs);
+  if (claimed.size) {
+    return { ...result, duplicateIds: [...claimed].sort(([a], [b]) => a.localeCompare(b, 'en')).map(([id, c]) => ({ id, tests: c.tests, ...(c.staleRecords.length ? { staleRecords: c.staleRecords } : {}) })) };
+  }
   const byId = new Map<string, TraceRun[]>();
   for (const r of found.runs) byId.set(r.scenarioId, [...(byId.get(r.scenarioId) ?? []), r]);
   const admissible = (runs: TraceRun[]): TraceRun[] => runs.filter((r) => r.status === 'admissible' && r.trace)
@@ -79,7 +120,7 @@ export async function deriveFreeFeature(i: DeriveInput): Promise<DeriveResult> {
   for (const id of [...byId.keys()].sort((a, b) => a.localeCompare(b, 'en'))) {
     const runs = admissible(byId.get(id)!);
     if (!runs.length) { result.skipped.push({ id, reason: byId.get(id)![0].reason ?? 'no admissible trace' }); continue; }
-    if (kept.some((b) => b.id === id && !b.proposed)) { result.skipped.push({ id, reason: 'approved — derive never rewrites an approved scenario; use `sungen contract check --trace`' }); continue; }
+    if (kept.some((b) => b.id === id && !b.proposed)) { result.skipped.push({ id, reason: 'approved — derive never rewrites an approved scenario; use `sungen contract check --trace`', approved: true }); continue; }
     const secrets = new Set<string>();
     const rendered = runs.map((r) => {
       const steps = traceIntentSteps(r.trace!);
@@ -98,6 +139,8 @@ export async function deriveFreeFeature(i: DeriveInput): Promise<DeriveResult> {
     result.scenarios.push({ id, title, steps: rendered[0].length, low: rendered[0].filter((s) => s.low).length, opaque: rendered[0].filter((s) => s.opaque).length });
   }
   if (!result.scenarios.length) return result;
+  const reused = reusedIdWarnings(i.unit, file, result.scenarios.map((x) => x.id));
+  if (reused.length) result.warnings = reused;
 
   const text = freeFeatureText(unitBase, [...blocks.values()]);
   const label = path.basename(file);

package/src/contract/project-contract-blockers.ts

@@ -4,12 +4,14 @@
  * HEAD is read once (one `git ls-tree`, bounded by the caller's timeout). A unit with no lock in the
  * working tree AND none in HEAD has no contract to break and is skipped without parsing anything.
  * Every other unit gets its verdict rebuilt by buildContractVerdict — the same function `contract
- * check` runs — and anything but `pass` blocks. A lock deleted from the working tree still counts
+ * check` runs — and anything but `pass` blocks. Its trace part gets the guard's ~3 s at most:
+ * SUNGEN_TRACE_VERDICT_BUDGET_MS can shorten that here, never lengthen it (#926). A lock deleted from the working tree still counts
  * while HEAD holds it. If git FAILS in a checkout that has .git while a delivered unit has a lock,
  * this throws (GitUnavailableError): the guard asks rather than calling an unverifiable lock clean.
  */
 import * as fs from 'fs';
 import { buildContractVerdict, ContractUnit, VerdictValue } from './build-contract-verdict';
+import { guardTraceBudgetMs } from './build-trace-conformance';
 import { CLI_GIT_TIMEOUT_MS, GitUnavailableError, headSnapshot, posixRel } from './contract-git';
 import { HARD_CLASSES } from './contract-schema';
 import { lockPathFor } from './contracts-lock-file';
@@ -24,7 +26,7 @@ export function contractBlockers(projectRoot: string, units: ContractUnit[], opt
   const out: ContractBlocker[] = [];
   for (const unit of unique) {
     if (!hasWorkingLock(unit) && !snap.blobs?.has(posixRel(projectRoot, lockPathFor(unit.dir)))) continue;
-    const v = buildContractVerdict(projectRoot, unit, { snapshot: snap });
+    const v = buildContractVerdict(projectRoot, unit, { snapshot: snap, traceBudgetMs: guardTraceBudgetMs() });
     if (v.verdict === 'pass') continue;
     const worst = v.scenarios.find((s) => HARD_CLASSES.has(s.class)) ?? v.scenarios.find((s) => s.class === 'hash-changed');
     const headline = worst

package/src/contract/record-contract-approval.ts

@@ -9,13 +9,17 @@
  * The decision goes first: a crash between the two leaves a record without a lock entry, never an
  * entry pointing at nothing. Only `sungen contract approve` calls this after its TTY confirmation;
  * the confirmation itself lives there (approve-contract.ts).
+ *
+ * `--accept-opaque` (#923, accept-opaque-steps.ts) writes the same kind of decision for ONE scenario,
+ * listing it at its hash WITH the opaque steps QA accepted (step + sha); its lock entry is rewritten to
+ * point at that decision and carries the same list, which verify-approval-decisions.ts cross-checks.
  */
 import * as path from 'path';
 import { appendDecision } from '../decisions/append-decision';
 import { isValidScope } from '../decisions/decision-file';
 import type { JsonValue } from '../decisions/decision-schema';
 import { gitUserName } from '../decisions/decision-source';
-import { ContractLock, ContractScenario, LOCK_SCHEMA } from './contract-schema';
+import { AcceptedOpaqueStep, ContractLock, ContractScenario, LOCK_SCHEMA } from './contract-schema';
 import { lockEntryFor, lockPathFor, serializeLock, writeLockFile } from './contracts-lock-file';
 import { assertNoLockSecrets } from './lock-secret-guard';
 
@@ -30,6 +34,18 @@ export interface ApprovalWrite {
 }
 
 export const DEFAULT_APPROVAL_REASON = 'QA reviewed the normalized Gherkin contract';
+export const DEFAULT_OPAQUE_REASON = 'QA reviewed the opaque step(s) sungen cannot compare';
+
+export interface OpaqueAcceptanceWrite {
+  projectRoot: string;
+  unitDir: string;
+  unit: string;
+  /** The scenario as it reads now — its hash equals its approved lock entry's. */
+  scenario: ContractScenario;
+  accepted: AcceptedOpaqueStep[];
+  reason?: string;
+  lock: ContractLock;
+}
 
 /** The decision scope of a unit directory (`screens/login`, `api/flows/pay`…). */
 export function scopeOfUnitDir(projectRoot: string, unitDir: string): string {
@@ -68,3 +84,27 @@ export function recordContractApproval(w: ApprovalWrite): { decisionId: string;
   writeLockFile(lockPathFor(w.unitDir), lock);
   return { decisionId: decision.entry.id, lock };
 }
+
+function lockWithAcceptance(w: OpaqueAcceptanceWrite, decisionId: string, approvedAt: string): ContractLock {
+  const entry = { ...lockEntryFor(w.scenario, decisionId, approvedAt), acceptedOpaque: w.accepted.map((a) => ({ step: a.step, sha: a.sha })) };
+  return { schema: LOCK_SCHEMA, scenarios: { ...w.lock.scenarios, [w.scenario.id]: entry } };
+}
+
+export function recordOpaqueAcceptance(w: OpaqueAcceptanceWrite): { decisionId: string; lock: ContractLock } {
+  const scope = scopeOfUnitDir(w.projectRoot, w.unitDir);
+  assertNoLockSecrets([w.scenario], serializeLock(lockWithAcceptance(w, 'D-0000000000000000', new Date().toISOString())));
+  const sc = w.scenario;
+  const accepted = w.accepted.map((a) => ({ step: a.step, sha: a.sha }));
+  const payload: Record<string, JsonValue> = {
+    unit: w.unit, scenarios: [{ id: sc.id, hash: sc.hash, implementation: sc.implementation, acceptedOpaque: accepted }], removed: [],
+  };
+  const decision = appendDecision(w.projectRoot, scope, {
+    kind: 'contract-approval', anchors: [], visibility: 'internal', valid_from: new Date().toISOString(), payload,
+    text: `Accepted the reviewed opaque step(s) ${[...new Set(accepted.map((a) => a.step))].join(', ')} of ${sc.id} (${w.unit})`,
+    reason: w.reason?.trim() || DEFAULT_OPAQUE_REASON,
+    source: { by: gitUserName(w.projectRoot), where: 'cli' },
+  });
+  const lock = lockWithAcceptance(w, decision.entry.id, decision.entry.valid_from);
+  writeLockFile(lockPathFor(w.unitDir), lock);
+  return { decisionId: decision.entry.id, lock };
+}

package/src/contract/render-free-gherkin.ts

@@ -22,6 +22,11 @@ import { isPageLevel } from './trace/trace-identity-resolution';
 import type { IntentStep } from './trace/trace-steps';
 
 export const CONTROL_CHARS = /[\u0000-\u001f\u007f\u2028\u2029]/g;
+/** Text from a trace or report shown in one line of a finding: control characters dropped, at most `max` characters. */
+export function clip(s: string, max = 120): string {
+  const t = s.replace(CONTROL_CHARS, '');
+  return t.length > max ? `${t.slice(0, max - 1)}\u2026` : t;
+}
 
 export interface ResolvedTarget { identity: TargetIdentity; facts?: TargetFacts }
 export interface RenderedStep {

package/src/contract/resolve-unit-trace-identities.ts

@@ -3,33 +3,56 @@
  * resolver (driver-ui — a real browser) about every target of the unit's admissible traces and
  * cache the answers (DOS-14.5). The verdict itself never calls a browser; it reads the cache, so
  * the CLI and the Claude Code guard keep building the same verdict from the same files.
+ *
+ * What it reports is split for QA (#966): a WARNING only when something needs attention — no
+ * resolver, a mobile project, a target the browser could not name (its steps stay opaque). "Every
+ * target was already known" and "N new targets identified" are information, in plain words.
  */
-import * as fs from 'fs';
 import { capabilityRegistry } from '../capabilities/registry';
 import { readCapabilities } from '../harness/capability';
 import { MOBILE_NOT_SUPPORTED } from './build-trace-conformance';
-import { lockPathFor } from './contracts-lock-file';
-import { contractFeatureFiles, loadContractScenarios } from './normalize-feature-steps';
+import { loadContractScenarios } from './normalize-feature-steps';
 import { collectScenarioEvidence } from './trace/collect-trace-evidence';
+import { readIdentityCache } from './trace/identity-cache';
+import { unitContract } from './trace/trace-freshness';
 import type { TraceIdentityResolver } from './trace/target-identity';
 import { resolveWithDriver } from './trace/trace-identity-resolution';
 
-const mtimeMs = (f: string): number => { try { return fs.statSync(f).mtimeMs; } catch { return 0; } };
+export interface TraceIdentityOutcome { warnings: string[]; info: string[] }
 
 /** The first registered capability that can resolve trace identities (UI: driver-ui), if any. */
 export function registeredTraceResolver(): TraceIdentityResolver | undefined {
   return capabilityRegistry.all().find((c) => typeof c.traceIdentity === 'function')?.traceIdentity;
 }
 
-export async function resolveUnitTraceIdentities(projectRoot: string, unit: { name: string; dir: string }, resolver = registeredTraceResolver()): Promise<string[]> {
+export async function traceIdentityOutcome(projectRoot: string, unit: { name: string; dir: string }, resolver = registeredTraceResolver()): Promise<TraceIdentityOutcome> {
+  const none: TraceIdentityOutcome = { warnings: [], info: [] };
   const traced = loadContractScenarios(unit.dir, unit.name).filter((s) => s.implementation !== 'compiled');
-  if (!traced.length) return [];
-  if ((readCapabilities(projectRoot).platform ?? '').toLowerCase() === 'mobile') return [MOBILE_NOT_SUPPORTED];
-  if (!resolver) return ['no trace identity resolver is registered (install @sungen/driver-ui) — every target identity stays low, so nothing can match'];
-  const notBefore = Math.max(mtimeMs(lockPathFor(unit.dir)), ...contractFeatureFiles(unit.dir, unit.name).map(mtimeMs));
-  const evidence = collectScenarioEvidence(projectRoot, new Set(traced.map((s) => s.id)), notBefore);
+  if (!traced.length) return none;
+  if ((readCapabilities(projectRoot).platform ?? '').toLowerCase() === 'mobile') return { warnings: [MOBILE_NOT_SUPPORTED], info: [] };
+  if (!resolver) return { warnings: ['no trace identity resolver is registered (install @sungen/driver-ui) — every target identity stays low, so nothing can match'], info: [] };
+  const evidence = collectScenarioEvidence(projectRoot, new Set(traced.map((s) => s.id)), unitContract(projectRoot, unit));
   const traces = [...evidence.runs.values()].flat().filter((r) => r.status === 'admissible' && r.trace).map((r) => r.trace!);
-  if (!traces.length) return [];
+  if (!traces.length) return none;
   const r = await resolveWithDriver(projectRoot, traces, resolver);
-  return [`trace identity: ${r.asked} target(s) resolved by ${r.resolver || 'the cache'}${r.blockedRequests ? `, ${r.blockedRequests} replay request(s) blocked` : ''}`];
+  const { cache } = readIdentityCache(projectRoot);
+  const total = r.keys.length;
+  const unnamed = r.keys.filter((k) => cache.entries.get(k)?.identityConfidence !== 'high').length;
+  const blocked = r.blockedRequests ? `; the replayed pages tried ${r.blockedRequests} request(s), all blocked` : '';
+  const known = total - r.asked;
+  const info = r.asked
+    ? `trace identity: ${r.asked} new target(s) identified in a real browser (${r.resolver})${known ? `, ${known} already known` : ''}${blocked}`
+    : `trace identity: all ${total} target(s) were already identified (identity cache) — nothing new to resolve`;
+  const warnings = unnamed
+    ? [`trace identity: ${unnamed} of ${total} target(s) could not be identified (no unique accessible name) — the steps on them stay opaque, for QA to review, until the test targets a unique, named element`]
+    : [];
+  return { warnings, info: [info] };
+}
+
+/**
+ * What `contract check --trace` adds to the verdict's warnings: only what needs attention (#966).
+ * The plain-words information is `traceIdentityOutcome(...).info`.
+ */
+export async function resolveUnitTraceIdentities(projectRoot: string, unit: { name: string; dir: string }, resolver = registeredTraceResolver()): Promise<string[]> {
+  return (await traceIdentityOutcome(projectRoot, unit, resolver)).warnings;
 }