@sun-asterisk/sungen 3.3.0-alpha.7 → 3.3.0-alpha.9

package/src/contract/trace/trace-freshness.ts

@@ -0,0 +1,110 @@
+/**
+ * Is a trace newer than the contract it is asked to prove? (DOS-14.6: a trace older than the
+ * `.feature` or the lock is refused.) Judged by CONTENT, never by file time alone (#967): a `touch`,
+ * a checkout or a fresh clone changes no byte, so it stales nothing; an edit after the run always does.
+ *
+ *   schema 2 record   the reporter hashed every `.feature` and `contracts.lock.yaml` under `qa/` when
+ *                     the run started. Each of the unit's contract files must hash NOW to what the run
+ *                     saw: one that changed since, or did not exist yet, is newer than the trace → stale
+ *   schema 1 record   an older reporter recorded no content, so the files are dated against the run's
+ *                     start (the record's `startedAt`): one last written before it is older than the run;
+ *                     one written after it still is when git holds it unchanged and the commit that last
+ *                     changed it is an ancestor of HEAD committed before the run started (its bytes ARE
+ *                     that commit's). Anything else — edited, uncommitted, untracked, committed after the
+ *                     run started, no git, git failed or slow — is stale: fail closed.
+ *
+ * Limit of the schema-1 path: a commit time is what the committer's clock (or GIT_COMMITTER_DATE) said,
+ * so a backdated commit passes the time check — time-based checks cannot see through that. Schema 2
+ * compares content and retires this path: re-running the free tests once with the current reporter is
+ * the remedy.
+ */
+import { execFileSync } from 'child_process';
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { lockPathFor } from '../contracts-lock-file';
+import { contractFeatureFiles } from '../normalize-feature-steps';
+import type { RunRecord } from './trace-run-record';
+
+interface ContractFile { rel: string; sha: string; mtimeMs: number }
+interface LastCommit { sha: string; ms: number }
+/** A unit's contract as it is NOW — its `.feature` files and lock, read once per verdict. */
+export interface UnitContract {
+  projectRoot: string;
+  files: ContractFile[];
+  /** Schema 1 only, asked of git at most once: project path → the last commit that changed each file git holds unchanged. */
+  committed?: Map<string, LastCommit> | null;
+  /** Schema 1 only: commit → is it an ancestor of HEAD (asked once per commit). */
+  ancestors?: Map<string, boolean>;
+}
+
+/** Inside the Claude Code guard too: a slow git leaves a schema-1 trace stale rather than the hook waiting. */
+const GIT_TIMEOUT_MS = 2_000;
+const posix = (p: string): string => p.split(path.sep).join('/');
+
+export function unitContract(projectRoot: string, unit: { name: string; dir: string }): UnitContract {
+  const root = path.resolve(projectRoot);
+  const lock = path.resolve(lockPathFor(unit.dir));
+  const files = [...(fs.existsSync(lock) ? [lock] : []), ...contractFeatureFiles(unit.dir, unit.name)].map((abs) => {
+    let sha = 'unreadable';   // never equal to a recorded sha256: an unreadable contract file is stale
+    let mtimeMs = Number.POSITIVE_INFINITY;
+    try { sha = createHash('sha256').update(fs.readFileSync(abs)).digest('hex'); mtimeMs = fs.statSync(abs).mtimeMs; } catch { /* stale */ }
+    return { rel: posix(path.relative(root, abs)), sha, mtimeMs };
+  });
+  return { projectRoot: root, files };
+}
+
+function git(cwd: string, args: string[]): string | null {
+  try { return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 }).toString('utf8'); } catch { return null; }
+}
+
+/**
+ * Each contract file git holds unchanged → the last commit (first-parent history, merges included)
+ * that changed it, with its committer time. Two git calls for the whole unit; null when git cannot say.
+ * Paths are passed as literal pathspecs: no glob or `:(magic)` reading of a unit's file names.
+ */
+function committedTimes(c: UnitContract): Map<string, LastCommit> | null {
+  if (c.committed !== undefined) return c.committed;
+  const rels = c.files.map((f) => f.rel);
+  const changed = git(c.projectRoot, ['--literal-pathspecs', 'diff', '--name-only', '--relative', '-z', 'HEAD', '--', ...rels]);
+  const log = git(c.projectRoot, ['-c', 'core.quotePath=false', '--literal-pathspecs', 'log', '--first-parent', '-m', '-n', '500', '--format=%x01%H %ct', '--name-only', '--relative', '--', ...rels]);
+  if (changed === null || log === null) return (c.committed = null);
+  const dirty = new Set(changed.split('\0').filter(Boolean));
+  const times = new Map<string, LastCommit>();
+  let at: LastCommit | null = null;
+  for (const raw of log.split('\n')) {
+    const line = raw.trim();
+    if (raw.startsWith('\x01')) {
+      const [sha, ct] = raw.slice(1).trim().split(' ');
+      at = /^[0-9a-f]{40,64}$/.test(sha ?? '') && Number(ct) > 0 ? { sha, ms: Number(ct) * 1000 } : null;
+    } else if (line && at && !times.has(line) && !dirty.has(line)) times.set(line, at);
+  }
+  return (c.committed = times);
+}
+
+/** Is `sha` an ancestor of HEAD? First-parent history says so already; asserted, never assumed. */
+function isAncestorOfHead(c: UnitContract, sha: string): boolean {
+  if (!c.ancestors) c.ancestors = new Map();
+  if (!c.ancestors.has(sha)) c.ancestors.set(sha, git(c.projectRoot, ['merge-base', '--is-ancestor', sha, 'HEAD']) !== null);
+  return c.ancestors.get(sha)!;
+}
+
+/** Why a trace bound to `record` is older than the unit's contract — null when it is not. */
+export function staleReason(c: UnitContract, record: RunRecord): string | null {
+  if (record.contract) {
+    const f = c.files.find((x) => record.contract![x.rel] !== x.sha);
+    if (!f) return null;
+    const why = record.contract[f.rel] === undefined ? 'it did not exist when the run started' : 'its content changed after the run';
+    return `the trace is older than ${f.rel}: ${why} (stale) — re-run the test`;
+  }
+  const runStart = Date.parse(record.startedAt);   // unreadable → nothing is "before the run": stale
+  const late = c.files.filter((f) => !(f.mtimeMs <= runStart));
+  if (!late.length) return null;
+  const committed = committedTimes(c);
+  const vouched = (rel: string): boolean => {
+    const last = committed?.get(rel);
+    return !!last && last.ms <= runStart && isAncestorOfHead(c, last.sha);
+  };
+  const f = late.find((x) => !vouched(x.rel));
+  return f ? `the trace is older than ${f.rel}: it was written after the run, and no commit from before the run holds its bytes (stale) — re-run the test` : null;
+}

package/src/contract/trace/trace-identity-resolution.ts

@@ -51,13 +51,16 @@ export function identityRequestsFor(trace: ParsedTrace): TraceIdentityRequest[]
 }
 
 /** Ask the driver about every not-yet-cached target of these traces; rewrite the cache. */
-export async function resolveWithDriver(projectRoot: string, traces: ParsedTrace[], resolver: TraceIdentityResolver): Promise<{ asked: number; resolver: string; blockedRequests: number }> {
+/** `keys`: every target of the given traces (cached or asked) — what the caller reports on. */
+export async function resolveWithDriver(projectRoot: string, traces: ParsedTrace[], resolver: TraceIdentityResolver): Promise<{ asked: number; resolver: string; blockedRequests: number; keys: string[] }> {
   const { cache } = readIdentityCache(projectRoot);
   // The cache is project-wide (every unit's traces): answers are only ever ADDED, never pruned here.
   const keep = new Map<string, CachedIdentity>(cache.entries);
+  const all = traces.flatMap(identityRequestsFor);
+  const keys = [...new Set(all.map((req) => req.key))];
   const requests = new Map<string, TraceIdentityRequest>();
-  for (const req of traces.flatMap(identityRequestsFor)) if (!keep.has(req.key)) requests.set(req.key, req);
-  if (!requests.size) return { asked: 0, resolver: cache.resolver, blockedRequests: 0 };
+  for (const req of all) if (!keep.has(req.key)) requests.set(req.key, req);
+  if (!requests.size) return { asked: 0, resolver: cache.resolver, blockedRequests: 0, keys };
   const answer = await resolver({ requests: [...requests.values()] });
   if (!answer || !Array.isArray(answer.results)) throw new Error('the trace identity resolver returned no results');
   if (!TRUSTED_RESOLVER.test(String(answer.resolver)) || typeof answer.browser !== 'string' || !answer.browser) {
@@ -70,5 +73,5 @@ export async function resolveWithDriver(projectRoot: string, traces: ParsedTrace
     keep.set(key, { ...rest, browser: answer.browser.slice(0, 100) });
   }
   writeIdentityCache(projectRoot, answer.resolver, keep);
-  return { asked: requests.size, resolver: String(answer.resolver), blockedRequests: Number(answer.blockedRequests) || 0 };
+  return { asked: requests.size, resolver: String(answer.resolver), blockedRequests: Number(answer.blockedRequests) || 0, keys };
 }

package/src/contract/trace/trace-run-record.ts

@@ -8,6 +8,10 @@
  * own outputDir (#941) — or `<project>/test-results/sungen-run-record*.json` (one per run or shard).
  * Playwright wipes its outputDir at the start of every run, so a record and its traces share a
  * lifetime; the free run has its own so the compiled suite's next run cannot delete its traces.
+ *
+ * Schema 2 (#967) adds `contract`: the sha256 of every `.feature` and `contracts.lock.yaml` under `qa/`
+ * when the run started — what trace freshness compares by content. Schema 1 (an older reporter) has
+ * none; its traces are dated instead (trace-freshness.ts).
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -24,10 +28,13 @@ export interface RunRecord {
   shard: string | null;
   report: string | null;
   specs: Record<string, string>;
+  /** Schema 2: project path → sha256 of each contract file at run start. null: schema 1 (no content recorded). */
+  contract: Record<string, string> | null;
   attempts: RunRecordAttempt[];
 }
 
-const TOP = new Set(['schema', 'tool', 'runId', 'startedAt', 'playwrightVersion', 'shard', 'report', 'specs', 'attempts']);
+const TOP_V1: ReadonlySet<string> = new Set(['schema', 'tool', 'runId', 'startedAt', 'playwrightVersion', 'shard', 'report', 'specs', 'attempts']);
+const TOP_V2: ReadonlySet<string> = new Set([...TOP_V1, 'contract']);
 const ATTEMPT = new Set(['testId', 'file', 'title', 'retry', 'status', 'startTime', 'duration', 'trace']);
 const SHA = /^[0-9a-f]{64}$/;
 const isObj = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
@@ -65,16 +72,25 @@ export function readRunRecord(file: string, text?: string): RunRecord {
   let raw: unknown;
   try { raw = JSON.parse(text ?? fs.readFileSync(file, 'utf8')); } catch (e) { throw new Error(`not readable JSON (${(e as Error).message.split('\n')[0]})`); }
   if (!isObj(raw)) throw new Error('not an object');
-  const extra = Object.keys(raw).find((k) => !TOP.has(k));
+  if (raw.tool === 'sungen-trace-run-record' && typeof raw.schema === 'number' && raw.schema > 2) {
+    // A newer driver-ui wrote it (mixed versions): say what to upgrade, not just "not a record".
+    throw new Error(`record schema ${raw.schema} is newer than this sungen — upgrade @sun-asterisk/sungen (core before or together with driver-ui)`);
+  }
+  const keys = raw.schema === 2 ? TOP_V2 : raw.schema === 1 ? TOP_V1 : null;
+  if (!keys || raw.tool !== 'sungen-trace-run-record') throw new Error('not a sungen run record (schema 1 or 2)');
+  const extra = Object.keys(raw).find((k) => !keys.has(k));
   if (extra) throw new Error(`unknown key "${extra}"`);
-  if (raw.schema !== 1 || raw.tool !== 'sungen-trace-run-record') throw new Error('not a sungen run record (schema 1)');
   if (typeof raw.runId !== 'string' || !raw.runId || typeof raw.startedAt !== 'string' || typeof raw.playwrightVersion !== 'string') throw new Error('runId, startedAt and playwrightVersion must be strings');
   if (raw.shard !== null && typeof raw.shard !== 'string') throw new Error('shard must be a string or null');
   if (raw.report !== null && typeof raw.report !== 'string') throw new Error('report must be a string or null');
   if (!isObj(raw.specs) || !Object.values(raw.specs).every((v) => typeof v === 'string' && (v === '' || SHA.test(v)))) throw new Error('specs must map files to sha256');
+  if (raw.schema === 2 && !(isObj(raw.contract) && Object.values(raw.contract).every((v) => typeof v === 'string' && SHA.test(v)))) {
+    throw new Error('contract must map contract files to sha256 (schema 2)');
+  }
   if (!Array.isArray(raw.attempts)) throw new Error('attempts must be a list');
   return {
     file, runId: raw.runId, startedAt: raw.startedAt, playwrightVersion: raw.playwrightVersion, shard: raw.shard as string | null,
-    report: raw.report as string | null, specs: raw.specs as Record<string, string>, attempts: raw.attempts.map(attemptOf),
+    report: raw.report as string | null, specs: raw.specs as Record<string, string>,
+    contract: raw.schema === 2 ? raw.contract as Record<string, string> : null, attempts: raw.attempts.map(attemptOf),
   };
 }

package/src/exporters/csv-exporter.ts

@@ -439,12 +439,12 @@ export function renderCsv(summary: ScreenSummary, rows: TestCaseRow[], specLink:
  * multi-locale delivery aggregator. Pass an empty string to force the
  * base (no suffix) variant.
  */
-export function writeCsv(cwd: string, screen: string, csvContent: string, locale?: string | null): string {
+export function writeCsv(cwd: string, screen: string, csvContent: string, locale?: string | null, opts: DeliverableFileOptions = {}): string {
   const outDir = path.join(cwd, 'qa', 'deliverables');
   if (!fs.existsSync(outDir)) {
     fs.mkdirSync(outDir, { recursive: true });
   }
-  const outPath = path.join(outDir, `${deliverableBasename(screen, locale)}.csv`);
+  const outPath = path.join(outDir, `${deliverableBasename(screen, locale, opts)}.csv`);
   fs.writeFileSync(outPath, csvContent, 'utf-8');
   return outPath;
 }
@@ -455,8 +455,16 @@ export function writeCsv(cwd: string, screen: string, csvContent: string, locale
  * locale is given (or `SUNGEN_ENV` is set and no explicit override). Pass
  * `null` / empty string to force the base variant.
  */
-export function deliverableBasename(screen: string, locale?: string | null): string {
+export function deliverableBasename(screen: string, locale?: string | null, opts: DeliverableFileOptions = {}): string {
   const effective = locale !== undefined ? locale : process.env.SUNGEN_ENV;
-  return effective ? `${screen}-testcases.${effective}` : `${screen}-testcases`;
+  return `${effective ? `${screen}-testcases.${effective}` : `${screen}-testcases`}${opts.draft ? DRAFT_MARK : ''}`;
 }
 
+/**
+ * A DRAFT render (a watermarked `--preview`) is written beside the official deliverable, never onto it
+ * (#965): `<screen>-testcases[.env].DRAFT.<ext>`. Readers of `qa/deliverables/` skip it (isDraftDeliverable).
+ */
+export interface DeliverableFileOptions { draft?: boolean }
+export const DRAFT_MARK = '.DRAFT';
+export const isDraftDeliverable = (fileName: string): boolean => /\.DRAFT\.[^.]+$/.test(fileName);
+

package/src/exporters/matrix/export.ts

@@ -169,7 +169,12 @@ export function approveMatrix(paths: MatrixTargetPaths, groupIds?: string[]): {
 
 export type MatrixFormat = 'xlsx' | 'csv' | 'both';
 
-/** Render + write the requested format(s). Caller has already enforced the gate policy. */
+/**
+ * Render + write the requested format(s). Caller has already enforced the gate policy. A draft (the
+ * matrix is not approved for official delivery: it carries the DRAFT banner) goes to its own
+ * `…-testcases.DRAFT.<ext>` and never overwrites the official file (#965); the tester's Manual results
+ * are still carried from the official workbook when it can be read.
+ */
 export async function writeMatrixDeliverables(
   paths: MatrixTargetPaths,
   model: MatrixModel,
@@ -179,23 +184,25 @@ export async function writeMatrixDeliverables(
 ): Promise<{ csvPath?: string; xlsxPath?: string; manualCarry?: ManualCarryReport }> {
   const out: { csvPath?: string; xlsxPath?: string; manualCarry?: ManualCarryReport } = {};
   const xlsx = format === 'xlsx' || format === 'both';
+  const draft = model.manifest.approvalState === 'draft';
   // Read the workbook about to be overwritten BEFORE writing anything, so the tester's Manual
   // results survive (#756) and a refusal leaves no half-written target behind.
   // A CSV-only export overwrites no workbook, so an unreadable one is no reason to refuse it — but a
   // readable one still holds the Manual results the CSV should show.
+  // A draft overwrites nothing official either, so an unreadable official workbook is no reason to refuse it.
   const prior = priorRead !== undefined ? priorRead
-    : xlsx ? await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit))
+    : xlsx && !draft ? await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit))
       : await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit)).catch(() => null);
   // Into the model first: the CSV, every cached total and roll-up, and the caller's summary
   // all read it (#891).
   applyManualCarry(model, prior);
   if (format === 'csv' || format === 'both') {
-    out.csvPath = writeCsv(paths.cwd, paths.unit, renderMatrixCsv(model));
+    out.csvPath = writeCsv(paths.cwd, paths.unit, renderMatrixCsv(model), undefined, { draft });
   }
   if (xlsx) {
     const wb = renderMatrixXlsx(model, getPackageVersion());
     out.manualCarry = carryManualResults(wb, model, prior);
-    out.xlsxPath = await writeXlsx(paths.cwd, paths.unit, wb);
+    out.xlsxPath = await writeXlsx(paths.cwd, paths.unit, wb, undefined, { draft });
   }
   return out;
 }

package/src/exporters/xlsx-exporter.ts

@@ -18,7 +18,7 @@ import ExcelJS from 'exceljs';
 import JSZip from 'jszip';
 import { ApiCatalogEntry, ApiDetailRow, ScreenSummary, TestCaseRow } from './types';
 import { getPackageVersion } from './package-info';
-import { deliverableBasename } from './csv-exporter';
+import { deliverableBasename, DeliverableFileOptions } from './csv-exporter';
 import {
   extractApiCallOrder,
   extractCasesDataset,
@@ -114,8 +114,8 @@ export function buildApiDetailRows(
  * to force the base (no suffix) variant.
  */
 /** Where `writeXlsx` puts a unit's workbook — shared so a reader targets the identical file. */
-export function deliverableXlsxPath(cwd: string, screen: string, locale?: string | null): string {
-  return path.join(cwd, 'qa', 'deliverables', `${deliverableBasename(screen, locale)}.xlsx`);
+export function deliverableXlsxPath(cwd: string, screen: string, locale?: string | null, opts: DeliverableFileOptions = {}): string {
+  return path.join(cwd, 'qa', 'deliverables', `${deliverableBasename(screen, locale, opts)}.xlsx`);
 }
 
 export async function writeXlsx(
@@ -123,8 +123,9 @@ export async function writeXlsx(
   screen: string,
   wb: ExcelJS.Workbook,
   locale?: string | null,
+  opts: DeliverableFileOptions = {},
 ): Promise<string> {
-  const outPath = deliverableXlsxPath(cwd, screen, locale);
+  const outPath = deliverableXlsxPath(cwd, screen, locale, opts);
   const outDir = path.dirname(outPath);
   if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
   const buffer = await wb.xlsx.writeBuffer();

package/src/graph/evaluate-graph.ts

@@ -84,12 +84,14 @@ export function evaluateGraph(
  * rules of its own: each offered step's node says what a person runs (its `human` hook), and a decide
  * step without one is its own command. `cut`: an open blocking node ended the walk, so only what does
  * not depend on it is offered (a hard verdict that surfaces past the cut), and the board's asks that
- * need the unit past it (sign-off, accept-in-run) wait; `heldBy` is that node's title.
+ * need the unit past it (sign-off, accept-in-run) wait; `heldBy` is that node's title and `heldByCommand`
+ * its offered step's command (#966: "More appear once …" names what to run).
  */
-export function evaluateHumanActions(nodes: readonly NodeDecl[], s: UnitState, tcStates?: TestCaseState[]): { actions: HumanAction[]; cut: boolean; heldBy?: string } {
+export function evaluateHumanActions(nodes: readonly NodeDecl[], s: UnitState, tcStates?: TestCaseState[]): { actions: HumanAction[]; cut: boolean; heldBy?: string; heldByCommand?: string } {
   const { offered, cut, cutBy } = walkFrontier(nodes, s, tcStates, {});
   const actions = offered.flatMap(({ node, step, cases }) => (node.human
     ? node.human(s, step, cases)
     : step.kind === 'decide' ? [{ command: step.command, reason: step.because, kind: 'decide' as const }] : []));
-  return { actions, cut, ...(cutBy ? { heldBy: cutBy.title } : {}) };
+  const heldByCommand = cutBy ? offered.find((o) => o.node === cutBy)?.step.command : undefined;
+  return { actions, cut, ...(cutBy ? { heldBy: cutBy.title } : {}), ...(heldByCommand ? { heldByCommand } : {}) };
 }

package/src/graph/unit-artifact-probes.ts

@@ -9,6 +9,7 @@ import { parse as parseYaml } from 'yaml';
 import { featureFilesFor } from '../harness/unit-paths';
 import { readTextFile } from '../harness/read-text';
 import { loadPlaywrightReport } from '../exporters/playwright-report-parser';
+import { isDraftDeliverable } from '../exporters/csv-exporter';
 
 /** `<f>-test-result[.<os>][.<env>].json` — a mobile run writes the OS into the name, an env run the env (#868). */
 export const RESULT_FILE = /-test-result(?:\.[^.]+)*\.json$/;
@@ -72,6 +73,7 @@ export function countFailedResults(resultFiles: string[]): number {
 
 export function hasDeliverableFor(projectRoot: string, slug: string): boolean {
   try {
-    return fs.readdirSync(path.join(projectRoot, 'qa', 'deliverables')).some((f) => f.startsWith(`${slug}-`));
+    // A `--preview` DRAFT is not a deliverable (#965).
+    return fs.readdirSync(path.join(projectRoot, 'qa', 'deliverables')).some((f) => f.startsWith(`${slug}-`) && !isDraftDeliverable(f));
   } catch { return false; }                                    // nothing exported yet
 }

package/src/harness/gates/audit-report-verification.ts

@@ -58,6 +58,8 @@ function provenanceField(r: Record<string, unknown>, key: 'sungenVersion' | 'cat
 const writtenBy = (r: Record<string, unknown>): string | null => provenanceField(r, 'sungenVersion');
 
 export interface RulesStamp { catalogHash: string | null; rulesHash: string | null }
+/** rulesProblem's answer for a report that records no rules (`provenance.catalogHash` / `rulesHash`): an older sungen wrote it. */
+export const NO_RULES_STAMP = 'audited by an older sungen, which did not record the rules it scored with';
 /** What getProvenance writes when it could not read a catalog — never a match, on either side. */
 const UNKNOWN = 'unknown';
 
@@ -67,7 +69,7 @@ const UNKNOWN = 'unknown';
  * unknown == unknown proves nothing.
  */
 export function rulesProblem(was: RulesStamp, now: RulesStamp): string | null {
-  if (!was.catalogHash || !was.rulesHash) return 'it does not say which rules scored it (no provenance.catalogHash / rulesHash)';
+  if (!was.catalogHash || !was.rulesHash) return NO_RULES_STAMP;
   if ([was.catalogHash, was.rulesHash].includes(UNKNOWN)) return 'the rules that scored it are unknown (provenance says "unknown")';
   if (!now.catalogHash || !now.rulesHash || [now.catalogHash, now.rulesHash].includes(UNKNOWN)) return 'this sungen cannot read its own rules (catalog or rules hash unknown), so it trusts no report';
   if (was.catalogHash === now.catalogHash && was.rulesHash === now.rulesHash) return null;
@@ -162,7 +164,10 @@ export function verifyAuditReport(projectRoot: string, unit: string): AuditVerif
   }
   const stale: AuditVerification['problems'] = [];
   const rules = otherRules(r);
-  if (rules) stale.push({ code: 'rules-changed', message: `${writtenBy(r) ? `written by sungen ${writtenBy(r)}, ` : ''}${rules}` });
+  // A report from before the rules stamp reads in plain words, with the one command that clears it (#966).
+  if (rules) stale.push({ code: 'rules-changed', message: rules === NO_RULES_STAMP
+    ? `audited by an older sungen${writtenBy(r) ? ` (${writtenBy(r)})` : ''} — run \`sungen audit --screen ${unit}\` once`
+    : `${writtenBy(r) ? `written by sungen ${writtenBy(r)}, ` : ''}${rules}` });
   if (r.decisionsHash !== current) stale.push({ code: 'decisions-changed', message: 'the gate-override decisions changed since this audit' });
   if (!unitDir) return result('invalid', [{ code: 'unit-unresolved', message: `"${unit}" does not name exactly one unit, so the audit's inputs cannot be checked` }]);
   if (r.inputsHash !== auditInputsHash(unitDir, unit, r.decisionsHash as string)) {

package/src/harness/next-step.ts

@@ -106,6 +106,8 @@ export interface UnitState {
    * are listed (sign-off, accept-in-run and the first contract approval wait). Absent when nothing cuts.
    */
   humanActionsHeldBy?: string;
+  /** The canonical command of that blocking step (#966) — what clears the hold. */
+  humanActionsHeldByCommand?: string;
 }
 
 export interface ReadUnitStateOptions {
@@ -188,6 +190,7 @@ export function readUnitState(
   state.humanActions = [...graph.actions, ...boardHumanActions(projectRoot, unitDir, state, graph.cut)]
     .filter((a) => !seen.has(a.command) && Boolean(seen.add(a.command)));
   if (graph.heldBy) state.humanActionsHeldBy = graph.heldBy;
+  if (graph.heldByCommand) state.humanActionsHeldByCommand = graph.heldByCommand;
   return state;
 }
 

package/src/hooks/hand-back-core.ts

@@ -10,7 +10,7 @@
  * commander's preAction, so a usage error — which never reaches an action — and `main().catch`
  * ended in silence. The state now starts the moment parsing does; the action only refines it.
  */
-import { sungenInvocation, withProjectInvocation } from '../cli/project-sungen-invocation';
+import { sungenInvocation, withProjectInvocationInText } from '../cli/project-sungen-invocation';
 import { waitingForYouLines } from '../cli/waiting-for-you-block';
 import { resolveUnitCandidates } from '../cli/resolve-unit';
 import { readUnitState, NextStep, UnitState } from '../harness/next-step';
@@ -88,10 +88,14 @@ export function attachCliHandBack(argv: string[], cwd: string): { onAction: (nam
 
 const MARK: Record<NextStep['kind'], string> = { do: '→', blocked: '⛔', optional: '○', decide: '⚖' };
 
-/** `sungen next` rendered compactly for an agent's context; commands as `root` runs sungen. */
+/**
+ * `sungen next` rendered compactly for an agent's context; commands — the step's own and those quoted in
+ * its reason (#966) — as `root` runs sungen, the way `sungen next` prints them.
+ */
 export function formatSteps(steps: NextStep[], max = 4, root?: string): string[] {
+  const asRun = (text: string): string => (root ? withProjectInvocationInText(text, root) : text);
   return steps.slice(0, max).map((st) =>
-    `  ${MARK[st.kind]} ${root ? withProjectInvocation(st.command, root) : st.command}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}\n     ${st.because}`);
+    `  ${MARK[st.kind]} ${asRun(st.command)}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}\n     ${asRun(st.because)}`);
 }
 
 /** The unit a session is on (a named one when it exists, else the nearest) and its derived state. */
@@ -109,6 +113,6 @@ export function run(input: HookInput, ctx: HookContext): HookResult {
   return {
     status: 'context',
     output: [`${handBackLine(found.unit.name, sungenInvocation(found.root))} — derived from what the project holds now:`, ...formatSteps(found.state.steps, 4, found.root),
-      ...waitingForYouLines(found.state.humanActions, found.root, found.state.humanActionsHeldBy)].join('\n'),
+      ...waitingForYouLines(found.state.humanActions, found.root, found.state.humanActionsHeldBy, found.state.humanActionsHeldByCommand)].join('\n'),
   };
 }

package/src/hooks/session-start-unit-state-hook.ts

@@ -50,7 +50,7 @@ export const sessionStartUnitStateHook: SungenHook = {
       state.audit ? `Audit: ${state.audit.overall}/10 [${state.audit.gateStatus}] · ${state.audit.findings.length} finding(s).` : '',
       `Next (\`${sungen} next ${unit.name}\`, derived from the project state):`,
       ...formatSteps(state.steps, 4, root),
-      ...waitingForYouLines(state.humanActions, root, state.humanActionsHeldBy),
+      ...waitingForYouLines(state.humanActions, root, state.humanActionsHeldBy, state.humanActionsHeldByCommand),
       input.source === 'compact' ? 'Context was compacted: re-read the unit\'s files before acting on them.' : '',
       others > 0 ? `Working on another unit? Ask \`${sungen} next <unit>\` (or \`${sungen} next\` for all).` : '',
     ];

package/src/orchestrator/templates/ai-src/commands/create-test.md

@@ -111,7 +111,10 @@ terminal (`script`, `expect`, a pty wrapper), and never edit `contracts.lock.yam
 traces, write their Gherkin with `sungen contract derive --screen <name>` — deterministic, it writes
 `features/<name>.free.feature` with every scenario tagged `@free @proposed`. Do not author those
 steps yourself; you may name the scenarios and suggest VP-ids. A `@proposed` scenario is not
-counted by the audit until a QA approves it (`sungen contract approve --screen <name>`).
+counted by the audit until a QA approves it (`sungen contract approve --screen <name>`). When
+two recorded tests claim one ID, `sungen contract derive` exits `1`, names both tests and writes
+nothing: stop and ask the QA to give each test its own ID (its title's leading ID, or its `@tag`).
+Never rename a test's ID — or a scenario's — yourself to get past it.
 
 ## Platform detection (do this FIRST)