@sun-asterisk/sungen 3.3.0-alpha.5 → 3.3.0-alpha.7

package/src/graph/evaluate-graph.ts

@@ -11,8 +11,12 @@
  * `--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).
+ *
+ * evaluateHumanActions reads the SAME walk for "Waiting for you" (#954): the human-only actions behind
+ * the offered steps, and whether the walk was cut.
  */
 import type { NextStep, UnitState } from '../harness/next-step';
+import type { HumanAction } from './human-action';
 import type { NodeDecl, StepCore } from './node-decl';
 import type { TestCaseState } from './test-case-state-shape';
 
@@ -37,30 +41,55 @@ function openCases(node: NodeDecl, s: UnitState, tcStates: TestCaseState[] | und
   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[] {
+/** One offered step and what produced it: the node, and the cases open at it (test-case nodes). */
+interface Offered { node: NodeDecl; step: NextStep; cases: TestCaseState[] }
+
+/** The walk both answers share: the offered steps in rank order, and whether an open blocking node cut it. */
+function walkFrontier(nodes: readonly NodeDecl[], s: UnitState, tcStates: TestCaseState[] | undefined, opts: EvaluateOptions): { offered: Offered[]; cut: boolean; cutBy?: NodeDecl } {
   const ordered = [...nodes].sort((a, b) => a.rank - b.rank);
   const open = new Set<string>();
-  const out: NextStep[] = [];
+  const offered: Offered[] = [];
   let cut = false;
+  let cutBy: NodeDecl | undefined;
   for (const node of ordered) {
     if (!node.appliesTo.includes(s.kind) || (node.granularity === 'test-case' && node.caseOnly && !opts.testCase)) continue;
     if (cut && !node.surfacesPastCut) continue;
     let step: NextStep | null = null;
+    let cases: TestCaseState[] = [];
     if (node.granularity === 'unit') {
       if (!node.active(s) || node.satisfied(s) || (cut && !node.surfacesPastCut!(s))) continue;
       if (!opts.testCase || node.blocking) step = withMeta(node, node.step(s));
     } else {
-      const cases = openCases(node, s, tcStates, opts.testCase).filter((tc) => !cut || node.surfacesPastCut!(s, tc));
+      cases = openCases(node, s, tcStates, opts.testCase).filter((tc) => !cut || node.surfacesPastCut!(s, tc));
       if (!cases.length) continue;
       const single = Boolean(opts.testCase);
       step = withMeta(node, node.step(s, cases, single), single ? cases[0].id : undefined);
     }
     open.add(node.id);
     const ready = node.requires.every((r) => !open.has(r));
-    if (step && (cut || ready || !node.blocking)) out.push(step);
-    if (node.blocking && !cut) cut = true;
+    if (step && (cut || ready || !node.blocking)) offered.push({ node, step, cases });
+    if (node.blocking && !cut) { cut = true; cutBy = node; }
   }
-  return out;
+  return { offered, cut, ...(cutBy ? { cutBy } : {}) };
+}
+
+export function evaluateGraph(
+  nodes: readonly NodeDecl[], s: UnitState, tcStates?: TestCaseState[], opts: EvaluateOptions = {},
+): NextStep[] {
+  return walkFrontier(nodes, s, tcStates, opts).offered.map((o) => o.step);
+}
+
+/**
+ * The HUMAN-ONLY actions of the same frontier ("Waiting for you", #954) — never a second walk with
+ * rules of its own: each offered step's node says what a person runs (its `human` hook), and a decide
+ * step without one is its own command. `cut`: an open blocking node ended the walk, so only what does
+ * not depend on it is offered (a hard verdict that surfaces past the cut), and the board's asks that
+ * need the unit past it (sign-off, accept-in-run) wait; `heldBy` is that node's title.
+ */
+export function evaluateHumanActions(nodes: readonly NodeDecl[], s: UnitState, tcStates?: TestCaseState[]): { actions: HumanAction[]; cut: boolean; heldBy?: string } {
+  const { offered, cut, cutBy } = walkFrontier(nodes, s, tcStates, {});
+  const actions = offered.flatMap(({ node, step, cases }) => (node.human
+    ? node.human(s, step, cases)
+    : step.kind === 'decide' ? [{ command: step.command, reason: step.because, kind: 'decide' as const }] : []));
+  return { actions, cut, ...(cutBy ? { heldBy: cutBy.title } : {}) };
 }

package/src/graph/human-action.ts

@@ -0,0 +1,33 @@
+/**
+ * A HUMAN-ONLY action of a unit — what `sungen next` lists under "Waiting for you" (#954) and `--json`
+ * carries as `humanActions`. An agent presents these and never runs them: they approve, sign, waive,
+ * classify or accept something on a person's behalf, and most refuse without a typed confirmation.
+ *
+ * `command` is canonical (`sungen …`, or a slash command); the text renders it as the project runs
+ * sungen (`npx sungen` with a local install). Placeholders a human fills are quoted (`"<name>"`, `"…"`)
+ * so a copied command never turns into a shell redirection.
+ */
+export type HumanActionKind =
+  | 'contract-approve'   // approve (or re-approve) the Test Contract — `sungen contract approve`
+  | 'accept-opaque'      // accept a reviewed opaque trace step — `contract approve --scenario <id> --accept-opaque`
+  | 'contract-commit'    // commit, or restore, a lock / approval decision through review
+  | 'contract-review'    // read the contract verdict on a terminal (it could not be built)
+  | 'accept-viewpoint'   // accept the changed viewpoint baseline — `sungen audit --accept-viewpoint`
+  | 'defect-draft'       // decide whether a product-defect candidate is a defect — `sungen defect draft`
+  | 'rerun-environment'  // re-run the reds the environment caused, once a human confirms it is up
+  | 'triage-classify'    // classify a red by hand as test-defect / environment — `sungen triage --case --as`
+  | 'signoff'            // the single human gate — `sungen journey --signoff`
+  | 'waive'              // give a waiver again — `sungen journey --waive`
+  | 'decide'             // record a decision — `sungen journey --decide`
+  | 'accept-in-run';     // deliver despite decisions recorded during the run — `sungen delivery --accept-in-run`
+
+export interface HumanAction {
+  command: string;
+  reason: string;
+  kind: HumanActionKind;
+  /**
+   * `command` is an instruction a person carries out by hand (commit through review, restore from git),
+   * not a command line to copy — the block marks it so, and never renders it as one.
+   */
+  instruction?: true;
+}

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

@@ -11,6 +11,7 @@
  * `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';
@@ -35,8 +36,18 @@ interface NodeDeclBase {
   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;

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

@@ -16,8 +16,9 @@
  * unit.gate-fail), #940; tc.contract-approve (changed, not weaker) is review and waits behind it. Exempt cases (DOS-11.2) open nothing. A proposed case (never approved) asks nothing of its own: a
  * compiled test without a lock is never blocked, and the unit view offers the approval.
  */
-import { ALL_KINDS, StepCore, TestCaseNodeDecl } from '../node-decl';
+import { 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';
@@ -31,7 +32,7 @@ const withDetail = (cases: TestCaseState[]): string =>
 const check = (s: UnitState, trace = false): string => `sungen contract check --screen ${s.unit}${trace ? ' --trace' : ''}`;
 
 function contractNode(id: string, rank: number, title: string, actor: TestCaseNodeDecl['actor'], gates: string[], caseOnly: boolean,
-  active: (tc: TestCaseState) => boolean, step: Step, hard?: (tc: TestCaseState) => boolean): TestCaseNodeDecl {
+  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'],
@@ -39,9 +40,23 @@ function contractNode(id: string, rank: number, title: string, actor: TestCaseNo
     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) {
@@ -57,7 +72,8 @@ const conformanceStep: Step = (s, cases) => {
 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` })),
+    (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) ?? ''),
@@ -70,5 +86,5 @@ export const TEST_CASE_CONTRACT_NODES: readonly TestCaseNodeDecl[] = [
     (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),
+    (tc) => classOf(tc) === 'opaque' || classOf(tc) === 'inconclusive', conformanceStep, undefined, acceptOpaque),
 ];

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

@@ -8,12 +8,16 @@
  *   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, StepCore, TestCaseNodeDecl } from '../node-decl';
+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';
 
@@ -23,17 +27,33 @@ export const listed = (cases: TestCaseState[]): string => `${cases.slice(0, 4).m
 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[]): TestCaseNodeDecl {
+  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',
@@ -50,14 +70,26 @@ export const TEST_CASE_NODES: readonly TestCaseNodeDecl[] = [
     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`,
+      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']),
+  }, ['.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']),
+  }), ['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). */

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

@@ -8,7 +8,7 @@
  *    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 { 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. */
@@ -66,6 +66,7 @@ export const UNIT_AUDIT_NODES: readonly UnitNodeDecl[] = [
       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',

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

@@ -16,8 +16,9 @@
  * 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 { 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}`;
@@ -50,6 +51,10 @@ function contractStep(s: UnitState): StepCore {
   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';
@@ -67,6 +72,11 @@ export const UNIT_CONTRACT_NODES: readonly UnitNodeDecl[] = [
     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
@@ -85,5 +95,6 @@ export const UNIT_CONTRACT_NODES: readonly UnitNodeDecl[] = [
       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'),
   },
 ];

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

@@ -7,15 +7,21 @@
  *   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)
+ *            older than the case's result files (a re-run voids it) — unless a manual classification
+ *            in force judged this very red (manual-triage-decisions.ts, #928): that one wins
+ *   evidence a red case's hash of its red final attempts (file, title, status, start, duration,
+ *            messages): what a manual classification is bound to
  */
+import { createHash } from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
+import { canonicalJson } from '../decisions/decision-identity';
 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 { manualClassificationFor, manualClassifications } from './manual-triage-decisions';
 import type { FeatureCase } from './test-case-identity';
 import type { TestCaseResult, TestCaseState } from './test-case-state-shape';
 import { generatedDirs, RESULT_FILE } from './unit-artifact-probes';
@@ -24,7 +30,7 @@ const RED = new Set<PlaywrightResult['status']>(['failed', 'timedOut', 'interrup
 /** 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'] }
+export interface CaseOutcome { result: TestCaseResult; failedResults: number; resultFiles: string[]; stale?: string; triage?: TestCaseState['triage']; evidence?: string }
 
 const ownsTitle = (key: string, title: string): boolean => key === title || key.endsWith(` > ${title}`)
   || key.startsWith(`${title} — `) || key.includes(` > ${title} — `);
@@ -63,16 +69,28 @@ function triageRows(projectRoot: string, unitId: string): { at: number; rows: Ar
   return { at: report && typeof report.generatedAt === 'string' ? Date.parse(report.generatedAt) : NaN, rows };
 }
 
+/** The red final attempts of one case, hashed: the same red reads the same; a re-run (new start, duration) does not. */
+function redEvidence(projectRoot: string, reds: Array<{ file: string; key: string; r: PlaywrightResult }>): string {
+  const rows = reds.map(({ file, key, r }) => ({
+    file: path.relative(projectRoot, file).split(path.sep).join('/'), key, status: r.status,
+    startTime: r.startTime ?? null, duration: r.duration ?? null, messages: r.errorMessages ?? (r.error ? [r.error] : []),
+  })).sort((a, b) => (`${a.file}\n${a.key}` < `${b.file}\n${b.key}` ? -1 : 1));
+  return createHash('sha256').update(canonicalJson(rows)).digest('hex');
+}
+
 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);
+  const manual = manualClassifications(projectRoot, unitDir);
   return cases.map((c) => {
     const statuses: PlaywrightResult['status'][] = [];
     const files: string[] = [];
+    const reds: Array<{ file: string; key: string; r: PlaywrightResult }> = [];
     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 mine = [...report.entries()].filter(([key]) => ownsTitle(key, c.title));
+      if (mine.length) { statuses.push(...mine.map(([, r]) => r.status)); files.push(file); }
+      for (const [key, r] of mine) if (RED.has(r.status)) reds.push({ file, key, r });
     }
     const result: TestCaseResult = statuses.some((s) => RED.has(s)) ? 'failed'
       : statuses.includes('passed') ? 'passed' : statuses.includes('skipped') ? 'skipped' : 'never-run';
@@ -81,10 +99,13 @@ export function caseOutcomes(projectRoot: string, unitDir: string, unit: string,
       resultFiles: files.map((f) => path.relative(projectRoot, f).split(path.sep).join('/')),
     };
     if (result !== 'never-run' && stale[c.title]) out.stale = stale[c.title];
+    if (result === 'failed') out.evidence = redEvidence(projectRoot, reds);
     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 };
+    const byHand = manualClassificationFor(manual, c.id, out.evidence);
+    if (byHand) out.triage = { class: byHand.class, ruleId: 'manual', decision: byHand.decision };
     return out;
   });
 }

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

@@ -8,14 +8,15 @@
  *   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).
+ *            is still owed) · triaged product-candidate → a QA decision · triaged environment →
+ *            rerun-environment (once it is up) · triaged test-defect → fix-test (#928)
+ * A pass — Pass (Mocked) included — needs nothing. The class may be `sungen triage`'s or a manual
+ * classification in force (manual-triage-decisions.ts); test-case-results.ts decides which.
  */
 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';
+export type TestCaseNeed = 'run' | 'rerun-stale' | 'triage' | 'product-candidate' | 'rerun-environment' | 'fix-test';
 
 const tagged = (tc: TestCaseState, tag: string): boolean => tc.tags.some((t) => t === tag || t.startsWith(`${tag}:`));
 
@@ -36,6 +37,8 @@ export function triggerOf(tc: TestCaseState): TestCaseNeed | null {
   if (tc.result === 'failed') {
     if (!tc.triage || tc.triage.class === 'unclassified') return 'triage';
     if (tc.triage.class === 'product-candidate') return 'product-candidate';
+    if (tc.triage.class === 'environment') return 'rerun-environment';
+    if (tc.triage.class === 'test-defect') return 'fix-test';
   }
   return null;
 }

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

@@ -52,8 +52,13 @@ export interface TestCaseState {
   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 };
+  /**
+   * The class of a red case: a manual classification in force (`ruleId: 'manual'` and its decision id,
+   * #928), else the current `sungen triage` row — absent when neither has judged this result.
+   */
+  triage?: { class: TriageClass; ruleId: string; decision?: string };
+  /** Hash of the red final attempts the case accounts for (failed only) — a manual classification is bound to it; a re-run changes it. */
+  evidence?: 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[];