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

package/src/graph/evaluate-graph.ts

@@ -0,0 +1,66 @@
+/**
+ * The ready frontier of the `sungen next` graph (OES-10.1). Deterministic, read-only: the same
+ * unit state and test-case states always give the same steps, in rank order.
+ *
+ *   open       active ∧ ¬satisfied (a test-case node is open when at least one case is)
+ *   frontier   open ∧ (every `requires` satisfied ∨ ¬blocking)
+ *   cut        an open blocking node ends the walk — nothing ranked after it is offered, except a
+ *              node's instances that `surfacesPastCut` (a hard contract verdict, #940), which follow
+ *              the cutting step and never cut themselves
+ *
+ * `--case <id>` (`testCase` option): the frontier is that case's test-case nodes plus the blocking
+ * unit nodes before them; non-blocking unit advice is left to the unit view. A `caseOnly` test-case
+ * node speaks only there (its unit-level decision is in the unit view already).
+ */
+import type { NextStep, UnitState } from '../harness/next-step';
+import type { NodeDecl, StepCore } from './node-decl';
+import type { TestCaseState } from './test-case-state-shape';
+
+export interface EvaluateOptions {
+  /** Only this test case's nodes (plus the blocking unit nodes before them). */
+  testCase?: string;
+}
+
+function withMeta(node: NodeDecl, core: StepCore, testCase?: string): NextStep {
+  return {
+    ...core,
+    nodeId: node.id,
+    granularity: node.granularity,
+    ...(testCase ? { testCase } : {}),
+    ...(node.gates.length ? { gates: [...node.gates] } : {}),
+  };
+}
+
+/** The cases open at a test-case node, in their given order; none without test-case states. */
+function openCases(node: NodeDecl, s: UnitState, tcStates: TestCaseState[] | undefined, only?: string): TestCaseState[] {
+  if (node.granularity !== 'test-case' || !tcStates) return [];
+  return tcStates.filter((tc) => (!only || tc.id === only) && node.active(s, tc) && !node.satisfied(s, tc));
+}
+
+export function evaluateGraph(
+  nodes: readonly NodeDecl[], s: UnitState, tcStates?: TestCaseState[], opts: EvaluateOptions = {},
+): NextStep[] {
+  const ordered = [...nodes].sort((a, b) => a.rank - b.rank);
+  const open = new Set<string>();
+  const out: NextStep[] = [];
+  let cut = false;
+  for (const node of ordered) {
+    if (!node.appliesTo.includes(s.kind) || (node.granularity === 'test-case' && node.caseOnly && !opts.testCase)) continue;
+    if (cut && !node.surfacesPastCut) continue;
+    let step: NextStep | null = null;
+    if (node.granularity === 'unit') {
+      if (!node.active(s) || node.satisfied(s) || (cut && !node.surfacesPastCut!(s))) continue;
+      if (!opts.testCase || node.blocking) step = withMeta(node, node.step(s));
+    } else {
+      const cases = openCases(node, s, tcStates, opts.testCase).filter((tc) => !cut || node.surfacesPastCut!(s, tc));
+      if (!cases.length) continue;
+      const single = Boolean(opts.testCase);
+      step = withMeta(node, node.step(s, cases, single), single ? cases[0].id : undefined);
+    }
+    open.add(node.id);
+    const ready = node.requires.every((r) => !open.has(r));
+    if (step && (cut || ready || !node.blocking)) out.push(step);
+    if (node.blocking && !cut) cut = true;
+  }
+  return out;
+}

package/src/graph/locate-finding.ts

@@ -0,0 +1,93 @@
+/**
+ * Audit findings pinned to the test case they name, in the shared trace vocabulary (DOS-12.1, takumi
+ * T7): a citation `repo@SHA:path#Lx-Ly` plus a confidence label.
+ *
+ *   EXTRACTED 0.95  the finding names the case's VP-id, and only that case carries it
+ *   EXTRACTED 0.90  the finding quotes the case's full title, and only that case has it
+ *   INFERRED  0.60  the finding names the id's family (`VP-LOGIC` for `VP-LOGIC-003`), shared by ≤ 3 cases
+ *   AMBIGUOUS 0.40  the id or title it names is carried by several cases — each is cited
+ * A finding that names no case is located nowhere (it stays a unit-level finding).
+ *
+ * SHA is the HEAD commit when the file's bytes equal its HEAD blob; otherwise (no git, uncommitted
+ * edit) it is `worktree`, so a citation never points a commit at lines it does not hold. git runs
+ * twice per unit at most, with fixed arguments and a short timeout; a git failure only means `worktree`.
+ */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { gitBlobId, GUARD_GIT_TIMEOUT_MS } from '../contract/contract-git';
+import { idPrefix } from '../harness/parse';
+import type { ConfidenceLabel, LocatedFinding } from './test-case-state-shape';
+
+export interface CitableCase { id: string; unstableId?: true; title: string; absFile: string; lines: [number, number] }
+export interface GitCitationContext { repo: string; repoRoot: string; sha: string | null; headBlobs: Map<string, string> }
+
+/** git reports real paths (macOS `/var` is `/private/var`), so paths are compared real. */
+const real = (p: string): string => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
+
+function git(cwd: string, args: string[]): string | null {
+  try {
+    return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: GUARD_GIT_TIMEOUT_MS }).toString('utf8');
+  } catch { return null; }
+}
+
+/** HEAD sha, repository root and HEAD blob ids of `files` — or a no-git context. */
+export function gitCitationContext(projectRoot: string, files: string[]): GitCitationContext {
+  const top = git(projectRoot, ['rev-parse', '--show-toplevel', 'HEAD'])?.trim().split('\n');
+  if (!top || top.length < 2 || !/^[0-9a-f]{40,64}$/.test(top[1])) {
+    return { repo: path.basename(projectRoot), repoRoot: real(projectRoot), sha: null, headBlobs: new Map() };
+  }
+  const repoRoot = real(top[0]);
+  const root = real(projectRoot);
+  const rels = files.map((f) => path.relative(root, real(f)));
+  const headBlobs = new Map<string, string>();
+  for (const line of (git(projectRoot, ['ls-tree', 'HEAD', '--', ...rels]) ?? '').split('\n')) {
+    const m = line.match(/^\d+ blob ([0-9a-f]+)\t(.+)$/);
+    if (m) headBlobs.set(path.resolve(root, m[2]), m[1]);
+  }
+  return { repo: path.basename(repoRoot), repoRoot, sha: top[1].slice(0, 12), headBlobs };
+}
+
+export function citationOf(ctx: GitCitationContext, absFile: string, lines: [number, number]): string {
+  const file = real(absFile);
+  let sha = 'worktree';
+  try {
+    if (ctx.sha && ctx.headBlobs.get(file) === gitBlobId(fs.readFileSync(file, 'utf8'))) sha = ctx.sha;
+  } catch { /* unreadable now — cite the working tree */ }
+  const rel = path.relative(ctx.repoRoot, file).split(path.sep).join('/');
+  return `${ctx.repo}@${sha}:${rel}#L${lines[0]}-L${lines[1]}`;
+}
+
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** `id` as a whole token — `VP-UI-001` in "VP-UI-001 does not…", never inside `VP-UI-0012`. */
+const namesId = (text: string, id: string): boolean => new RegExp(`(?<![A-Za-z0-9-])${escapeRe(id)}(?![A-Za-z0-9-])`).test(text);
+/** A family token standing alone — `VP-LOGIC` but not the start of another case's `VP-LOGIC-004`. */
+const namesFamily = (text: string, family: string): boolean => new RegExp(`(?<![A-Za-z0-9-])${escapeRe(family)}(?![A-Za-z0-9])(?!-[A-Za-z0-9])`).test(text);
+
+/** Which cases a finding names, and how surely. */
+function matchesOf(finding: string, cases: CitableCase[]): { hits: CitableCase[]; label: ConfidenceLabel; score: number } | null {
+  const byId = cases.filter((c) => !c.unstableId && namesId(finding, c.id));
+  if (byId.length) return byId.length === 1 ? { hits: byId, label: 'EXTRACTED', score: 0.95 } : { hits: byId, label: 'AMBIGUOUS', score: 0.4 };
+  const byTitle = cases.filter((c) => c.title.length >= 8 && finding.includes(c.title));
+  if (byTitle.length) return byTitle.length === 1 ? { hits: byTitle, label: 'EXTRACTED', score: 0.9 } : { hits: byTitle, label: 'AMBIGUOUS', score: 0.4 };
+  const byFamily = cases.filter((c) => !c.unstableId && idPrefix(c.id) !== c.id && namesFamily(finding, idPrefix(c.id)));
+  if (byFamily.length && byFamily.length <= 3) return { hits: byFamily, label: 'INFERRED', score: 0.6 };
+  return null;
+}
+
+/** Every finding that names a case, keyed by the case's index in `cases`. */
+export function locateFindings(findings: string[], cases: CitableCase[], ctx: GitCitationContext): Map<number, LocatedFinding[]> {
+  const out = new Map<number, LocatedFinding[]>();
+  for (const text of findings) {
+    if (typeof text !== 'string' || !text.trim()) continue;
+    const m = matchesOf(text, cases);
+    if (!m) continue;
+    const head = text.split(':')[0].trim();
+    const code = /^[A-Z][A-Z0-9-]+$/.test(head) ? head : 'FINDING';
+    for (const c of m.hits) {
+      const i = cases.indexOf(c);
+      out.set(i, [...(out.get(i) ?? []), { code, text, citation: citationOf(ctx, c.absFile, c.lines), confidence: { label: m.label, score: m.score } }]);
+    }
+  }
+  return out;
+}

package/src/graph/node-decl.ts

@@ -0,0 +1,72 @@
+/**
+ * One node of the `sungen next` graph (OES-10.1) — core-internal, no SPI (red-team #10).
+ *
+ * `deriveSteps` used to be a chain of if/return in which every `return` was a blocking node that cut
+ * everything after it. Each branch is now one declaration: when it applies (`active`), when its goal
+ * is met (`satisfied`), the step it offers, and whether an open instance cuts the nodes ranked after
+ * it (`blocking`). `evaluateGraph` walks them by `rank`.
+ *
+ * Granularity: a `unit` node judges the unit's state; a `test-case` node judges one test case at a
+ * time, and the cases that need it fold into ONE step at unit level (one step per case under
+ * `sungen next <unit> --case <id>`).
+ */
+import type { NextStep, UnitState } from '../harness/next-step';
+import type { TestCaseState } from './test-case-state-shape';
+
+export type NodeActor = 'ai' | 'human' | 'deterministic';
+export type NodeGranularity = 'unit' | 'test-case';
+export type UnitKind = UnitState['kind'];
+
+/** What a node's `step` returns; the engine adds `nodeId`, `granularity`, `gates`, `testCase`. */
+export type StepCore = Pick<NextStep, 'kind' | 'command' | 'because'>;
+
+interface NodeDeclBase {
+  id: string;
+  title: string;
+  /** Who runs the step: an AI agent, a human (`decide`, never auto-run), or sungen itself. */
+  actor: NodeActor;
+  appliesTo: readonly UnitKind[];
+  /** Nodes that must be satisfied first. Each is a lower-ranked blocking node (pinned by a test). */
+  requires: readonly string[];
+  /** An active, unsatisfied blocking node cuts every node ranked after it. */
+  blocking: boolean;
+  rank: number;
+  /** Catalog rule ids (gate-rules.yaml) this step answers to. */
+  gates: readonly string[];
+  /** Artifacts the step produces, for a reader of the graph. */
+  produces: readonly string[];
+}
+
+export interface UnitNodeDecl extends NodeDeclBase {
+  granularity: 'unit';
+  active(s: UnitState): boolean;
+  satisfied(s: UnitState): boolean;
+  step(s: UnitState): StepCore;
+  /**
+   * Offered even when a blocking node ranked before it cut the walk — only while this holds (#940: a
+   * hard contract verdict must not hide behind a stale or failing audit). It never cuts by itself.
+   */
+  surfacesPastCut?(s: UnitState): boolean;
+}
+
+export interface TestCaseNodeDecl extends NodeDeclBase {
+  granularity: 'test-case';
+  /**
+   * Speaks only under `--case <id>`: the unit view already carries the decision at unit level (the
+   * contract's unit.contract-approve), so folding the cases there would say it twice.
+   */
+  caseOnly?: true;
+  active(s: UnitState, tc: TestCaseState): boolean;
+  satisfied(s: UnitState, tc: TestCaseState): boolean;
+  /** One step for `cases` (all open at this node): a unit-level fold, or exactly one case when `single`. */
+  step(s: UnitState, cases: TestCaseState[], single: boolean): StepCore;
+  /** The cases offered even past a cut (see UnitNodeDecl.surfacesPastCut). */
+  surfacesPastCut?(s: UnitState, tc: TestCaseState): boolean;
+}
+
+export type NodeDecl = UnitNodeDecl | TestCaseNodeDecl;
+
+/** `qa/<dir>/<unit>` for the unit kind, as the steps name it. */
+export const unitKindDir = (kind: UnitKind): string => (kind === 'screen' ? 'screens' : kind === 'flow' ? 'flows' : 'api');
+
+export const ALL_KINDS: readonly UnitKind[] = ['screen', 'flow', 'api'];

package/src/graph/nodes/core-node-catalog.ts

@@ -0,0 +1,15 @@
+/**
+ * The core node catalog of `sungen next` (OES-10.1), in rank order. Internal to core: there is no
+ * SPI slot for driver-contributed nodes in P0 (red-team #10).
+ */
+import type { NodeDecl } from '../node-decl';
+import { TEST_CASE_CONTRACT_NODES } from './test-case-contract-nodes';
+import { TEST_CASE_NODES } from './test-case-nodes';
+import { UNIT_AUDIT_NODES } from './unit-audit-nodes';
+import { UNIT_CONTRACT_NODES } from './unit-contract-node';
+import { UNIT_DESIGN_NODES } from './unit-design-nodes';
+import { UNIT_EXECUTION_NODES } from './unit-execution-nodes';
+
+export const CORE_NODES: readonly NodeDecl[] = [
+  ...UNIT_DESIGN_NODES, ...UNIT_AUDIT_NODES, ...UNIT_CONTRACT_NODES, ...UNIT_EXECUTION_NODES, ...TEST_CASE_NODES, ...TEST_CASE_CONTRACT_NODES,
+].sort((a, b) => a.rank - b.rank);

package/src/graph/nodes/test-case-contract-nodes.ts

@@ -0,0 +1,74 @@
+/**
+ * The Test Contract per test case (P0 phase 09, DOS-14.4–14.6) — read off each case's class in the
+ * verdict `sungen contract check` and the delivery guard rebuild (TestCaseState.contract), so the
+ * three never disagree. The unit view keeps phase 05's QA decisions (unit.contract-approve,
+ * unit.contract-proposed); these add what only a case can say:
+ *
+ *   tc.contract-approve  --case only   approved, changed, not weaker      decide   approve --scenario <id>
+ *   tc.contract-check    --case only   weaker / other target / lost check,
+ *                                      or its lock entry is uncommitted   blocked  contract check
+ *   tc.unproven          approved free / impl:code, no admissible trace   do       run-test --ids (traced)
+ *   tc.conformance       its trace is in review: a `low` target identity  do       contract check --trace
+ *                        · its final attempt did not pass (inconclusive)  do       run-test --ids
+ *                        · a step no code can compare (opaque)            decide   contract check
+ * tc.contract-check (a weaker / retargeted / lost check, or an uncommitted lock entry) and tc.unproven
+ * are hard verdicts: they are offered past a stale or failing audit (the cut at unit.audit-stale /
+ * unit.gate-fail), #940; tc.contract-approve (changed, not weaker) is review and waits behind it. Exempt cases (DOS-11.2) open nothing. A proposed case (never approved) asks nothing of its own: a
+ * compiled test without a lock is never blocked, and the unit view offers the approval.
+ */
+import { ALL_KINDS, StepCore, TestCaseNodeDecl } from '../node-decl';
+import type { UnitState } from '../../harness/next-step';
+import type { TestCaseState } from '../test-case-state-shape';
+import { exemptionOf } from '../test-case-satisfied';
+import { idsArg, listed } from './test-case-nodes';
+
+type Step = (s: UnitState, cases: TestCaseState[], single: boolean) => StepCore;
+const HARD_LADDER = new Set(['oracle-weakened', 'target-changed', 'assertion-lost']);
+const classOf = (tc: TestCaseState): string | undefined => tc.contract?.class;
+/** Up to three cases with the finding behind each. */
+const withDetail = (cases: TestCaseState[]): string =>
+  `${cases.slice(0, 3).map((c) => (c.contract?.detail ? `${c.id}: ${c.contract.detail}` : c.id)).join('; ')}${cases.length > 3 ? '; …' : ''}`;
+const check = (s: UnitState, trace = false): string => `sungen contract check --screen ${s.unit}${trace ? ' --trace' : ''}`;
+
+function contractNode(id: string, rank: number, title: string, actor: TestCaseNodeDecl['actor'], gates: string[], caseOnly: boolean,
+  active: (tc: TestCaseState) => boolean, step: Step, hard?: (tc: TestCaseState) => boolean): TestCaseNodeDecl {
+  return {
+    id, title, actor, granularity: 'test-case', appliesTo: ALL_KINDS, blocking: false, rank, gates, step,
+    requires: caseOnly ? ['unit.gate-fail'] : ['unit.run'], produces: ['contracts.lock.yaml', 'decisions/<id>.yaml'],
+    ...(caseOnly ? { caseOnly: true as const } : {}),
+    active: (_s, tc) => active(tc),
+    satisfied: (_s, tc) => exemptionOf(tc) !== null,
+    ...(hard ? { surfacesPastCut: (_s: UnitState, tc: TestCaseState) => hard(tc) } : {}),
+  };
+}
+
+const conformanceStep: Step = (s, cases) => {
+  const low = cases.filter((c) => c.contract?.lowIdentity);
+  if (low.length) {
+    return { kind: 'do', command: check(s, true), because: `${low.length} free / impl:code test case(s) act on a target whose identity is only \`low\` (${listed(low)}) — resolve them in a real browser (needs @sungen/driver-ui). A low identity is never a match, so the contract stays in review and \`sungen delivery\` waits` };
+  }
+  const failed = cases.filter((c) => classOf(c) === 'inconclusive');
+  if (failed.length) {
+    return { kind: 'do', command: `/sungen:run-test ${s.unit}${idsArg(failed)}`, because: `${failed.length} approved free / impl:code test case(s) have no passing final attempt (${listed(failed)}) — the trace of a failed run proves nothing (contract.inconclusive): fix and triage the red, get a passing run, then \`${check(s, true)}\`` };
+  }
+  return { kind: 'decide', command: check(s), because: `${cases.length} free / impl:code test case(s) carry a step sungen cannot compare (${withDetail(cases)}) — a QA reviews it in \`sungen contract check\`; until then the contract is in review and \`sungen delivery\` waits. An agent presents this and never approves it` };
+};
+
+export const TEST_CASE_CONTRACT_NODES: readonly TestCaseNodeDecl[] = [
+  contractNode('tc.contract-approve', 106, 'Re-approve this changed case', 'human', ['contract.hash-changed'], true,
+    (tc) => classOf(tc) === 'hash-changed' && !tc.contract?.uncommitted,
+    (s, [c]) => ({ kind: 'decide', command: `sungen contract approve --screen ${s.unit} --scenario ${c.id}`, because: `this case changed since QA approved it, not weaker${c.contract?.detail ? ` (${c.contract.detail})` : ''} — a QA re-approves this scenario on a terminal; until then review blocks \`sungen delivery\`. An agent presents it and never approves its own edit` })),
+  contractNode('tc.contract-check', 107, 'Restore the approved check of this case', 'human',
+    ['contract.oracle-weakened', 'contract.target-changed', 'contract.assertion-lost', 'contract.lock-uncommitted'], true,
+    (tc) => Boolean(tc.contract?.uncommitted) || HARD_LADDER.has(classOf(tc) ?? ''),
+    (s, [c]) => ({ kind: 'blocked', command: check(s), because: c.contract?.uncommitted
+      ? `its lock entry is not what QA approved and committed (contract.lock-uncommitted) — \`sungen next ${s.unit}\` names the repair; \`sungen delivery\` is blocked until then`
+      : `this case breaks its approved contract (${c.contract?.class}${c.contract?.detail ? `: ${c.contract.detail}` : ''}) — restore the approved check (in the .feature, or in the hand-written test of a free / impl:code case), or a QA approves the change on a terminal (\`sungen contract approve --screen ${s.unit} --scenario ${c.id}\`). \`sungen delivery\` is blocked until then; never weaken an expected value to go green` }),
+    (tc) => Boolean(tc.contract?.uncommitted) || HARD_LADDER.has(classOf(tc) ?? '')),
+  contractNode('tc.unproven', 136, 'Prove the approved free cases with a trace', 'ai', ['contract.unproven'], false,
+    (tc) => classOf(tc) === 'unproven',
+    (s, cases) => ({ kind: 'do', command: `/sungen:run-test ${s.unit}${idsArg(cases)}`, because: `${cases.length} approved free / impl:code test case(s) have no trace that proves them (${withDetail(cases)}) — run them again with trace: 'on' and the sungen run-record reporter (run-test Phase 4 does), then \`${check(s, true)}\`. Until then \`sungen contract check\` fails (contract.unproven) and \`sungen delivery\` is blocked; re-approving or editing the .feature cannot prove them` }),
+    (tc) => classOf(tc) === 'unproven'),
+  contractNode('tc.conformance', 138, 'Settle the traces in review', 'ai', ['contract.opaque-step', 'contract.inconclusive'], false,
+    (tc) => classOf(tc) === 'opaque' || classOf(tc) === 'inconclusive', conformanceStep),
+];

package/src/graph/nodes/test-case-nodes.ts

@@ -0,0 +1,68 @@
+/**
+ * Test-case nodes (OES-10.3) — added after parity, as an intentional output change. Each judges one
+ * case at a time; the cases open at a node fold into ONE step at unit level ("N test case(s) …"),
+ * and `sungen next <unit> --case <id>` shows the one case's step. Satisfied semantics: DOS-11.2
+ * (test-case-satisfied.ts) — exempt cases never open a node.
+ *
+ *   tc.run                never run (a case added after the run)            do      run-test --ids
+ *   tc.rerun-stale        changed after the recorded run (run manifest)     do      run-test --change-only
+ *   tc.triage             red, not classified by a current triage           do      sungen triage
+ *   tc.product-candidate  triage found a product-defect candidate           decide  sungen defect draft
+ * They sit after unit.run (which cuts a unit that never ran) and before delivery. tc.triage takes
+ * the reds the cases account for; unit.triage keeps the rest (unattributedReds), so a red no case
+ * explains — an @cases row, a renamed scenario, a nested describe title — still gets a triage step.
+ */
+import { ALL_KINDS, StepCore, TestCaseNodeDecl } from '../node-decl';
+import type { UnitState } from '../../harness/next-step';
+import type { TestCaseState } from '../test-case-state-shape';
+import { exemptionOf, TestCaseNeed, triggerOf } from '../test-case-satisfied';
+
+const MAX_IDS = 10;
+export const listed = (cases: TestCaseState[]): string => `${cases.slice(0, 4).map((c) => c.id).join(', ')}${cases.length > 4 ? ', …' : ''}`;
+/** `--ids` only names cases `sungen select` can resolve: stable ids, a short list. */
+export const idsArg = (cases: TestCaseState[]): string =>
+  (cases.length <= MAX_IDS && cases.every((c) => !c.unstableId) ? ` --ids ${cases.map((c) => c.id).join(',')}` : '');
+const flag = (s: UnitState): string => (s.kind === 'api' ? '--api' : '--screen');
+
+function caseNode(id: string, need: TestCaseNeed, rank: number, title: string, actor: TestCaseNodeDecl['actor'],
+  step: (s: UnitState, cases: TestCaseState[], single: boolean) => StepCore, produces: string[]): TestCaseNodeDecl {
+  return {
+    id, title, actor, granularity: 'test-case', appliesTo: ALL_KINDS, requires: ['unit.run'], blocking: false, rank,
+    gates: [], produces, step,
+    active: (_s, tc) => triggerOf(tc) === need,
+    satisfied: (_s, tc) => exemptionOf(tc) !== null,
+  };
+}
+
+export const TEST_CASE_NODES: readonly TestCaseNodeDecl[] = [
+  caseNode('tc.run', 'run', 131, 'Run the cases that never ran', 'ai', (s, cases) => ({
+    kind: 'do',
+    command: `/sungen:run-test ${s.unit}${idsArg(cases)}`,
+    because: `${cases.length} test case(s) have never run (${listed(cases)}) — their rows read Pending in the deliverable`,
+  }), ['specs/generated/<unit>/<unit>-test-result.json']),
+  caseNode('tc.rerun-stale', 'rerun-stale', 132, 'Re-run the cases that changed after their run', 'ai', (s, cases, single) => ({
+    kind: 'do',
+    command: single && idsArg(cases) ? `/sungen:run-test ${s.unit}${idsArg(cases)}` : `/sungen:run-test ${s.unit} --change-only`,
+    because: `${cases.length} test case(s) changed after the run that produced their result (${cases.slice(0, 3).map((c) => `${c.id}: ${c.stale}`).join('; ')}${cases.length > 3 ? '; …' : ''}) — that result no longer describes the scenario`,
+  }), ['specs/generated/<unit>/<unit>-test-result.json', '.sungen/run-manifest/<unit>.json']),
+  caseNode('tc.triage', 'triage', 133, 'Classify the red cases', 'deterministic', (s, cases) => {
+    const left = cases.filter((c) => c.triage?.class === 'unclassified').length;
+    return {
+      kind: 'do',
+      command: `sungen triage ${flag(s)} ${s.unit}`,
+      because: `${cases.length} test case(s) failed in the latest run and are not classified yet${left ? ` (${left} left unclassified by the last triage — read its evidence and classify by hand)` : ''} — classify each (known defect, test defect, environment, product candidate) before exporting or extending: an unexplained red in the deliverable is a finding nobody has judged`,
+    };
+  }, ['.sungen/triage/<unit>.json']),
+  caseNode('tc.product-candidate', 'product-candidate', 134, 'Decide on the product-defect candidates', 'human', (s, cases, single) => ({
+    kind: 'decide',
+    command: `sungen defect draft ${flag(s)} ${s.unit}${single ? ` --scenario ${cases[0].id}` : ''}`,
+    because: `${cases.length} red test case(s) look like a product defect (${listed(cases)}) — the app answered and the answer differs from the oracle. A QA decides whether it is a defect to record; an agent presents it and does not draft it on its own`,
+  }), ['qa/defects/DEF-<n>-<slug>.md']),
+];
+
+/** Red final attempts the test cases account for (a case read without the count stands for one). */
+export const attributedReds = (s: UnitState): number =>
+  (s.testCases ?? []).reduce((n, tc) => n + (tc.failedResults ?? (tc.result === 'failed' ? 1 : 0)), 0);
+
+/** The reds unit.triage still owns: all of them without test-case states, else those no case accounts for. */
+export const unattributedReds = (s: UnitState): number => (s.failedCount ?? 0) - (s.testCases ? attributedReds(s) : 0);

package/src/graph/nodes/unit-audit-nodes.ts

@@ -0,0 +1,95 @@
+/**
+ * Audit-stage unit nodes — rows 7–10 of the OES-10.2 parity table (exact words of the frozen oracle).
+ *
+ *    7 unit.audit-missing     never audited → `sungen audit`, cuts
+ *    7 unit.audit-stale       a report that does not count (stale, untrusted) → re-audit, cuts (OES-10.3,
+ *                             phase 05: the report is read through verifyAuditReport, as gate and delivery do)
+ *    8 unit.baseline-changed  viewpoint baseline moved → `--accept-viewpoint`, a QA DECISION (#660)
+ *    9 unit.repair-findings   findings with a known repair → repair + re-audit, names ≤ 4 codes
+ *   10 unit.gate-fail         gateStatus FAIL → blocked, cuts
+ */
+import { ALL_KINDS, UnitNodeDecl } from '../node-decl';
+import type { UnitState } from '../../harness/next-step';
+
+/** The finding codes worth naming in a next step — each maps to a specific repair. */
+export const REPAIRABLE: readonly string[] = [
+  'FLOW-CONTRACT-MISSING', 'FLOW-INVENTORY-MISSING', 'FLOW-UNCOVERED', 'FLOW-UNDECLARED',
+  'FLOW-PHASE-MISFILED', 'FLOW-GUARANTEE-MISSING', 'FLOW-OUTCOME-UNPROVEN', 'CONTINUITY-ONE-SIDED',
+  'ORACLE-URL-ONLY',
+  'SPEC-RESTATED-UNVERIFIED', 'VIEWPOINT-GESTURE-SUBSTITUTED', 'SPEC-UNCOVERED', 'SPEC-CLAUSE-UNCOVERED',
+  'TRIGGER-UNCOVERED', 'PERMISSION-PAIR-MISSING', 'VISIBILITY-PAIR-MISSING',
+  'VIEWPOINT-ITEM-MISSING', 'MANUAL-CODE-MISSING', 'MANUAL-AUTOMATABLE', 'DEPTH-DEFERRED',
+  'UI-INVENTORY-MISSING', 'UI-INVENTORY-INCOMPLETE', 'UI-ITEM-UNCOVERED',
+];
+
+/** The repairable codes of the audit's findings, in finding order, duplicates kept (they are counted). */
+export function repairableCodes(s: UnitState): string[] {
+  return (s.audit?.findings ?? [])
+    .map((f) => f.split(':')[0].trim())
+    .filter((code) => REPAIRABLE.includes(code));
+}
+
+/** The rules whose conjunction is the audit's gateStatus (audit-gate-terms.ts). */
+const AUDIT_GATE_RULES = ['audit.viewpoint-coverage', 'audit.assertion-depth', 'audit.claim-proof', 'audit.spec-coverage',
+  'audit.taxonomy-mismatch', 'audit.gate-sensor-error', 'audit.scenario-id-reuse'];
+
+export const UNIT_AUDIT_NODES: readonly UnitNodeDecl[] = [
+  {
+    id: 'unit.audit-missing', title: 'Measure the suite', actor: 'deterministic', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.no-scenarios'], blocking: true, rank: 70, gates: [], produces: ['.sungen/reports/<unit>-audit.json'],
+    active: (s) => !s.auditNotCounted,
+    satisfied: (s) => Boolean(s.audit),
+    step: (s) => ({ kind: 'do', command: `sungen audit --screen ${s.unit}`, because: 'the suite has never been measured' }),
+  },
+  {
+    // OES-11.4: next, gate and delivery read one verdict — a report that does not count blocks all three.
+    id: 'unit.audit-stale', title: 'Re-measure the suite', actor: 'deterministic', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.no-scenarios'], blocking: true, rank: 71, gates: [], produces: ['.sungen/reports/<unit>-audit.json'],
+    active: (s) => Boolean(s.auditNotCounted),
+    satisfied: (s) => Boolean(s.audit),
+    step: (s) => ({
+      kind: 'do',
+      command: `sungen audit --screen ${s.unit}`,
+      because: s.auditNotCounted!.state === 'stale'
+        ? `the audit report is stale (${s.auditNotCounted!.reason}) — it no longer describes the suite and the decisions in force, so \`sungen gate\` and \`sungen delivery\` treat the unit as never audited until it is re-run`
+        : `the audit report is not trusted (${s.auditNotCounted!.reason}) — it counts as never audited (DOS-14.0) until \`sungen audit\` writes it again; never edit the report`,
+    }),
+  },
+  {
+    // A decision, not a step: accepting the yardstick an agent just wrote makes both axes read 100% (#660).
+    id: 'unit.baseline-changed', title: 'Accept the changed viewpoint', actor: 'human', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.audit-missing', 'unit.audit-stale'], blocking: false, rank: 80, gates: [], produces: ['.sungen/viewpoint-baseline.json'],
+    active: (s) => Boolean(s.audit),
+    satisfied: (s) => s.audit?.viewpointBaselineStatus !== 'changed',
+    step: (s) => ({
+      kind: 'decide',
+      command: `sungen audit --screen ${s.unit} --accept-viewpoint`,
+      because: 'test-viewpoint.md changed since the accepted baseline, so the ledger and traceability axes are not evidence until a QA confirms the new declaration. A decision, not a step: an agent presents it and does not run it — accepting the yardstick you just wrote makes both axes read 100% by construction',
+    }),
+  },
+  {
+    id: 'unit.repair-findings', title: 'Repair the named findings', actor: 'ai', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.audit-missing', 'unit.audit-stale'], blocking: false, rank: 90, gates: [], produces: ['features/<unit>.feature'],
+    active: (s) => Boolean(s.audit),
+    satisfied: (s) => repairableCodes(s).length === 0,
+    step: (s) => {
+      const repair = repairableCodes(s);
+      return {
+        kind: 'do',
+        command: `repair, then sungen audit --screen ${s.unit}`,
+        because: `${repair.length} finding(s) name a specific repair: ${[...new Set(repair)].slice(0, 4).join(', ')}`,
+      };
+    },
+  },
+  {
+    id: 'unit.gate-fail', title: 'Repair the failing gate', actor: 'ai', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.audit-missing', 'unit.audit-stale'], blocking: true, rank: 100, gates: AUDIT_GATE_RULES, produces: ['features/<unit>.feature'],
+    active: (s) => Boolean(s.audit),
+    satisfied: (s) => s.audit?.gateStatus !== 'FAIL',
+    step: (s) => ({
+      kind: 'blocked',
+      command: `repair the gate, then sungen audit --screen ${s.unit}`,
+      because: `the viewpoint gate is FAIL at ${s.audit!.overall}/10 — running tests against a design that fails its own gate measures the wrong thing`,
+    }),
+  },
+];

package/src/graph/nodes/unit-contract-node.ts

@@ -0,0 +1,89 @@
+/**
+ * The Test Contract as a QA DECISION in `sungen next` (DOS-14.4, phase 06 residual) — built from the
+ * verdict `sungen contract check` and the delivery guard rebuild (buildContractVerdict), so the three
+ * never disagree. Always `decide`: an agent presents it and never approves its own edit.
+ *
+ *   unit.contract-approve  (rank 105, after the audit gate, before the first run; a hard verdict —
+ *                          hard or uncommitted — is offered past a stale or failing audit too, #940)
+ *     error        the verdict could not be built → check it on a terminal
+ *     uncommitted  by kind: tampered → re-approve or restore · untracked → commit after review ·
+ *                  edited → review and commit, or `git checkout --` the lock · unverified → commit the
+ *                  decision (approving again cannot fix a commit, and offering it would loop)
+ *     hard         a check got weaker / changed target / was lost → restore it, or QA approves
+ *     review       changed, not weaker → QA re-approves (review blocks delivery)
+ *   unit.contract-proposed (rank 137, after every blocking unit step — it never preempts one)
+ *     proposed     never approved → QA approves (proposed scenarios never block)
+ * A free / impl:code scenario only its TRACE cannot prove — unproven, inconclusive, opaque — is not a
+ * unit decision: the case nodes say what proves it (test-case-contract-nodes.ts, phase 09).
+ */
+import { ALL_KINDS, StepCore, UnitNodeDecl, unitKindDir } from '../node-decl';
+import type { UnitState } from '../../harness/next-step';
+
+const HUMAN_ONLY = 'A QA decision on a terminal: an agent presents it and never approves its own edit';
+const approveCmd = (s: UnitState): string => `sungen contract approve --screen ${s.unit}`;
+
+function uncommittedStep(s: UnitState): StepCore {
+  const c = s.contract!;
+  const lock = `qa/${unitKindDir(s.kind)}/${s.unit}/contracts.lock.yaml`;
+  const n = c.uncommitted;
+  switch (c.uncommittedKind) {
+    case 'tampered':
+      return { kind: 'decide', command: approveCmd(s), because: `${n} lock entr(ies) no longer match their steps (edited by hand) — re-approve with \`${approveCmd(s)}\` on a terminal, or restore the lock from git` };
+    case 'untracked':
+      return { kind: 'decide', command: `commit ${lock} and its contract-approval decision after review`, because: `the lock has never been committed — ${n} entr(ies) are not in git HEAD (contract.lock-uncommitted); commit it after review` };
+    case 'unverified':
+      return { kind: 'decide', command: `commit the contract-approval decision behind ${lock} after review`, because: `${n} lock entr(ies) are not vouched for by a committed contract-approval decision (contract.lock-uncommitted) — commit the decision after review, or re-approve with \`${approveCmd(s)}\` on a terminal` };
+    default:
+      return { kind: 'decide', command: `review and commit ${lock}, or restore it: git checkout -- ${lock}`, because: `${n} lock entr(ies) differ from the lock in git HEAD (contract.lock-uncommitted) — review and commit the lock, or restore it with \`git checkout -- ${lock}\`; approving again cannot fix that` };
+  }
+}
+
+function contractStep(s: UnitState): StepCore {
+  const c = s.contract!;
+  if (c.error) {
+    return { kind: 'decide', command: `sungen contract check --screen ${s.unit}`, because: `the contract verdict could not be built (${c.error}) — check it on a terminal; until it builds, the delivery guard asks instead of passing` };
+  }
+  if (c.uncommitted > 0) return uncommittedStep(s);
+  if (c.hard > 0) {
+    return { kind: 'decide', command: approveCmd(s), because: `${c.hard} scenario(s) break the approved contract (${c.headline}) — restore the approved checks in the .feature, or, if the change is intended, a QA approves it on a terminal. An agent presents this and never approves its own edit` };
+  }
+  return { kind: 'decide', command: approveCmd(s), because: `${c.review} approved scenario(s) changed since QA approved them (changed, not weaker) — review blocks \`sungen delivery\` until QA re-approves. ${HUMAN_ONLY}` };
+}
+
+const CONTRACT_RULES = ['contract.hash-changed', 'contract.oracle-weakened', 'contract.target-changed', 'contract.assertion-lost', 'contract.lock-uncommitted'];
+/** The verdict is a pass and it was built: nothing blocks, nothing to repair. */
+const verdictClean = (s: UnitState): boolean => !s.contract!.error && s.contract!.verdict === 'pass';
+/** Nothing for a QA to decide at unit level: built, committed, nothing approved got weaker or changed. */
+const nothingToDecide = (s: UnitState): boolean => {
+  const c = s.contract!;
+  return !c.error && c.uncommitted === 0 && c.hard === 0 && c.review === 0 && (c.verdict === 'pass' || (c.unproven ?? 0) + (c.traceReview ?? 0) > 0);
+};
+
+export const UNIT_CONTRACT_NODES: readonly UnitNodeDecl[] = [
+  {
+    id: 'unit.contract-approve', title: 'Resolve the Test Contract', actor: 'human', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.gate-fail'], blocking: false, rank: 105, gates: CONTRACT_RULES,
+    produces: ['contracts.lock.yaml', 'decisions/<id>.yaml'],
+    active: (s) => Boolean(s.contract),
+    satisfied: nothingToDecide,
+    step: contractStep,
+    // A hard verdict must not wait behind a re-audit (#940): the audit's PASS says nothing about it —
+    // a broken approved check, or a lock that is not what QA approved and committed (contract.lock-
+    // uncommitted, hard in `contract check`; the step names that repair first). What stays behind the
+    // cut: a changed-not-weaker contract (review — QA re-approves after the design is fixed) and a
+    // verdict that could not be built (not a verdict; `contract check` names the error).
+    surfacesPastCut: (s) => !s.contract!.error && (s.contract!.uncommitted > 0 || s.contract!.hard > 0),
+  },
+  {
+    id: 'unit.contract-proposed', title: 'Approve the Test Contract', actor: 'human', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.run'], blocking: false, rank: 137, gates: [],
+    produces: ['contracts.lock.yaml', 'decisions/<id>.yaml'],
+    active: (s) => Boolean(s.contract) && verdictClean(s),
+    satisfied: (s) => s.contract!.proposed === 0,
+    step: (s) => ({
+      kind: 'decide',
+      command: approveCmd(s),
+      because: `${s.contract!.proposed} scenario(s) have no approved contract yet — approving locks the checks QA reviewed, so a later edit that weakens one (a healer's included) fails \`sungen contract check\`. ${HUMAN_ONLY}; proposed scenarios do not block`,
+    }),
+  },
+];