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

package/src/harness/gates/migrated-waiver-review.ts

@@ -7,62 +7,115 @@
  *
  *   vouched   HEAD's state file holds the record (same reason, `at`, auditHashAtWaive) — reviewedAt is
  *             the commit time of the oldest commit in the unbroken run, back from HEAD, that holds it
- *   with a run start   in-run when reviewedAt is after it (the same test as any committed decision)
- *   without one        in-run when reviewedAt is after the decision file first appeared (its first
- *             commit, else its creation time): a genuine import always follows the commit it read
+ *   imported  the record could have been the import's source (#925) — always checked, run start or not:
+ *             committed strictly before the decision file, the unit's import marker and the project's
+ *             adoption of 3.3 first appeared (migrated-waiver-import-bounds.ts). Failing one, the decision
+ *             claims a migration that never happened → in-run, even at `gate --phase deliver`, which has
+ *             no run start.
+ *   with a run start   also in-run when reviewedAt is after it (the same test as any committed decision)
  * Anything else — no git, no such record in HEAD, a record that differs — is not vouched for: the
- * decision is judged as any other (`not in git HEAD`, or its own commit time).
+ * decision is judged as any other (`not in git HEAD`, or its own commit time). Only a rewritten history
+ * (a squash or rebase that folds the record's commit into the import's) can fail a genuine import; the
+ * finding says which bound it crossed.
+ *
+ * Nor is a record whose introducing commit is out of reach — judged as any other, with `unvouched`
+ * saying why, never vouched for by a later commit taken for its introduction: the walk reads at most
+ * MAX_COMMITS commits of a state file and the record is held by the commit before them too (#924), or
+ * the record reaches a shallow clone's boundary commit. One review reads each state file's history
+ * once (one `git log`, one `git cat-file --batch`), however many waivers share it.
  */
-import * as fs from 'fs';
-import * as path from 'path';
-import { committedText, gitOutput } from '../../decisions/git-head-trust';
+import { gitFileTexts, gitOutput, isShallowRepository } from '../../decisions/git-head-trust';
 import type { ReadDecision } from '../../decisions/read-decisions';
 import { asLegacyWaiver, isLegacyWaiver, sameWaiver } from '../../decisions/waiver-decisions';
 import { reportSlug } from '../unit-paths';
+import { migratedWaiverImportBounds, migratedWaiverRemedy } from './migrated-waiver-import-bounds';
 
-/** Commits of one state file the walk reads at most (each is one `git show`). */
+/** Commits of one state file the walk reads at most. */
 const MAX_COMMITS = 200;
 
-const parse = (text: string | null): { waivers?: Record<string, unknown> } | null => {
+type State = { waivers?: Record<string, unknown> } | null;
+/** A state file in git: HEAD's version and its newest MAX_COMMITS + 1 commits (newest first; `root`: no parent shown). */
+interface StateHistory { rel: string; head: State; commits: Array<{ at: string; state: State; root: boolean }> }
+
+/** A migrated waiver HEAD's legacy file holds: when it was reviewed, or why that cannot be said. */
+export interface MigratedReview {
+  /** When its legacy record was committed; null when that commit is out of reach (see `unvouched`). */
+  at: string | null;
+  /** Set with `at`: why the record cannot have been the import's source — the decision is in-run. */
+  notImported?: string;
+  /** Set when `at` is null: why the record vouches for nothing — the decision is judged as any other. */
+  unvouched?: string;
+}
+
+const parse = (text: string | null): State => {
   if (text === null) return null;
   try { return JSON.parse(text.replace(/^/, '')); } catch { return null; }
 };
 
-function holds(state: { waivers?: Record<string, unknown> } | null, e: ReadDecision, ob: string): boolean {
+function holds(state: State, e: ReadDecision, ob: string): boolean {
   const w = state?.waivers?.[ob];
   return isLegacyWaiver(w) && w.at === e.valid_from && sameWaiver(w, asLegacyWaiver(e));
 }
 
-/** The commit time of the oldest commit, in the unbroken run back from HEAD, whose state file holds the record. */
-function introducedAt(projectRoot: string, rel: string, e: ReadDecision, ob: string): string | null {
-  const log = gitOutput(projectRoot, ['log', `--max-count=${MAX_COMMITS}`, '--format=%H %cI', '--', rel]) ?? '';
-  let oldest: string | null = null;
-  for (const line of log.split('\n').filter(Boolean)) {
-    const [sha, at] = line.split(' ');
-    if (!holds(parse(gitOutput(projectRoot, ['show', `${sha}:./${rel}`])), e, ob)) break;
-    oldest = at;
-  }
-  return oldest && !Number.isNaN(Date.parse(oldest)) ? oldest : null;
+function readHistory(projectRoot: string, rel: string): StateHistory {
+  const log = (gitOutput(projectRoot, ['log', `--max-count=${MAX_COMMITS + 1}`, '--format=%H %cI %P', '--', rel]) ?? '')
+    .split('\n').filter(Boolean).map((line) => line.trim().split(' '));
+  const texts = gitFileTexts(projectRoot, [`HEAD:./${rel}`, ...log.map(([sha]) => `${sha}:./${rel}`)]);
+  return {
+    rel,
+    head: parse(texts?.[0] ?? null),
+    commits: log.map(([, at, ...parents], i) => ({ at, state: parse(texts?.[i + 1] ?? null), root: parents.length === 0 })),
+  };
 }
 
-/** When a migrated waiver's legacy record was committed, or null when nothing in git HEAD vouches for it. */
-export function migratedWaiverReviewedAt(projectRoot: string, scope: string, e: ReadDecision): string | null {
-  const ob = e.payload?.obligation;
-  if (e.kind !== 'waiver' || e.source?.where !== 'migrated' || typeof ob !== 'string') return null;
-  // The journey keys its state by the unit name it was given: `<name>`, or the catalog id for api units.
-  const slugs = new Set([scope.split('/').pop() ?? '', reportSlug(scope.replace(/^(screens|flows)\//, ''))]);
-  for (const slug of slugs) {
-    const file = path.join(projectRoot, '.sungen', 'journey', `${slug}.state.json`);
-    if (!holds(parse(committedText(projectRoot, file)), e, ob)) continue;
-    const at = introducedAt(projectRoot, path.relative(projectRoot, file).split(path.sep).join('/'), e, ob);
-    if (at) return at;
+/**
+ * The commit time of the oldest commit, in the unbroken run back from HEAD, whose state file holds the
+ * record. The walk reads MAX_COMMITS commits; the next one only says whether the last of them introduced it.
+ * In a shallow clone a commit with no parent shown is the boundary: every file seems to appear there, so a
+ * record reaching it has no known commit time.
+ */
+function introducedAt(h: StateHistory, e: ReadDecision, ob: string, scope: string, shallow: () => boolean): MigratedReview | null {
+  let run = 0;
+  while (run < h.commits.length && holds(h.commits[run].state, e, ob)) run++;
+  const unvouched = (why: string): MigratedReview => ({ at: null, unvouched: `migrated, but its legacy record cannot vouch for it: ${why}` });
+  if (run > MAX_COMMITS) {
+    return unvouched(`${h.rel} changed in more than ${MAX_COMMITS} commits, and the commit that introduced the record is older than all of them`);
   }
-  return null;
+  const oldest = run ? h.commits[run - 1] : null;
+  if (oldest?.root && shallow()) {
+    return unvouched(`the git history is shallow, so the record's real commit time is unknown — fetch the full history `
+      + `(\`git fetch --unshallow\`; \`fetch-depth: 0\` in CI), or ${migratedWaiverRemedy(scope, ob)}`);
+  }
+  return oldest && !Number.isNaN(Date.parse(oldest.at)) ? { at: oldest.at } : null;
 }
 
-/** When a decision file first appeared: its first commit, else its creation (or last change) on disk. */
-export function decisionFirstSeenMs(projectRoot: string, rel: string, abs: string): number {
-  const added = gitOutput(projectRoot, ['log', '--diff-filter=A', '--format=%cI', '--', rel])?.trim().split('\n').filter(Boolean).pop();
-  if (added && !Number.isNaN(Date.parse(added))) return Date.parse(added);
-  try { const s = fs.statSync(abs); return s.birthtimeMs || s.mtimeMs; } catch { return Number.NEGATIVE_INFINITY; }
+/** One run's reads for migrated waivers: each state file's history, decision's first commit and import marker, read once. */
+export function migratedWaiverReview(projectRoot: string) {
+  const histories = new Map<string, StateHistory>();
+  const bounds = migratedWaiverImportBounds(projectRoot);
+  let isShallow: boolean | undefined;
+  const shallow = (): boolean => (isShallow ??= isShallowRepository(projectRoot));
+  const historyOf = (rel: string): StateHistory => {
+    if (!histories.has(rel)) histories.set(rel, readHistory(projectRoot, rel));
+    return histories.get(rel)!;
+  };
+
+  return {
+    /** How a migrated waiver was reviewed; null when it is not one HEAD's legacy file holds (judged as any other). */
+    reviewOf(scope: string, e: ReadDecision): MigratedReview | null {
+      const ob = e.payload?.obligation;
+      if (e.kind !== 'waiver' || e.source?.where !== 'migrated' || typeof ob !== 'string') return null;
+      // The journey keys its state by the unit name it was given: `<name>`, or the catalog id for api units.
+      const slugs = new Set([scope.split('/').pop() ?? '', reportSlug(scope.replace(/^(screens|flows)\//, ''))]);
+      let unvouched: MigratedReview | null = null;
+      for (const slug of slugs) {
+        const h = historyOf(`.sungen/journey/${slug}.state.json`);
+        if (!holds(h.head, e, ob)) continue;
+        const review = introducedAt(h, e, ob, scope, shallow);
+        if (review?.at) return { at: review.at, notImported: bounds.notImported(slug, e, review.at) };
+        unvouched = unvouched ?? review;
+      }
+      return unvouched;
+    },
+  };
 }

package/src/harness/journey.ts

@@ -20,8 +20,9 @@ import { readTextFile } from './read-text';
 import { assertNoPendingMigration } from '../basis/migration-sentinel';
 import { commitWaiverSync, planWaiverSync, recordWaiver, untrustedWaiverText } from '../decisions/legacy-waiver-migration';
 import { DecisionConflictError } from '../decisions/append-decision';
+import { gitUserName } from '../decisions/decision-source';
 import { resolveRule } from './gates/resolve-rule';
-import { applyAuditOverrides, decisionFindingText, DecisionGateFinding, ignoredOverrideText, journeyDecisionFindings, readJourneyAudit, unitOverrides } from './gates/journey-gate-inputs';
+import { applyAuditOverrides, decisionFindingText, DecisionGateFinding, ignoredOverrideText, journeyDecisionFindings, OBLIGATION_RULE, readJourneyAudit, unitOverrides } from './gates/journey-gate-inputs';
 import { IN_RUN_RULE, uncommittedReleaseDecisions } from './gates/in-run-decision-check';
 import { PROJECT_SCOPE } from '../decisions/decision-file';
 
@@ -85,6 +86,26 @@ function extractAnchor(text: string): Anchor {
 
 const SAT = 0.8; // axis at/above this = satisfied (below = needs-work)
 
+/**
+ * OB-coverage IS the audit's viewpoint gate (#934): the registry maps it to `audit.viewpoint-coverage`,
+ * whose condition is "no critical theme missing or shallow" (audit-gate-terms.ts). The coverage
+ * percentage alone can read 83% with a critical theme missing, so a gap the rule blocks on keeps the
+ * obligation open and names the themes. An override the audit applied is credited later by
+ * applyAuditOverrides — journey never re-applies one, so the rule is resolved from the catalog here.
+ */
+function coverageObligation(coverage: number | undefined, audit: any): Obligation {
+  const id = 'OB-coverage';
+  const title = 'Viewpoint coverage';
+  const pct = coverage === undefined ? '' : `${Math.round(coverage * 100)}% (need ${Math.round(SAT * 100)}%) — `;
+  const gaps: Array<{ theme?: unknown; status?: unknown }> = Array.isArray(audit.gate?.gaps) ? audit.gate.gaps : [];
+  if (gaps.length && resolveRule(OBLIGATION_RULE[id]).blocking) {
+    const themes = gaps.map((g) => `${String(g.theme)} (${g.status === 'shallow' ? 'shallow' : 'missing'})`).join(', ');
+    return { id, title, status: 'needs-work', detail: `${pct}critical theme(s) not covered: ${themes} — the audit's viewpoint gate fails on them` };
+  }
+  const status: ObStatus = coverage === undefined ? 'pending' : coverage >= SAT ? 'satisfied' : 'needs-work';
+  return { id, title, status, detail: `${pct}critical themes covered` };
+}
+
 function computeFresh(projectRoot: string, unit: string): JourneyReport {
   const slug = reportSlug(unit);
   // T3: the report is an output — read through the checks; stale or untrusted counts as never audited.
@@ -123,7 +144,7 @@ function computeFresh(projectRoot: string, unit: string): JourneyReport {
   });
 
   obligations.push(ob('OB-spec', 'Spec readiness', ax.specFR, 1, 'FR/sections sufficient to design from'));
-  obligations.push(ob('OB-coverage', 'Viewpoint coverage', ax.coverage, SAT, 'critical themes covered'));
+  obligations.push(coverageObligation(ax.coverage, audit));
   obligations.push(ob('OB-depth', 'Assertion depth', ax.businessDepth, depthThreshold, 'business-critical scenarios assert data'));
   obligations.push(ob('OB-trace', 'Traceability', ax.taxonomy ?? ax.traceability, SAT, 'scenarios trace to viewpoints'));
 
@@ -180,7 +201,8 @@ function computeFresh(projectRoot: string, unit: string): JourneyReport {
 // ---------------- S2: writable lifecycle — persisted waivers + reconcile ----------------
 
 // Waivers live in the decision layer (DOS-13.5); this file keeps a dual-written copy for one release.
-interface Signoff { by?: string; at: string; auditHashAtSignoff: string; }   // S5 — stays here in P0
+/** S5 — stays here in P0. `by` is who signs (--by, else the git user); `recordedBy` the git user when --by differs. */
+interface Signoff { by?: string; recordedBy?: string; at: string; auditHashAtSignoff: string; }
 interface JourneyState { unit: string; auditHash: string; waivers: Record<string, unknown>; signoff?: Signoff; }
 
 function statePath(projectRoot: string, slug: string): string {
@@ -221,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);
@@ -228,43 +296,52 @@ 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;
-    report.needsYou.unshift({ text: untrustedWaiverText(unit, slug, title, u), anchor: { vpId: 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 } });
   }
 
   for (const ob of report.obligations) {
     const w = sync.waivers[ob.id];
     if (!w) continue;
+    // A waiver recorded before `--waive` refused this obligation never opens it (review W1).
+    const ignored = unwaivableWhy(ob.id, unit);
+    if (ignored) { report.needsYou.unshift({ text: ignoredWaiverText(ob.id, ignored, w.reason), anchor: { vpId: ob.id } }); continue; }
     if (w.auditHashAtWaive === curHash) {
       ob.status = 'waived';
       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 : ''} at ${state.signoff.at}`;
+      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 } });
@@ -273,6 +350,42 @@ export function runJourney(projectRoot: string, unit: string): JourneyReport {
   return report;
 }
 
+/** The single human gate (DOS §3.4, S5): given with `--signoff`, never waived (#936). */
+export const SIGNOFF_OBLIGATION = 'OB-signoff';
+export const signoffCommand = (unit: string): string => `sungen journey --screen ${unit} --signoff --by "<name>"`;
+
+/** "Never audited" (T3): a unit is measured by `sungen audit`, never waived through (review W2). */
+export const CREATE_OBLIGATION = 'OB-create';
+
+/** Why a waiver can never accept `obId` (and what does instead), or null when it can. */
+function unwaivableWhy(obId: string, unit: string): string | null {
+  if (obId === SIGNOFF_OBLIGATION) return `sign-off is given with --signoff, never waived (${signoffCommand(unit)})`;
+  if (obId === CREATE_OBLIGATION) return `an unaudited unit cannot be waived through — re-run \`sungen audit --screen ${unit}\``;
+  return null;
+}
+
+/** The review-queue line for a recorded waiver the board does not honour. */
+const ignoredWaiverText = (obId: string, why: string, reason: string): string => `⚠️ waiver on ${obId} ignored: ${why}. Was: ${reason}`;
+
+/**
+ * Throws unless `obId` is an obligation of the board that a waiver can accept. Refused in every state,
+ * each with what does it instead: OB-signoff (before any audit it is not on the board, after one a
+ * waiver would let the human gate be waived away) and OB-create (an unaudited unit would pass every
+ * gate on a waiver; the audit measures it).
+ */
+export function assertWaivable(report: JourneyReport, unit: string, obId: string): void {
+  if (obId === SIGNOFF_OBLIGATION) {
+    throw new Error(`${SIGNOFF_OBLIGATION} is the human sign-off — it is given, not waived. Once every other obligation is satisfied or waived, a human runs: ${signoffCommand(unit)}`);
+  }
+  if (obId === CREATE_OBLIGATION) {
+    throw new Error(`${CREATE_OBLIGATION} means the unit has no audit that counts — an unaudited unit cannot be waived through. Run: sungen audit --screen ${unit}`);
+  }
+  const valid = report.obligations.map((o) => o.id).filter((id) => id !== SIGNOFF_OBLIGATION && id !== CREATE_OBLIGATION);
+  if (!valid.includes(obId)) {
+    throw new Error(`Unknown obligation "${obId}". Valid: ${valid.join(', ') || `none — the unit has no audit that counts; run sungen audit --screen ${unit}`}`);
+  }
+}
+
 /**
  * Waive an obligation — REQUIRES a reason (anti-amnesia: a waiver leaves a recorded "why").
  * Records the current evidence cursor so reconcile can invalidate it if the audit changes.
@@ -283,10 +396,7 @@ export function waive(projectRoot: string, unit: string, obId: string, reason: s
   }
   const slug = reportSlug(unit);
   const fresh = runJourney(projectRoot, unit);   // stops on a pending migration; imports legacy waivers first
-  const valid = fresh.obligations.map((o) => o.id);
-  if (!valid.includes(obId)) {
-    throw new Error(`Unknown obligation "${obId}". Valid: ${valid.join(', ')}`);
-  }
+  assertWaivable(fresh, unit, obId);
   const given = { reason: reason.trim(), at: new Date().toISOString(), auditHashAtWaive: auditHashOf(projectRoot, slug) };
   recordWaiver(projectRoot, unit, obId, given);   // DOS-13.5: the decision layer is the record …
   return runJourney(projectRoot, unit);           // … and runJourney dual-writes it to the legacy file
@@ -297,8 +407,8 @@ export function waive(projectRoot: string, unit: string, obId: string, reason: s
  * obligation is satisfied or waived (you cannot sign off an unclean suite). Records who/when +
  * the evidence cursor; reconcile invalidates it (stale → re-review) if the suite later changes.
  */
-export function signoff(projectRoot: string, unit: string, by?: string): JourneyReport {
-  const before = runJourney(projectRoot, unit);
+/** Throws unless the board may be signed off: no decision problem, every other obligation accepted. */
+export function assertCanSignOff(before: JourneyReport): void {
   const blockers = before.obligations.filter((o) => o.id !== 'OB-signoff' && !accepted(o.status));
   if (before.decisionFindings?.length) {
     throw new Error(`Cannot sign off — ${before.decisionFindings.length} decision problem(s): ${before.decisionFindings.map((f) => `${f.rule} ${f.path}`).join(', ')}.`);
@@ -306,10 +416,26 @@ export function signoff(projectRoot: string, unit: string, by?: string): Journey
   if (blockers.length) {
     throw new Error(`Cannot sign off — still open: ${blockers.map((b) => b.id).join(', ')}. Fix, or waive each with a reason, first.`);
   }
+}
+
+/** Who signs off: `--by`, else the git user; throws when neither names anyone (never `by: unknown`). */
+export function signoffSigner(projectRoot: string, unit: string, by?: string): { signer: string; gitUser: string } {
+  const gitUser = gitUserName(projectRoot);
+  const signer = by?.trim() || gitUser;
+  if (signer === 'unknown') {
+    throw new Error(`Cannot sign off — no git user.name is set and no --by was given, so the sign-off would name nobody. Say who signs: ${signoffCommand(unit)}`);
+  }
+  return { signer, gitUser };
+}
+
+export function signoff(projectRoot: string, unit: string, by?: string): JourneyReport {
+  // Attribution is not self-declared (review item 4): the git user is always on the record.
+  const { signer, gitUser } = signoffSigner(projectRoot, unit, by);
+  assertCanSignOff(runJourney(projectRoot, unit));
   const slug = reportSlug(unit);
   const sp = statePath(projectRoot, slug);
   const state = loadState(sp) || { unit, auditHash: '', waivers: {} };
-  state.signoff = { by, at: new Date().toISOString(), auditHashAtSignoff: auditHashOf(projectRoot, slug) };
+  state.signoff = { by: signer, ...(signer !== gitUser ? { recordedBy: gitUser } : {}), at: new Date().toISOString(), auditHashAtSignoff: auditHashOf(projectRoot, slug) };
   saveState(sp, state);
   return runJourney(projectRoot, unit);
 }
@@ -333,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');
@@ -432,7 +578,14 @@ export function renderGate(v: GateVerdict): string {
   if (v.blockers.length) {
     L.push(v.phaseOverriddenBy ? '  Open obligations:' : '  Blocking obligations (must be satisfied or explicitly waived):');
     for (const b of v.blockers) L.push(`   • ${b.id} ${b.title} — ${b.detail}`);
-    L.push('  → Self-correct (repair / run-test), or `sungen journey --screen ' + v.unit + ' --waive <OB> --reason "..."` if accepted.');
+    // Name what each kind of blocker takes (#936): never offer to waive the sign-off or "never audited".
+    const waivable = v.blockers.map((b) => b.id).filter((id) => id.startsWith('OB-') && id !== SIGNOFF_OBLIGATION && id !== 'OB-create');
+    if (waivable.length) {
+      L.push(`  → Self-correct (repair / run-test), or, if accepted, waive with a reason: \`sungen journey --screen ${v.unit} --waive ${waivable.length === 1 ? waivable[0] : `<${waivable.join('|')}>`} --reason "..."\`.`);
+    }
+    if (v.blockers.some((b) => b.id === SIGNOFF_OBLIGATION)) {
+      L.push(`  → Human sign-off: once everything else is satisfied or waived, a human runs \`${signoffCommand(v.unit)}\`.`);
+    }
   } else {
     L.push('  All required obligations satisfied' + (v.waivedCredit.length ? ` (${v.waivedCredit.length} accepted via waiver)` : '') + '.');
   }

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';
@@ -27,6 +29,7 @@ import {
   countFailedResults, countScenarios, hasDeliverableFor, hasResolvedSelector, isCompiled, readIfExists, unitResultFiles,
 } from '../graph/unit-artifact-probes';
 import { AuditNotCounted, ContractFacts, ContractSummary, readContractFacts, readTrustedAudit } from '../graph/unit-state-facts';
+import { ResultsFreshness, resultsFreshness } from '../graph/unit-results-freshness';
 
 export interface NextStep {
   /** The command to run, as the operator would type it. */
@@ -89,7 +92,22 @@ export interface UnitState {
   contract?: ContractSummary;
   /** Per-test-case state (DOS-11.1); absent when not read from disk or unreadable. */
   testCases?: TestCaseState[];
+  /** 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;
+  /** The canonical command of that blocking step (#966) — what clears the hold. */
+  humanActionsHeldByCommand?: string;
 }
 
 export interface ReadUnitStateOptions {
@@ -162,7 +180,17 @@ export function readUnitState(
     state.testCases = testCaseStates(projectRoot, unit, { unitDir, auditFindings: state.audit?.findings ?? [] })
       .map((tc) => (contract?.cases.has(tc.id) ? { ...tc, contract: contract.cases.get(tc.id) } : tc));
   } catch { /* an unparseable .feature — the unit-level nodes still answer, as before test-case state */ }
+  try {
+    const results = resultsFreshness(projectRoot, unitDir, unit);
+    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;
+  if (graph.heldByCommand) state.humanActionsHeldByCommand = graph.heldByCommand;
   return state;
 }
 
@@ -174,3 +202,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;
+}