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

package/src/graph/manual-triage-decisions.ts

@@ -0,0 +1,55 @@
+/**
+ * Manual triage classifications (#928) — a red `sungen triage` could not classify, or classified
+ * wrongly, judged by hand with `sungen triage --screen <u> --case <id> --as <class> --reason "…"`
+ * (harness/triage-manual-classification.ts writes them). Each is a `triage-classification` decision
+ * in the unit's `decisions/`, read here for the test-case state (test-case-results.ts):
+ *
+ *   payload        { case: <id>, class: product-candidate | test-defect | environment, humanConfirmed? }
+ *   evidence_hash  the hash of the red final attempts it judged (TestCaseState.evidence): a re-run
+ *                  makes a new red, and the classification no longer applies to it
+ *   in force       verifies (read-decisions), not superseded, bound to today's red — and, for
+ *                  test-defect / environment, typed by a human on a terminal (`humanConfirmed`, only
+ *                  ever set after the typed confirmation): those classes can hide a product defect,
+ *                  so an entry without it is ignored (fail closed). product-candidate is stricter than
+ *                  any automatic class, so anyone may record it.
+ * The latest classification in force wins over the automatic one.
+ */
+import { readDecisions } from '../decisions/read-decisions';
+import { unitScopeOfDir } from '../harness/gates/unit-gate-overrides';
+
+export const TRIAGE_DECISION_KIND = 'triage-classification' as const;
+export type ManualTriageClass = 'product-candidate' | 'test-defect' | 'environment';
+/** `--as` word → the triage class it records. */
+export const MANUAL_TRIAGE_AS: Readonly<Record<string, ManualTriageClass>> = { product: 'product-candidate', 'test-defect': 'test-defect', environment: 'environment' };
+/** Classes that can hide a product defect: a human types a confirmation on a terminal. */
+export const HUMAN_ONLY_TRIAGE: ReadonlySet<ManualTriageClass> = new Set(['test-defect', 'environment']);
+
+export interface ManualClassification {
+  decision: string;
+  caseId: string;
+  class: ManualTriageClass;
+  evidence: string;
+  reason: string;
+  by: string;
+}
+
+const isClass = (v: unknown): v is ManualTriageClass => Object.values(MANUAL_TRIAGE_AS).includes(v as ManualTriageClass);
+
+/** The unit's classifications that can be in force, oldest first (read-decisions orders by time). */
+export function manualClassifications(projectRoot: string, unitDir: string): ManualClassification[] {
+  const scope = unitScopeOfDir(projectRoot, unitDir);
+  if (!scope) return [];
+  return readDecisions(projectRoot, scope, { kind: TRIAGE_DECISION_KIND }).entries.flatMap((e) => {
+    const p = e.payload ?? {};
+    if (e.superseded_by || typeof p.case !== 'string' || !isClass(p.class) || typeof e.evidence_hash !== 'string') return [];
+    if (HUMAN_ONLY_TRIAGE.has(p.class) && p.humanConfirmed !== true) return [];
+    return [{ decision: e.id, caseId: p.case, class: p.class, evidence: e.evidence_hash, reason: e.reason, by: e.source.by }];
+  });
+}
+
+/** The latest classification of this case bound to this red, if any. */
+export function manualClassificationFor(list: ManualClassification[], caseId: string, evidence: string | undefined): ManualClassification | undefined {
+  if (!evidence) return undefined;
+  for (let i = list.length - 1; i >= 0; i--) if (list[i].caseId === caseId && list[i].evidence === evidence) return list[i];
+  return undefined;
+}

package/src/graph/node-decl.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 { HumanAction, HumanActionKind } from './human-action';
+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[];
+  /**
+   * The HUMAN-ONLY actions behind an offered step ("Waiting for you", #954): what a person runs, with
+   * why. Without it a `decide` step is one action of kind `decide` and any other step is none. `cases`
+   * are the cases open at a test-case node (none for a unit node).
+   */
+  human?(s: UnitState, step: StepCore, cases: TestCaseState[]): HumanAction[];
+}
+
+/** The `human` hook of a node whose decide step IS the human action: its command and reason, under `kind`. */
+export const humanStep = (kind: HumanActionKind) => (_s: UnitState, step: StepCore): HumanAction[] =>
+  [{ command: step.command, reason: step.because, kind }];
+
+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,90 @@
+/**
+ * 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, humanStep, StepCore, TestCaseNodeDecl } from '../node-decl';
+import type { UnitState } from '../../harness/next-step';
+import type { HumanAction } from '../human-action';
+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, human?: TestCaseNodeDecl['human']): 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) } : {}),
+    ...(human ? { human } : {}),
+  };
+}
+
+/**
+ * An opaque step is cleared by a QA accepting it as it reads now, never by re-approving (#923): one
+ * `--accept-opaque` per case whose only hold is the opaque step. A case held by a `low` identity is
+ * not acceptable yet (`contract check --trace` resolves it first), so it is not offered (#954).
+ */
+function acceptOpaque(s: UnitState, _step: StepCore, cases: TestCaseState[]): HumanAction[] {
+  return cases.filter((c) => classOf(c) === 'opaque' && !c.contract?.lowIdentity).map((c) => ({
+    kind: 'accept-opaque',
+    command: `sungen contract approve --screen ${s.unit} --scenario ${c.id} --accept-opaque`,
+    reason: `${c.id} carries a step sungen cannot compare${c.contract?.detail ? ` (${c.contract.detail})` : ''} — a QA reviews it verbatim with its file:line in \`${check(s)}\`, then accepts it as it reads now; until then the contract is in review and \`sungen delivery\` waits`,
+  }));
+}
+
+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` }),
+    undefined, humanStep('contract-approve')),
+  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, undefined, acceptOpaque),
+];

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

@@ -0,0 +1,100 @@
+/**
+ * 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
+ *   tc.rerun-environment  a red the environment caused (#928)               decide  run-test --ids, once a human confirms it is up
+ *   tc.fix-test           a red the test caused (#928)                      do      run-test --ids (auto-fix)
+ * The class is `sungen triage`'s, or a manual classification in force (`sungen triage --case --as`).
+ * 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, humanStep, StepCore, TestCaseNodeDecl } from '../node-decl';
+import type { UnitState } from '../../harness/next-step';
+import type { HumanAction } from '../human-action';
+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');
+/** Up to three cases with the triage rule that judged each. */
+const withRule = (cases: TestCaseState[]): string =>
+  `${cases.slice(0, 3).map((c) => `${c.id}: ${c.triage?.ruleId}`).join('; ')}${cases.length > 3 ? '; …' : ''}`;
+
+function caseNode(id: string, need: TestCaseNeed, rank: number, title: string, actor: TestCaseNodeDecl['actor'],
+  step: (s: UnitState, cases: TestCaseState[], single: boolean) => StepCore, produces: string[], human?: TestCaseNodeDecl['human']): 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,
+    ...(human ? { human } : {}),
+  };
+}
+
+/**
+ * A red triage left unclassified is a human's to classify (#928): test-defect and environment take it
+ * off the product-defect path, so they need a person on a terminal. One action per such case (#954).
+ */
+function classifyByHand(s: UnitState, _step: StepCore, cases: TestCaseState[]): HumanAction[] {
+  return cases.filter((c) => c.triage?.class === 'unclassified').map((c) => ({
+    kind: 'triage-classify',
+    command: `sungen triage ${flag(s)} ${s.unit} --case ${c.id} --as "<test-defect|environment>" --reason "…"`,
+    reason: `${c.id} failed and \`sungen triage\` left it unclassified — read its evidence (trace, error), then classify it: test-defect or environment take it off the product-defect path, so a human types them on a terminal (\`--as product\` anyone may record)`,
+  }));
+}
+
+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: \`sungen triage ${flag(s)} ${s.unit} --case <id> --as product|test-defect|environment --reason "…"\`; test-defect and environment are a human's call, on a terminal)` : ''} — 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'], classifyByHand),
+  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'], humanStep('defect-draft')),
+  // decide, not do: an agent re-running into an environment that is still down gets the same red and
+  // the same step again — a loop with no stop. A human confirms the environment first (#928 review W3).
+  caseNode('tc.rerun-environment', 'rerun-environment', 139, 'Re-run the cases the environment failed, once it is up', 'human', (s, cases) => ({
+    kind: 'decide',
+    command: `/sungen:run-test ${s.unit}${idsArg(cases)}`,
+    because: `${cases.length} red test case(s) failed on the environment, not the app (${withRule(cases)}) — the run never reached a usable app, so their results say nothing about it yet. A human confirms the app, base URL, network, auth state or device is up, then they are re-run; an agent presents this and does not re-run on its own — into an environment that is still down, the same red comes back`,
+  }), ['specs/generated/<unit>/<unit>-test-result.json'], humanStep('rerun-environment')),
+  caseNode('tc.fix-test', 'fix-test', 139.5, 'Fix the tests triaged as test defects', 'ai', (s, cases) => ({
+    kind: 'do',
+    command: `/sungen:run-test ${s.unit}${idsArg(cases)}`,
+    because: `${cases.length} red test case(s) are test defects (${withRule(cases)}) — the test, not the app, failed: fix its selector, test data or step (run-test's auto-fix reads the triage evidence), then re-run them; never weaken an assertion to make one pass`,
+  }), ['selectors/<unit>.yaml', 'specs/generated/<unit>/<unit>-test-result.json']),
+];
+
+/** 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,96 @@
+/**
+ * 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, humanStep, 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',
+    }),
+    human: humanStep('accept-viewpoint'),
+  },
+  {
+    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,100 @@
+/**
+ * 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, humanStep, StepCore, UnitNodeDecl, unitKindDir } from '../node-decl';
+import type { UnitState } from '../../harness/next-step';
+import type { HumanActionKind } from '../human-action';
+
+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}` };
+}
+
+/** What the human does for the step contractStep offered: approve, commit / restore through review, or read the verdict. */
+const contractActionKind = (command: string): HumanActionKind =>
+  command.startsWith('sungen contract approve') ? 'contract-approve' : command.startsWith('sungen contract check') ? 'contract-review' : 'contract-commit';
+
+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,
+    human: (_s, step) => {
+      const kind = contractActionKind(step.command);
+      // A lock repair is a commit (or `git checkout --`) after review — prose, never a sungen command to copy.
+      return [{ command: step.command, reason: step.because, kind, ...(kind === 'contract-commit' ? { instruction: true as const } : {}) }];
+    },
+    // 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`,
+    }),
+    human: humanStep('contract-approve'),
+  },
+];