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

package/src/exporters/matrix/render-xlsx.ts

@@ -8,6 +8,7 @@
  *   3. Manual   — the cases a person runs.
  *   4. Coverage — requirement coverage, the target × category grid,
  *      dispositions and the generation manifest, over the whole model.
+ *   5. Gate overrides — only when a gate-override touches the unit (client rows only).
  *
  * Auto and Manual are always both created, even when one side is empty: the
  * Overview then always reads the same two rows, and QA has a place to add
@@ -20,6 +21,7 @@ import { DeliveryItem, MatrixModel } from './types';
 import { addTestcaseSheet } from './render-testcase-sheet';
 import { addCoverageSheet } from './render-coverage-sheet';
 import { addMatrixOverviewSheet, SheetProjection } from './render-overview-sheet';
+import { addGateOverridesSheet } from './render-gate-overrides-sheet';
 
 // The CSV renderer and the tests import these from here — they moved to
 // `item-labels.ts` when this module was split, and stay reachable at the old path.
@@ -74,6 +76,9 @@ export function projectItems(model: MatrixModel, mode: 'auto' | 'manual'): Deliv
 
 export function renderMatrixXlsx(model: MatrixModel, sungenVersion?: string): ExcelJS.Workbook {
   const wb = new ExcelJS.Workbook();
+  // Every total and roll-up is a formula with a cached result. The cache is what a preview
+  // (GitHub, Drive, QuickLook) shows; a spreadsheet app recomputes on open as well (#891).
+  wb.calcProperties.fullCalcOnLoad = true;
   const sheets: SheetProjection[] = [
     { sheetName: 'Auto', items: projectItems(model, 'auto') },
     { sheetName: 'Manual', items: projectItems(model, 'manual') },
@@ -82,5 +87,6 @@ export function renderMatrixXlsx(model: MatrixModel, sungenVersion?: string): Ex
   addMatrixOverviewSheet(wb, model, sheets, sungenVersion);
   for (const s of sheets) addTestcaseSheet(wb, s.sheetName, model, s.items, sungenVersion);
   addCoverageSheet(wb, model, sungenVersion);
+  addGateOverridesSheet(wb, model);   // only when a gate-override touches the unit (OES-11.6)
   return wb;
 }

package/src/exporters/matrix/types.ts

@@ -147,6 +147,11 @@ export interface CoverageVariant {
   fingerprint: string;
   /** Execution result, when the run report has one for this variant. */
   result?: PlaywrightResult;
+  /** A Manual variant's result as the tester recorded it in the previous workbook, carried
+   *  BEFORE rendering so every total, roll-up, the CSV and the CLI count it (#891). */
+  manualState?: VariantState;
+  /** The Executed Date the tester recorded with it (yyyy-mm-dd, or as typed). */
+  manualDate?: string;
 }
 
 export type ItemResult = 'passed' | 'failed' | 'blocked' | 'partial' | 'not_run' | 'na';
@@ -214,7 +219,8 @@ export interface RequirementCoverage {
 // ---------------------------------------------------------------------------
 
 export type GateId = 'A' | 'B' | 'C' | 'D' | 'E' | 'G' | 'K' | 'R' | 'W';
-export type FindingSeverity = 'error' | 'review' | 'warning';
+/** `info` appears only when a gate-override lowered a soft rule (OES-11.3). */
+export type FindingSeverity = 'error' | 'review' | 'warning' | 'info';
 
 export interface MatrixFinding {
   gate: GateId;
@@ -260,6 +266,8 @@ export interface MatrixModel {
   /** Who ran the suite and against what — fills Test Executor / Test Environment on rows that
    *  ran (#850). Absent when the caller has no run context (gates-only paths). */
   runEnv?: import('../run-environment').RunEnvironment;
+  /** Gate overrides touching the unit (OES-11.6) — client-visible rows only; internal ones are only counted. */
+  gateOverrides?: import('../../harness/gates/gate-override-report').DeliverableGateOverrides;
 }
 
 /** Complexity warning threshold (rules draft Gate I; raised for compact grouping) — echoed in the manifest. */

package/src/exporters/playwright-report-parser.ts

@@ -161,6 +161,7 @@ export function loadPlaywrightReport(reportPath: string): Map<string, Playwright
       errorMessages: distinct.length > 0 ? distinct : undefined,
       tracePath: trace,
       projectName: test?.projectName,
+      attempts: results.length || undefined,
     });
   }
   return result;

package/src/exporters/scenario-merger.ts

@@ -9,7 +9,7 @@
  */
 
 import { FeatureMetadata, OrderedStep, ScenarioMetadata, SpecFileData, SpecTest } from './types';
-import { isStepsBaseScenario, isSampleScaffoldScenario, extractTestcaseType } from './feature-parser';
+import { isStepsBaseScenario, isSampleScaffoldScenario, isHookScenario, extractTestcaseType } from './feature-parser';
 import { SCENARIO_ID } from './feature-parser';
 import { extractUnlabeledOracle, onlyPresenceAssertions } from './manual-hybrid-oracle';
 
@@ -139,6 +139,7 @@ export function mergeFeatureAndSpec(
   for (const scenario of feature.scenarios) {
     if (isStepsBaseScenario(scenario)) continue;       // skip @steps base scenarios
     if (isSampleScaffoldScenario(scenario)) continue;  // skip default sample
+    if (isHookScenario(scenario)) continue;            // skip @beforeAll/@afterEach/@afterAll hooks
 
     const specTest = findMatchingSpecTest(scenario, spec.tests, feature.scenarios);
     const base = scenario.extendsName ? stepsBaseByName.get(scenario.extendsName) : undefined;

package/src/exporters/types.ts

@@ -95,6 +95,9 @@ export interface ScenarioMetadata {
    * as Gherkin steps — the merger parses these into Steps/Expected for the report.
    */
   comments?: string[];
+  /** Set for a `@beforeAll` / `@afterEach` / `@afterAll` scenario — a hook the compiler emits as
+   *  `test.beforeAll()` etc., never a test case (#880). */
+  hookType?: 'beforeAll' | 'afterEach' | 'afterAll';
 }
 
 /**
@@ -134,6 +137,8 @@ export interface PlaywrightResult {
   errorMessages?: string[];
   tracePath?: string;
   projectName?: string;
+  /** How many attempts the test took (retries + 1). A pass with attempts > 1 is flaky. */
+  attempts?: number;
 }
 
 /**

package/src/generators/test-generator/code-generator.ts

@@ -9,6 +9,7 @@ import { parseResetTier, DEFAULT_RESET_TIER } from './reset-tier';
 import { capabilityRegistry } from '../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 import { readCapabilities } from '../../harness/capability';
+import { isHandWritten } from '../../harness/parse';
 import { parseManualComments } from '../../exporters/scenario-merger';
 import { isPresencePlaceholderHybrid } from '../../exporters/manual-hybrid-oracle';
 import { findSyntaxError } from './utils/spec-syntax-check';
@@ -780,6 +781,12 @@ export class CodeGenerator {
 
     const renderedScenarios: Array<{ code: string; authRole?: string; noAuth?: boolean }> = [];
     for (const scenario of feature.scenarios) {
+      // @free / @impl:code / @proposed: implemented by hand-written code and proven by its trace —
+      // never compiled (DOS-14.8). The same predicate script-check uses, so the counts agree.
+      if (!scenario.stepsName && !scenario.hookType && isHandWritten([...(feature.tags || []), ...(scenario.tags || [])], feature.sourceFile)) {
+        console.log(`  ⊘ Skipped hand-written scenario: ${scenario.name}`);
+        continue;
+      }
       if (isManual(scenario.tags)) {
         // SG-W008 — two-direction rule for @manual scenarios:
         //  • HAS Gherkin steps → the Gherkin must be COMPLETE: Given/When/Then. A dangling
@@ -1458,6 +1465,12 @@ export class CodeGenerator {
         console.log(`⊘ Skipped @manual feature: ${feature.name}`);
         continue;
       }
+      // A feature whose scenarios are all hand-written (a derived *.free.feature) emits no spec.
+      const own = feature.scenarios.filter((sc) => !sc.stepsName && !sc.hookType);
+      if (own.length && own.every((sc) => isHandWritten([...(feature.tags || []), ...(sc.tags || [])], feature.sourceFile))) {
+        console.log(`⊘ Skipped hand-written feature: ${feature.name}`);
+        continue;
+      }
 
       try {
         const generatedTest = await this.generateTest(feature, outputDir);

package/src/graph/evaluate-graph.ts

@@ -0,0 +1,62 @@
+/**
+ * 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
+ *
+ * `--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[] = [];
+  for (const node of ordered) {
+    if (!node.appliesTo.includes(s.kind) || (node.granularity === 'test-case' && node.caseOnly && !opts.testCase)) continue;
+    let step: NextStep | null = null;
+    if (node.granularity === 'unit') {
+      if (!node.active(s) || node.satisfied(s)) continue;
+      if (!opts.testCase || node.blocking) step = withMeta(node, node.step(s));
+    } else {
+      const cases = openCases(node, s, tcStates, opts.testCase);
+      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 && (ready || !node.blocking)) out.push(step);
+    if (node.blocking) break;
+  }
+  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,65 @@
+/**
+ * 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;
+}
+
+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;
+}
+
+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,69 @@
+/**
+ * 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
+ * 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): 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,
+  };
+}
+
+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` })),
+  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` })),
+  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`,
+    }),
+  },
+];