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

package/src/harness/journey.ts

@@ -17,8 +17,17 @@ import * as path from 'path';
 import * as crypto from 'crypto';
 import { reportSlug } from './unit-paths';
 import { readTextFile } from './read-text';
-
-export type ObStatus = 'satisfied' | 'needs-work' | 'pending' | 'waived';
+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, 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';
+
+/** `overridden`: the audit recorded a gate-override on the obligation's rule (OES-11.2) — accepted like a waiver. */
+export type ObStatus = 'satisfied' | 'needs-work' | 'pending' | 'waived' | 'overridden';
 
 export interface Obligation {
   id: string;
@@ -26,6 +35,7 @@ export interface Obligation {
   status: ObStatus;
   detail: string;
   waivedReason?: string;   // S2 — set when the QA explicitly waived this obligation
+  overriddenBy?: string;   // P0 — the gate-override decision the audit applied to this obligation's rule
 }
 
 /** S5 — a parsed anchor so an IDE can jump straight to what needs review. */
@@ -42,6 +52,10 @@ export interface JourneyReport {
   obligations: Obligation[];
   needsYou: ReviewItem[];           // S5 — the review queue: human-judgment findings, each with an anchor
   nextSuggested: string;
+  /** T3 — set when an audit report exists but does not count (stale or untrusted). */
+  auditNotCounted?: string;
+  /** Decision files that do not verify, edited committed entries, rejected overrides — hard, block the gate. */
+  decisionFindings?: DecisionGateFinding[];
 }
 
 function readJSON(p: string): any {
@@ -72,9 +86,33 @@ 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);
-  const audit = readJSON(path.join(projectRoot, '.sungen', 'reports', `${slug}-audit.json`));
+  // T3: the report is an output — read through the checks; stale or untrusted counts as never audited.
+  const read = readJourneyAudit(projectRoot, unit);
+  const notCountedReason = read.notCountedReason;
+  // The verifier checked the top-level keys and types; nested fields are read defensively below, as before.
+  const audit = read.audit as any;
   const phases = readLedgerPhases(path.join(projectRoot, '.sungen', 'ledger', `${slug}.jsonl`));
 
   const from: string[] = [];
@@ -89,10 +127,11 @@ function computeFresh(projectRoot: string, unit: string): JourneyReport {
 
   if (!audit) {
     // Nothing measured yet — the journey hasn't really begun.
-    obligations.push({ id: 'OB-create', title: 'Generate test cases', status: 'pending', detail: 'No audit report yet — run /sungen:create-test.' });
+    obligations.push({ id: 'OB-create', title: 'Generate test cases', status: 'pending', detail: notCountedReason ?? 'No audit report yet — run /sungen:create-test.' });
     return {
-      unit, generatedFrom: from, youAreHere, phasesDone: phases, gateStatus: null, score: null,
-      obligations, needsYou, nextSuggested: 'Run `/sungen:create-test ' + unit + '` to begin.',
+      unit, generatedFrom: from, youAreHere, phasesDone: phases, gateStatus: null, score: null, obligations, needsYou,
+      nextSuggested: notCountedReason ?? 'Run `/sungen:create-test ' + unit + '` to begin.',
+      ...(notCountedReason ? { auditNotCounted: notCountedReason } : {}),
     };
   }
 
@@ -105,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'));
 
@@ -116,6 +155,8 @@ function computeFresh(projectRoot: string, unit: string): JourneyReport {
     status: autoPending ? 'needs-work' : 'satisfied',
     detail: autoPending ? `${audit.automatableManual.automatable} @manual scenario(s) a driver could automate` : 'no capability-pending automatable cases',
   });
+  // What the audit already applied — never re-applied here, and only while that override is in force.
+  const ignored = applyAuditOverrides(obligations, audit, unitOverrides(projectRoot, unit).inForce);
 
   // Needs-you: the review queue. Prefer PRECISE per-scenario anchors from audit's structured
   // depth data — each shallow business-critical scenario carries its own VP id — over regex-parsing
@@ -128,6 +169,7 @@ function computeFresh(projectRoot: string, unit: string): JourneyReport {
       anchor: extractAnchor(s.name),
     });
   }
+  for (const g of ignored) needsYou.push({ text: ignoredOverrideText(g), anchor: {} });
   const haveStructuredDepth = shallowBC.length > 0;
   for (const f of (audit.findings || [])) {
     if (!isHumanFinding(f)) continue;
@@ -143,7 +185,7 @@ function computeFresh(projectRoot: string, unit: string): JourneyReport {
   });
 
   // Next suggested = first non-satisfied obligation; if all satisfied but run-test not done → run.
-  const firstGap = obligations.find((o) => o.status !== 'satisfied' && o.id !== 'OB-signoff');
+  const firstGap = obligations.find((o) => o.status !== 'satisfied' && o.status !== 'overridden' && o.id !== 'OB-signoff');
   let nextSuggested: string;
   if (firstGap) nextSuggested = `Repair "${firstGap.title}" (${firstGap.detail}).`;
   else if (!ran('run')) nextSuggested = `Quality satisfied — run \`/sungen:run-test ${unit}\`.`;
@@ -158,9 +200,10 @@ function computeFresh(projectRoot: string, unit: string): JourneyReport {
 
 // ---------------- S2: writable lifecycle — persisted waivers + reconcile ----------------
 
-interface Waiver { reason: string; at: string; auditHashAtWaive: string; }
-interface Signoff { by?: string; at: string; auditHashAtSignoff: string; }   // S5
-interface JourneyState { unit: string; auditHash: string; waivers: Record<string, Waiver>; signoff?: Signoff; }
+// Waivers live in the decision layer (DOS-13.5); this file keeps a dual-written copy for one release.
+/** 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 {
   return path.join(projectRoot, '.sungen', 'journey', `${slug}.state.json`);
@@ -176,9 +219,14 @@ function saveState(p: string, s: JourneyState): void {
   fs.writeFileSync(p, JSON.stringify(s, null, 2), 'utf-8');
 }
 
+/** An obligation that does not block: met, waived by a human, or overridden by the audit's gate-override. */
+const accepted = (s: ObStatus): boolean => s === 'satisfied' || s === 'waived' || s === 'overridden';
+
 /** Recompute nextSuggested AFTER waivers are applied (a waived obligation is not a gap). */
 function computeNext(r: JourneyReport, unit: string): string {
-  const gap = r.obligations.find((o) => o.status !== 'satisfied' && o.status !== 'waived' && o.id !== 'OB-signoff');
+  const bad = r.decisionFindings?.[0];
+  if (bad) return `Resolve ${r.decisionFindings!.length} decision problem(s) first — ${bad.rule} on ${bad.path}.`;
+  const gap = r.obligations.find((o) => !accepted(o.status) && o.id !== 'OB-signoff');
   if (gap) return `Repair "${gap.title}" (${gap.detail}).`;
   if (!r.phasesDone.some((s) => s === 'run' || s.startsWith('run'))) return `Quality satisfied — run \`/sungen:run-test ${unit}\`.`;
   return `All obligations satisfied/waived — review the ${r.needsYou.length} queued item(s), then sign off & deliver.`;
@@ -190,41 +238,154 @@ function computeNext(r: JourneyReport, unit: string): string {
  *  - an active waiver (evidence unchanged) sets status='waived' (carries the reason);
  *  - a STALE waiver (audit changed since it was waived) is re-surfaced for re-decision (anti-amnesia).
  * Then persist the current evidence cursor.
+ * Waivers in force come from the decision layer; legacy waivers that match git HEAD are imported once,
+ * others are UNTRUSTED (not counted, listed for a human), and the result is dual-written back.
+ * 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);
   const sp = statePath(projectRoot, slug);
   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 } });
+  }
 
   for (const ob of report.obligations) {
-    const w = state.waivers[ob.id];
+    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 };
+  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 } });
+  }
   report.nextSuggested = computeNext(report, unit);
-  saveState(sp, { unit, auditHash: curHash, waivers: state.waivers, signoff: state.signoff });
   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.
@@ -234,16 +395,11 @@ export function waive(projectRoot: string, unit: string, obId: string, reason: s
     throw new Error('A reason is required to waive (anti-amnesia: a waiver must record WHY). Use --reason "...".');
   }
   const slug = reportSlug(unit);
-  const fresh = computeFresh(projectRoot, unit);
-  const valid = fresh.obligations.map((o) => o.id);
-  if (!valid.includes(obId)) {
-    throw new Error(`Unknown obligation "${obId}". Valid: ${valid.join(', ')}`);
-  }
-  const sp = statePath(projectRoot, slug);
-  const state = loadState(sp) || { unit, auditHash: '', waivers: {} };
-  state.waivers[obId] = { reason: reason.trim(), at: new Date().toISOString(), auditHashAtWaive: auditHashOf(projectRoot, slug) };
-  saveState(sp, state);
-  return runJourney(projectRoot, unit);
+  const fresh = runJourney(projectRoot, unit);   // stops on a pending migration; imports legacy waivers first
+  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
 }
 
 /**
@@ -251,27 +407,83 @@ 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);
-  const blockers = before.obligations.filter((o) => o.id !== 'OB-signoff' && o.status !== 'satisfied' && o.status !== 'waived');
+/** 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(', ')}.`);
+  }
   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);
 }
 
-const ICON: Record<ObStatus, string> = { satisfied: '✅', 'needs-work': '⚠️ ', pending: '⏳', waived: '🚫' };
+const UNWRITABLE = new Set(['EACCES', 'EROFS', 'ENOSPC', 'EPERM']);
+
+/**
+ * Write a DERIVED journey file (board, report, roll-up). Best-effort by contract (DOS-13.3): a read-only
+ * or full checkout still shows the board — the file is skipped and null returned; any other error throws.
+ */
+export function writeJourneyFileBestEffort(file: string, text: string): string | null {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, text, 'utf-8');
+    return file;
+  } catch (err) {
+    if (UNWRITABLE.has((err as NodeJS.ErrnoException)?.code ?? '')) return null;
+    throw err;
+  }
+}
+
+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');
@@ -308,6 +520,10 @@ export interface GateVerdict {
   required: string[];
   blockers: { id: string; title: string; detail: string }[];
   waivedCredit: { id: string; title: string }[]; // required obligations accepted via an explicit waiver
+  /** Required obligations accepted because the audit applied a gate-override to their rule. */
+  overriddenCredit?: { id: string; title: string; by: string }[];
+  /** The phase rule itself was lowered by this gate-override: the open obligations do not halt. */
+  phaseOverriddenBy?: string;
 }
 
 const PHASE_REQUIRED: Record<GatePhase, string[]> = {
@@ -319,25 +535,57 @@ const PHASE_REQUIRED: Record<GatePhase, string[]> = {
   deliver: ['OB-spec', 'OB-coverage', 'OB-depth', 'OB-trace', 'OB-automation', 'OB-signoff'],
 };
 
+/** The catalog rule each phase boundary halts by (OES-11.2): soft, so a reasoned override may lower it. */
+const PHASE_RULE: Record<GatePhase, string> = { create: 'journey.phase-create', run: 'journey.phase-run', deliver: 'journey.phase-deliver' };
+
 export function runGate(projectRoot: string, unit: string, phase: GatePhase): GateVerdict {
   const r = runJourney(projectRoot, unit);
   const required = PHASE_REQUIRED[phase];
-  const reqObs = r.obligations.filter((o) => required.includes(o.id));
-  const blockers = reqObs
-    .filter((o) => o.status !== 'satisfied' && o.status !== 'waived')
-    .map((o) => ({ id: o.id, title: o.title, detail: o.detail }));
+  // T3: a unit never audited (or whose report does not count) is never clean — OB-create blocks every phase.
+  const reqObs = r.obligations.filter((o) => required.includes(o.id) || o.id === 'OB-create');
+  const asBlocker = (o: Obligation) => ({ id: o.id, title: o.title, detail: o.detail });
+  // Never audited is not something a lowered phase rule may wave through (review M4).
+  const neverAudited = reqObs.filter((o) => o.id === 'OB-create' && !accepted(o.status)).map(asBlocker);
+  const open = reqObs.filter((o) => o.id !== 'OB-create' && !accepted(o.status)).map(asBlocker);
+  const overrides = unitOverrides(projectRoot, unit);
+  // Decision problems are hard rules: no phase override lowers them. At the release boundary an
+  // override, waiver or approval git HEAD does not hold is refused too (decision.in-run, review H1).
+  const scopes = [PROJECT_SCOPE, ...(overrides.unitScope ? [overrides.unitScope] : [])];
+  const hard = [
+    ...(r.decisionFindings ?? []).filter((f) => resolveRule(f.rule).blocking)
+      .map((f) => ({ id: f.rule, title: 'Decision integrity', detail: `${f.path} — ${f.message}` })),
+    ...(phase === 'deliver' && resolveRule(IN_RUN_RULE).blocking ? uncommittedReleaseDecisions(projectRoot, scopes) : [])
+      .map((d) => ({ id: IN_RUN_RULE, title: 'Decision not reviewed', detail: `${d.kind} ${d.id} (${d.path}) — ${d.why.join('; ')}` })),
+    ...neverAudited,
+  ];
+  const phaseRule = resolveRule(PHASE_RULE[phase], overrides.context);
+  const blockers = [...hard, ...open];
+  const halt = hard.length > 0 || (open.length > 0 && phaseRule.blocking);
   const waivedCredit = reqObs.filter((o) => o.status === 'waived').map((o) => ({ id: o.id, title: o.title }));
-  return { unit, phase, status: blockers.length ? 'halt' : 'pass', required, blockers, waivedCredit };
+  const overriddenCredit = reqObs.filter((o) => o.status === 'overridden').map((o) => ({ id: o.id, title: o.title, by: o.overriddenBy ?? '' }));
+  return {
+    unit, phase, status: halt ? 'halt' : 'pass', required, blockers, waivedCredit,
+    ...(overriddenCredit.length ? { overriddenCredit } : {}),
+    ...(open.length && phaseRule.overriddenBy ? { phaseOverriddenBy: phaseRule.overriddenBy } : {}),
+  };
 }
 
 export function renderGate(v: GateVerdict): string {
   const L: string[] = [];
   L.push('');
   L.push(`━━━ Gate: ${v.unit} @ phase "${v.phase}" → ${v.status === 'pass' ? '✅ PASS' : '⛔ HALT'} ━━━`);
+  if (v.phaseOverriddenBy) L.push(`  Phase rule lowered by ${v.phaseOverriddenBy}: open obligations are advisory (decision problems still block).`);
   if (v.blockers.length) {
-    L.push('  Blocking obligations (must be satisfied or explicitly waived):');
+    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)` : '') + '.');
   }
@@ -388,7 +636,7 @@ export function rollupJourney(projectRoot: string): UnitSummary[] {
     const r = runJourney(projectRoot, unit);
     const signedOff = r.obligations.find((o) => o.id === 'OB-signoff')?.status === 'satisfied';
     const obligationsOpen = r.obligations.filter(
-      (o) => o.id !== 'OB-signoff' && o.status !== 'satisfied' && o.status !== 'waived',
+      (o) => o.id !== 'OB-signoff' && !accepted(o.status),
     ).length;
     return {
       unit, kind, score: r.score, gateStatus: r.gateStatus, youAreHere: r.youAreHere,