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

package/src/harness/defect-draft.ts

@@ -0,0 +1,115 @@
+/**
+ * `sungen defect draft` — turn each `product-candidate` row of a unit's last triage into a record
+ * `qa/defects/DEF-NNN-<slug>.md` (see defects.ts for the link checks). Deterministic: Steps come
+ * from the scenario's Gherkin with test-data resolved, Expected/Actual from the assertion, and the
+ * severity is PROPOSED by rule until QA confirms it. Never overwrites a file, and never drafts a
+ * scenario an existing record already names.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { stringify as toYaml } from 'yaml';
+import type { ResolvedUnit } from '../cli/resolve-unit';
+import { redactSecrets } from '../exporters/api-testcase-formatter';
+import { getEnvironment } from '../exporters/run-environment';
+import { parseFeatureMetadata } from '../exporters/feature-parser';
+import { mergeFeatureAndSpec, MergedScenario } from '../exporters/scenario-merger';
+import { maskCredentialValue } from '../exporters/sensitive-key';
+import { parseSpecFile } from '../exporters/spec-parser';
+import { loadTestData, substituteTestDataVars } from '../exporters/test-data-resolver';
+import { readCapabilities } from './capability';
+import { defectsDir, nextDefectId, readDefects } from './defects';
+import type { TriageRow } from './triage';
+import { readTriageReport, unitSecrets } from './triage-unit';
+
+export interface DraftResult {
+  /** `sungen triage` has not run for this unit. */
+  missingTriage?: boolean;
+  written: string[];
+  skipped: Array<{ scenario: string; id: string }>;
+}
+
+/** Blocking actions: a @high scenario that fails on one of these is `major`, otherwise `minor`. */
+const BLOCKING = /\b(?:submit|save|apply|log ?in|sign ?in|sign ?up|register|checkout|pay|confirm|send|navigate|redirect)\b/i;
+
+const slug = (s: string): string =>
+  s.replace(/^\s*(?:VP|FL)-[A-Z0-9-]+\s+/i, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 50).replace(/-$/, '');
+
+interface UnitScenario { merged: MergedScenario; testData: Record<string, string>; secrets: string[] }
+
+/** Scenario title → its merged Gherkin, test-data (credentials masked) and secret values. */
+function unitScenarios(cwd: string, unit: ResolvedUnit): Map<string, UnitScenario> {
+  const out = new Map<string, UnitScenario>();
+  const featuresDir = path.join(unit.dir, 'features');
+  if (!fs.existsSync(featuresDir)) return out;
+  for (const f of fs.readdirSync(featuresDir).filter((x) => x.endsWith('.feature'))) {
+    const base = f.replace(/\.feature$/, '');
+    const spec = parseSpecFile(path.join(cwd, 'specs', 'generated', unit.unitId, `${base}.spec.ts`));
+    const dataFile = path.join(unit.dir, 'test-data', `${base}.yaml`);
+    const raw = fs.existsSync(dataFile) ? loadTestData(dataFile) : {};
+    const testData = Object.fromEntries(Object.entries(raw).map(([k, v]) => [k, maskCredentialValue(k, String(v))]));
+    const secrets = unitSecrets(raw, cwd);
+    for (const m of mergeFeatureAndSpec(parseFeatureMetadata(path.join(featuresDir, f)), spec)) {
+      out.set(m.feature.name, { merged: m, testData, secrets });
+    }
+  }
+  return out;
+}
+
+function render(cwd: string, unit: ResolvedUnit, id: string, row: TriageRow, sc: UnitScenario | undefined): string {
+  const tags = sc?.merged.feature.tags ?? [];
+  const resolve = (t: string): string => (sc ? substituteTestDataVars(t, sc.testData) : t);
+  const steps = (sc?.merged.resolvedSteps ?? []).map((s) => resolve(s.text));
+  const thens = (sc?.merged.resolvedExpected ?? []).map((s) => resolve(s.text));
+  const high = tags.some((t) => t === '@high' || t === '@critical');
+  const severity = high && BLOCKING.test([row.scenario, ...steps].join(' ')) ? 'major' : 'minor';
+  const specFile = path.join(unit.dir, 'requirements', 'spec.md');
+  const env = getEnvironment(cwd);
+  const front = {
+    id, title: row.scenario, severity, severity_source: 'proposed', status: 'open',
+    units: [unit.unitId], scenarios: [row.scenario], claims: row.ids, legacy: row.legacy,
+    spec: fs.existsSync(specFile) ? path.relative(cwd, specFile) : '',
+    found: {
+      date: new Date().toISOString().slice(0, 10),
+      env: process.env.SUNGEN_ENV || 'default',
+      base_url: env.baseURL,
+      platform: row.variant || readCapabilities(cwd).platform || 'web',
+    },
+    tracker: '',
+  };
+  const body = [
+    '---', toYaml(front).trimEnd(), '---', '',
+    `# ${id}: ${row.scenario}`, '',
+    '## Summary', '', '(to fill: what is wrong, where, and who it affects)', '',
+    '## Steps to reproduce', '', ...(steps.length ? steps.map((s, i) => `${i + 1}. ${s}`) : ['(scenario steps not found — see the feature)']), '',
+    '## Expected', '', ...thens.map((t) => `- ${t}`), ...(row.expected ? [`- Asserted value: ${row.expected}`] : []), '',
+    '## Actual', '', `- ${row.received ? `Received: ${row.received}` : row.evidence}`, '',
+    '## Evidence', '', `- Error: ${row.evidence}`, ...(row.tracePath ? [`- Trace: ${row.tracePath}`] : []), '',
+    '## Notes', '', `- Triage: ${row.class} (${row.ruleId})${row.variant ? ` on ${row.variant}` : ''}`, '',
+  ].join('\n');
+  return redactSecrets(body, sc?.secrets ?? []);
+}
+
+export function draftDefects(cwd: string, unit: ResolvedUnit, opts: { scenario?: string } = {}): DraftResult {
+  const triage = readTriageReport(cwd, unit.unitId);
+  if (!triage) return { missingTriage: true, written: [], skipped: [] };
+  const recorded = new Map<string, string>();
+  for (const r of readDefects(cwd)) if (r.units.includes(unit.unitId)) for (const s of r.scenarios) recorded.set(s, r.id);
+
+  const wanted = triage.rows.filter((r) => r.class === 'product-candidate'
+    && (!opts.scenario || r.scenario.includes(opts.scenario) || r.ids.includes(opts.scenario)));
+  const scenarios = unitScenarios(cwd, unit);
+  const result: DraftResult = { written: [], skipped: [] };
+  const seen = new Set<string>();
+  for (const row of wanted) {
+    if (seen.has(row.scenario)) continue;   // one record per scenario, even across OS variants
+    seen.add(row.scenario);
+    const existing = recorded.get(row.scenario);
+    if (existing) { result.skipped.push({ scenario: row.scenario, id: existing }); continue; }
+    const id = nextDefectId(cwd);
+    const file = path.join(defectsDir(cwd), `${id}-${slug(row.scenario) || 'defect'}.md`);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, render(cwd, unit, id, row, scenarios.get(row.scenario)), { encoding: 'utf-8', flag: 'wx' });
+    result.written.push(path.relative(cwd, file));
+  }
+  return result;
+}

package/src/harness/defects.ts

@@ -0,0 +1,94 @@
+/**
+ * Defect records — `qa/defects/DEF-NNN-<slug>.md`, one project-wide folder. A scenario points at a
+ * record with `@known-defect:DEF-NNN`; the record points back at units, scenarios, claims and legacy
+ * TCs in its frontmatter. This module reads the records and checks both directions of that link.
+ * Drafting a record from a triage row lives in defect-draft.ts.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
+
+export const DEFECT_STATUSES = ['open', 'fixed', 'verified', 'closed', 'wont-fix'] as const;
+export type DefectStatus = typeof DEFECT_STATUSES[number];
+
+export interface DefectRecord {
+  id: string;
+  title: string;
+  severity: string;
+  status: string;
+  units: string[];
+  scenarios: string[];
+  /** Project-relative path of the record file. */
+  file: string;
+}
+
+const DEF_FILE = /^(DEF-(\d+))-.*\.md$/;
+const KNOWN_DEFECT_TAG = /@known-defect:(DEF-\d+)\b/g;
+
+export function defectsDir(cwd: string): string {
+  return path.join(cwd, 'qa', 'defects');
+}
+
+function defectFiles(cwd: string): string[] {
+  const dir = defectsDir(cwd);
+  return fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => DEF_FILE.test(f)).sort() : [];
+}
+
+/** The next free id: one above the highest number on disk, zero-padded to 3. */
+export function nextDefectId(cwd: string): string {
+  const max = defectFiles(cwd).reduce((m, f) => Math.max(m, Number(f.match(DEF_FILE)![2])), 0);
+  return `DEF-${String(max + 1).padStart(3, '0')}`;
+}
+
+const list = (v: unknown): string[] => (Array.isArray(v) ? v.map(String) : []);
+
+/** Every record whose frontmatter parses; a malformed file is skipped, never thrown on. */
+export function readDefects(cwd: string): DefectRecord[] {
+  const out: DefectRecord[] = [];
+  for (const f of defectFiles(cwd)) {
+    const file = path.join(defectsDir(cwd), f);
+    try {
+      const fm = parseYaml(fs.readFileSync(file, 'utf-8').split(/^---\s*$/m)[1] ?? '') as Record<string, unknown> | null;
+      if (!fm || typeof fm !== 'object') continue;
+      out.push({
+        id: String(fm.id ?? f.match(DEF_FILE)![1]),
+        title: String(fm.title ?? ''),
+        severity: String(fm.severity ?? ''),
+        status: String(fm.status ?? ''),
+        units: list(fm.units),
+        scenarios: list(fm.scenarios),
+        file: path.relative(cwd, file),
+      });
+    } catch {
+      // unreadable frontmatter: not a record we can reason about
+    }
+  }
+  return out;
+}
+
+/**
+ * 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 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.`);
+    }
+  }
+  const names = new Set(scenarioNames);
+  for (const r of records) {
+    if (r.status !== 'open' || !r.units.includes(unitId)) continue;
+    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.`);
+      }
+    }
+  }
+  return findings;
+}

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,78 @@
+/**
+ * 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
+ *   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,55 @@
+/**
+ * `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)
+ * Not yet (phase 05 follow-ups): qa/defects/ and the sibling flows credited to a screen.
+ */
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { canonicalJson } from '../../decisions/decision-identity';
+import { projectRootFromScreenDir } from '../intent';
+import { featureFilesFor } 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));
+}
+
+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 }));
+}

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

@@ -0,0 +1,201 @@
+/**
+ * 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 { 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 }
+/** 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})`;
+}
+
+/** 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);
+  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)) {
+    stale.push({ code: 'inputs-changed', message: 'an input the audit judged (.feature, spec, viewpoint, context, design) changed since this audit' });
+  }
+  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}.`;
+}