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

package/src/graph/board-human-actions.ts

@@ -0,0 +1,80 @@
+/**
+ * The human-only actions the graph does not hold ("Waiting for you", #954) — asked by the journey
+ * board and the delivery's decision check, read through THEIR functions (never restated here):
+ *
+ *   waive          a waiver the board re-surfaces: stale (the audit changed since) or untrusted (not
+ *                  in git HEAD) — readJourneyHumanAsks, the reconcile `runJourney` commits
+ *   decide         a gate-override that relaxes nothing because no human confirmed it (ineffective) —
+ *                  re-recorded with `journey --decide`, superseding it (loadUnitGateOverrides)
+ *   signoff        every other obligation holds — assertCanSignOff, as `journey --signoff` checks it
+ *   accept-in-run  a decision recorded during the run — evaluateDeliveryDecisions, as `delivery` runs it
+ * The sign-off and accept-in-run only once the frontier was not cut (the unit has run and nothing
+ * blocks before it). Read-only and advisory: whatever cannot be read adds nothing.
+ */
+import { formatCommand } from '../decisions/human-confirmation';
+import { waiveCommand } from '../decisions/legacy-waiver-migration';
+import { evaluateDeliveryDecisions } from '../harness/gates/delivery-decision-gate';
+import { IN_RUN_RULE } from '../harness/gates/in-run-decision-check';
+import { loadUnitGateOverrides, unitScopeOfDir } from '../harness/gates/unit-gate-overrides';
+import { readJourneyHumanAsks, signoffCommand } from '../harness/journey';
+import type { UnitState } from '../harness/next-step';
+import type { HumanAction } from './human-action';
+import { unitResultFiles } from './unit-artifact-probes';
+
+function journeyActions(projectRoot: string, s: UnitState, cut: boolean): HumanAction[] {
+  const asks = readJourneyHumanAsks(projectRoot, s.unit);
+  const out: HumanAction[] = asks.redecide.map((w) => ({
+    kind: 'waive',
+    command: waiveCommand(s.unit, w.obligation, w.reason),
+    reason: w.why === 'stale'
+      ? `the waiver on "${w.title}" is stale — the evidence changed since it was given, so it no longer counts; if it still holds, a human gives it again on a terminal (or repair the obligation)`
+      : `the waiver on "${w.title}" is not in git HEAD (decision.in-run), so it is not counted — if it is yours, confirm it on a terminal`,
+  }));
+  if (!cut && asks.canSignOff && asks.signoff.status !== 'given') {
+    out.push({
+      kind: 'signoff',
+      command: signoffCommand(s.unit),
+      reason: asks.signoff.status === 'stale'
+        ? `the sign-off of ${asks.signoff.at} is stale — the suite changed since; review the queue (\`sungen journey --screen ${s.unit}\`) and sign off again`
+        : `every other obligation is satisfied or waived — the human sign-off is the one gate \`sungen gate --phase deliver\` still waits on; review the queue (\`sungen journey --screen ${s.unit}\`, ${asks.report.needsYou.length} item(s)), then sign`,
+    });
+  }
+  return out;
+}
+
+function unconfirmedOverrides(projectRoot: string, unitDir: string, s: UnitState): HumanAction[] {
+  return loadUnitGateOverrides(projectRoot, unitScopeOfDir(projectRoot, unitDir)).ineffective.map((o) => {
+    const { humanAccepted: _ignored, ...payload } = o.entry.payload ?? {};
+    return {
+      kind: 'decide',
+      command: formatCommand(['sungen', 'journey', '--screen', s.unit, '--decide', 'gate-override', '--text', o.entry.text, '--reason', o.entry.reason,
+        '--payload', JSON.stringify(payload), '--supersedes', o.decisionId]),
+      reason: `the gate-override ${o.decisionId}${o.rule ? ` (${o.rule})` : ''} relaxes nothing: ${o.reason} — if it is meant, a human records it again on a terminal, superseding it`,
+    };
+  });
+}
+
+function inRunActions(projectRoot: string, unitDir: string, s: UnitState): HumanAction[] {
+  const files = unitResultFiles(projectRoot, s.unit);
+  const refs = (files.length ? files : [null]).map((resultsPath) => ({ label: s.unit, unitName: s.unit, unitDir, resultsPath }));
+  const inRun = evaluateDeliveryDecisions(projectRoot, refs).inRun;
+  if (!inRun.length) return [];
+  const which = inRun.slice(0, 3).map((d) => `${d.kind} ${d.id}`).join(', ');
+  return [{
+    kind: 'accept-in-run',
+    command: formatCommand(['sungen', 'delivery', s.unit, '--accept-in-run']),
+    reason: `${inRun.length} decision(s) recorded during the run (${IN_RUN_RULE}): ${which}${inRun.length > 3 ? ', …' : ''} — \`sungen delivery\` refuses them until they are committed through review and the tests re-run, or a human accepts them on a terminal`,
+  }];
+}
+
+/** The board's and the delivery's asks of a human for this unit. `cut`: the frontier stopped at a blocking node. */
+export function boardHumanActions(projectRoot: string, unitDir: string, s: UnitState, cut: boolean): HumanAction[] {
+  const out: HumanAction[] = [];
+  const add = (read: () => HumanAction[]): void => {
+    try { out.push(...read()); } catch { /* advisory: an unreadable board or decision adds nothing */ }
+  };
+  add(() => journeyActions(projectRoot, s, cut));
+  add(() => unconfirmedOverrides(projectRoot, unitDir, s));
+  if (!cut) add(() => inRunActions(projectRoot, unitDir, s));
+  return out;
+}

package/src/graph/evaluate-graph.ts

@@ -4,13 +4,19 @@
  *
  *   open       active ∧ ¬satisfied (a test-case node is open when at least one case is)
  *   frontier   open ∧ (every `requires` satisfied ∨ ¬blocking)
- *   cut        an open blocking node ends the walk — nothing ranked after it is offered
+ *   cut        an open blocking node ends the walk — nothing ranked after it is offered, except a
+ *              node's instances that `surfacesPastCut` (a hard contract verdict, #940), which follow
+ *              the cutting step and never cut themselves
  *
  * `--case <id>` (`testCase` option): the frontier is that case's test-case nodes plus the blocking
  * unit nodes before them; non-blocking unit advice is left to the unit view. A `caseOnly` test-case
  * node speaks only there (its unit-level decision is in the unit view already).
+ *
+ * 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';
 
@@ -35,28 +41,57 @@ 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)) continue;
+      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);
+      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 && (ready || !node.blocking)) out.push(step);
-    if (node.blocking) break;
+    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 and `heldByCommand`
+ * its offered step's command (#966: "More appear once …" names what to run).
+ */
+export function evaluateHumanActions(nodes: readonly NodeDecl[], s: UnitState, tcStates?: TestCaseState[]): { actions: HumanAction[]; cut: boolean; heldBy?: string; heldByCommand?: 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 }] : []));
+  const heldByCommand = cutBy ? offered.find((o) => o.node === cutBy)?.step.command : undefined;
+  return { actions, cut, ...(cutBy ? { heldBy: cutBy.title } : {}), ...(heldByCommand ? { heldByCommand } : {}) };
 }

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,13 +36,28 @@ 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;
   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 {
@@ -55,6 +71,8 @@ export interface TestCaseNodeDecl extends NodeDeclBase {
   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;

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

@@ -11,11 +11,14 @@
  *   tc.conformance       its trace is in review: a `low` target identity  do       contract check --trace
  *                        · its final attempt did not pass (inconclusive)  do       run-test --ids
  *                        · a step no code can compare (opaque)            decide   contract check
- * Exempt cases (DOS-11.2) open nothing. A proposed case (never approved) asks nothing of its own: a
+ * tc.contract-check (a weaker / retargeted / lost check, or an uncommitted lock entry) and tc.unproven
+ * are hard verdicts: they are offered past a stale or failing audit (the cut at unit.audit-stale /
+ * unit.gate-fail), #940; tc.contract-approve (changed, not weaker) is review and waits behind it. Exempt cases (DOS-11.2) open nothing. A proposed case (never approved) asks nothing of its own: a
  * compiled test without a lock is never blocked, and the unit view offers the approval.
  */
-import { ALL_KINDS, StepCore, TestCaseNodeDecl } from '../node-decl';
+import { 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';
@@ -29,16 +32,31 @@ 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): 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'],
     ...(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) {
@@ -54,16 +72,19 @@ 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) ?? ''),
     (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` })),
+      : `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` })),
+    (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

@@ -3,7 +3,8 @@
  * 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)
+ *   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
@@ -15,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}`;
@@ -49,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';
@@ -66,6 +72,17 @@ 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
+    // 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',
@@ -78,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/nodes/unit-design-nodes.ts

@@ -10,6 +10,7 @@
  *   6 unit.flow-inventory    a flow contract without `flows:` → add it, re-audit
  */
 import { ALL_KINDS, UnitNodeDecl, unitKindDir } from '../node-decl';
+import { updateChannelFlag } from '../../cli/project-sungen-invocation';
 
 const design = (unit: string): string => `/sungen:create-test ${unit}`;
 
@@ -34,7 +35,7 @@ export const UNIT_DESIGN_NODES: readonly UnitNodeDecl[] = [
     satisfied: (s) => !s.assetsDrift,
     step: (s) => ({
       kind: 'do',
-      command: 'sungen update',
+      command: `sungen update${updateChannelFlag(s.assetsDrift!.runningVersion)}`,   // keep the channel (#939)
       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`,
     }),
   },