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

package/src/harness/defects.ts

@@ -66,24 +66,37 @@ export function readDefects(cwd: string): DefectRecord[] {
   return out;
 }
 
+/**
+ * Everything the defect-link findings of one unit read off qa/defects/ — and so what the audit's
+ * inputsHash covers there (#927): the unit's `@known-defect:<id>` tags with no record, in tag order,
+ * and the unit's OPEN records with the scenarios they name. Title, severity and prose are not read,
+ * so editing them never asks for a re-audit.
+ */
+export interface DefectLinkInputs { missing: string[]; open: Array<{ id: string; scenarios: string[] }> }
+
+export function defectLinkInputs(cwd: string, unitId: string, featureText: string): DefectLinkInputs {
+  const records = readDefects(cwd);
+  const known = new Set(records.map((r) => r.id));
+  const tagged = [...new Set([...featureText.matchAll(KNOWN_DEFECT_TAG)].map((m) => m[1]))];
+  return {
+    missing: tagged.filter((id) => !known.has(id)),
+    open: records.filter((r) => r.status === 'open' && r.units.includes(unitId)).map((r) => ({ id: r.id, scenarios: r.scenarios })),
+  };
+}
+
 /**
  * Advisory audit findings for one unit (never scored):
  *   DEFECT-REF-MISSING     a `@known-defect:DEF-NNN` tag with no record file.
  *   DEFECT-ORPHAN (info)   an OPEN record of this unit names a scenario the unit no longer has.
  */
 export function defectLinkFindings(cwd: string, unitId: string, featureText: string, scenarioNames: string[]): string[] {
-  const records = readDefects(cwd);
+  const { missing, open } = defectLinkInputs(cwd, unitId, featureText);
   const findings: string[] = [];
-  const known = new Set(records.map((r) => r.id));
-  const tagged = new Set([...featureText.matchAll(KNOWN_DEFECT_TAG)].map((m) => m[1]));
-  for (const id of tagged) {
-    if (!known.has(id)) {
-      findings.push(`DEFECT-REF-MISSING: \`@known-defect:${id}\` has no record in qa/defects/ — draft it with \`sungen defect draft --screen ${unitId}\`, or correct the id.`);
-    }
+  for (const id of missing) {
+    findings.push(`DEFECT-REF-MISSING: \`@known-defect:${id}\` has no record in qa/defects/ — draft it with \`sungen defect draft --screen ${unitId}\`, or correct the id.`);
   }
   const names = new Set(scenarioNames);
-  for (const r of records) {
-    if (r.status !== 'open' || !r.units.includes(unitId)) continue;
+  for (const r of open) {
     for (const s of r.scenarios) {
       if (!names.has(s)) {
         findings.push(`DEFECT-ORPHAN (info): ${r.id} is open and names scenario "${s}", which ${unitId} no longer has — update the record's scenarios, or close it.`);

package/src/harness/flow-check.ts

@@ -70,6 +70,17 @@ export function loadFlowScenarios(cwd: string): FlowScenario[] {
   return out;
 }
 
+/**
+ * What a screen audit reads from its sibling flows (#927): the scenarios that can credit a gate theme
+ * — only deep ones do (flowCoveredThemes) — by flow and haystack. The screen's inputsHash covers them,
+ * sorted so the hash does not depend on directory order; a shallow scenario or prose moves nothing.
+ */
+export function flowCreditInputs(cwd: string): Array<{ flow: string; haystack: string }> {
+  const key = (s: { flow: string; haystack: string }): string => `${s.flow}\n${s.haystack}`;
+  return loadFlowScenarios(cwd).filter((s) => s.deep).map(({ flow, haystack }) => ({ flow, haystack }))
+    .sort((a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0));
+}
+
 export function buildFlowCheck(cwd: string, onlyFlow?: string): FlowCheckReport {
   const screens = listDirs(path.join(cwd, 'qa', 'screens'));
   const flows = (onlyFlow ? [onlyFlow] : listDirs(path.join(cwd, 'qa', 'flows')));

package/src/harness/gates/audit-gate-terms.ts

@@ -0,0 +1,80 @@
+/**
+ * The audit's gateStatus conjunction, in ONE place (OES-11.2): `runAudit` evaluates it to set
+ * gateStatus, and `verifyAuditReport` re-evaluates it from the report's own fields to catch a stored
+ * PASS the report cannot reproduce (a hand-flipped gateStatus + exitCode — tester finding m1).
+ *
+ * Each term names its catalog rule; `resolveRule` decides whether a violated one blocks. The decision
+ * layer adds three hard terms: a rejected override, a decision file that does not verify (id / hash).
+ * Re-evaluating catches casual tampering only: a forger who also rewrites every finding, gap and
+ * verdict in the report is out of scope here, as for inputsHash (anti-staleness, not anti-forgery).
+ */
+import { evaluateGateTerms, GateTerm } from './gate-terms';
+import { trackGateRules } from './resolve-rule';
+import { UnitGateOverrides } from './unit-gate-overrides';
+
+/** The report fields the conjunction reads — present in every report runAudit writes. */
+export interface AuditTermSources {
+  gate: { gaps: unknown[] };
+  depth: { verdict: string };
+  claim: { verdict: string };
+  spec: { verdict: string };
+  taxonomyMismatch: boolean;
+  gateSensorError: boolean;
+  reusedScenarioIds: unknown[];
+}
+
+export function auditGateTerms(r: AuditTermSources): GateTerm[] {
+  return [
+    { rule: 'audit.viewpoint-coverage', holds: r.gate.gaps.length === 0 },
+    { rule: 'audit.assertion-depth', holds: r.depth.verdict !== 'fail' },
+    { rule: 'audit.claim-proof', holds: r.claim.verdict !== 'fail' },
+    { rule: 'audit.spec-coverage', holds: r.spec.verdict !== 'fail' },
+    { rule: 'audit.taxonomy-mismatch', holds: !r.taxonomyMismatch },
+    // An 'error' finding from a capability gate sensor (api, db, …) — the driver's own verdict.
+    { rule: 'audit.gate-sensor-error', holds: !r.gateSensorError },
+    // #694 — a reused id reaches the deliverable as two rows under one testcase id.
+    { rule: 'audit.scenario-id-reuse', holds: r.reusedScenarioIds.length === 0 },
+  ];
+}
+
+export function decisionTerms(o: UnitGateOverrides): GateTerm[] {
+  return [
+    { rule: 'gate.override-rejected', holds: o.rejected.length === 0 },
+    { rule: 'decision.id-reuse', holds: !o.problems.some((p) => p.code === 'id-mismatch') },
+    { rule: 'decision.mutated', holds: !o.problems.some((p) => p.code !== 'id-mismatch') },
+  ];
+}
+
+/** The gateStatus a report's own terms produce under the unit's overrides — what the audit computed. */
+export function recomputeAuditGateStatus(sources: AuditTermSources, overrides: UnitGateOverrides): 'PASS' | 'FAIL' {
+  const outcome = evaluateGateTerms([...auditGateTerms(sources), ...decisionTerms(overrides)], trackGateRules(overrides.context));
+  return outcome.pass ? 'PASS' : 'FAIL';
+}
+
+const isObj = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * The term sources of a parsed audit.json. `strict` (a current report): every field must be there with
+ * its type, else null. Not strict (a legacy report, written before some fields): a missing field reads
+ * as "holds", so only a stored PASS that a present field contradicts can be caught.
+ */
+export function termSourcesOf(r: Record<string, unknown>, strict: boolean): AuditTermSources | null {
+  const verdict = (k: string): string | null | undefined => {
+    const v = r[k];
+    if (!isObj(v)) return strict ? null : undefined;
+    return typeof v.verdict === 'string' ? v.verdict : strict ? null : undefined;
+  };
+  const gaps = isObj(r.gate) && Array.isArray(r.gate.gaps) ? r.gate.gaps : strict ? null : [];
+  const depth = verdict('depth');
+  const claim = verdict('claim');
+  const spec = verdict('spec');
+  const flag = (k: string): boolean | null => (typeof r[k] === 'boolean' ? r[k] as boolean : strict ? null : false);
+  const taxonomyMismatch = flag('taxonomyMismatch');
+  const gateSensorError = flag('gateSensorError');
+  const reused = Array.isArray(r.reusedScenarioIds) ? r.reusedScenarioIds : strict ? null : [];
+  if ([gaps, depth, claim, spec, taxonomyMismatch, gateSensorError, reused].some((x) => x === null)) return null;
+  return {
+    gate: { gaps: gaps as unknown[] }, depth: { verdict: depth ?? 'pass' }, claim: { verdict: claim ?? 'pass' }, spec: { verdict: spec ?? 'pass' },
+    taxonomyMismatch: taxonomyMismatch as boolean, gateSensorError: gateSensorError as boolean, reusedScenarioIds: reused as unknown[],
+  };
+}

package/src/harness/gates/audit-gate-verdict.ts

@@ -0,0 +1,79 @@
+/**
+ * The audit's side of the gate registry (OES-11.2/11.4): load the unit's gate overrides, hand the
+ * tracked rules to the sensors, evaluate the gateStatus conjunction, and produce the fields the
+ * report records so readers can verify it (takumi T3):
+ *
+ *   gateOverrides[]  every override touching the unit, applied / ineffective / rejected
+ *   decisionsHash    the overrides it was judged under       (stale when they change)
+ *   inputsHash       .feature + spec + viewpoint + … + decisionsHash, and the defect records and
+ *                    crediting flows it reads (audit-input-hash.ts, #927)
+ *   exitCode         0 on PASS, 2 on FAIL — what `sungen audit` exits with
+ *
+ * The decision layer adds three hard terms: a rejected override (gate.override-rejected) and a
+ * decision file in the unit's reach that does not verify (decision.id-reuse / decision.mutated).
+ * With no decision at all none of this changes an outcome.
+ */
+import * as path from 'path';
+import { projectRootFromScreenDir } from '../intent';
+import { auditInputsHash } from './audit-input-hash';
+import { evaluateGateTerms, ruleVerdict, SensorVerdict } from './gate-terms';
+import { auditGateTerms, AuditTermSources, decisionTerms } from './audit-gate-terms';
+import { GateOverrideReport, gateOverrideReports } from './gate-override-report';
+import { GateRules, TrackedGateRules, trackGateRules } from './resolve-rule';
+import { loadUnitGateOverrides, unitScopeOfDir, UnitGateOverrides } from './unit-gate-overrides';
+
+export const AUDIT_EXIT_CODE = { PASS: 0, FAIL: 2 } as const;
+
+export interface AuditGateContext {
+  projectRoot: string;
+  overrides: UnitGateOverrides;
+  rules: TrackedGateRules;
+}
+
+export function auditGateContext(unitDir: string): AuditGateContext {
+  const projectRoot = projectRootFromScreenDir(unitDir);
+  const overrides = loadUnitGateOverrides(projectRoot, unitScopeOfDir(projectRoot, unitDir));
+  return { projectRoot, overrides, rules: trackGateRules(overrides.context) };
+}
+
+/** A depth verdict a capability computed with the catalog alone, re-levelled for this unit's rules. */
+export function relevelProvidedDepth<T extends { verdict: SensorVerdict }>(depth: T, rules: GateRules): T {
+  if (depth.verdict !== 'fail') return depth;
+  const verdict = ruleVerdict(rules, 'audit.assertion-depth', true, false);
+  return verdict === 'fail' ? depth : { ...depth, verdict };
+}
+
+/** Findings for the decision layer — empty when the unit has no override and no bad decision file. */
+export function decisionFindings(ctx: AuditGateContext): string[] {
+  const o = ctx.overrides;
+  const rel = (p: string): string => path.relative(ctx.projectRoot, p).split(path.sep).join('/');
+  return [
+    ...o.rejected.map((r) => `GATE-OVERRIDE-REJECTED (gate.override-rejected): ${r.decisionId} in ${r.path} cannot apply — ${r.reason}. Record a valid override that supersedes it.`),
+    ...o.ineffective.map((r) => `GATE-OVERRIDE-INEFFECTIVE: ${r.decisionId} (${r.rule ?? '?'}) in ${r.path} relaxes nothing — ${r.reason}. Record it with \`sungen journey --decide gate-override\` on a terminal.`),
+    ...o.problems.map((p) => `${p.code === 'id-mismatch' ? 'DECISION-ID-REUSED (decision.id-reuse)' : 'DECISION-UNVERIFIABLE (decision.mutated)'}: ${rel(p.path)} — ${p.message}. Restore it from git; change a decision by recording a superseding one.`),
+    ...o.inForce.map((x) => `GATE-OVERRIDDEN: ${x.rule} is ${x.severity} for ${x.scope} (catalog level lowered by ${x.decisionId}, recorded by ${x.by}) — ${x.reason}`),
+    // Review H1: it counts here so its author sees the effect; release refuses it until reviewed.
+    ...o.inForce.filter((x) => x.committed === false).map((x) => `GATE-OVERRIDE-UNCOMMITTED: ${x.decisionId} (${x.rule}) is not in git HEAD — it counts in this audit, but \`sungen gate --phase deliver\` and \`sungen delivery\` refuse it (decision.in-run) until it is committed through review.`),
+  ];
+}
+
+export interface AuditGateVerdict {
+  gateStatus: 'PASS' | 'FAIL';
+  gateOverrides: GateOverrideReport[];
+  decisionsHash: string;
+  inputsHash: string;
+  exitCode: number;
+}
+
+/** Evaluate the gateStatus conjunction (audit-gate-terms.ts, shared with the reader) and the verifiable fields. */
+export function auditGateVerdict(ctx: AuditGateContext, sources: AuditTermSources, unitDir: string, unitName: string): AuditGateVerdict {
+  const outcome = evaluateGateTerms([...auditGateTerms(sources), ...decisionTerms(ctx.overrides)], ctx.rules);
+  const gateStatus = outcome.pass ? 'PASS' : 'FAIL';
+  return {
+    gateStatus,
+    gateOverrides: gateOverrideReports(ctx.overrides, ctx.rules.triggered()),
+    decisionsHash: ctx.overrides.decisionsHash,
+    inputsHash: auditInputsHash(unitDir, unitName, ctx.overrides.decisionsHash),
+    exitCode: AUDIT_EXIT_CODE[gateStatus],
+  };
+}

package/src/harness/gates/audit-input-hash.ts

@@ -0,0 +1,79 @@
+/**
+ * `inputsHash` of an audit (OES-11.4, takumi T3): the hash of what the audit judged plus the
+ * `decisionsHash` it was judged under. A reader recomputes it; any difference means the report no
+ * longer describes the unit, so it counts as never audited.
+ *
+ * It is ANTI-STALENESS, NOT ANTI-FORGERY: anyone who can write audit.json can also compute this hash
+ * (the function is public). It catches a report that outlived its inputs; verdicts built by code and
+ * the git-HEAD checks on decisions are what stand against a forger.
+ *
+ * Inputs — every file whose change can move a verdict:
+ *   the unit's .feature files · requirements/spec.md · requirements/test-viewpoint.md ·
+ *   requirements/flow-contract.yaml · requirements/spec_figma.md · requirements/ui-inventory.md ·
+ *   requirements/ui/* · qa/context.md (intent focus → thresholds) · qa/capabilities.yaml (platform,
+ *   enabled drivers → gate sensors)
+ * and what it reads outside the unit (#927), as the audit reads it — not the files whole, so a
+ * re-audit is asked for only when the verdict can move:
+ *   defects     qa/defects/: the unit's `@known-defect:<id>` tags with no record, and its OPEN records
+ *               with their scenarios (defectLinkInputs — DEFECT-REF-MISSING, DEFECT-ORPHAN)
+ *   flowCredit  a SCREEN's sibling flows: the deep scenarios that can credit a gate theme
+ *               (flowCreditInputs — TQ-4, COVERED-VIA-FLOW); a flow or api unit is never credited
+ * Each is part of the hash only when it holds something, so a project with neither keeps the hash it
+ * had; a report written before #927 in a project with either reads stale once.
+ */
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { canonicalJson } from '../../decisions/decision-identity';
+import { defectLinkInputs } from '../defects';
+import { flowCreditInputs } from '../flow-check';
+import { projectRootFromScreenDir } from '../intent';
+import { catalogIdFromScreenDir, featureFilesFor, isScreenUnitId } from '../unit-paths';
+
+const sha256 = (s: string | Buffer): string => createHash('sha256').update(s).digest('hex');
+
+function fileSha(file: string): string | null {
+  try { return sha256(fs.readFileSync(file)); } catch { return null; }
+}
+
+function filesIn(dir: string): string[] {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile()).map((e) => path.join(dir, e.name)).sort();
+  } catch { return []; }
+}
+
+/** The audit's input files that exist, in a stable order. */
+export function auditInputFiles(unitDir: string, unitName: string): string[] {
+  const req = path.join(unitDir, 'requirements');
+  const qa = path.join(projectRootFromScreenDir(unitDir), 'qa');
+  const candidates = [
+    ...featureFilesFor(unitDir, unitName),
+    ...['spec.md', 'test-viewpoint.md', 'flow-contract.yaml', 'spec_figma.md', 'ui-inventory.md'].map((f) => path.join(req, f)),
+    ...filesIn(path.join(req, 'ui')),
+    path.join(qa, 'context.md'),
+    path.join(qa, 'capabilities.yaml'),
+  ];
+  return candidates.filter((f) => fs.existsSync(f));
+}
+
+/** What the audit reads outside the unit — each key only when it holds something. */
+function crossUnitInputs(root: string, unitDir: string, unitName: string): Record<string, unknown> {
+  const unitId = catalogIdFromScreenDir(unitDir);
+  const featureText = featureFilesFor(unitDir, unitName).map((f) => { try { return fs.readFileSync(f, 'utf8'); } catch { return ''; } }).join('\n');
+  const defects = defectLinkInputs(root, unitId, featureText);
+  const flowCredit = isScreenUnitId(unitId) ? flowCreditInputs(root) : [];
+  return { ...(defects.missing.length || defects.open.length ? { defects } : {}), ...(flowCredit.length ? { flowCredit } : {}) };
+}
+
+export function auditInputsHash(unitDir: string, unitName: string, decisionsHash: string): string {
+  const root = projectRootFromScreenDir(unitDir);
+  const inputs = auditInputFiles(unitDir, unitName)
+    .map((f) => ({ file: path.relative(root, f).split(path.sep).join('/'), sha: fileSha(f) }));
+  return sha256(canonicalJson({ schema: 2, inputs, decisionsHash, ...crossUnitInputs(root, unitDir, unitName) }));
+}
+
+/** The stale reason when the inputsHash moved — it names every kind of input, the ones outside the unit too. */
+export function auditInputsChangedReason(unitDir: string): string {
+  const outside = isScreenUnitId(catalogIdFromScreenDir(unitDir)) ? 'the defect records and sibling flows it reads' : 'the defect records it reads';
+  return `an input the audit judged (.feature, spec, viewpoint, context, design, or ${outside}) changed since this audit`;
+}

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

@@ -0,0 +1,206 @@
+/**
+ * Reading `audit.json` back without trusting it (takumi T3, DOS-14.0, OES-11.4). The report is an
+ * OUTPUT of `sungen audit`; every reader (journey/gate, delivery, and `next` via this module) checks:
+ *
+ *   schema       a JSON object; only the keys the audit writes; known keys have their type
+ *   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, #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 { getProvenance } from '../provenance';
+import { auditInputsChangedReason, 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' | 'stale' | 'invalid';
+export type AuditProblemCode = 'unreadable' | 'unknown-key' | 'bad-type' | 'partial-fields' | 'status-exit-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. */
+  notes: string[];
+  /** 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;
+}
+
+/** 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 }
+/** rulesProblem's answer for a report that records no rules (`provenance.catalogHash` / `rulesHash`): an older sungen wrote it. */
+export const NO_RULES_STAMP = 'audited by an older sungen, which did not record the rules it scored with';
+/** 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 NO_RULES_STAMP;
+  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})`;
+}
+
+/** 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';
+const OBJ = 'object' as const;
+/** Every top-level key `runAudit` writes (tests/gates/audit-report-trust.run.ts keeps this in step). */
+export const AUDIT_REPORT_KEYS: Record<string, JsonKind> = {
+  screen: 'string', scenarioCount: 'number', gate: OBJ, depth: OBJ, claim: OBJ, taxonomy: OBJ, balance: OBJ,
+  duplicates: OBJ, trace: OBJ, taxonomyMismatch: 'boolean', reusedScenarioIds: 'array', downstream: OBJ,
+  manualOracle: OBJ, automatableManual: OBJ, flowDepth: OBJ, oracle: OBJ, ledger: OBJ, viewpointBaseline: OBJ,
+  flowQuality: OBJ, flowInventory: OBJ, uiInventory: OBJ, calibration: OBJ, score: OBJ, gateStatus: 'string',
+  findings: 'array', intent: OBJ, provenance: OBJ, spec: OBJ,
+  gateOverrides: 'array', decisionsHash: 'string', inputsHash: 'string', exitCode: 'number', gateSensorError: 'boolean',
+};
+const P0_KEYS = ['exitCode', 'inputsHash', 'decisionsHash', 'gateOverrides', 'gateSensorError'];
+const HASH_RE = /^[0-9a-f]{64}$/;
+
+const kindOf = (v: unknown): JsonKind | 'null' => (v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v as JsonKind);
+
+/** Structural problems of a parsed report, independent of the unit's current inputs. */
+function schemaProblems(r: Record<string, unknown>): AuditVerification['problems'] {
+  const out: AuditVerification['problems'] = [];
+  for (const [k, v] of Object.entries(r)) {
+    const want = AUDIT_REPORT_KEYS[k];
+    if (!want) out.push({ code: 'unknown-key', message: `unknown key "${k}" — the audit never writes it` });
+    else if (kindOf(v) !== want) out.push({ code: 'bad-type', message: `"${k}" must be ${want}, got ${kindOf(v)}` });
+  }
+  if (r.gateStatus !== 'PASS' && r.gateStatus !== 'FAIL') out.push({ code: 'bad-type', message: 'gateStatus must be PASS or FAIL' });
+  if (Array.isArray(r.findings) && !r.findings.every((f) => typeof f === 'string')) out.push({ code: 'bad-type', message: 'findings must be strings' });
+  const present = P0_KEYS.filter((k) => k in r);
+  if (present.length > 0 && present.length < P0_KEYS.length) {
+    out.push({ code: 'partial-fields', message: `carries ${present.join(', ')} but not ${P0_KEYS.filter((k) => !(k in r)).join(', ')}` });
+  }
+  if (present.length === P0_KEYS.length) {
+    if (!Number.isInteger(r.exitCode)) out.push({ code: 'bad-type', message: 'exitCode must be an integer' });
+    else if (r.gateStatus === 'PASS' || r.gateStatus === 'FAIL') {
+      if (r.exitCode !== AUDIT_EXIT_CODE[r.gateStatus]) out.push({ code: 'status-exit-mismatch', message: `gateStatus ${r.gateStatus} with exitCode ${r.exitCode} — a ${r.gateStatus} audit exits ${AUDIT_EXIT_CODE[r.gateStatus]}` });
+    }
+    for (const k of ['inputsHash', 'decisionsHash']) if (typeof r[k] !== 'string' || !HASH_RE.test(r[k] as string)) out.push({ code: 'bad-type', message: `${k} must be 64 hex characters` });
+    if (Array.isArray(r.gateOverrides) && !r.gateOverrides.every((g) => kindOf(g) === 'object')) out.push({ code: 'bad-type', message: 'gateOverrides must be objects' });
+  }
+  return out;
+}
+
+export function auditReportPath(projectRoot: string, unit: string): string {
+  return path.join(projectRoot, '.sungen', 'reports', `${reportSlug(unit)}-audit.json`);
+}
+
+/** Today's decisionsHash for a unit name — what `next` compares an audit with (phase 05). */
+export function currentDecisionsHash(projectRoot: string, unit: string): string {
+  const found = resolveUnitCandidates(unit, projectRoot);
+  const scope = found.length === 1 ? unitScopeOfDir(projectRoot, found[0].dir) : null;
+  return loadUnitGateOverrides(projectRoot, scope).decisionsHash;
+}
+
+export function verifyAuditReport(projectRoot: string, unit: string): AuditVerification {
+  const file = auditReportPath(projectRoot, unit);
+  const found = resolveUnitCandidates(unit, projectRoot);
+  const unitDir = found.length === 1 ? found[0].dir : null;
+  const overrides = loadUnitGateOverrides(projectRoot, unitDir ? unitScopeOfDir(projectRoot, unitDir) : null);
+  const current = overrides.decisionsHash;
+  const result = (state: AuditState, problems: AuditVerification['problems'], report: Record<string, unknown> | null = null, notes: string[] = []): AuditVerification =>
+    ({ state, problems, notes, report, path: file, currentDecisionsHash: current });
+
+  if (!fs.existsSync(file)) return result('absent', []);
+  let parsed: unknown;
+  try { parsed = JSON.parse(fs.readFileSync(file, 'utf8').replace(/^/, '')); } catch (err) {
+    return result('invalid', [{ code: 'unreadable', message: err instanceof Error ? err.message : String(err) }]);
+  }
+  if (kindOf(parsed) !== 'object') return result('invalid', [{ code: 'unreadable', message: 'not a JSON object' }]);
+  const r = parsed as Record<string, unknown>;
+  const schema = schemaProblems(r);
+  if (schema.length) return result('invalid', schema);
+
+  if (!P0_KEYS.some((k) => k in r)) {
+    // 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)]);
+    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);
+  // A report from before the rules stamp reads in plain words, with the one command that clears it (#966).
+  if (rules) stale.push({ code: 'rules-changed', message: rules === NO_RULES_STAMP
+    ? `audited by an older sungen${writtenBy(r) ? ` (${writtenBy(r)})` : ''} — run \`sungen audit --screen ${unit}\` once`
+    : `${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)) {
+    stale.push({ code: 'inputs-changed', message: auditInputsChangedReason(unitDir) });
+  }
+  if (stale.length) return result('stale', stale);
+  const tampered = verdictProblem(r, overrides);
+  return tampered ? result('invalid', [tampered]) : result('verified', [], r);
+}
+
+const verdictMismatch = (r: Record<string, unknown>): AuditVerification['problems'][number] => ({
+  code: 'verdict-mismatch',
+  message: `verdict mismatch — gateStatus ${String(r.gateStatus)} is not what the report's own findings produce under today's overrides (edited by hand)`,
+});
+
+/** A current report re-evaluated from its own terms (audit-gate-terms.ts): missing terms or another verdict = not trusted. */
+function verdictProblem(r: Record<string, unknown>, overrides: UnitGateOverrides): AuditVerification['problems'][number] | null {
+  const sources = termSourcesOf(r, true);
+  if (!sources) return { code: 'bad-type', message: 'the gate terms (gate.gaps, depth/claim/spec verdicts, taxonomyMismatch, gateSensorError, reusedScenarioIds) are incomplete' };
+  return recomputeAuditGateStatus(sources, overrides) === r.gateStatus ? null : verdictMismatch(r);
+}
+
+/** 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';
+
+/** One line saying why the report does not count, for a needs-you item or a blocker. */
+export function auditNotCountedReason(v: AuditVerification, unit: string): string {
+  const why = v.problems.map((p) => p.message).join('; ');
+  const rerun = `re-run \`sungen audit --screen ${unit}\``;
+  if (v.state === 'stale') return `Audit report is stale (${why}) — ${rerun}.`;
+  if (v.state === 'invalid') return `Audit report is not trusted (${why}) — treated as never audited; ${rerun}.`;
+  return `No audit report yet — ${rerun}.`;
+}

package/src/harness/gates/decisions-hash.ts

@@ -0,0 +1,42 @@
+/**
+ * `decisionsHash` (OES-11.4, red-team #12): a fingerprint of the decisions that can change a unit's
+ * gate outcome. The audit records it; `next`, `gate` and `delivery` recompute it — a mismatch means
+ * the audit was measured under other decisions: stale, re-audit.
+ *
+ * What it covers, for one unit — the project's `qa/decisions/` plus the unit's own directory:
+ *   - every `gate-override` entry that can apply to the unit (accepted, ineffective, rejected,
+ *     superseded alike), by path and entry_hash
+ *   - every file there that does not verify (unreadable, invalid, id or hash mismatch), by path,
+ *     problem and content — it may be an override nobody can read
+ * What it does NOT cover: waivers. A waiver is bound to the audit by `evidence_hash = hash of the
+ * audit report`; folding it in here would make every waiver stale the audit that it waives.
+ */
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { canonicalJson } from '../../decisions/decision-identity';
+import { DecisionProblem } from '../../decisions/decision-file';
+
+export interface DecisionsHashItem {
+  path: string;
+  entryHash?: string;
+  problem?: string;
+  contentSha?: string;
+}
+
+const sha256 = (s: string | Buffer): string => createHash('sha256').update(s).digest('hex');
+
+export function computeDecisionsHash(items: DecisionsHashItem[]): string {
+  const sorted = [...items].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return sha256(canonicalJson({ schema: 1, decisions: sorted }));
+}
+
+/** The hash of a unit with no decision that can touch its gates. */
+export const EMPTY_DECISIONS_HASH = computeDecisionsHash([]);
+
+/** A problem file as a hash item: its content counts, so editing it re-stales the audit. */
+export function problemHashItem(projectRoot: string, p: DecisionProblem): DecisionsHashItem {
+  let contentSha = 'unreadable';
+  try { contentSha = sha256(fs.readFileSync(p.path)); } catch { /* gone or unreadable: the marker stands */ }
+  return { path: path.relative(projectRoot, p.path).split(path.sep).join('/'), problem: p.code, contentSha };
+}