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

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, 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 } };
+  });
+}
+
+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,100 @@
+/**
+ * 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 newest `.feature` / lock is refused (stale).
+ */
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import { readCapabilities } from '../harness/capability';
+import { classifyTraceRuns, notJudged, TraceOutcome } from './classify-trace-conformance';
+import { ContractLock, ContractScenario, isHumanApproved, LockEntry } from './contract-schema';
+import { lockPathFor } from './contracts-lock-file';
+import { loadTestDataIndex, TestDataIndex } from './data-normalize';
+import { contractFeatureFiles } from './normalize-feature-steps';
+import { renderTraceSteps, RenderedStep } from './render-free-gherkin';
+import { 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 mtimeMs = (f: string): number => { try { return fs.statSync(f).mtimeMs; } catch { return 0; } };
+const sha = (s: string | Buffer): string => createHash('sha256').update(s).digest('hex');
+const why = (e: unknown): string => (e instanceof Error ? e.message : String(e)).split('\n')[0].slice(0, 300);
+
+export const MOBILE_NOT_SUPPORTED = 'trace conformance is web-only: free / impl:code scenarios of a mobile project are not supported yet (not judged)';
+/** The guard path's deadline for the trace part of one unit's verdict (override: SUNGEN_TRACE_VERDICT_BUDGET_MS). */
+export function defaultTraceBudgetMs(env: Record<string, string | undefined> = process.env): number {
+  const v = Number(env.SUNGEN_TRACE_VERDICT_BUDGET_MS);
+  return Number.isFinite(v) && v > 0 ? v : 3_000;
+}
+
+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 {
+    const notBefore = Math.max(mtimeMs(lockPathFor(unit.dir)), ...contractFeatureFiles(unit.dir, unit.name).map(mtimeMs));
+    evidence = collectScenarioEvidence(projectRoot, new Set(traced.map((s) => s.id)), notBefore, deadline);
+    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, RULE_OF, ScenarioClass, TraceClass } from './contract-schema';
+import { compareAsserts } from './oracle-strength';
+
+export interface ContractFinding { class: FindingClass; rule?: string; detail: string; step?: number }
+/** What a free / impl:code scenario's traces fingerprinted to (DOS-14.6) — output only. */
+export interface TraceSummary { hashes: string[]; runs: string[] }
+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 };
+}

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

@@ -0,0 +1,47 @@
+/**
+ * Every scenario id of a unit, locked or current, with its ladder class (DOS-14.3, DOS-14.4).
+ *
+ *   approved entry, one current copy      classifyScenario (the ladder)
+ *   approved entry, no current copy       assertion-lost
+ *   approved entry, several copies        assertion-lost — the lock can no longer tell which copy QA
+ *                                         approved, and picking one would let the others hide (M7)
+ *   no approved entry                     proposed (never blocks); a tampered entry counts as none
+ *   Scenario Outline (any lock state)     at least hash-changed: the compiler does not support the
+ *                                         construct, so the contract cannot judge its Examples
+ */
+import { classifyScenario, finding, ScenarioResult, severityOf } from './classify-contract-change';
+import { ContractLock, ContractScenario, isHumanApproved } from './contract-schema';
+
+const OUTLINE = 'Scenario Outline is not supported by the compiler — the contract cannot judge its Examples rows; rewrite it as @cases data';
+
+function withOutlineFinding(r: ScenarioResult): ScenarioResult {
+  const findings = [...r.findings, finding('hash-changed', OUTLINE)];
+  return { ...r, class: severityOf(r.class) >= severityOf('hash-changed') ? r.class : 'hash-changed', findings };
+}
+
+export function classifyUnit(
+  lock: ContractLock | null, current: ContractScenario[], untrusted: ReadonlySet<string> = new Set(),
+): { results: ScenarioResult[]; warnings: string[] } {
+  const groups = new Map<string, ContractScenario[]>();
+  for (const sc of current) groups.set(sc.id, [...(groups.get(sc.id) ?? []), sc]);
+  const approvedIds = Object.entries(lock?.scenarios ?? {}).filter(([id, e]) => isHumanApproved(e) && !untrusted.has(id)).map(([id]) => id);
+  const results: ScenarioResult[] = [];
+  const warnings: string[] = [];
+  for (const id of [...new Set([...approvedIds, ...groups.keys()])].sort((a, b) => a.localeCompare(b, 'en'))) {
+    const entry = lock?.scenarios[id];
+    const copies = groups.get(id) ?? [];
+    const approved = isHumanApproved(entry) && !untrusted.has(id);
+    let mine: ScenarioResult[];
+    if (!approved) {
+      if (copies.length > 1) warnings.push(`scenario id ${id} is used by ${copies.length} scenarios — give each its own ID before approving`);
+      mine = copies.map((c) => ({ id, class: 'proposed', findings: [], file: c.source.file }));
+    } else if (copies.length > 1) {
+      mine = [{ id, class: 'assertion-lost', file: copies[0].source.file, findings: [finding('assertion-lost',
+        `the approved id ${id} is now carried by ${copies.length} scenarios — the lock cannot tell which one QA approved; give each its own ID`)] }];
+    } else {
+      mine = [classifyScenario(id, entry!, copies[0])];
+    }
+    results.push(...(copies.some((c) => c.source.outline) ? mine.map(withOutlineFinding) : mine));
+  }
+  return { results, warnings };
+}

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

@@ -0,0 +1,116 @@
+/**
+ * A free / impl:code scenario's traces against its approved lock entry (DOS-14.5 – 14.6) — the SAME
+ * strength ladder as the Gherkin check (DOS-14.4, oracle-strength.ts), fed from the trace fingerprint.
+ *
+ *   free        classifyScenario(lock entry, fingerprint): equal hash → match, else the ladder
+ *   impl:code   group by group: each approved step must be realized inside the `test.step` titled
+ *               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)
+ *   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 { compareAsserts } from './oracle-strength';
+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[] }
+
+/** 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}`) };
+}
+
+/** How a low target identity opens its finding — `next` reads it to offer `contract check --trace`. */
+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[] = [];
+  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));
+  });
+  return out;
+}
+
+function implCodeFindings(entry: LockEntry, fp: TraceFingerprint): { findings: ContractFinding[]; used: Set<number> } {
+  const findings: ContractFinding[] = [];
+  const used = new Set<number>();
+  const taken = new Set<number>();
+  entry.steps.forEach((locked, i) => {
+    const g = fp.groups.findIndex((x, gi) => !taken.has(gi) && sameJson(x.titleStep, locked));
+    if (g < 0) {
+      findings.push(locked.kind === 'assert'
+        ? finding('assertion-lost', `no test.step implements the approved check "${locked.verb}" (step ${i + 1})`)
+        : finding('hash-changed', `no test.step implements the approved step "${locked.verb}" (step ${i + 1})`));
+      return;
+    }
+    taken.add(g);
+    const members = fp.groups[g].members;
+    const same = members.find((m) => sameJson(fp.steps[m], locked));
+    if (same !== undefined) { used.add(same); return; }
+    const candidates = members.filter((m) => fp.steps[m].kind === locked.kind);
+    if (!candidates.length) {
+      findings.push(locked.kind === 'assert' ? finding('assertion-lost', `the test.step for "${locked.verb}" checks nothing`, i + 1)
+        : finding('hash-changed', `the test.step for "${locked.verb}" does nothing on the page`, i + 1));
+      return;
+    }
+    candidates.forEach((m) => used.add(m));
+    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);
+    const best = judged.sort((a, b) => rank(b.class) - rank(a.class))[0];
+    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 };
+}
+
+function classifyOne(id: string, implementation: Implementation, entry: LockEntry, fp: TraceFingerprint): ContractFinding[] {
+  if (implementation === 'impl:code') {
+    const { findings, used } = implCodeFindings(entry, fp);
+    return [...findings, ...overlays(fp, used)];
+  }
+  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 runLabel = (r: TraceRun): string => `${r.record?.runId ?? '?'}#${r.result?.retry ?? '?'}`;
+
+export function classifyTraceRuns(
+  id: string, implementation: Implementation, entry: LockEntry | undefined, runs: TraceRun[], fingerprints: Map<TraceRun, TraceFingerprint>,
+): TraceOutcome {
+  const admissible = runs.filter((r) => r.status === 'admissible' && fingerprints.has(r));
+  const others = runs.filter((r) => !admissible.includes(r));
+  const labels = admissible.map(runLabel);
+  const hashes = admissible.map((r) => fingerprints.get(r)!.hash);
+  if (!admissible.length) {
+    const allInconclusive = others.length > 0 && others.every((r) => r.status === 'inconclusive');
+    return { ...notJudged(id, !!entry, allInconclusive ? 'inconclusive' : 'unproven', others.map((r) => r.reason ?? r.status)), hashes, runs: labels };
+  }
+  // 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 };
+  const perRun = admissible.map((r) => classifyOne(id, implementation, entry, fingerprints.get(r)!));
+  const findings = perRun.flat();
+  let cls = worstOf(perRun.flat());
+  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 };
+}

package/src/contract/contract-git.ts

@@ -0,0 +1,106 @@
+/**
+ * What git HEAD holds under `qa/`, for the contract (DOS-14.4) — with a timeout the caller picks
+ * (≈3 s inside the Claude Code guard, whose own budget is 5 s; 30 s for the CLI).
+ *
+ * Three answers, never confused:
+ *   blobs          one `git ls-tree -r -z HEAD -- qa`: every committed lock and decision with its blob id
+ *   no git         no `.git` at or above the project, or a repository without a first commit
+ *   git FAILED     `.git` is there but git errors, times out, refuses (dubious ownership) or is not
+ *                  installed — reported as `error`, so the caller can refuse to call a lock "clean"
+ *
+ * A file whose working bytes hash to its HEAD blob id IS its committed version: it is read from disk
+ * and needs no `git show`. git runs with fixed arguments, never through a shell.
+ */
+import { execFileSync } from 'child_process';
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+
+export const CLI_GIT_TIMEOUT_MS = 30_000;
+export const GUARD_GIT_TIMEOUT_MS = 3_000;
+
+export class GitUnavailableError extends Error {
+  constructor(detail: string) {
+    super(`git is unavailable in a checkout that has .git (${detail}) — the contract lock cannot be compared with HEAD`);
+    this.name = 'GitUnavailableError';
+  }
+}
+
+/** One flat shape: the project compiles without strictNullChecks, where a boolean-tagged union does not narrow. */
+interface GitRun { ok: boolean; out: string; timedOut: boolean; message: string }
+
+function runGit(cwd: string, args: string[], timeoutMs: number): GitRun {
+  try {
+    const out = execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024, timeout: timeoutMs }).toString('utf8');
+    return { ok: true, out, timedOut: false, message: '' };
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException & { signal?: string; stderr?: Buffer };
+    const message = (err.stderr?.toString().trim() || err.message || String(e)).split('\n')[0];
+    return { ok: false, out: '', timedOut: err.code === 'ETIMEDOUT' || err.signal === 'SIGTERM', message };
+  }
+}
+
+function hasDotGit(start: string): boolean {
+  let dir = path.resolve(start);
+  for (let i = 0; i < 40; i++) {
+    if (fs.existsSync(path.join(dir, '.git'))) return true;
+    const parent = path.dirname(dir);
+    if (parent === dir) return false;
+    dir = parent;
+  }
+  return false;
+}
+
+export interface HeadSnapshot {
+  root: string;
+  timeoutMs: number;
+  /** Project-relative path → blob id of each committed lock and decision; null when there is nothing to compare with. */
+  blobs: Map<string, string> | null;
+  /** Set when git FAILED in a checkout that has .git (blobs is then null). */
+  error?: string;
+}
+
+const RECORD = /^\d+ blob ([0-9a-f]+)\t(.+)$/s;
+const KEEP = (p: string): boolean => p.endsWith('/contracts.lock.yaml') || /\/decisions\/[^/]+\.yaml$/.test(p);
+
+export function headSnapshot(root: string, timeoutMs = CLI_GIT_TIMEOUT_MS): HeadSnapshot {
+  const r = runGit(root, ['ls-tree', '-r', '-z', 'HEAD', '--', 'qa'], timeoutMs);
+  if (r.ok) {
+    const blobs = new Map<string, string>();
+    for (const rec of r.out.split('\0')) { const m = rec.match(RECORD); if (m && KEEP(m[2])) blobs.set(m[2], m[1]); }
+    return { root, timeoutMs, blobs };
+  }
+  if (r.timedOut) return { root, timeoutMs, blobs: null, error: `git timed out after ${timeoutMs} ms` };
+  if (!hasDotGit(root)) return { root, timeoutMs, blobs: null };
+  const repo = runGit(root, ['rev-parse', '--git-dir'], timeoutMs);
+  if (repo.ok && !runGit(root, ['rev-parse', '--verify', '-q', 'HEAD'], timeoutMs).ok) return { root, timeoutMs, blobs: null };  // no first commit yet
+  return { root, timeoutMs, blobs: null, error: r.message || 'git failed' };
+}
+
+export const gitBlobId = (text: string): string => {
+  const body = Buffer.from(text, 'utf8');
+  return createHash('sha1').update(Buffer.concat([Buffer.from(`blob ${body.length}\0`), body])).digest('hex');
+};
+
+export const posixRel = (root: string, abs: string): string => path.relative(root, abs).split(path.sep).join('/');
+
+/**
+ * The committed text of a project-relative path, or null when HEAD does not hold it. `workingText`
+ * (the file as it is on disk, if any) spares the `git show` when it is byte-identical to HEAD.
+ */
+export function headFileText(snap: HeadSnapshot, rel: string, workingText: string | null): string | null {
+  const blob = snap.blobs?.get(rel);
+  if (blob === undefined) return null;
+  if (workingText !== null && gitBlobId(workingText) === blob) return workingText;
+  const r = runGit(snap.root, ['show', `HEAD:./${rel}`], snap.timeoutMs);
+  if (!r.ok) throw new GitUnavailableError(`git show HEAD:${rel}: ${r.timedOut ? 'timed out' : r.message}`);
+  return r.out;
+}
+
+/** A file's text, or null when it does not exist. */
+export function readTextOrNull(file: string): string | null {
+  try { return fs.readFileSync(file, 'utf8'); } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw e;
+  }
+}

package/src/contract/contract-hash.ts

@@ -0,0 +1,34 @@
+/**
+ * Contract hash (DOS-14.2): `sha256-12` of the normalized steps PLUS the implementation path, so
+ * retagging `@free` → none is a contract change (red-team #5).
+ *
+ * Canonical JSON is keys-sorted with absent fields dropped and NO other rewriting: a literal's
+ * whitespace is part of what the test types or expects, so two values that differ only in spaces
+ * hash apart rather than "matching" by normalization.
+ */
+import { createHash } from 'crypto';
+import type { ContractStep, Implementation } from './contract-schema';
+
+function canonical(v: unknown): unknown {
+  if (Array.isArray(v)) return v.map(canonical);
+  if (v && typeof v === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const k of Object.keys(v).sort()) {
+      const x = (v as Record<string, unknown>)[k];
+      if (x !== undefined) out[k] = canonical(x);
+    }
+    return out;
+  }
+  return v;
+}
+
+export const canonicalJson = (v: unknown): string => JSON.stringify(canonical(v));
+
+/** Structural equality, key order ignored. */
+export const sameJson = (a: unknown, b: unknown): boolean => canonicalJson(a) === canonicalJson(b);
+
+export const sha256Hex = (s: string): string => createHash('sha256').update(s).digest('hex');
+
+export function contractHash(implementation: Implementation, steps: ContractStep[]): string {
+  return sha256Hex(canonicalJson({ implementation, steps })).slice(0, 12);
+}

package/src/contract/contract-report-file.ts

@@ -0,0 +1,25 @@
+/**
+ * `.sungen/reports/<slug>-contract.json` — the contract verdict as OUTPUT (DOS-14.0, takumi T3).
+ *
+ * Written by `sungen contract check` from a verdict it just built; never read back as a source of
+ * truth. Anything that needs the verdict calls buildContractVerdict() and rebuilds it from the
+ * `.feature`, the lock and git HEAD — so editing this file to "pass" changes nothing, and the next
+ * check overwrites it. It records `inputsHash` so a reader can see the report is stale, and
+ * `exitCode` next to `verdict` (fail ⇔ exitCode ≠ 0).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { writeFileAtomic } from '../harness/write-atomic';
+import { reportSlug } from '../harness/unit-paths';
+import type { ContractVerdict } from './build-contract-verdict';
+
+export const contractReportPath = (projectRoot: string, unit: string): string =>
+  path.join(projectRoot, '.sungen', 'reports', `${reportSlug(unit)}-contract.json`);
+
+export function writeContractReport(projectRoot: string, verdict: ContractVerdict): string {
+  const file = contractReportPath(projectRoot, verdict.unit);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const doc = { ...verdict, generatedBy: 'sungen contract check', generatedAt: new Date().toISOString() };
+  writeFileAtomic(file, `${JSON.stringify(doc, null, 2)}\n`);
+  return file;
+}