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

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

@@ -15,8 +15,9 @@
  * 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';
 
@@ -31,15 +32,28 @@ 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',
@@ -58,19 +72,19 @@ export const TEST_CASE_NODES: readonly TestCaseNodeDecl[] = [
       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']),
+  }, ['.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']),
+  }), ['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)}`,

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/harness/catalog/gate-rules.yaml

@@ -586,7 +586,7 @@ rules:
     severity: review
     kind: hard
     rationale: "A check on a JS value, API or canvas result is not tied to an element and cannot be compared automatically (DOS-14.6); it always goes to review and is locked at review."
-    fix: "QA reviews the verbatim step and its file:line, then approves."
+    fix: "QA reviews the verbatim step and its file:line (`sungen contract check`), then accepts it as it reads now on a terminal: `sungen contract approve --screen <unit> --scenario <id> --accept-opaque`. A plain re-approve never clears it."
     since: "p0"
     offAllowed: false
   - id: contract.nondeterministic

package/src/harness/gates/delivery-checklist.ts

@@ -50,13 +50,23 @@ async function quietly<T>(fn: () => Promise<T>): Promise<T> {
   try { return await fn(); } finally { Object.assign(console, saved); }
 }
 
+/** Findings a fresh `sungen generate` cures: the spec is out of step with the .feature, not hollow. */
+const REGENERATE_CURES = /^(?:DRIFT|MISSING in spec|EXTRA in spec|Count mismatch)\b/;
+
+/** The first finding's first sentence — its cause after "→" kept (#943) — and, when regenerating cures it, the command. */
+function scriptCheckFailure(u: ChecklistUnit, finding = 'not faithful'): string {
+  const first = finding.split(/\. /)[0].slice(0, 240);
+  const generate = `sungen generate --${u.kind === 'flow' ? 'flow' : u.kind === 'api' ? 'api' : 'screen'} ${u.unitName}`;
+  return `FAIL — ${first}${REGENERATE_CURES.test(finding) ? ` — run \`${generate}\` after fixing the scenario` : ''} (\`sungen script-check\` exits 2)`;
+}
+
 async function scriptCheckBox(u: ChecklistUnit): Promise<ChecklistBox> {
   try {
     const r = await quietly(() => runScriptCheck(u.unitDir, u.unitName, u.kind));
     if (!r.specPath) return box('script-check', 'skipped', 'no compiled spec to compare: nothing was compiled for this unit');
     return r.status === 'OK'
       ? box('script-check', 'pass', `OK — the spec is a 1:1 of the .feature, no drift (${r.automatedScenarios} automated)`)
-      : box('script-check', 'fail', `FAIL — ${(r.findings[0] ?? 'not faithful').split(/ → |\. /)[0].slice(0, 160)} (\`sungen script-check\` exits 2)`);
+      : box('script-check', 'fail', scriptCheckFailure(u, r.findings[0]));
   } catch (e) {
     return box('script-check', 'fail', `could not run: ${why(e)}`);
   }

package/src/harness/gates/in-run-decision-check.ts

@@ -23,7 +23,8 @@
  * `humanConfirmed`, #928) is a claim the entry makes about itself — a script can write one. What backs
  * it is review, so it is in-run while git HEAD does not hold it (and, with no git, always: nothing
  * shows it was reviewed). Judged by HEAD membership only: it is always recorded after the run it
- * judges, so its commit time says nothing.
+ * judges, so its commit time says nothing. Only a test-defect / environment entry that is not
+ * superseded counts — the only kind the reader puts in force on that claim.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -31,6 +32,7 @@ import { DECISION_FILE_PATH } from '../../decisions/decision-file';
 import { DecisionVisibility } from '../../decisions/decision-schema';
 import { gitOutput } from '../../decisions/git-head-trust';
 import { readDecisions } from '../../decisions/read-decisions';
+import { HUMAN_ONLY_TRIAGE, ManualTriageClass, TRIAGE_DECISION_KIND } from '../../graph/manual-triage-decisions';
 import { migratedWaiverReview } from './migrated-waiver-review';
 
 export const IN_RUN_KINDS = ['gate-override', 'waiver', 'contract-approval'] as const;
@@ -64,9 +66,14 @@ export function runStartOf(resultsPath: string | null): string | null {
 }
 
 const isInRunKind = (kind: string): boolean => (IN_RUN_KINDS as readonly string[]).includes(kind);
-/** A triage classification claiming a human typed it (#928): reviewed only once git HEAD holds it. */
-const claimsHumanTriage = (e: { kind: string; payload?: Record<string, unknown> }): boolean =>
-  e.kind === 'triage-classification' && e.payload?.humanConfirmed === true;
+/**
+ * A triage classification claiming a human typed it (#928): reviewed only once git HEAD holds it.
+ * Only what the reader (manual-triage-decisions.ts) can put in force: a superseded entry is never read,
+ * and a product classification needs no human — its claim backs nothing, so it blocks nothing.
+ */
+const claimsHumanTriage = (e: { kind: string; payload?: Record<string, unknown>; superseded_by?: string }): boolean =>
+  e.kind === TRIAGE_DECISION_KIND && !e.superseded_by && e.payload?.humanConfirmed === true
+  && HUMAN_ONLY_TRIAGE.has(e.payload?.class as ManualTriageClass);
 
 /** In-run decisions among `scopes`, judged against one run start (null: HEAD membership only) and the committed set. */
 export function inRunDecisions(projectRoot: string, scopes: string[], runStart: string | null, committed: Set<string> | null): InRunDecision[] {

package/src/harness/journey.ts

@@ -243,6 +243,52 @@ function computeNext(r: JourneyReport, unit: string): string {
  * A read-only checkout gets the same board without throwing.
  */
 export function runJourney(projectRoot: string, unit: string): JourneyReport {
+  const r = reconcileJourney(projectRoot, unit);
+  try {
+    commitWaiverSync(projectRoot, unit, r.slug, r.sync, r.statePath, JSON.stringify(r.next, null, 2));
+  } catch (err) {
+    if (!(err instanceof DecisionConflictError)) throw err;
+    const rel = path.relative(projectRoot, err.path).split(path.sep).join('/');
+    if (!r.decisionFindings.some((f) => f.path === rel)) r.decisionFindings.push({ rule: 'decision.mutated', path: rel, message: err.message });
+  }
+  return finishReport(r, unit);
+}
+
+/** A waiver the board asks a human to give again: its evidence moved (stale), or git HEAD does not hold it (untrusted). */
+export interface WaiverToRedecide { obligation: string; title: string; reason: string; why: 'stale' | 'untrusted' }
+
+/** What the board asks of a human, read without writing anything (`sungen next`'s "Waiting for you", #954). */
+export interface JourneyHumanAsks {
+  report: JourneyReport;
+  redecide: WaiverToRedecide[];
+  /** OB-signoff: `pending` (never given), `stale` (given before the audit changed), `given`. */
+  signoff: { status: 'pending' | 'stale' | 'given'; at?: string };
+  /** `sungen journey --signoff` would be accepted now (assertCanSignOff holds). */
+  canSignOff: boolean;
+}
+
+/** The board's asks, read-only: no import, no dual-write, no state file — the same reconcile `runJourney` commits. */
+export function readJourneyHumanAsks(projectRoot: string, unit: string): JourneyHumanAsks {
+  const r = reconcileJourney(projectRoot, unit);
+  const report = finishReport(r, unit);
+  let canSignOff = report.obligations.some((o) => o.id === SIGNOFF_OBLIGATION);
+  try { assertCanSignOff(report); } catch { canSignOff = false; }
+  return { report, redecide: r.redecide, signoff: r.signoff, canSignOff };
+}
+
+interface Reconciled {
+  report: JourneyReport;
+  slug: string;
+  statePath: string;
+  sync: ReturnType<typeof planWaiverSync>;
+  next: JourneyState;
+  decisionFindings: DecisionGateFinding[];
+  redecide: WaiverToRedecide[];
+  signoff: JourneyHumanAsks['signoff'];
+}
+
+/** Compute fresh, apply the waivers and the sign-off in force — read-only; `runJourney` commits the plan. */
+function reconcileJourney(projectRoot: string, unit: string): Reconciled {
   const slug = reportSlug(unit);
   assertNoPendingMigration(projectRoot, slug);
   const report = computeFresh(projectRoot, unit);
@@ -250,9 +296,11 @@ export function runJourney(projectRoot: string, unit: string): JourneyReport {
   const state = loadState(sp) || { unit, auditHash: '', waivers: {} };
   const curHash = auditHashOf(projectRoot, slug);
   const sync = planWaiverSync(projectRoot, unit, slug, sp, state.waivers);
+  const redecide: WaiverToRedecide[] = [];
   for (const u of sync.untrusted) {
     const title = report.obligations.find((o) => o.id === u.obligation)?.title ?? u.obligation;
     const ignored = unwaivableWhy(u.obligation, unit);
+    if (!ignored) redecide.push({ obligation: u.obligation, title, reason: u.waiver.reason, why: 'untrusted' });
     report.needsYou.unshift({ text: ignored ? ignoredWaiverText(u.obligation, ignored, u.waiver.reason) : untrustedWaiverText(unit, slug, title, u), anchor: { vpId: u.obligation } });
   }
 
@@ -267,30 +315,33 @@ export function runJourney(projectRoot: string, unit: string): JourneyReport {
       ob.waivedReason = w.reason;
       ob.detail = `waived — ${w.reason}`;
     } else {
+      redecide.push({ obligation: ob.id, title: ob.title, reason: w.reason, why: 'stale' });
       report.needsYou.unshift({ text: `⚠️ Waiver on "${ob.title}" is STALE (evidence changed since ${w.at}) — re-decide. Was: ${w.reason}`, anchor: { vpId: ob.id } });
     }
   }
   // S5 — sign-off reconcile: a recorded sign-off satisfies OB-signoff while its evidence holds;
   // if the audit changed since, the sign-off is STALE → re-surface for re-review (anti-amnesia).
   const signoffOb = report.obligations.find((o) => o.id === 'OB-signoff');
+  let signoff: Reconciled['signoff'] = { status: 'pending' };
   if (signoffOb && state.signoff) {
     if (state.signoff.auditHashAtSignoff === curHash) {
+      signoff = { status: 'given', at: state.signoff.at };
       signoffOb.status = 'satisfied';
       signoffOb.detail = `signed off${state.signoff.by ? ' by ' + state.signoff.by : ''}${state.signoff.recordedBy ? ` (recorded by ${state.signoff.recordedBy})` : ''} at ${state.signoff.at}`;
     } else {
+      signoff = { status: 'stale', at: state.signoff.at };
       report.needsYou.unshift({ text: `⚠️ Sign-off is STALE (suite changed since ${state.signoff.at}) — re-review and sign off again.`, anchor: { vpId: 'OB-signoff' } });
     }
   }
   // Phase-03 carry-over: a decision that does not verify is a FINDING the gate blocks on, not a crash.
   const decisionFindings = journeyDecisionFindings(projectRoot, unitOverrides(projectRoot, unit));
   const next: JourneyState = { unit, auditHash: curHash, waivers: sync.stateWaivers, signoff: state.signoff };
-  try {
-    commitWaiverSync(projectRoot, unit, slug, sync, sp, JSON.stringify(next, null, 2));
-  } catch (err) {
-    if (!(err instanceof DecisionConflictError)) throw err;
-    const rel = path.relative(projectRoot, err.path).split(path.sep).join('/');
-    if (!decisionFindings.some((f) => f.path === rel)) decisionFindings.push({ rule: 'decision.mutated', path: rel, message: err.message });
-  }
+  return { report, slug, statePath: sp, sync, next, decisionFindings, redecide, signoff };
+}
+
+/** The decision findings on the board, then the next suggestion — after the waivers and the sign-off. */
+function finishReport(r: Reconciled, unit: string): JourneyReport {
+  const { report, decisionFindings } = r;
   if (decisionFindings.length) {
     report.decisionFindings = decisionFindings;
     for (const f of [...decisionFindings].reverse()) report.needsYou.unshift({ text: decisionFindingText(f), anchor: { file: f.path } });
@@ -408,11 +459,31 @@ export function writeJourneyFileBestEffort(file: string, text: string): string |
 
 const ICON: Record<ObStatus, string> = { satisfied: '✅', 'needs-work': '⚠️ ', pending: '⏳', waived: '🚫', overridden: '🔓' };
 
+/** `ms` as a person reads a duration: `850 ms`, `45 s`, `8 min 40 s`. */
+function elapsedLabel(ms: number): string {
+  if (ms < 1000) return `${ms} ms`;
+  const s = Math.round(ms / 1000);
+  return s < 60 ? `${s} s` : `${Math.floor(s / 60)} min${s % 60 ? ` ${s % 60} s` : ''}`;
+}
+
+/**
+ * A ledger step as the board shows it (#939 item 8). A step recorded with its elapsed milliseconds in the
+ * NAME (`--step "viewpoint 45000"`, the time meant for `--ms`) printed as a bare number; it reads
+ * `viewpoint (45 s)` now, and `timed` says the line needs its legend.
+ */
+function phaseLabel(step: string): { label: string; timed: boolean } {
+  const m = step.match(/^(.*\S)\s+(\d+)$/);
+  return m ? { label: `${m[1]} (${elapsedLabel(Number(m[2]))})`, timed: true } : { label: step, timed: false };
+}
+
 export function renderJourneyBoard(r: JourneyReport): string {
   const L: string[] = [];
   L.push(`# Journey — ${r.unit}`);
   L.push('');
-  L.push(`📍 **You are here:** ${r.youAreHere}` + (r.phasesDone.length ? `  (phases: ${r.phasesDone.join(' → ')})` : ''));
+  const phases = r.phasesDone.map(phaseLabel);
+  const legend = phases.some((p) => p.timed) || phaseLabel(r.youAreHere).timed
+    ? ` — a time is that phase's elapsed time, from the ledger (\`sungen ledger report --screen ${r.unit}\`)` : '';
+  L.push(`📍 **You are here:** ${phaseLabel(r.youAreHere).label}` + (phases.length ? `  (phases: ${phases.map((p) => p.label).join(' → ')})${legend}` : ''));
   if (r.gateStatus) L.push(`   gate: **${r.gateStatus}** · score: ${r.score ?? '—'}/10`);
   L.push('');
   L.push('## What must still be true');

package/src/harness/next-step.ts

@@ -19,7 +19,9 @@ import * as path from 'path';
 import { reportSlug } from './unit-paths';
 import { checkAssetsDrift } from '../orchestrator/assets-drift';
 import type { HeadSnapshot } from '../contract/contract-git';
-import { evaluateGraph, EvaluateOptions } from '../graph/evaluate-graph';
+import { boardHumanActions } from '../graph/board-human-actions';
+import { evaluateGraph, evaluateHumanActions, EvaluateOptions } from '../graph/evaluate-graph';
+import type { HumanAction } from '../graph/human-action';
 import { CORE_NODES } from '../graph/nodes/core-node-catalog';
 import type { TestCaseState } from '../graph/test-case-state-shape';
 import { testCaseStates } from '../graph/test-case-states';
@@ -93,6 +95,17 @@ export interface UnitState {
   /** Which run the results come from and what they are older than (#942); absent without results. Advisory, decides no step. */
   results?: ResultsFreshness;
   steps: NextStep[];
+  /**
+   * Every pending HUMAN-ONLY action ("Waiting for you", #954): the frontier's decisions (deriveHumanActions)
+   * and the board's asks (sign-off, a waiver to give again, a decision recorded during the run). Set by
+   * readUnitState; commands canonical (`sungen …`). An agent presents them and never runs them.
+   */
+  humanActions?: HumanAction[];
+  /**
+   * The title of the blocking step that cut the frontier: past it only actions that do not depend on it
+   * are listed (sign-off, accept-in-run and the first contract approval wait). Absent when nothing cuts.
+   */
+  humanActionsHeldBy?: string;
 }
 
 export interface ReadUnitStateOptions {
@@ -170,6 +183,11 @@ export function readUnitState(
     if (results) state.results = results;
   } catch { /* advisory: results that cannot be dated add nothing */ }
   state.steps = deriveSteps(state);
+  const graph = evaluateHumanActions(CORE_NODES, state, state.testCases);
+  const seen = new Set<string>();
+  state.humanActions = [...graph.actions, ...boardHumanActions(projectRoot, unitDir, state, graph.cut)]
+    .filter((a) => !seen.has(a.command) && Boolean(seen.add(a.command)));
+  if (graph.heldBy) state.humanActionsHeldBy = graph.heldBy;
   return state;
 }
 
@@ -181,3 +199,8 @@ export function readUnitState(
 export function deriveSteps(s: UnitState, opts: EvaluateOptions = {}): NextStep[] {
   return evaluateGraph(CORE_NODES, s, s.testCases, opts);
 }
+
+/** The human-only actions of the same frontier (#954) — the graph's part of `humanActions`, without the board. */
+export function deriveHumanActions(s: UnitState): HumanAction[] {
+  return evaluateHumanActions(CORE_NODES, s, s.testCases).actions;
+}

package/src/hooks/guard-tty-spoof-rule.ts

@@ -2,8 +2,9 @@
  * Guard rule `tty-spoof` (phase 06, M5): ASK before an agent runs a human-confirmed sungen command
  * through a terminal emulator.
  *
- * `contract approve`, `journey --waive`, `journey --decide`, `journey --signoff` and `triage --as test-defect|environment`
- * (#928: a red classified away from the product-defect path) refuse without a TTY (DOS-13.4), and
+ * `contract approve`, `journey --waive`, `journey --decide`, `journey --signoff`, `triage --as test-defect|environment`
+ * (#928: a red classified away from the product-defect path) and `delivery --accept-in-run` (delivering past
+ * decisions recorded during the run) refuse without a TTY (DOS-13.4), and
  * an agent's Bash has none — unless it borrows one: `script`, `expect`, `unbuffer`, or a pty from
  * Python/Perl/zsh. Then the prompt sees a "terminal" and a piped phrase reads as a human typing it.
  * This rule spots the pair in the raw command (quotes included, so `bash -c "…"` and `expect -c '…'`
@@ -14,7 +15,7 @@
 import type { GuardRule } from './guard-rules';
 
 const TTY_EMULATOR = /\b(?:script|unbuffer|expect|pty|zpty|openpty|forkpty|ptyprocess)\b/i;
-const HUMAN_GATED = /\bsungen\b[\s\S]*?\b(?:contract['",\s]+approve\b|journey\b[\s\S]*?--(?:waive|decide|signoff)\b|triage\b[\s\S]*?--as[\s='",]+(?:test-defect|environment)\b)/i;
+const HUMAN_GATED = /\bsungen\b[\s\S]*?\b(?:contract['",\s]+approve\b|journey\b[\s\S]*?--(?:waive|decide|signoff)\b|triage\b[\s\S]*?--as[\s='",]+(?:test-defect|environment)\b|delivery\b[\s\S]*?--accept-in-run\b)/i;
 
 export const ttySpoof: GuardRule = {
   id: 'tty-spoof',
@@ -25,7 +26,7 @@ export const ttySpoof: GuardRule = {
     return {
       status: 'ask',
       askReason: 'sungen: this runs a human-confirmed sungen action (`contract approve` / `journey --waive|--decide|--signoff` / '
-        + '`triage --as test-defect|environment`) through a terminal '
+        + '`triage --as test-defect|environment` / `delivery --accept-in-run`) through a terminal '
         + 'emulator (script / expect / unbuffer / pty). Those confirmations exist so a PERSON at a terminal decides — allow only if you '
         + 'are that person and asked for exactly this; otherwise run the command yourself in your own terminal.',
     };

package/src/hooks/hand-back-core.ts

@@ -11,6 +11,7 @@
  * ended in silence. The state now starts the moment parsing does; the action only refines it.
  */
 import { sungenInvocation, withProjectInvocation } from '../cli/project-sungen-invocation';
+import { waitingForYouLines } from '../cli/waiting-for-you-block';
 import { resolveUnitCandidates } from '../cli/resolve-unit';
 import { readUnitState, NextStep, UnitState } from '../harness/next-step';
 import { NO_OP, HookContext, HookInput, HookResult } from './hook-result-contract';
@@ -101,12 +102,13 @@ export function locateUnitState(ctx: HookContext, preferred?: string): { root: s
   return unit ? { root, unit, state: readUnitState(root, unit.dir, unit.name, unit.kind) } : null;
 }
 
-/** Hook core: the next steps for the session's unit (input.unit, else the nearest) as context. */
+/** Hook core: the next steps for the session's unit (input.unit, else the nearest) as context, then what waits for a human (#954). */
 export function run(input: HookInput, ctx: HookContext): HookResult {
   const found = locateUnitState(ctx, typeof input.unit === 'string' ? input.unit : undefined);
   if (!found || found.state.steps.length === 0) return NO_OP;
   return {
     status: 'context',
-    output: [`${handBackLine(found.unit.name, sungenInvocation(found.root))} — derived from what the project holds now:`, ...formatSteps(found.state.steps, 4, found.root)].join('\n'),
+    output: [`${handBackLine(found.unit.name, sungenInvocation(found.root))} — derived from what the project holds now:`, ...formatSteps(found.state.steps, 4, found.root),
+      ...waitingForYouLines(found.state.humanActions, found.root, found.state.humanActionsHeldBy)].join('\n'),
   };
 }

package/src/hooks/session-start-unit-state-hook.ts

@@ -5,11 +5,13 @@
  * After `/clear` or a context compaction the agent has lost the thread: it re-derives the state
  * from memory, or worse, re-runs work that is already done. This injects what `sungen next`
  * derives for the session's unit (the one cwd sits in, else the most recently active): what the
- * project already holds — stated as "do not redo" — the audit verdict, and the next steps.
+ * project already holds — stated as "do not redo" — the audit verdict, the next steps, and what waits
+ * for a human (#954).
  */
 import { NO_OP, HookMeta, SungenHook } from './hook-result-contract';
 import { formatSteps, locateUnitState } from './hand-back-core';
 import { sungenInvocation } from '../cli/project-sungen-invocation';
+import { waitingForYouLines } from '../cli/waiting-for-you-block';
 import { listUnits } from './sungen-project-root';
 import type { UnitState } from '../harness/next-step';
 
@@ -48,6 +50,7 @@ export const sessionStartUnitStateHook: SungenHook = {
       state.audit ? `Audit: ${state.audit.overall}/10 [${state.audit.gateStatus}] · ${state.audit.findings.length} finding(s).` : '',
       `Next (\`${sungen} next ${unit.name}\`, derived from the project state):`,
       ...formatSteps(state.steps, 4, root),
+      ...waitingForYouLines(state.humanActions, root, state.humanActionsHeldBy),
       input.source === 'compact' ? 'Context was compacted: re-read the unit\'s files before acting on them.' : '',
       others > 0 ? `Working on another unit? Ask \`${sungen} next <unit>\` (or \`${sungen} next\` for all).` : '',
     ];

package/src/hooks/stop-next-step-hook.ts

@@ -30,6 +30,7 @@ export const stopNextStepHook: SungenHook = {
       output: [
         '[sungen] This turn ran sungen work but ended without the next-step hand-back.',
         'Hand back now: present these steps to the user with AskUserQuestion and stop — do not run them yourself.',
+        ...(/Waiting for you/.test(core.output) ? ['Quote the "Waiting for you" block verbatim: the user runs those commands in their own terminal (`! <command>`); never run them.'] : []),
         core.output,
       ].join('\n'),
     };

package/src/orchestrator/templates/ai-src/commands/delivery.md

@@ -237,3 +237,5 @@ sungen delivery [names...]        # matrix (default; needs the map) → XLSX onl
 Outputs: `qa/deliverables/<unit>-testcases.xlsx` (Overview + Auto + Manual + Coverage sheets) by default;
 `--format csv` writes `<unit>-testcases.csv` instead (flat, `Level` column `item|variant`),
 `--format both` writes both. Legacy mode writes the classic files instead.
+
+<!-- include: waiting-for-you -->

package/src/orchestrator/templates/ai-src/commands/review.md

@@ -97,3 +97,5 @@ You are an **independent QA Reviewer** — you did not author these tests. You d
 5. **Trace + next** — `sungen trace --screen ${input:name}` (human-loop focus), then offer:
    - **`/sungen-run-test ${input:name}`** (Recommended) · **`/sungen-delivery ${input:name}`** · **`/sungen-create-test ${input:name}`** · Done.
 {{/cap}}
+
+<!-- include: waiting-for-you -->

package/src/orchestrator/templates/ai-src/partials/waiting-for-you.claude.md

@@ -0,0 +1,11 @@
+<!-- sungen:waiting-for-you v1 -->
+## Waiting for you — the commands only the QA runs
+
+Right before the hand-back question, run `sungen next {{unitArg}}` and quote its **⏳ Waiting for you**
+block **verbatim** — every command exactly as printed, each with its reason. Those commands approve,
+sign off, waive, classify a red, accept in-run decisions or re-run once the environment is up: they are
+the QA's alone, and most refuse without a person typing a confirmation. Tell the QA to run each one in
+their own terminal — in Claude Code, type `! <command>` in the prompt (a `/sungen:…` command is typed
+as is). **Never run them yourself**, and never pipe or type a confirmation into them. When `sungen next`
+prints no such block, say that nothing is waiting for the QA.
+<!-- /sungen:waiting-for-you -->

package/src/orchestrator/templates/ai-src/partials/waiting-for-you.codex.md

@@ -0,0 +1,11 @@
+<!-- sungen:waiting-for-you v1 -->
+## Waiting for you — the commands only the QA runs
+
+Right before the hand-back list, run `sungen next {{unitArg}}` and quote its **⏳ Waiting for you**
+block **verbatim** — every command exactly as printed, each with its reason. Those commands approve,
+sign off, waive, classify a red, accept in-run decisions or re-run once the environment is up: they are
+the QA's alone, and most refuse without a person typing a confirmation. Tell the QA to run each one
+themselves, in their own terminal (a slash command is typed as is). **Never run them yourself**, and
+never pipe or type a confirmation into them. When `sungen next` prints no such block, say that nothing
+is waiting for the QA.
+<!-- /sungen:waiting-for-you -->

package/src/orchestrator/templates/ai-src/partials/waiting-for-you.copilot.md

@@ -0,0 +1,11 @@
+<!-- sungen:waiting-for-you v1 -->
+## Waiting for you — the commands only the QA runs
+
+Right before the hand-back list, run `sungen next {{unitArg}}` and quote its **⏳ Waiting for you**
+block **verbatim** — every command exactly as printed, each with its reason. Those commands approve,
+sign off, waive, classify a red, accept in-run decisions or re-run once the environment is up: they are
+the QA's alone, and most refuse without a person typing a confirmation. Tell the QA to run each one
+themselves, in their own terminal (a slash command is typed as is). **Never run them yourself**, and
+never pipe or type a confirmation into them. When `sungen next` prints no such block, say that nothing
+is waiting for the QA.
+<!-- /sungen:waiting-for-you -->