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

package/src/harness/gates/audit-report-verification.ts

@@ -6,50 +6,77 @@
  *   status       `gateStatus` is PASS|FAIL and agrees with the integer `exitCode` (0 | 2)
  *   inputs       `inputsHash` equals the hash of today's inputs + decisions (audit-input-hash.ts)
  *   decisions    `decisionsHash` equals today's — otherwise the audit is stale: re-audit
+ *   rules        `provenance.catalogHash` and `provenance.rulesHash` are the running sungen's — other
+ *                catalogs or another AUDIT_RULES_VERSION scored it (a 3.2 PASS can be a 3.3 FAIL on the
+ *                same files): stale, re-audit. Missing → stale (fail closed). The package VERSION
+ *                alone is not a reason: a newer sungen with the same rules gives the same verdict (W4)
  *   verdict      gateStatus re-evaluated from the report's own terms (audit-gate-terms.ts) under the
  *                overrides in force — a flipped gateStatus + exitCode is `verdict-mismatch` (tester m1)
  * Anything else counts as NEVER AUDITED, not as clean; only an explicit `gateStatus: PASS` passes.
  * These checks are anti-STALENESS and anti-casual-tamper, NOT anti-forgery: a writer of audit.json can
  * recompute the hashes, and one who rewrites every finding, gap and verdict is out of scope here.
  *
- * Legacy (DOS-11.4): a report written before these fields existed carries none of exitCode /
- * inputsHash / decisionsHash / gateOverrides. It is still read — with the note "legacy audit, inputs
- * unverified" — while no gate-override can apply to the unit and no input file is newer than it
- * (mtime, review M1); otherwise it is stale. A report carrying SOME of the fields is malformed.
+ * Legacy (DOS-11.4, #933): a report written before these fields existed carries none of exitCode /
+ * inputsHash / decisionsHash / gateOverrides, so nothing in it can vouch for today's inputs. It reads
+ * STALE — one `sungen audit` records a current one. (It used to count while no input file was newer:
+ * a fresh checkout gives every file the checkout's mtime, so that proved nothing and an old PASS was
+ * trusted.) A legacy report claiming a PASS its own fields contradict is invalid. A report carrying
+ * SOME of the fields is malformed.
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import { resolveUnitCandidates } from '../../cli/resolve-unit';
 import { reportSlug } from '../unit-paths';
-import { auditInputFiles, auditInputsHash } from './audit-input-hash';
+import { getProvenance } from '../provenance';
+import { auditInputsHash } from './audit-input-hash';
 import { AUDIT_EXIT_CODE } from './audit-gate-verdict';
 import { recomputeAuditGateStatus, termSourcesOf } from './audit-gate-terms';
 import { EMPTY_DECISIONS_HASH } from './decisions-hash';
 import { loadUnitGateOverrides, unitScopeOfDir, UnitGateOverrides } from './unit-gate-overrides';
 
-export type AuditState = 'absent' | 'verified' | 'legacy' | 'stale' | 'invalid';
+export type AuditState = 'absent' | 'verified' | 'stale' | 'invalid';
 export type AuditProblemCode = 'unreadable' | 'unknown-key' | 'bad-type' | 'partial-fields' | 'status-exit-mismatch'
-  | 'unit-unresolved' | 'decisions-changed' | 'inputs-changed' | 'legacy-with-overrides' | 'legacy-inputs-newer' | 'verdict-mismatch';
+  | 'unit-unresolved' | 'decisions-changed' | 'inputs-changed' | 'rules-changed' | 'legacy-with-overrides' | 'legacy-unverified' | 'verdict-mismatch';
 
 export interface AuditVerification {
   state: AuditState;
   problems: Array<{ code: AuditProblemCode; message: string }>;
-  /** Caveats on a report that counts (a legacy report's inputs are unverified). */
+  /** Caveats on a report that counts. */
   notes: string[];
-  /** The parsed report — only when it counts (verified or legacy). */
+  /** The parsed report — only when it counts (verified). */
   report: Record<string, unknown> | null;
   path: string;
   /** Today's decisionsHash for the unit (what a fresh audit would record). */
   currentDecisionsHash: string;
 }
 
-export const LEGACY_AUDIT_NOTE = 'legacy audit, inputs unverified — written before inputsHash existed; re-run `sungen audit` to record it';
+/** A string field of the report's provenance, or null when it does not say. */
+function provenanceField(r: Record<string, unknown>, key: 'sungenVersion' | 'catalogHash' | 'rulesHash'): string | null {
+  const v = r.provenance && typeof r.provenance === 'object' ? (r.provenance as Record<string, unknown>)[key] : undefined;
+  return typeof v === 'string' && v ? v : null;
+}
+const writtenBy = (r: Record<string, unknown>): string | null => provenanceField(r, 'sungenVersion');
+
+export interface RulesStamp { catalogHash: string | null; rulesHash: string | null }
+/** What getProvenance writes when it could not read a catalog — never a match, on either side. */
+const UNKNOWN = 'unknown';
+
+/**
+ * Why the rules a report was scored by (`was`) cannot be taken as this sungen's (`now`), or null when
+ * they are the same KNOWN rules. Missing or `unknown` on either side is a problem (fail closed):
+ * unknown == unknown proves nothing.
+ */
+export function rulesProblem(was: RulesStamp, now: RulesStamp): string | null {
+  if (!was.catalogHash || !was.rulesHash) return 'it does not say which rules scored it (no provenance.catalogHash / rulesHash)';
+  if ([was.catalogHash, was.rulesHash].includes(UNKNOWN)) return 'the rules that scored it are unknown (provenance says "unknown")';
+  if (!now.catalogHash || !now.rulesHash || [now.catalogHash, now.rulesHash].includes(UNKNOWN)) return 'this sungen cannot read its own rules (catalog or rules hash unknown), so it trusts no report';
+  if (was.catalogHash === now.catalogHash && was.rulesHash === now.rulesHash) return null;
+  return `scored by other rules (catalog ${was.catalogHash} · rules ${was.rulesHash}) than this sungen's (catalog ${now.catalogHash} · rules ${now.rulesHash})`;
+}
 
-/** A legacy report is stale once an input it judged is newer than the report itself (mtime). */
-function newerLegacyInput(reportFile: string, unitDir: string | null, unit: string): string | null {
-  if (!unitDir) return null;
-  const at = fs.statSync(reportFile).mtimeMs;
-  return auditInputFiles(unitDir, unit).find((f) => fs.statSync(f).mtimeMs > at) ?? null;
+/** Why a current-format report was judged by other rules than this sungen's, or null when the same. */
+function otherRules(r: Record<string, unknown>): string | null {
+  return rulesProblem({ catalogHash: provenanceField(r, 'catalogHash'), rulesHash: provenanceField(r, 'rulesHash') }, getProvenance());
 }
 
 type JsonKind = 'string' | 'number' | 'boolean' | 'object' | 'array';
@@ -124,17 +151,18 @@ export function verifyAuditReport(projectRoot: string, unit: string): AuditVerif
   if (schema.length) return result('invalid', schema);
 
   if (!P0_KEYS.some((k) => k in r)) {
-    if (current !== EMPTY_DECISIONS_HASH) {
-      return result('stale', [{ code: 'legacy-with-overrides', message: 'written by an earlier sungen (no decisionsHash) and a gate-override now applies to this unit' }]);
-    }
-    const newer = newerLegacyInput(file, unitDir, unit);
-    if (newer) return result('stale', [{ code: 'legacy-inputs-newer', message: `written by an earlier sungen and ${path.basename(newer)} changed after it` }]);
     // A legacy report predates gateSensorError, so only a stored PASS its own fields contradict is caught.
     const sources = termSourcesOf(r, false);
     if (r.gateStatus === 'PASS' && sources && recomputeAuditGateStatus(sources, overrides) === 'FAIL') return result('invalid', [verdictMismatch(r)]);
-    return result('legacy', [], r, [LEGACY_AUDIT_NOTE]);
+    const by = `written by ${writtenBy(r) ? `sungen ${writtenBy(r)}` : 'an earlier sungen'}`;
+    if (current !== EMPTY_DECISIONS_HASH) {
+      return result('stale', [{ code: 'legacy-with-overrides', message: `${by} (no decisionsHash) and a gate-override now applies to this unit` }]);
+    }
+    return result('stale', [{ code: 'legacy-unverified', message: `${by}, before inputsHash existed — its inputs cannot be verified` }]);
   }
   const stale: AuditVerification['problems'] = [];
+  const rules = otherRules(r);
+  if (rules) stale.push({ code: 'rules-changed', message: `${writtenBy(r) ? `written by sungen ${writtenBy(r)}, ` : ''}${rules}` });
   if (r.decisionsHash !== current) stale.push({ code: 'decisions-changed', message: 'the gate-override decisions changed since this audit' });
   if (!unitDir) return result('invalid', [{ code: 'unit-unresolved', message: `"${unit}" does not name exactly one unit, so the audit's inputs cannot be checked` }]);
   if (r.inputsHash !== auditInputsHash(unitDir, unit, r.decisionsHash as string)) {
@@ -157,8 +185,8 @@ function verdictProblem(r: Record<string, unknown>, overrides: UnitGateOverrides
   return recomputeAuditGateStatus(sources, overrides) === r.gateStatus ? null : verdictMismatch(r);
 }
 
-/** Whether the report may be used at all (verified, or a legacy report no override touches). */
-export const auditCounts = (v: AuditVerification): boolean => v.state === 'verified' || v.state === 'legacy';
+/** Whether the report may be used at all: only a verified one. */
+export const auditCounts = (v: AuditVerification): boolean => v.state === 'verified';
 
 /** Only an explicit `gateStatus: PASS` on a report that counts passes; a score never does. */
 export const auditPassed = (v: AuditVerification): boolean => auditCounts(v) && v.report?.gateStatus === 'PASS';

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

@@ -33,10 +33,10 @@ function auditBox(projectRoot: string, u: ChecklistUnit): ChecklistBox {
   const v = verifyAuditReport(projectRoot, u.unitName);
   if (!auditCounts(v)) return box('audit', 'fail', auditNotCountedReason(v, u.unitName));
   const overall = (v.report?.score as { overall?: number } | undefined)?.overall;
-  const how = v.state === 'legacy' ? 'legacy report, inputs unverified' : "verified against today's inputs";
+  const how = "verified against today's inputs";
   return v.report?.gateStatus === 'PASS'
     ? box('audit', 'pass', `PASS ${overall ?? '?'}/10 — ${how}`)
-    : box('audit', 'fail', `FAIL ${overall ?? '?'}/10 — \`sungen audit\` exits 2 (${how})`);
+    : box('audit', 'fail', `FAIL ${overall ?? '?'}/10 — \`sungen audit\` exits 2 (${how}); an official delivery is blocked until it passes — --preview renders a draft`);
 }
 
 /** The compiler prints progress on stdout; the checklist keeps the delivery output to itself. */

package/src/harness/gates/delivery-decision-gate.ts

@@ -8,12 +8,16 @@
  *   no trusted    no audit report, or one that does not count (stale, invalid, verdict-mismatch):
  *   audit         a real delivery stops and asks for `sungen audit` (owner decision 2026-10-22);
  *                 `--preview` / `--check` go on with a warning — the caller decides (`untrustedAudits`)
+ *   failing       a trusted audit whose verdict is FAIL (`sungen audit` exits 2): the same — a real
+ *   audit         delivery stops, naming the failing gate rules (#935, owner decision); `--preview`
+ *                 renders a DRAFT, `--check` reports it (`failingAudits`)
  * It also hands each target its gate rules (catalog + overrides) for the matrix gates, and the
  * override rows the XLSX may show. With no decision in reach nothing here changes the delivery.
  */
 import { checkDecisionIntegrity, DecisionFinding } from '../../decisions/decision-integrity-check';
 import { PROJECT_SCOPE } from '../../decisions/decision-file';
 import { auditCounts, verifyAuditReport } from './audit-report-verification';
+import { auditGateTerms, termSourcesOf } from './audit-gate-terms';
 import { GateOverrideReport, gateOverrideReports, gateOverrideSummaryLine, InRunAcceptance } from './gate-override-report';
 import { unitsCoveredByScope } from './gate-override-scope';
 import { committedDecisionPaths, hasInRunKindDecisions, inRunDecisions, InRunDecision, IN_RUN_RULE, runStartOf } from './in-run-decision-check';
@@ -35,6 +39,10 @@ export interface DeliveryDecisionGate {
   blocking: string[];
   /** Units with no trusted audit — a real delivery stops on them, --preview / --check warn. */
   untrustedAudits: string[];
+  /** Units whose trusted audit FAILs (#935) — a real delivery stops on them, --preview / --check warn. */
+  failingAudits: string[];
+  /** The unit's audit does not let it be delivered officially (untrusted or FAIL): its render is a DRAFT. */
+  auditDraft(unitDir: string): boolean;
   notes: string[];
   inRun: Array<InRunDecision & { unit: string }>;
   /** The unit's tracked gate rules, for the matrix gates of its targets. */
@@ -48,9 +56,22 @@ export interface DeliveryDecisionGate {
 
 const reachOf = (scope: string | null): string[] => [`qa/decisions/`, ...(scope ? [`qa/${scope}/decisions/`] : [])];
 
+/** The audit gate rules a FAIL report's own terms violate under the unit's overrides, gaps named. */
+function failingGateRules(report: Record<string, unknown>, overrides: UnitGateOverrides): string {
+  const sources = termSourcesOf(report, true);
+  if (!sources) return 'its gate terms';
+  const gaps = (sources.gate.gaps as Array<{ theme?: unknown; status?: unknown }>)
+    .map((g) => `${g.status === 'shallow' ? 'SHALLOW' : 'MISSING'}: ${String(g.theme)}`);
+  const rules = auditGateTerms(sources).filter((t) => !t.holds && resolveRule(t.rule, overrides.context).blocking)
+    .map((t) => (t.rule === 'audit.viewpoint-coverage' && gaps.length ? `${t.rule} (${gaps.join(', ')})` : t.rule));
+  return rules.join(', ') || 'its gate terms';
+}
+
 export function evaluateDeliveryDecisions(projectRoot: string, refs: DeliveryUnitRef[]): DeliveryDecisionGate {
   const blocking: string[] = [];
   const untrustedAudits: string[] = [];
+  const failingAudits: string[] = [];
+  const draftDirs = new Set<string>();
   const notes: string[] = [];
   const inRun: DeliveryDecisionGate['inRun'] = [];
   const units = new Map<string, UnitState>();
@@ -63,10 +84,15 @@ export function evaluateDeliveryDecisions(projectRoot: string, refs: DeliveryUni
       ? (audit.report!.gateOverrides as GateOverrideReport[]).filter((g) => g?.triggered).map((g) => g.rule) : []);
     units.set(ref.unitDir, { ref, resultsPaths: [ref.resultsPath], overrides, rules: trackGateRules(overrides.context), auditTriggered });
     for (const r of overrides.rejected) blocking.push(`${ref.label}: gate.override-rejected — ${r.decisionId} (${r.path}): ${r.reason}`);
+    const flag = /[\\/]qa[\\/]api[\\/]/.test(ref.unitDir) ? '--api' : '--screen';
     if (!auditCounts(audit)) {
       const why = audit.state === 'absent' ? 'no audit report' : `the audit is ${audit.state === 'stale' ? 'stale' : 'not trusted'}: ${audit.problems.map((p) => p.message).join('; ')}`;
-      const flag = /[\\/]qa[\\/]api[\\/]/.test(ref.unitDir) ? '--api' : '--screen';
       untrustedAudits.push(`${ref.label}: ${why} — re-run \`sungen audit ${flag} ${ref.unitName}\``);
+      draftDirs.add(ref.unitDir);
+    } else if (audit.report?.gateStatus !== 'PASS') {
+      const overall = (audit.report?.score as { overall?: number } | undefined)?.overall;
+      failingAudits.push(`${ref.label}: FAIL ${overall ?? '?'}/10 on ${failingGateRules(audit.report!, overrides)} — fix the suite, then re-run \`sungen audit ${flag} ${ref.unitName}\``);
+      draftDirs.add(ref.unitDir);
     }
     for (const n of audit.notes) notes.push(`${ref.label}: ${n}`);
   }
@@ -95,6 +121,8 @@ export function evaluateDeliveryDecisions(projectRoot: string, refs: DeliveryUni
   return {
     blocking,
     untrustedAudits,
+    failingAudits,
+    auditDraft: (dir) => draftDirs.has(dir),
     notes,
     inRun,
     rulesFor: (dir) => units.get(dir)?.rules,

package/src/harness/gates/delivery-decision-step.ts

@@ -16,7 +16,10 @@ export interface DeliveryDecisionStepInput {
   argv: string[];
   io: ConfirmationIO;
   log: (line: string) => void;
-  /** A real export needs a trusted audit per unit (owner decision 2026-10-22); false for --preview / --check. */
+  /**
+   * A real export needs, per unit, a trusted audit (owner decision 2026-10-22) that PASSes (#935);
+   * false for --preview / --check, which go on with a warning (a DRAFT render / a report).
+   */
   requireTrustedAudit: boolean;
 }
 
@@ -29,6 +32,8 @@ export async function runDeliveryDecisionStep(i: DeliveryDecisionStepInput): Pro
     for (const b of gate.blocking) i.log(`  - ${b}`);
     return null;
   }
+  // Every reason to stop is listed before stopping, so one run names all of them (audit and in-run).
+  let blocked = false;
   if (gate.untrustedAudits.length) {
     i.log(i.requireTrustedAudit
       ? `✗ Delivery blocked — ${gate.untrustedAudits.length} unit(s) without a trusted audit (a delivery stands on an audit that matches today's suite):`
@@ -36,10 +41,20 @@ export async function runDeliveryDecisionStep(i: DeliveryDecisionStepInput): Pro
     for (const u of gate.untrustedAudits) i.log(`  - ${u}`);
     if (i.requireTrustedAudit) {
       i.log('  Or render a watermarked draft with --preview.');
-      return null;
+      blocked = true;
     }
   }
-  if (gate.inRun.length === 0) return gate;
+  if (gate.failingAudits.length) {
+    i.log(i.requireTrustedAudit
+      ? `✗ Delivery blocked — ${gate.failingAudits.length} unit(s) whose audit FAILs (\`sungen audit\` exits 2; an official delivery stands on a passing audit):`
+      : `⚠ Rendering ${gate.failingAudits.length} unit(s) whose audit FAILs — a draft, not an official delivery:`);
+    for (const u of gate.failingAudits) i.log(`  - ${u}`);
+    if (i.requireTrustedAudit) {
+      i.log('  Fix the suite and re-run the audit, or render a watermarked draft with --preview.');
+      blocked = true;
+    }
+  }
+  if (gate.inRun.length === 0) return blocked ? null : gate;
   const acceptCommand = formatCommand([...i.argv, '--accept-in-run']);
   if (!i.acceptInRun) {
     i.log(`✗ Delivery blocked — ${gate.inRun.length} decision(s) recorded during the run (${IN_RUN_RULE}, hard):`);
@@ -48,6 +63,7 @@ export async function runDeliveryDecisionStep(i: DeliveryDecisionStepInput): Pro
     i.log(`    ${acceptCommand}`);
     return null;
   }
+  if (blocked) return null;   // nothing to accept on top of a delivery the audit already stops
   try {
     await requireTypedConfirmation({
       what: `deliver with ${gate.inRun.length} decision(s) recorded during the run (${IN_RUN_RULE})`,

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 {
@@ -230,12 +252,16 @@ export function runJourney(projectRoot: string, unit: string): JourneyReport {
   const sync = planWaiverSync(projectRoot, unit, slug, sp, state.waivers);
   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);
+    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;
@@ -250,7 +276,7 @@ export function runJourney(projectRoot: string, unit: string): JourneyReport {
   if (signoffOb && state.signoff) {
     if (state.signoff.auditHashAtSignoff === curHash) {
       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 {
       report.needsYou.unshift({ text: `⚠️ Sign-off is STALE (suite changed since ${state.signoff.at}) — re-review and sign off again.`, anchor: { vpId: 'OB-signoff' } });
     }
@@ -273,6 +299,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 +345,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 +356,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 +365,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);
 }
@@ -432,7 +507,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/provenance.ts

@@ -1,22 +1,110 @@
 /**
- * Provenance stamp for deterministic reports (score-determinism D1).
+ * Provenance stamp for deterministic reports (score-determinism D1), and the RULES the audit's
+ * verdict was judged by (#933, owner decision W4).
  *
- * The audit score is a pure function of the project files + the bundled catalog.
- * Stamping the sungen version + a catalog hash into the report lets two users who
- * get different scores see IMMEDIATELY whether the cause is a version/catalog
- * mismatch (the main residual source of cross-user variance) rather than a real
- * difference in their test design.
+ * The audit score is a pure function of the project files + the bundled catalogs + the scoring
+ * code. Stamping them into the report lets two users who get different scores see IMMEDIATELY
+ * whether the cause is a rules mismatch rather than a real difference in their test design — and
+ * lets `verifyAuditReport` tell a report judged by today's rules from one judged by other rules:
+ *
+ *   sungenVersion   which package wrote it — informational: a newer sungen with the same rules
+ *                   gives the same verdict, so the version alone never makes a report stale
+ *   catalogHash     sha256(universal-viewpoints.yaml), first 12 hex — the viewpoint catalog
+ *   rulesHash       sha256(AUDIT_RULES_VERSION + every catalog file under harness/catalog/ + each
+ *                   bundled driver's sources/catalogs), first 12 hex — everything the verdict
+ *                   depends on that is not the project's own files. No package VERSION is hashed:
+ *                   packages are lockstep-versioned, so a release would stale every report
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as crypto from 'crypto';
 
+/**
+ * The version of the audit's SCORING CODE. Bump it (by one) in the same change whenever what
+ * `runAudit` computes for the same project can change: a sensor, a threshold, a gate term
+ * (audit-gate-terms.ts), the score model or weights, a finding that feeds the verdict, or the
+ * audit sensor of a bundled driver. Every report scored before the bump then reads stale and asks
+ * for one `sungen audit`. Catalog edits (harness/catalog/*.yaml) and bundled-driver changes (their
+ * sources and catalogs are hashed) need no bump.
+ * A release that changes none of these keeps every report trusted across the upgrade.
+ * Enforced by tests/audit/run.ts: its rules lock (tests/audit/audit-rules.lock.json) fails when the
+ * fixtures' audit output changes under an unchanged rules hash. After the bump, re-record it:
+ *   npx tsx tests/audit/run.ts --record-rules-lock
+ */
+export const AUDIT_RULES_VERSION = 1;
+
 export interface Provenance {
   sungenVersion: string;
   catalogHash: string; // sha256(universal-viewpoints.yaml), first 12 hex — the catalog that drives the score
+  rulesHash: string;   // sha256(AUDIT_RULES_VERSION + harness/catalog/*.yaml + bundled drivers), first 12 hex — the verdict's rules
+}
+
+/** A bundled driver as an input of the rules: its package dir, or null when it is not installed. */
+export interface DriverRulesInput { name: string; version?: string; dir: string | null }
+
+/** What is not a driver's rule: dependencies, build output, tests, docs, editor and lock files. */
+const SKIP_DIR = new Set(['node_modules', 'dist', 'tests', 'test', 'coverage']);
+const SKIP_FILE = /^(?:\.|package(?:-lock)?\.json$|tsconfig.*\.json$|.*\.(?:md|tsbuildinfo)$)/;
+
+function driverFiles(root: string, rel = ''): string[] {
+  const out: string[] = [];
+  for (const e of fs.readdirSync(path.join(root, rel), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name, 'en'))) {
+    if (e.name.startsWith('.')) continue;
+    const r = rel ? `${rel}/${e.name}` : e.name;
+    if (e.isDirectory()) { if (!SKIP_DIR.has(e.name)) out.push(...driverFiles(root, r)); }
+    else if (e.isFile() && !SKIP_FILE.test(e.name)) out.push(r);
+  }
+  return out;
+}
+
+/** The package root above a driver's resolved entry file (the dir whose package.json names it). */
+function packageRootOf(entry: string, name: string): string | null {
+  let dir = path.dirname(entry);
+  for (let i = 0; i < 8; i++) {
+    try { if (JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'))?.name === name) return dir; } catch { /* keep walking */ }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
 }
 
+/** Each bundled driver as discovery would load it (project anchor, then core's), or `absent`. */
+export function bundledDriverRulesInputs(): DriverRulesInput[] {
+  // Lazy: discovery pulls the capability registry, which nothing else here needs.
+  const { bundledDriverNames, resolveDriverCopy } = require('../capabilities/discover') as typeof import('../capabilities/discover');
+  return bundledDriverNames().map((name) => {
+    const copy = resolveDriverCopy(name);
+    const dir = copy ? packageRootOf(copy.resolved, name) : null;
+    return { name, version: copy?.version, dir };
+  });
+}
+
+const CATALOG_DIR = path.join(__dirname, 'catalog');
+const sha12 = (s: string | Buffer): string => crypto.createHash('sha256').update(s).digest('hex').slice(0, 12);
+
+/**
+ * The rules hash: the scoring version, every *.yaml of the catalog dir (by name), and each bundled
+ * driver — every source / catalog file of its package (by relative path; build output, tests and
+ * dependencies excluded), or a stable `absent` marker when it is not installed. A driver's version is
+ * deliberately left out: releases bump every package in lockstep, and only content changes the rules.
+ */
+export function rulesHashOf(rulesVersion: number, catalogDir: string = CATALOG_DIR, drivers: DriverRulesInput[] = bundledDriverRulesInputs()): string {
+  const files = fs.readdirSync(catalogDir).filter((f) => f.endsWith('.yaml')).sort();
+  const h = crypto.createHash('sha256').update(`audit-rules:${rulesVersion}\n`);
+  for (const f of files) h.update(`${f}\n`).update(fs.readFileSync(path.join(catalogDir, f))).update('\n');
+  for (const d of [...drivers].sort((a, b) => a.name.localeCompare(b.name, 'en'))) {
+    h.update(`driver:${d.name}\n`);
+    if (!d.dir) { h.update('absent\n'); continue; }
+    for (const f of driverFiles(d.dir)) h.update(`${f}\n`).update(fs.readFileSync(path.join(d.dir, f))).update('\n');
+  }
+  return h.digest('hex').slice(0, 12);
+}
+
+let cached: Provenance | null = null;
+
 export function getProvenance(): Provenance {
+  if (cached) return cached;
   let sungenVersion = 'unknown';
   try {
     const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', 'package.json'), 'utf-8'));
@@ -24,10 +112,10 @@ export function getProvenance(): Provenance {
   } catch { /* version stays 'unknown' */ }
 
   let catalogHash = 'unknown';
-  try {
-    const cat = fs.readFileSync(path.join(__dirname, 'catalog', 'universal-viewpoints.yaml'), 'utf-8');
-    catalogHash = crypto.createHash('sha256').update(cat).digest('hex').slice(0, 12);
-  } catch { /* hash stays 'unknown' */ }
+  try { catalogHash = sha12(fs.readFileSync(path.join(CATALOG_DIR, 'universal-viewpoints.yaml'), 'utf-8')); } catch { /* hash stays 'unknown' */ }
+  let rulesHash = 'unknown';
+  try { rulesHash = rulesHashOf(AUDIT_RULES_VERSION); } catch { /* hash stays 'unknown' */ }
 
-  return { sungenVersion, catalogHash };
+  cached = { sungenVersion, catalogHash, rulesHash };
+  return cached;
 }

package/src/hooks/guard-protected-paths.ts

@@ -10,7 +10,8 @@
  *     — the CLI still writes the last two itself; the guard only judges an agent's tool calls
  *   trace evidence — DENY an agent write (phase 08; the verdict trusts it only as far as this guard and git review):
  *     .sungen/trace-identity/**                    (the driver's identity answers — written by the CLI)
- *     test-results/sungen-run-record*.json         (run id + test-file hashes — written by the Playwright reporter)
+ *     test-results[-free]/sungen-run-record*.json  (run id + test-file hashes — written by the Playwright reporter;
+ *                                                  test-results-free/ is the free run's own outputDir, #941)
  *   hook control — ASK before an agent write (the agent must not switch its own guard off):
  *     qa/sungen.config.yaml · .claude/settings.json · .claude/settings.local.json ·
  *     .claude/hooks/sungen-hook.cjs
@@ -25,7 +26,7 @@ const LOCK = /^qa\/(?:.+\/)?contracts\.lock\.yaml$/i;
 const DECISION = /^qa\/(?:(?:screens|flows|api(?:\/flows)?)\/[^/]+\/)?decisions\/[^/]+/i;
 const APPROVAL_STATE = /^\.sungen\/(?:journey\/[^/]+\.state\.json|viewpoint-baseline\.json)$/i;
 /** Trace evidence (phase 08, DOS-14.6): the driver's identity answers and the run records. */
-const TRACE_EVIDENCE = /^(?:\.sungen\/trace-identity\/.+|test-results\/sungen-run-record(?:\.[A-Za-z0-9._-]+)?\.json)$/i;
+const TRACE_EVIDENCE = /^(?:\.sungen\/trace-identity\/.+|test-results(?:-free)?\/sungen-run-record(?:\.[A-Za-z0-9._-]+)?\.json)$/i;
 const HOOK_CONTROL = ['qa/sungen.config.yaml', '.claude/settings.json', '.claude/settings.local.json', '.claude/hooks/sungen-hook.cjs'];
 
 /** The same paths as they appear INSIDE a command string (e.g. in `bash -c "…"` or `python -c "…"`). */

package/src/hooks/guard-rules.ts

@@ -4,7 +4,7 @@
  *
  *   protected-approval-paths  DENY  a precise write (Edit/Write/MultiEdit, or Bash `>`, `tee`,
  *                                   `sed -i`) to a contract lock, a decision record, approval state or
- *                                   trace evidence (.sungen/trace-identity, test-results/sungen-run-record*)
+ *                                   trace evidence (.sungen/trace-identity, test-results[-free]/sungen-run-record*)
  *   protected-hook-control    ASK   the same writes to the files that control the hooks, so the
  *                                   agent cannot switch its own guard off unasked
  *   bash-protected-mention    ASK   any other Bash segment that names a protected path and does not