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

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

@@ -0,0 +1,101 @@
+/**
+ * `sungen contract approve --screen <u> [--scenario <id>]` — the human act that locks a contract
+ * (DOS-14.4, DOS-13.4, takumi T5). In order, so a human never confirms something then rejected:
+ *
+ *   1. resolve the unit, read the current scenarios and the lock (an unreadable lock refuses)
+ *   2. pick what changes: new, changed or tampered scenarios, and — when approving the whole unit —
+ *      the entries of scenarios that left the feature; nothing changed → nothing to approve, no prompt
+ *   3. refuse a duplicated id or a Scenario Outline, and run the secret guard
+ *   4. show each change with its ladder class (a weakening is named before it is confirmed) and
+ *      require the typed phrase on a TTY — without one: refuse and print the exact command
+ *   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 { 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; acceptOpaque?: boolean }
+export interface ApproveResult {
+  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 }
+
+function plan(i: ApproveInput): Plan {
+  const unit = resolveContractUnit(i.projectRoot, i.unit);
+  const lock = readLockFile(lockPathFor(unit.dir));
+  const current = loadContractScenarios(unit.dir, unit.name);
+  const ids = new Set(current.map((s) => s.id));
+  if (i.scenario && !ids.has(i.scenario) && !lock?.scenarios[i.scenario]) {
+    throw new Error(`--scenario ${i.scenario} names no scenario of ${i.unit} (current: ${[...ids].join(', ') || 'none'})`);
+  }
+  const chosen = current.filter((s) => !i.scenario || s.id === i.scenario);
+  const dup = [...new Set(chosen.map((s) => s.id))].find((id) => current.filter((s) => s.id === id).length > 1);
+  if (dup) throw new Error(`Refused: scenario id ${dup} is used by ${current.filter((s) => s.id === dup).length} scenarios — a lock entry must name exactly one. Give each its own ID.`);
+  const outlines = chosen.filter((s) => s.source.outline).map((s) => s.id);
+  if (outlines.length) throw new Error(`Refused: ${outlines.join(', ')} ${outlines.length > 1 ? 'are' : 'is a'} Scenario Outline — the compiler does not support it, so it cannot be locked. Rewrite it as @cases data.`);
+  const tampered = new Set(lock?.tampered ?? []);
+  const approve = chosen.filter((s) => { const e = lock?.scenarios[s.id]; return !isHumanApproved(e) || e.hash !== s.hash || tampered.has(s.id); });
+  const removed = Object.keys(lock?.scenarios ?? {}).filter((id) => !ids.has(id) && (!i.scenario || id === i.scenario));
+  const write: ApprovalWrite = { projectRoot: i.projectRoot, unitDir: unit.dir, unit: unit.name, approve, removed, reason: i.reason, lock };
+  return { write, lock, fingerprint: canonicalJson({ lock, approve: approve.map((s) => [s.id, s.hash]), removed }) };
+}
+
+function describe(sc: ContractScenario, lock: ReadLock | null): string {
+  const entry = lock?.scenarios[sc.id];
+  if (!isHumanApproved(entry) || lock?.tampered.includes(sc.id)) return `+ ${sc.id}  new (${sc.steps.length} steps, ${sc.implementation})`;
+  const r = classifyScenario(sc.id, entry, sc);
+  return `~ ${sc.id}  ${r.class}${r.findings.length ? ` — ${r.findings.map((f) => f.detail).join('; ')}` : ''}`;
+}
+
+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);
+  if (!approve.length && !removed.length) return { status: 'nothing-to-approve', lockPath, approved: [], removed: [] };
+  checkApprovalSecrets(before.write);
+
+  const unnamed = approve.filter((s) => !s.source.hasId).length;
+  await requireTypedConfirmation({
+    what: `approve the Test Contract of ${i.unit} (${approve.length} scenario(s)${removed.length ? `, ${removed.length} removed` : ''})`,
+    phrase: i.unit,
+    command: formatCommand(['sungen', 'contract', 'approve', '--screen', i.unit, ...(i.scenario ? ['--scenario', i.scenario] : []), ...(i.reason ? ['--reason', i.reason] : [])]),
+    summary: [
+      ...approve.map((s) => describe(s, before.lock)),
+      ...removed.map((id) => `- ${id}  removed from the feature — its approved checks leave the contract`),
+      ...(unnamed ? [`note: ${unnamed} scenario(s) have no ID and are locked by name — renaming one will read as removing it`] : []),
+      `recorded by: ${gitUserName(i.projectRoot)}`,
+    ],
+    io: i.io,
+  });
+
+  const after = plan(i);
+  if (after.fingerprint !== before.fingerprint) {
+    throw new Error('Refused: the feature or the lock changed while you were confirming — nothing was written. Run the command again and review the new summary.');
+  }
+  const { decisionId } = recordContractApproval(after.write);
+  // A derived `@free @proposed` scenario stops being a proposal once QA locks it (DOS-14.8).
+  const approvedIds = new Set(approve.map((s) => s.id));
+  for (const f of contractFeatureFiles(after.write.unitDir, after.write.unit)) dropProposedTags(f, approvedIds);
+  return { status: 'approved', lockPath, decisionId, approved: approve.map((s) => s.id), removed };
+}

package/src/contract/assertion-matcher-vocabulary.ts

@@ -0,0 +1,93 @@
+/**
+ * What an assertion checks — the CLOSED vocabulary of the strength ladder (DOS-14.1, DOS-14.4).
+ *
+ * Read off the normalized sentence the QA wrote (the documented `see` / `is on` / `expect` forms of
+ * sungen-gherkin-syntax), not off the compiler's pattern registry: that registry is assembled from
+ * whichever drivers a machine has installed, so a hash built on it would differ between two
+ * checkouts of the same `.feature`, and the hook would judge differently from the CLI. A sentence
+ * outside the vocabulary is `unknown`, and an unknown check that changed is `review`, never `match`.
+ *
+ *   strength 1  visible · exists                                  (something is there)
+ *   strength 2  page · state · contains · matches · range · key-matching · child · url-/title-contains|matches
+ *   strength 3  equals · count · table-data · tab-order · schema · url · title
+ *   `all:` (every item) adds one. A negation (`not see`, `is not <state>`, `is hidden`) is a flag.
+ */
+import type { StateClause } from '../generators/test-generator/patterns/types';
+
+export interface AssertShape { matcher: string; negated: boolean }
+
+const NEGATION = /\b(?:not|no longer|never|cannot|can't|don't|doesn't|isn't|aren't|shouldn't)\b/;
+const NOT_SEE = /^(?:do not|does not|don't|doesn't|should not|shouldn't|cannot|can't|not|never) see\b/;
+const IS_NOT_STATE = /\bis not (sorted ascending|sorted descending|unchecked|checked|hidden|visible|disabled|enabled|focused|empty|loading|selected)$/;
+const RANGE = /\b(?:at least|at most|more than|less than|greater than|fewer than|between)\b/;
+const PAGE_SUBJECT = /^see (?:the )?(?:current |page )?(url|title)\b(.*)$/;
+/** A state and its complement are one check with a negation: hidden = not visible. */
+const STATE_AS: Partial<Record<StateClause, [string, boolean]>> = {
+  visible: ['visible', false], hidden: ['visible', true],
+  enabled: ['enabled', false], disabled: ['enabled', true],
+  checked: ['checked', false], unchecked: ['checked', true],
+};
+
+function comparison(rest: string): string | null {
+  if (/\bcontains?\b/.test(rest)) return '-contains';
+  if (/\bmatches\b/.test(rest)) return '-matches';
+  return /\b(?:is|equals?|with) \{\}|^ ?\{\}$/.test(rest) ? '' : null;
+}
+
+function baseMatcher(verb: string, state?: StateClause): string {
+  if (/^expect\b/.test(verb)) {
+    if (/\bmatches schema\b/.test(verb)) return 'schema';
+    if (RANGE.test(verb)) return 'range';
+    if (/\bcontains?\b/.test(verb)) return 'contains';
+    if (/\bmatches\b/.test(verb)) return 'matches';
+    return /\b(?:is|equals?)\b/.test(verb) ? 'equals' : 'unknown';
+  }
+  if (/\bin (?:local|session) storage\b/.test(verb)) {
+    if (/\bkey matching\b/.test(verb)) return 'key-matching';
+    if (/\bhas length\b/.test(verb)) return 'count';
+    if (/\bis not empty\b/.test(verb)) return 'state:empty';
+    return /\b(?:exists?|exist)\b/.test(verb) ? 'exists' : 'unknown';
+  }
+  if (/^see tab order\b/.test(verb)) return 'tab-order';
+  if (/\bmatch data$/.test(verb)) return 'table-data';
+  if (!/^(?:see|is on)\b/.test(verb)) return 'unknown';
+  const page = verb.match(PAGE_SUBJECT);
+  if (page) { const c = comparison(page[2]); return c === null ? 'unknown' : `${page[1]}${c}`; }
+  if (state) return STATE_AS[state]?.[0] ?? `state:${state}`;
+  if (/^see all \[\] contains? \[\]/.test(verb)) return 'child';
+  if (RANGE.test(verb)) return 'range';
+  if (/\bmatches \{\}/.test(verb)) return 'matches';
+  if (/\b(?:contains?|includes?) \{\}/.test(verb)) return 'contains';
+  if (/\b(?:has|have|with) (?:text|value) \{\}|\bwith \{\}/.test(verb)) return 'equals';
+  if (/\b(?:has|have) (?:\d+|\{\})(?: [\w-]+)?$/.test(verb)) return 'count';
+  if (/^is on \[\] (?:page|screen|dialog)$|^see \[\] page$/.test(verb)) return 'page';
+  if (/^see (?:all )?\[\](?: [\w-]+)?$/.test(verb)) return 'visible';
+  return 'unknown';
+}
+
+/** What an assertion sentence (the normalized `verb`) checks. `state` is the parser's trailing clause. */
+export function assertShapeOf(verb: string, parsedState?: StateClause): AssertShape {
+  const v = verb.replace(NOT_SEE, 'see');
+  const state = parsedState ?? (v.match(IS_NOT_STATE)?.[1] as StateClause | undefined);
+  const base = baseMatcher(v, state);
+  const flips = state ? STATE_AS[state]?.[1] === true : false;
+  const negated = NEGATION.test(verb) !== flips;
+  const all = /^see all\b/.test(v) && base !== 'unknown';
+  return { matcher: all ? `all:${base}` : base, negated };
+}
+
+const STRENGTH: Record<string, number> = {
+  visible: 1, exists: 1,
+  page: 2, enabled: 2, checked: 2, contains: 2, matches: 2, range: 2, 'key-matching': 2, child: 2,
+  'url-contains': 2, 'url-matches': 2, 'title-contains': 2, 'title-matches': 2,
+  equals: 3, count: 3, 'table-data': 3, 'tab-order': 3, schema: 3, url: 3, title: 3,
+};
+
+/** The ordinal strength of a matcher, or null when the ladder cannot judge it. */
+export function matcherStrength(matcher: string | undefined): number | null {
+  if (!matcher || matcher === 'unknown') return null;
+  const all = matcher.startsWith('all:');
+  const base = all ? matcher.slice(4) : matcher;
+  const s = base.startsWith('state:') ? 2 : STRENGTH[base];
+  return s === undefined ? null : s + (all ? 1 : 0);
+}

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

@@ -0,0 +1,108 @@
+/**
+ * The contract verdict of one unit, BUILT BY CODE from raw inputs every time (DOS-14.0, takumi T3):
+ * the `.feature` files, the working lock, the lock and the approval decisions in git HEAD. No report
+ * file is read — the `.sungen/reports/<slug>-contract.json` that `contract check` writes is output
+ * only, so a hand-edited "pass" there changes nothing. The CLI and the Claude Code guard call this
+ * same function, so they cannot disagree.
+ *
+ *   fail    oracle-weakened / target-changed / assertion-lost, or any lock-uncommitted issue
+ *           (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 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
+ *
+ * free / impl:code scenarios are ALSO held against their recorded traces (DOS-14.6,
+ * build-trace-conformance.ts): the worse of the Gherkin class and the trace class wins. A
+ * proposed (unapproved) one's trace problems are warnings — it is not locked yet.
+ *
+ * git failing in a checkout that has .git is not "no git": with a lock present the verdict cannot be
+ * built (GitUnavailableError → CLI exit 1, guard `ask`); without one it is only a warning.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { canonicalJson, sha256Hex } from './contract-hash';
+import { CLI_GIT_TIMEOUT_MS, GitUnavailableError, HeadSnapshot, headSnapshot, readTextOrNull } from './contract-git';
+import { HARD_CLASSES, REVIEW_CLASSES } from './contract-schema';
+import { ScenarioResult, severityOf } from './classify-contract-change';
+import { traceConformanceForUnit } from './build-trace-conformance';
+import type { TraceOutcome } from './classify-trace-conformance';
+import { classifyUnit } from './classify-contract-unit';
+import { lockPathFor, parseLockText } from './contracts-lock-file';
+import { compareLockWithHead, UncommittedEntry } from './lock-vs-git-head';
+import { contractFeatureFiles, loadContractScenarios } from './normalize-feature-steps';
+import { unverifiedApprovals } from './verify-approval-decisions';
+
+export { classifyUnit } from './classify-contract-unit';
+
+export interface ContractUnit { name: string; dir: string }
+export type VerdictValue = 'pass' | 'review' | 'fail';
+
+export interface ContractVerdict {
+  schema: 1;
+  unit: string;
+  verdict: VerdictValue;
+  exitCode: 0 | 2;
+  /** sha256 over the inputs the verdict was built from: features, working lock, lock issues. */
+  inputsHash: string;
+  scenarios: ScenarioResult[];
+  /** Every lock entry that is not what QA approved and committed (rule contract.lock-uncommitted). */
+  uncommitted: UncommittedEntry[];
+  warnings: string[];
+}
+
+/**
+ * `snapshot` lets a caller checking many units read HEAD once; `gitTimeoutMs` bounds each git call;
+ * `traceBudgetMs` bounds the trace part (default ~3 s for the guard; `contract check` passes more).
+ */
+export interface VerdictOptions { snapshot?: HeadSnapshot; gitTimeoutMs?: number; traceBudgetMs?: number }
+
+/** Fold a free / impl:code scenario's trace outcome into its Gherkin result: the worse class wins. */
+function withTrace(results: ScenarioResult[], outcomes: Map<string, TraceOutcome>): ScenarioResult[] {
+  return results.map((r) => {
+    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, ...(o.opaque.length ? { opaque: o.opaque } : {}) } };
+  });
+}
+
+export function buildContractVerdict(projectRoot: string, unit: ContractUnit, opts: VerdictOptions = {}): ContractVerdict {
+  const snap = opts.snapshot ?? headSnapshot(projectRoot, opts.gitTimeoutMs ?? CLI_GIT_TIMEOUT_MS);
+  const files = contractFeatureFiles(unit.dir, unit.name);
+  const current = loadContractScenarios(unit.dir, unit.name);
+  const lockFile = lockPathFor(unit.dir);
+  const lockText = readTextOrNull(lockFile);
+  if (snap.error && lockText !== null) throw new GitUnavailableError(snap.error);
+  const lock = lockText === null ? null : parseLockText(lockText, lockFile);
+  const tampered = new Set(lock?.tampered ?? []);
+  const gherkin = classifyUnit(lock, current, tampered);
+  const traced = traceConformanceForUnit(projectRoot, unit, current, lock, tampered, { budgetMs: opts.traceBudgetMs });
+  const results = withTrace(gherkin.results, traced.outcomes);
+  const warnings = [...gherkin.warnings, ...traced.warnings];
+  const head = compareLockWithHead(projectRoot, lockFile, lockText, lock, snap);
+  if (head.status === 'no-git') {
+    warnings.push(snap.error
+      ? `git failed (${snap.error}); this unit has no lock, so nothing was compared with git HEAD`
+      : 'not a git checkout with a commit: the lock was not compared with git HEAD (working tree used)');
+  }
+  const uncommitted: UncommittedEntry[] = head.status === 'compared' ? [...head.uncommitted] : [];
+  for (const id of tampered) {
+    if (!uncommitted.some((u) => u.id === id)) uncommitted.push({ id, change: 'tampered', detail: 'its steps no longer hash to its `hash` — edited by hand' });
+  }
+  uncommitted.push(...unverifiedApprovals(projectRoot, unit.dir, lock, new Set(uncommitted.map((u) => u.id)), snap));
+
+  const hard = uncommitted.length > 0 || results.some((r) => HARD_CLASSES.has(r.class));
+  const verdict: VerdictValue = hard ? 'fail' : results.some((r) => REVIEW_CLASSES.has(r.class)) ? 'review' : 'pass';
+  const rel = (f: string): string => path.relative(projectRoot, f).split(path.sep).join('/');
+  const inputsHash = sha256Hex(canonicalJson({
+    features: files.map((f) => [rel(f), sha256Hex(fs.readFileSync(f, 'utf8'))]),
+    lock: lockText === null ? null : sha256Hex(lockText),
+    head: head.status,
+    uncommitted,
+    ...(traced.inputs === null ? {} : { trace: traced.inputs }),
+  }));
+  const scenarios = results.map((r) => (r.file ? { ...r, file: rel(r.file) } : r));
+  return { schema: 1, unit: unit.name, verdict, exitCode: verdict === 'fail' ? 2 : 0, inputsHash, scenarios, uncommitted, warnings };
+}

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

@@ -0,0 +1,103 @@
+/**
+ * Trace conformance of one unit, built by code every time (DOS-14.0, 14.6; takumi T3) — the part of
+ * the contract verdict that only free / impl:code scenarios have. Synchronous and read-only, so
+ * `contract check` and the Claude Code delivery guard (both via buildContractVerdict) agree.
+ *
+ *   platform mobile        not supported yet: a warning, nothing judged, exit unaffected
+ *   no free / impl:code    nothing to do (the verdict is byte-identical to the Gherkin-only one)
+ *   otherwise              evidence (run records → reports → final attempts → bound traces) →
+ *                          identities (driver cache or low heuristic) → render → ONE batched
+ *                          fingerprint parse → the ladder
+ *
+ * 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 `.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 { loadTestDataIndex, TestDataIndex } from './data-normalize';
+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';
+import { identityCachePath, readIdentityCache } from './trace/identity-cache';
+import { identitiesFor } from './trace/trace-identity-resolution';
+import { fingerprintsOf, TraceFingerprint } from './trace/trace-fingerprint';
+import { traceIntentSteps } from './trace/trace-steps';
+
+export interface UnitTraceConformance { outcomes: Map<string, TraceOutcome>; warnings: string[]; inputs: unknown }
+
+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 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 : 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,
+  untrusted: ReadonlySet<string>, opts: { budgetMs?: number } = {},
+): UnitTraceConformance {
+  const deadline = Date.now() + (opts.budgetMs ?? defaultTraceBudgetMs());
+  const traced = [...new Map(current.filter((s) => s.implementation !== 'compiled').map((s) => [s.id, s])).values()];
+  if (!traced.length) return { outcomes: new Map(), warnings: [], inputs: null };
+  if ((readCapabilities(projectRoot).platform ?? '').toLowerCase() === 'mobile') return { outcomes: new Map(), warnings: [MOBILE_NOT_SUPPORTED], inputs: { platform: 'mobile' } };
+
+  const approvedEntry = (id: string): LockEntry | undefined => { const e = lock?.scenarios[id]; return isHumanApproved(e) && !untrusted.has(id) ? e : undefined; };
+  const outcomes = new Map<string, TraceOutcome>();
+  const warnings: string[] = [];
+  let evidence: ScenarioEvidence = { runs: new Map(), problems: [], inputs: [] };
+  let index: TestDataIndex = { byValue: new Map() };
+  let setupError = '';
+  try {
+    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);
+  warnings.push(...evidence.problems, ...(problem ? [problem] : []));
+
+  // 1. render every admissible run (deadline checked per scenario), 2. ONE fingerprint parse, 3. ladder.
+  const pending: Array<{ sc: ContractScenario; runs: TraceRun[]; rendered: Map<TraceRun, RenderedStep[]> }> = [];
+  for (const sc of traced) {
+    if (setupError) { outcomes.set(sc.id, notJudged(sc.id, !!approvedEntry(sc.id), 'unproven', [setupError])); continue; }
+    if (Date.now() > deadline) { outcomes.set(sc.id, notJudged(sc.id, !!approvedEntry(sc.id), 'unproven', [OVER_BUDGET])); continue; }
+    const runs = evidence.runs.get(sc.id) ?? [];
+    const rendered = new Map<TraceRun, RenderedStep[]>();
+    try {
+      for (const run of runs.filter((r) => r.status === 'admissible' && r.trace)) {
+        const steps = traceIntentSteps(run.trace!);
+        rendered.set(run, renderTraceSteps(steps, identitiesFor(run.trace!, steps, cache), { index, projectRoot, specFile: run.specFile, secrets: new Set() }));
+      }
+      pending.push({ sc, runs, rendered });
+    } catch (e) { outcomes.set(sc.id, notJudged(sc.id, !!approvedEntry(sc.id), 'unproven', [`trace conformance failed: ${why(e)}`])); }
+  }
+  const items = pending.flatMap((p) => [...p.rendered.entries()].map(([run, rendered]) => ({ p, run, rendered, implementation: p.sc.implementation })));
+  let fps: TraceFingerprint[] = [];
+  try { fps = fingerprintsOf(items); } catch (e) {
+    for (const p of pending) outcomes.set(p.sc.id, notJudged(p.sc.id, !!approvedEntry(p.sc.id), 'unproven', [`trace conformance failed: ${why(e)}`]));
+  }
+  if (fps.length === items.length) {
+    for (const p of pending) {
+      const byRun = new Map(items.map((it, i) => [it, fps[i]] as const).filter(([it]) => it.p === p).map(([it, fp]) => [it.run, fp]));
+      outcomes.set(p.sc.id, classifyTraceRuns(p.sc.id, p.sc.implementation, approvedEntry(p.sc.id), p.runs, byRun));
+    }
+  }
+  for (const o of outcomes.values()) warnings.push(...o.warnings);
+  const cacheFile = identityCachePath(projectRoot);
+  const traceShas = [...evidence.runs.values()].flat().filter((r) => r.trace).map((r) => r.trace!.sha256).sort();
+  return { outcomes, warnings, inputs: { runs: evidence.inputs, traces: traceShas, identities: fs.existsSync(cacheFile) ? sha(fs.readFileSync(cacheFile)) : null } };
+}

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

@@ -0,0 +1,92 @@
+/**
+ * One approved lock entry against the scenario as it reads now → its class on the strength ladder
+ * (DOS-14.4) and the findings behind it.
+ *
+ *   same hash                         match
+ *   assertions, paired in three passes:
+ *     1. identical                    nothing to say
+ *     2. same target (ref + scope)    compareAsserts against the WORST candidate: weakened · strengthened · review
+ *     3. same sentence, other target  target-changed
+ *     left over in the lock           assertion-lost        left over now     strengthened (new check)
+ *   actions changed · implementation retagged · only reordered    hash-changed (review)
+ *
+ * The scenario's class is its most severe finding. A change that produced no finding at all is
+ * still `hash-changed`: equal hashes are the only road to `match`.
+ */
+import { sameJson } from './contract-hash';
+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), 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> = {
+  proposed: 0, match: 0, strengthened: 1, nondeterministic: 1, 'hash-changed': 2, opaque: 2, inconclusive: 2,
+  'target-changed': 3, 'oracle-weakened': 3, 'assertion-lost': 3, unproven: 3,
+};
+export const severityOf = (c: ScenarioClass): number => SEVERITY[c];
+
+export const finding = (cls: Exclude<LadderClass, 'match'> | TraceClass, detail: string, step?: number): ContractFinding =>
+  ({ class: cls, ...(RULE_OF[cls] ? { rule: RULE_OF[cls] } : {}), detail, ...(step ? { step } : {}) });
+
+type Indexed = { step: ContractStep; at: number };
+const asserts = (steps: ContractStep[]): Indexed[] => steps.map((step, i) => ({ step, at: i + 1 })).filter((x) => x.step.kind === 'assert');
+const targetKey = (s: ContractStep): string => s.target ? `${s.target.ref}\u0000${s.target.parent ?? ''}` : `\u0001${s.verb}`;
+const label = (s: ContractStep): string => s.target ? `[${s.target.ref}]${s.target.parent ? ` in ${s.target.parent}` : ''}` : `"${s.verb}"`;
+
+function compareAssertions(locked: ContractStep[], current: ContractStep[]): ContractFinding[] {
+  const out: ContractFinding[] = [];
+  const was = asserts(locked);
+  const now = asserts(current);
+  const used = new Set<number>();
+  const take = (pred: (c: Indexed) => boolean): Indexed | undefined => {
+    const hit = now.find((c) => !used.has(c.at) && pred(c));
+    if (hit) used.add(hit.at);
+    return hit;
+  };
+  const open: Indexed[] = [];
+  for (const l of was) if (!take((c) => sameJson(c.step, l.step))) open.push(l);
+  const unpaired: Indexed[] = [];
+  for (const l of open) {
+    const candidates = now.filter((c) => !used.has(c.at) && targetKey(c.step) === targetKey(l.step));
+    if (!candidates.length) { unpaired.push(l); continue; }
+    // The WORST replacement is the one judged: picking the kindest let `see [X]` → `is hidden` +
+    // `is empty` read as strengthened, the inversion hiding behind a harmless extra check.
+    const judged = candidates.map((c) => ({ c, r: compareAsserts(l.step, c.step) }));
+    const rank = (k: string): number => (k === 'oracle-weakened' ? 2 : k === 'review' ? 1 : 0);
+    const worst = judged.sort((a, b) => rank(b.r.class) - rank(a.r.class))[0];
+    used.add(worst.c.at);
+    const cls = worst.r.class === 'review' ? 'hash-changed' : worst.r.class;
+    out.push(finding(cls, `${label(l.step)}: ${worst.r.detail}`, worst.c.at));
+  }
+  for (const l of unpaired) {
+    const moved = take((c) => c.step.verb === l.step.verb && !!l.step.target && !!c.step.target);
+    out.push(moved
+      ? finding('target-changed', `the check "${l.step.verb}" moved from ${label(l.step)} to ${label(moved.step)}`, moved.at)
+      : finding('assertion-lost', `the approved check ${label(l.step)} "${l.step.verb}" (step ${l.at}) is gone`));
+  }
+  for (const c of now) if (!used.has(c.at)) out.push(finding('strengthened', `new check ${label(c.step)} "${c.step.verb}"`, c.at));
+  return out;
+}
+
+export function classifyScenario(id: string, entry: LockEntry, current: ContractScenario | undefined): ScenarioResult {
+  if (!current) {
+    return { id, class: 'assertion-lost', findings: [finding('assertion-lost', 'the approved scenario is no longer in the feature (removed, its ID changed, or made @manual)')] };
+  }
+  const base = { id, file: current.source.file };
+  if (current.hash === entry.hash) return { ...base, class: 'match', findings: [] };
+  const findings = compareAssertions(entry.steps, current.steps);
+  if (entry.implementation !== current.implementation) {
+    findings.push(finding('hash-changed', `implementation path changed: ${entry.implementation} → ${current.implementation} (retag)`));
+  }
+  const actionsOf = (steps: ContractStep[]) => steps.filter((s) => s.kind === 'action');
+  if (!sameJson(actionsOf(entry.steps), actionsOf(current.steps))) findings.push(finding('hash-changed', 'the actions changed (what the test does before it checks)'));
+  if (!findings.length) findings.push(finding('hash-changed', 'the steps changed without a weaker or stronger check (e.g. reordered)'));
+  const worst = findings.reduce<ScenarioClass>((acc, f) => {
+    const c = f.class as ScenarioClass;
+    return severityOf(c) > severityOf(acc) ? c : acc;
+  }, 'match');
+  return { ...base, class: worst, findings };
+}