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

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

@@ -0,0 +1,82 @@
+/**
+ * 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)
+ *     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,
+  },
+  {
+    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`,
+    }),
+  },
+];

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

@@ -0,0 +1,88 @@
+/**
+ * Design-stage unit nodes — rows 1–6 of the OES-10.2 parity table, in the order and with the exact
+ * words `deriveSteps` used (frozen in tests/graph/fixtures/legacy-derive-steps.ts).
+ *
+ *   1 unit.no-source         no spec and no viewpoint → blocked; cuts BEFORE even `sungen update`
+ *   2 unit.assets-drift      AI assets from another build → `sungen update` (first, it voids the rest)
+ *   3 unit.viewpoint-missing no test-viewpoint.md → blocked, does not cut
+ *   4 unit.flow-contract     a flow without flow-contract.yaml → blocked, cuts
+ *   5 unit.no-scenarios      zero scenarios → create-test, cuts
+ *   6 unit.flow-inventory    a flow contract without `flows:` → add it, re-audit
+ */
+import { ALL_KINDS, UnitNodeDecl, unitKindDir } from '../node-decl';
+
+const design = (unit: string): string => `/sungen:create-test ${unit}`;
+
+export const UNIT_DESIGN_NODES: readonly UnitNodeDecl[] = [
+  {
+    id: 'unit.no-source', title: 'Write a source to generate from', actor: 'human', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: [], blocking: true, rank: 10, gates: [], produces: ['requirements/spec.md'],
+    active: () => true,
+    satisfied: (s) => s.hasSpec || s.hasViewpoint,
+    step: (s) => ({
+      kind: 'blocked',
+      command: `write qa/${unitKindDir(s.kind)}/${s.unit}/requirements/spec.md`,
+      because: 'the unit has neither a spec nor a test-viewpoint, so there is nothing to generate FROM — generation without a source invents behaviour',
+    }),
+  },
+  {
+    // Stale AI assets come FIRST: a HARD RULE added to `create-test` reaches nobody until `sungen update`
+    // runs, and upgrading the package alone does not refresh them (#620).
+    id: 'unit.assets-drift', title: 'Refresh the AI commands and skills', actor: 'ai', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.no-source'], blocking: false, rank: 20, gates: [], produces: ['.claude/', '.github/', '.agents/'],
+    active: () => true,
+    satisfied: (s) => !s.assetsDrift,
+    step: (s) => ({
+      kind: 'do',
+      command: 'sungen update',
+      because: `this project's AI commands/skills were written by sungen ${s.assetsDrift!.recordedVersion} and you are running ${s.assetsDrift!.runningVersion} — upgrading the package does NOT refresh them, so any rule added since ${s.assetsDrift!.recordedVersion} is not in effect for the next run`,
+    }),
+  },
+  {
+    // The yardstick `atomicLedger` and `traceability` are measured against; it can go missing from a
+    // unit that already HAS a spec, which unit.no-source never sees.
+    id: 'unit.viewpoint-missing', title: 'Restore the test viewpoint', actor: 'human', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.no-source'], blocking: false, rank: 30, gates: [], produces: ['requirements/test-viewpoint.md'],
+    active: () => true,
+    satisfied: (s) => s.hasViewpoint,
+    step: (s) => ({
+      kind: 'blocked',
+      command: s.kind === 'flow'
+        ? `sungen add-flow --flow ${s.unit} --path <start-url>    # repairs the missing scaffold; never overwrites`
+        : `write qa/screens/${s.unit}/requirements/test-viewpoint.md`,
+      because: 'requirements/test-viewpoint.md is missing — it is the yardstick `atomicLedger` and `traceability` are measured against, and four sensors read it, so the audit reports VIEWPOINT-MISSING and those axes are excluded. A flow contract does not substitute: it declares the use case, the viewpoint declares the claims',
+    }),
+  },
+  {
+    id: 'unit.flow-contract', title: 'Author the flow contract', actor: 'human', granularity: 'unit',
+    appliesTo: ['flow'], requires: ['unit.no-source'], blocking: true, rank: 40, gates: [], produces: ['requirements/flow-contract.yaml'],
+    active: () => true,
+    satisfied: (s) => s.hasContract,
+    step: (s) => ({
+      kind: 'blocked',
+      command: `author requirements/flow-contract.yaml, then ${design(s.unit)}`,
+      because: 'a flow with no contract is scored as a generic screen against page-type themes a journey cannot have (FLOW-CONTRACT-MISSING)',
+    }),
+  },
+  {
+    id: 'unit.no-scenarios', title: 'Generate the scenarios', actor: 'ai', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.no-source', 'unit.flow-contract'], blocking: true, rank: 50,
+    gates: ['journey.phase-create'], produces: ['features/<unit>.feature'],
+    active: () => true,
+    satisfied: (s) => s.scenarioCount !== 0,
+    step: (s) => ({ kind: 'do', command: design(s.unit), because: 'no scenarios exist yet' }),
+  },
+  {
+    // Without the inventory, coverage is per PHASE, and a phase counts as covered once one scenario
+    // carries it — so the number cannot show a missing flow.
+    id: 'unit.flow-inventory', title: 'Declare the flow inventory', actor: 'ai', granularity: 'unit',
+    appliesTo: ['flow'], requires: ['unit.no-scenarios'], blocking: false, rank: 60, gates: [], produces: ['requirements/flow-contract.yaml'],
+    active: () => true,
+    satisfied: (s) => s.hasFlowInventory,
+    step: (s) => ({
+      kind: 'do',
+      command: `add \`flows:\` to requirements/flow-contract.yaml, then sungen audit --screen ${s.unit}`,
+      because: 'without the inventory, coverage is measured per PHASE — and a phase counts as covered as soon as one scenario carries it, so the number cannot tell you a flow is missing',
+    }),
+  },
+];

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

@@ -0,0 +1,77 @@
+/**
+ * Execution-stage unit nodes — rows 11–15 (+13b from phase 01) of the OES-10.2 parity table, with the
+ * exact words of the frozen oracle.
+ *
+ *   11  unit.selectors  non-api, no selectors or a placeholder file → run-test, cuts
+ *   12  unit.compile    not compiled → `sungen generate`, cuts
+ *   13  unit.run        never run → run-test, cuts
+ *   13b unit.triage     results with failures → `sungen triage`, before delivery, does not cut —
+ *                       with test-case states it keeps only the reds no case accounts for; tc.triage
+ *                       takes the rest (phase 05)
+ *   14  unit.deliver    no deliverable → delivery
+ *   15  unit.extend     always → optional create-test (the end of the path)
+ */
+import { ALL_KINDS, UnitNodeDecl } from '../node-decl';
+import { attributedReds, unattributedReds } from './test-case-nodes';
+
+const TRIAGE_TAIL = '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';
+
+export const UNIT_EXECUTION_NODES: readonly UnitNodeDecl[] = [
+  {
+    // A scaffolded selector file exists but resolves nothing; treating it as done makes a run look further along.
+    id: 'unit.selectors', title: 'Generate selectors from the live page', actor: 'ai', granularity: 'unit',
+    appliesTo: ['screen', 'flow'], requires: ['unit.gate-fail'], blocking: true, rank: 110, gates: [], produces: ['selectors/<unit>.yaml'],
+    active: () => true,
+    satisfied: (s) => s.hasSelectors && !s.selectorsArePlaceholder,
+    step: (s) => ({
+      kind: 'do',
+      command: `/sungen:run-test ${s.unit}`,
+      because: s.hasSelectors
+        ? 'the selector file is still a placeholder, so nothing resolves against a live page'
+        : 'no selectors exist yet — run-test generates them from the live page, compiles and auto-fixes',
+    }),
+  },
+  {
+    id: 'unit.compile', title: 'Compile the suite', actor: 'deterministic', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.gate-fail', 'unit.selectors'], blocking: true, rank: 120, gates: [], produces: ['specs/generated/<unit>/'],
+    active: () => true,
+    satisfied: (s) => s.compiled,
+    step: (s) => ({ kind: 'do', command: `sungen generate --${s.kind === 'flow' ? 'flow' : 'screen'} ${s.unit}`, because: 'the suite has not been compiled to a spec yet' }),
+  },
+  {
+    id: 'unit.run', title: 'Run the compiled suite', actor: 'ai', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.compile'], blocking: true, rank: 130, gates: ['journey.phase-run'], produces: ['specs/generated/<unit>/<unit>-test-result.json'],
+    active: () => true,
+    satisfied: (s) => s.hasResults,
+    step: (s) => ({ kind: 'do', command: `/sungen:run-test ${s.unit}`, because: 'the compiled spec has never been run, so every case is Pending' }),
+  },
+  {
+    // Reds are classified before they are exported or built on; the steps after it still follow.
+    id: 'unit.triage', title: 'Classify the failed scenarios', actor: 'deterministic', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.run'], blocking: false, rank: 135, gates: [], produces: ['.sungen/triage/<unit>.json'],
+    active: () => true,
+    satisfied: (s) => !(unattributedReds(s) > 0),
+    step: (s) => ({
+      kind: 'do',
+      command: `sungen triage --${s.kind === 'api' ? 'api' : 'screen'} ${s.unit}`,
+      because: attributedReds(s) > 0
+        ? `${unattributedReds(s)} failed result(s) in the latest run match no test case of the .feature (a renamed scenario, an @cases row or a title the .feature does not show) — ${TRIAGE_TAIL}`
+        : `${s.failedCount} scenario(s) failed in the latest run — ${TRIAGE_TAIL}`,
+    }),
+  },
+  {
+    id: 'unit.deliver', title: 'Export the deliverable', actor: 'ai', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.run'], blocking: false, rank: 140, gates: ['journey.phase-deliver', 'decision.in-run'],
+    produces: ['qa/deliverables/<unit>-testcases.xlsx'],
+    active: () => true,
+    satisfied: (s) => s.hasDeliverable,
+    step: (s) => ({ kind: 'do', command: `/sungen:delivery ${s.unit}`, because: 'results exist but have not been exported to the Test Case & Coverage Matrix' }),
+  },
+  {
+    id: 'unit.extend', title: 'Extend coverage', actor: 'ai', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.run'], blocking: false, rank: 150, gates: [], produces: ['features/<unit>.feature'],
+    active: () => true,
+    satisfied: () => false,
+    step: (s) => ({ kind: 'optional', command: `/sungen:create-test ${s.unit}`, because: 'extend coverage — the next tier, or the flows the inventory still lists as pending' }),
+  },
+];

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

@@ -0,0 +1,75 @@
+/**
+ * Which test cases a unit holds, read off its `.feature` files (DOS-11.1): one per runnable scenario
+ * — `@steps` bases, hooks and the scaffold sample are not test cases (as in delivery).
+ *
+ *   id      the scenario's VP-id (the exporters' format-tolerant SCENARIO_ID); without one,
+ *           `T-<hash8>` of file + title, flagged `unstableId` (a rename changes it)
+ *   lines   the scenario block, its tag lines included, up to the line before the next block
+ *   mocked  verified against a declared mock (`@mock` / `@network`, or a mock step) — Pass (Mocked)
+ */
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { isHookScenario, isSampleScaffoldScenario, isStepsBaseScenario, parseFeatureMetadata, splitVpAndName } from '../exporters/feature-parser';
+import { featureFilesFor } from '../harness/unit-paths';
+
+export interface FeatureCase {
+  id: string;
+  unstableId?: true;
+  title: string;
+  absFile: string;
+  /** The feature's basename — result files are named after it. */
+  featureBase: string;
+  lines: [number, number];
+  tags: string[];
+  mocked: boolean;
+}
+
+const SCENARIO_LINE = /^\s*Scenario(?: Outline)?:\s*(.*?)\s*$/;
+const ENDS_BLOCK = /^\s*(?:Rule|Background):/;
+/** Blank lines and the next block's section marker are not part of a scenario. */
+const TRAILER = /^\s*(?:#\s*-{2,}\s*Section:.*)?$/i;
+/** Literal twin of the mock grammar (exporters/matrix/build.ts detectMocked), without loading drivers. */
+const MOCK_TAGS = ['@mock', '@network'];
+const MOCK_STEP = /\[[^\]]+\]\s+mock\s+(?:is\s+active|called\s+(?:\{\{[^}]+\}\}|\d+)\s+times?)\b/i;
+
+/** 1-based [first, last] line of every Scenario block, in file order. */
+function scenarioBlocks(lines: string[]): Array<{ title: string; range: [number, number] }> {
+  const starts: Array<{ title: string; first: number; at: number }> = [];
+  lines.forEach((line, i) => {
+    const m = line.match(SCENARIO_LINE);
+    if (!m) return;
+    let first = i;
+    while (first > 0 && /^\s*@/.test(lines[first - 1])) first--;
+    starts.push({ title: m[1], first, at: i });
+  });
+  return starts.map((b, k) => {
+    let end = k + 1 < starts.length ? starts[k + 1].first : lines.length;   // exclusive
+    for (let j = b.at + 1; j < end; j++) if (ENDS_BLOCK.test(lines[j])) { end = j; break; }
+    while (end - 1 > b.at && TRAILER.test(lines[end - 1])) end--;
+    return { title: b.title, range: [b.first + 1, end] as [number, number] };
+  });
+}
+
+export function featureCases(unitDir: string, unit: string): FeatureCase[] {
+  const out: FeatureCase[] = [];
+  for (const absFile of featureFilesFor(unitDir, unit).filter((f) => fs.existsSync(f))) {
+    const meta = parseFeatureMetadata(absFile);
+    const blocks = scenarioBlocks(fs.readFileSync(absFile, 'utf8').split(/\r?\n/));
+    const used = new Set<number>();
+    for (const sc of meta.scenarios) {
+      const at = blocks.findIndex((b, i) => !used.has(i) && b.title === sc.name);
+      if (at >= 0) used.add(at);
+      if (isStepsBaseScenario(sc) || isHookScenario(sc) || isSampleScaffoldScenario(sc)) continue;
+      const vpId = splitVpAndName(sc.name).vpId;
+      const rel = path.basename(absFile);
+      const id = vpId ?? `T-${createHash('sha1').update(`${rel}\n${sc.name}`).digest('hex').slice(0, 8)}`;
+      out.push({
+        id, ...(vpId ? {} : { unstableId: true as const }), title: sc.name, absFile, featureBase: path.basename(absFile, '.feature'),
+        lines: at >= 0 ? blocks[at].range : [1, 1], tags: sc.tags,
+        mocked: sc.tags.some((t) => MOCK_TAGS.some((m) => t === m || t.startsWith(`${m}:`))) || sc.orderedSteps.some((s) => MOCK_STEP.test(s.text)),
+      });
+    }
+  }
+  return out;
+}

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

@@ -0,0 +1,90 @@
+/**
+ * What has happened to each test case: its result, whether that result still describes the
+ * scenario, and the triage verdict on it — all read off files that already exist (DOS-11.1).
+ *
+ *   result   final attempt across every result file of its feature (`<base>-test-result[.<os>][.<env>].json`)
+ *            and every `@cases` row (`<title> — <label>`): any red → failed; else any pass → passed
+ *   stale    the run manifest (`sungen changed`) selects the scenario: its steps/tags, a selector or a
+ *            test-data key it uses, or a project input changed since the recorded run
+ *   triage   the rows of `.sungen/triage/<unit>.json` for the case, only when that triage is not
+ *            older than the case's result files (a re-run voids it)
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { loadPlaywrightReport } from '../exporters/playwright-report-parser';
+import type { PlaywrightResult } from '../exporters/types';
+import { buildRunManifest, readRunManifest, selectChanged } from '../harness/run-manifest';
+import { readTriageReport } from '../harness/triage-unit';
+import type { TriageClass } from '../harness/triage';
+import type { FeatureCase } from './test-case-identity';
+import type { TestCaseResult, TestCaseState } from './test-case-state-shape';
+import { generatedDirs, RESULT_FILE } from './unit-artifact-probes';
+
+const RED = new Set<PlaywrightResult['status']>(['failed', 'timedOut', 'interrupted']);
+/** The class a case shows when its rows disagree: what needs a human first. */
+const TRIAGE_PRECEDENCE: TriageClass[] = ['product-candidate', 'unclassified', 'test-defect', 'environment', 'known-defect', 'blocked-capability', 'flaky'];
+
+export interface CaseOutcome { result: TestCaseResult; failedResults: number; resultFiles: string[]; stale?: string; triage?: TestCaseState['triage'] }
+
+const ownsTitle = (key: string, title: string): boolean => key === title || key.endsWith(` > ${title}`)
+  || key.startsWith(`${title} — `) || key.includes(` > ${title} — `);
+const rowOwns = (scenario: string, title: string): boolean => scenario === title || scenario.startsWith(`${title} — `);
+const mtime = (f: string): number => { try { return fs.statSync(f).mtimeMs; } catch { return 0; } };
+
+/** Every result file of each feature, with its parsed report (read once per file). */
+function resultsByFeature(projectRoot: string, unit: string, unitId: string): Map<string, Array<{ file: string; report: Map<string, PlaywrightResult> }>> {
+  const dirs = [...new Set([...generatedDirs(projectRoot, unit), path.join(projectRoot, 'specs', 'generated', unitId)])];
+  const out = new Map<string, Array<{ file: string; report: Map<string, PlaywrightResult> }>>();
+  for (const d of dirs) {
+    let names: string[] = [];
+    try { names = fs.readdirSync(d).filter((f) => RESULT_FILE.test(f)).sort(); } catch { continue; }
+    for (const name of names) {
+      const report = loadPlaywrightReport(path.join(d, name));
+      if (!report) continue;                               // unreadable = unknown, never red
+      const base = name.replace(RESULT_FILE, '');
+      out.set(base, [...(out.get(base) ?? []), { file: path.join(d, name), report }]);
+    }
+  }
+  return out;
+}
+
+/** Scenarios `sungen changed` would re-run. No baseline, or one that cannot be read, claims nothing. */
+function staleReasons(projectRoot: string, unitDir: string, unit: string): Record<string, string> {
+  const before = readRunManifest(projectRoot, unit);
+  if (!before || typeof before.scenarios !== 'object' || !before.selectorKeys || !before.dataKeys) return {};
+  try { return selectChanged(before, buildRunManifest(projectRoot, unitDir, unit)).reasons; } catch { return {}; }
+}
+
+/** The triage rows, shape-checked: the report is a file anyone can edit. */
+function triageRows(projectRoot: string, unitId: string): { at: number; rows: Array<{ scenario: string; class: TriageClass; ruleId: string }> } {
+  const report = readTriageReport(projectRoot, unitId);
+  const rows = Array.isArray(report?.rows)
+    ? report!.rows.filter((r) => r && typeof r.scenario === 'string' && TRIAGE_PRECEDENCE.includes(r.class)) : [];
+  return { at: report && typeof report.generatedAt === 'string' ? Date.parse(report.generatedAt) : NaN, rows };
+}
+
+export function caseOutcomes(projectRoot: string, unitDir: string, unit: string, unitId: string, cases: FeatureCase[]): CaseOutcome[] {
+  const byFeature = resultsByFeature(projectRoot, unit, unitId);
+  const stale = staleReasons(projectRoot, unitDir, unit);
+  const triage = triageRows(projectRoot, unitId);
+  return cases.map((c) => {
+    const statuses: PlaywrightResult['status'][] = [];
+    const files: string[] = [];
+    for (const { file, report } of byFeature.get(c.featureBase) ?? []) {
+      const mine = [...report.entries()].filter(([key]) => ownsTitle(key, c.title)).map(([, r]) => r.status);
+      if (mine.length) { statuses.push(...mine); files.push(file); }
+    }
+    const result: TestCaseResult = statuses.some((s) => RED.has(s)) ? 'failed'
+      : statuses.includes('passed') ? 'passed' : statuses.includes('skipped') ? 'skipped' : 'never-run';
+    const out: CaseOutcome = {
+      result, failedResults: statuses.filter((st) => RED.has(st)).length,
+      resultFiles: files.map((f) => path.relative(projectRoot, f).split(path.sep).join('/')),
+    };
+    if (result !== 'never-run' && stale[c.title]) out.stale = stale[c.title];
+    const current = !Number.isNaN(triage.at) && files.every((f) => mtime(f) <= triage.at);
+    const rows = current ? triage.rows.filter((r) => rowOwns(r.scenario, c.title)) : [];
+    const worst = TRIAGE_PRECEDENCE.find((cls) => rows.some((r) => r.class === cls));
+    if (worst) out.triage = { class: worst, ruleId: rows.find((r) => r.class === worst)!.ruleId };
+    return out;
+  });
+}

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

@@ -0,0 +1,55 @@
+/**
+ * When a test case generates work, and which (DOS-11.2).
+ *
+ *   exempt — satisfied, no work: `@manual` (a human executes it), `@requires:<cap>` (waits on a
+ *            capability the QA has not enabled), `@known-defect` (a recorded product defect),
+ *            `@deferred:flow` (owned and automated by its flow — the contract excludes it too),
+ *            triage `blocked-capability`. Any other `@deferred:*` is NOT exempt.
+ *   trigger — what the case needs otherwise, first match wins:
+ *            never run → run · result older than the scenario (run manifest) → rerun-stale ·
+ *            red with no current triage, or left `unclassified` by it → triage (a classification
+ *            is still owed) · triaged product-candidate → a QA decision
+ * A pass — Pass (Mocked) included — needs nothing. A red triaged test-defect / environment has been
+ * judged; the triage report and the deliverable carry it (no P0 node — a P1 follow-up).
+ */
+import type { TestCaseState } from './test-case-state-shape';
+
+export type TestCaseExemption = 'manual' | 'requires' | 'known-defect' | 'deferred' | 'blocked-capability';
+export type TestCaseNeed = 'run' | 'rerun-stale' | 'triage' | 'product-candidate';
+
+const tagged = (tc: TestCaseState, tag: string): boolean => tc.tags.some((t) => t === tag || t.startsWith(`${tag}:`));
+
+/** Why the case is satisfied regardless of its result, or null when it is not exempt. */
+export function exemptionOf(tc: TestCaseState): TestCaseExemption | null {
+  if (tagged(tc, '@manual')) return 'manual';
+  if (tc.tags.some((t) => t.startsWith('@requires:'))) return 'requires';
+  if (tagged(tc, '@known-defect')) return 'known-defect';
+  if (tc.tags.some((t) => /^@deferred:flow$/i.test(t))) return 'deferred';
+  if (tc.triage?.class === 'blocked-capability') return 'blocked-capability';
+  return null;
+}
+
+/** What the case would need if it were not exempt. */
+export function triggerOf(tc: TestCaseState): TestCaseNeed | null {
+  if (tc.result === 'never-run') return 'run';
+  if (tc.stale) return 'rerun-stale';
+  if (tc.result === 'failed') {
+    if (!tc.triage || tc.triage.class === 'unclassified') return 'triage';
+    if (tc.triage.class === 'product-candidate') return 'product-candidate';
+  }
+  return null;
+}
+
+export function testCaseNeed(tc: TestCaseState): TestCaseNeed | null {
+  return exemptionOf(tc) ? null : triggerOf(tc);
+}
+
+/** One word for `--case`: why the case asks for nothing, or what it needs. */
+export function testCaseStatusLabel(tc: TestCaseState): string {
+  const exempt = exemptionOf(tc);
+  if (exempt) return `satisfied (${exempt})`;
+  const need = triggerOf(tc);
+  if (need) return `needs ${need}`;
+  if (tc.result === 'passed') return tc.mocked ? 'satisfied (Pass (Mocked))' : 'satisfied (passed)';
+  return tc.triage ? `satisfied (triaged ${tc.triage.class})` : `satisfied (${tc.result})`;
+}

package/src/graph/test-case-state-shape.ts

@@ -0,0 +1,62 @@
+/**
+ * The shape of one test case's state (DOS-11.1) — facts read off files that already exist, never a
+ * stored record. `testCaseStates()` (test-case-states.ts) builds it; `test-case-satisfied.ts` decides
+ * whether it generates work; the test-case nodes turn the unsatisfied ones into steps.
+ */
+import type { ScenarioClass } from '../contract/contract-schema';
+import type { TriageClass } from '../harness/triage';
+
+/** DOS-12.1 confidence labels: EXTRACTED 0.9–1.0 · INFERRED 0.5–0.89 · AMBIGUOUS < 0.5. */
+export type ConfidenceLabel = 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';
+
+/** An audit finding pinned to the scenario it names, in the shared trace vocabulary (DOS-12.1). */
+export interface LocatedFinding {
+  code: string;
+  text: string;
+  /** `repo@SHA:path#Lx-Ly` — SHA is `worktree` when git is absent or the file differs from HEAD. */
+  citation: string;
+  confidence: { label: ConfidenceLabel; score: number };
+}
+
+export type TestCaseResult = 'passed' | 'failed' | 'skipped' | 'never-run';
+
+/** The case in the contract verdict `sungen contract check` rebuilds (DOS-14.4–14.6) — attached on read. */
+export interface TestCaseContract {
+  class: ScenarioClass;
+  /** Its first finding, as the check prints it. */
+  detail?: string;
+  /** A trace step acts on a target whose identity is only `low` — `contract check --trace` can resolve it. */
+  lowIdentity?: true;
+  /** Its lock entry is not what QA approved and committed (contract.lock-uncommitted). */
+  uncommitted?: true;
+}
+
+export interface TestCaseState {
+  /** The scenario's VP-id; `T-<hash8>` of file + title when it carries none (`unstableId`). */
+  id: string;
+  unstableId?: true;
+  title: string;
+  /** Project-relative, `/`-separated path of the `.feature`. */
+  file: string;
+  /** 1-based first and last line of the scenario block (its tags included). */
+  lines: [number, number];
+  /** Feature and scenario tags. */
+  tags: string[];
+  /** Final-attempt outcome across every result file and variant: any red is `failed`. */
+  result: TestCaseResult;
+  /** Red final attempts this case accounts for — one per result file, variant and `@cases` row. */
+  failedResults?: number;
+  /** Verified against a declared mock — a pass is Pass (Mocked), not Pass (Real). */
+  mocked: boolean;
+  /** Result files that carry this case, project-relative. */
+  resultFiles: string[];
+  /** Set when the scenario changed after the run that produced its result (run manifest). */
+  stale?: string;
+  /** The current `sungen triage` row for a red case — absent when triage has not judged this result. */
+  triage?: { class: TriageClass; ruleId: string };
+  /** Spec anchors the case was generated from (manifest), and whether they moved since. */
+  anchors: Array<{ anchor: string; change: 'keep' | 'regenerate' | 'retire' | 'unknown' }>;
+  findings: LocatedFinding[];
+  /** Its class in the rebuilt contract verdict; absent outside the contract (@manual, no scenario id) or unread. */
+  contract?: TestCaseContract;
+}

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

@@ -0,0 +1,84 @@
+/**
+ * `testCaseStates(projectRoot, unit)` — the state of every test case of a unit, a PURE function of
+ * files that already exist, evaluated whenever it is read (DOS-11.1, red-team #9): no state file, no
+ * facet registry, nothing written. A step interrupted yesterday is recomputed today, not remembered.
+ *
+ *   identity   .feature                       test-case-identity.ts
+ *   outcome    results · run manifest · triage test-case-results.ts
+ *   anchors    .sungen/manifest/<unit>.json — the spec anchors each scenario came from, and their drift
+ *   findings   the audit's findings, located on the case they name (locate-finding.ts, DOS-12.1)
+ *
+ * The audit's findings are taken only from a report that counts (verifyAuditReport): a stale or
+ * untrusted report locates nothing. A caller that already verified the report passes its findings.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { resolveUnitCandidates } from '../cli/resolve-unit';
+import { auditCounts, verifyAuditReport } from '../harness/gates/audit-report-verification';
+import { diffManifest, Manifest } from '../harness/manifest';
+import { reportSlug } from '../harness/unit-paths';
+import { gitCitationContext, locateFindings } from './locate-finding';
+import { caseOutcomes } from './test-case-results';
+import { featureCases } from './test-case-identity';
+import type { TestCaseState } from './test-case-state-shape';
+
+export interface TestCaseStateOptions {
+  /** The unit's directory, when the caller has resolved it already. */
+  unitDir?: string;
+  /** The findings of an audit report the caller verified; read through verifyAuditReport otherwise. */
+  auditFindings?: string[];
+}
+
+type Anchor = TestCaseState['anchors'][number];
+
+/** scenario title → its anchors, with the change `diffManifest` reports (unknown when it cannot say). */
+function anchorsByScenario(projectRoot: string, unitDir: string, unit: string): Map<string, Anchor[]> {
+  const out = new Map<string, Anchor[]>();
+  let manifest: Manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(path.join(projectRoot, '.sungen', 'manifest', `${reportSlug(unit)}.json`), 'utf8'));
+  } catch { return out; }
+  if (!manifest || !Array.isArray(manifest.entries)) return out;
+  let changes: Map<string, Anchor['change']> = new Map();
+  try {
+    changes = new Map(diffManifest(unitDir, unit, manifest).scenarios.map((s) => [`${s.scenario}\n${s.section}`, s.change]));
+  } catch { /* a pending migration or an unreadable spec — the drift is unknown */ }
+  for (const e of manifest.entries) {
+    if (!e || typeof e.scenario !== 'string' || typeof e.section !== 'string') continue;
+    out.set(e.scenario, [...(out.get(e.scenario) ?? []), { anchor: e.section, change: changes.get(`${e.scenario}\n${e.section}`) ?? 'unknown' }]);
+  }
+  return out;
+}
+
+function verifiedFindings(projectRoot: string, unit: string): string[] {
+  const v = verifyAuditReport(projectRoot, unit);
+  const findings = auditCounts(v) ? v.report?.findings : undefined;
+  return Array.isArray(findings) ? findings.filter((f): f is string => typeof f === 'string') : [];
+}
+
+export function testCaseStates(projectRoot: string, unit: string, opts: TestCaseStateOptions = {}): TestCaseState[] {
+  const found = resolveUnitCandidates(unit, projectRoot);
+  const unitDir = opts.unitDir ?? (found.length === 1 ? found[0].dir : undefined);
+  if (!unitDir || !fs.existsSync(unitDir)) return [];
+  const unitId = found.find((f) => f.dir === unitDir)?.unitId ?? unit;
+  const cases = featureCases(unitDir, unit);
+  if (!cases.length) return [];
+  const outcomes = caseOutcomes(projectRoot, unitDir, unit, unitId, cases);
+  const anchors = anchorsByScenario(projectRoot, unitDir, unit);
+  const findings = opts.auditFindings ?? verifiedFindings(projectRoot, unit);
+  const located = findings.length
+    ? locateFindings(findings, cases, gitCitationContext(projectRoot, [...new Set(cases.map((c) => c.absFile))]))
+    : new Map();
+  return cases.map((c, i) => ({
+    id: c.id,
+    ...(c.unstableId ? { unstableId: true as const } : {}),
+    title: c.title,
+    file: path.relative(projectRoot, c.absFile).split(path.sep).join('/'),
+    lines: c.lines,
+    tags: c.tags,
+    mocked: c.mocked,
+    ...outcomes[i],
+    anchors: anchors.get(c.title) ?? [],
+    findings: located.get(i) ?? [],
+  }));
+}