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

package/src/harness/gates/gate-rule-catalog.ts

@@ -0,0 +1,82 @@
+/**
+ * The gate-rule catalog (OES-11.1): `harness/catalog/gate-rules.yaml`, shipped next to the code
+ * (`copy-templates` copies it into `dist/harness/catalog/`).
+ *
+ * The catalog is code-owned data — a malformed one is a build defect, so loading it throws rather
+ * than degrading to "no rules" (which would silently stop every gate from blocking).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse } from 'yaml';
+
+export const GATE_SEVERITIES = ['error', 'review', 'warning', 'info'] as const;
+export type GateSeverity = typeof GATE_SEVERITIES[number];
+export type GateKind = 'hard' | 'soft';
+export const GATE_STAGES = ['spec', 'create', 'generate', 'run', 'deliver'] as const;
+export type GateStage = typeof GATE_STAGES[number];
+
+export interface GateRule {
+  id: string;
+  stage: GateStage;
+  severity: GateSeverity;
+  kind: GateKind;
+  rationale: string;
+  fix: string;
+  since: string;
+  offAllowed: boolean;
+}
+
+const CATALOG_FILE = path.join(__dirname, '..', 'catalog', 'gate-rules.yaml');
+const ID_RE = /^[a-z0-9]+(\.[a-z0-9]+(-[a-z0-9]+)*)+$/;
+
+/** Parse and validate catalog text. Throws on the first structural defect. */
+export function parseGateRuleCatalog(text: string): Map<string, GateRule> {
+  const doc = parse(text) as { rules?: unknown } | null;
+  if (!doc || !Array.isArray(doc.rules)) throw new Error('gate-rules.yaml: no `rules:` list');
+  const out = new Map<string, GateRule>();
+  for (const raw of doc.rules as Array<Record<string, unknown>>) {
+    const id = String(raw?.id ?? '');
+    const bad = (why: string): never => { throw new Error(`gate-rules.yaml: rule "${id}" ${why}`); };
+    if (!ID_RE.test(id)) bad('has no dotted kebab-case id');
+    if (out.has(id)) bad('is declared twice');
+    if (!GATE_STAGES.includes(raw.stage as GateStage)) bad(`has an unknown stage "${raw.stage}"`);
+    if (!GATE_SEVERITIES.includes(raw.severity as GateSeverity)) bad(`has an unknown severity "${raw.severity}"`);
+    if (raw.kind !== 'hard' && raw.kind !== 'soft') bad('kind must be hard|soft');
+    if (typeof raw.offAllowed !== 'boolean') bad('offAllowed must be a boolean');
+    if (raw.kind === 'hard' && raw.offAllowed) bad('is hard, so it can never be switched off');
+    out.set(id, {
+      id,
+      stage: raw.stage as GateStage,
+      severity: raw.severity as GateSeverity,
+      kind: raw.kind as GateKind,
+      rationale: String(raw.rationale ?? ''),
+      fix: String(raw.fix ?? ''),
+      since: String(raw.since ?? ''),
+      offAllowed: raw.offAllowed as boolean,
+    });
+  }
+  return out;
+}
+
+let cached: ReadonlyMap<string, GateRule> | null = null;
+
+/** Every rule, keyed by id (loaded once per process). */
+export function gateRuleCatalog(): ReadonlyMap<string, GateRule> {
+  if (!cached) cached = parseGateRuleCatalog(fs.readFileSync(CATALOG_FILE, 'utf8'));
+  return cached;
+}
+
+export function findGateRule(id: string): GateRule | undefined {
+  return gateRuleCatalog().get(id);
+}
+
+/** A rule the CODE names. An unknown id is a programming error, never user input — so it throws. */
+export function gateRule(id: string): GateRule {
+  const rule = findGateRule(id);
+  if (!rule) throw new Error(`gate rule "${id}" is not in harness/catalog/gate-rules.yaml`);
+  return rule;
+}
+
+export function listRules(): GateRule[] {
+  return [...gateRuleCatalog().values()];
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Turning a gate CONDITION into an outcome through `resolveRule` — the only shapes a gate site uses,
+ * so no site writes a severity literal of its own (OES-11.2).
+ *
+ *   evaluateGateTerms  a conjunction (audit gateStatus, script-check status): each term names its
+ *                      rule and whether its condition holds; a violated term blocks only when its
+ *                      resolved severity blocks
+ *   ruleVerdict        a sensor verdict (pass | warn | fail) for one rule
+ *   sensorSeverityOf   a per-finding sensor severity (fail | warn | info), or null when switched off
+ */
+import { GateRules, ResolvedRule } from './resolve-rule';
+
+export interface GateTerm {
+  rule: string;
+  /** The condition the rule wants to see — `true` means the term passes. */
+  holds: boolean;
+}
+
+export interface GateTermsOutcome {
+  pass: boolean;
+  /** Violated rules whose resolved severity blocks. */
+  blocking: string[];
+  /** Violated rules an override lowered to advisory. */
+  relaxed: string[];
+}
+
+export function evaluateGateTerms(terms: GateTerm[], rules: GateRules): GateTermsOutcome {
+  const blocking: string[] = [];
+  const relaxed: string[] = [];
+  for (const t of terms) {
+    if (t.holds) continue;
+    const r = rules.resolve(t.rule);
+    if (r.blocking) blocking.push(t.rule);
+    else if (r.overriddenBy) relaxed.push(t.rule);
+  }
+  return { pass: blocking.length === 0, blocking, relaxed };
+}
+
+export type SensorVerdict = 'pass' | 'warn' | 'fail';
+
+/**
+ * A sensor verdict for one rule. `advisoryAnyway` is a reason the miss can never block that is not
+ * a severity (the `smoke` focus, or no failing row) — the rule is then not consulted at all.
+ */
+export function ruleVerdict(rules: GateRules, id: string, conditionMet: boolean, advisoryAnyway: boolean): SensorVerdict {
+  if (!conditionMet) return 'pass';
+  if (advisoryAnyway) return 'warn';
+  const r = rules.resolve(id);
+  if (r.severity === 'off') return 'pass';
+  return r.blocking ? 'fail' : 'warn';
+}
+
+export type SensorSeverity = 'fail' | 'warn' | 'info';
+
+export function sensorSeverityOf(r: ResolvedRule): SensorSeverity | null {
+  if (r.severity === 'off') return null;
+  if (r.blocking) return 'fail';
+  return r.severity === 'info' ? 'info' : 'warn';
+}

package/src/harness/gates/in-run-decision-check.ts

@@ -0,0 +1,124 @@
+/**
+ * `decision.in-run` (OES-11.5, red-team #3/#15) — a hard rule: a decision that relaxes or approves
+ * something (`gate-override`, `waiver`, `contract-approval`) must have been reviewed BEFORE the run
+ * being delivered. It is in-run when
+ *   - it is not in `git show HEAD:` (never committed, so never reviewed), or
+ *   - it was committed after the start of that run — judged by its git COMMIT time, not by the
+ *     `valid_from` it carries, which its author writes and can backdate (review H1).
+ * Without git only the second test is possible, on `valid_from`; the caller says so (lower confidence).
+ * Without git AND without a run, nothing can be judged — reported, not guessed. A commit time can be
+ * forged too (GIT_COMMITTER_DATE); it raises the bar, it is not a signature.
+ *
+ * A MIGRATED waiver (DOS-13.5) was reviewed when its legacy record was committed — the only record the
+ * import trusts — so it is judged by THAT commit (migrated-waiver-review.ts), never by its own decision
+ * file: in-run when the record was committed after the run started, or — run start or not (#925) —
+ * when it could not have been the import's source: not strictly before the decision file, the unit's
+ * import marker or the project's adoption of 3.3 appeared. Holding it to its decision file's commit would make
+ * every legacy project's waivers in-run the day they are imported (phase 09). An entry HEAD's legacy
+ * file does not vouch for — absent, uncommitted, different, introduced beyond the commits the walk
+ * reads (#924) or at a shallow clone's boundary — is judged as any other; in the last two cases an
+ * in-run finding says why.
+ *
+ * A manual triage classification that claims a human typed it (`triage-classification` with
+ * `humanConfirmed`, #928) is a claim the entry makes about itself — a script can write one. What backs
+ * it is review, so it is in-run while git HEAD does not hold it (and, with no git, always: nothing
+ * shows it was reviewed). Judged by HEAD membership only: it is always recorded after the run it
+ * judges, so its commit time says nothing. Only a test-defect / environment entry that is not
+ * superseded counts — the only kind the reader puts in force on that claim.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { DECISION_FILE_PATH } from '../../decisions/decision-file';
+import { DecisionVisibility } from '../../decisions/decision-schema';
+import { gitOutput } from '../../decisions/git-head-trust';
+import { readDecisions } from '../../decisions/read-decisions';
+import { HUMAN_ONLY_TRIAGE, ManualTriageClass, TRIAGE_DECISION_KIND } from '../../graph/manual-triage-decisions';
+import { migratedWaiverReview } from './migrated-waiver-review';
+
+export const IN_RUN_KINDS = ['gate-override', 'waiver', 'contract-approval'] as const;
+export const IN_RUN_RULE = 'decision.in-run';
+
+export interface InRunDecision { id: string; kind: string; path: string; visibility: DecisionVisibility; why: string[] }
+
+/** Paths (relative to the project, `/`-separated) of decision files in git HEAD; null outside git. */
+export function committedDecisionPaths(projectRoot: string): Set<string> | null {
+  if (gitOutput(projectRoot, ['rev-parse', '--is-inside-work-tree'])?.trim() !== 'true') return null;
+  const listed = gitOutput(projectRoot, ['ls-tree', '-r', '-z', '--name-only', 'HEAD', '--', 'qa']) ?? '';   // no HEAD yet → nothing committed
+  return new Set(listed.split('\0').filter((p) => DECISION_FILE_PATH.test(p)));
+}
+
+/** When a committed file was last committed (ISO), or null when git cannot say. */
+function commitTimeOf(projectRoot: string, rel: string): string | null {
+  const t = gitOutput(projectRoot, ['log', '-1', '--format=%cI', '--', rel])?.trim();
+  return t && !Number.isNaN(Date.parse(t)) ? t : null;
+}
+
+/** When the delivered run started: Playwright's `stats.startTime`; null when there is no readable run. */
+export function runStartOf(resultsPath: string | null): string | null {
+  if (!resultsPath) return null;
+  try {
+    const json = JSON.parse(fs.readFileSync(resultsPath, 'utf8')) as { stats?: { startTime?: unknown } };
+    const t = json?.stats?.startTime;
+    return typeof t === 'string' && !Number.isNaN(Date.parse(t)) ? t : null;
+  } catch {
+    return null;
+  }
+}
+
+const isInRunKind = (kind: string): boolean => (IN_RUN_KINDS as readonly string[]).includes(kind);
+/**
+ * A triage classification claiming a human typed it (#928): reviewed only once git HEAD holds it.
+ * Only what the reader (manual-triage-decisions.ts) can put in force: a superseded entry is never read,
+ * and a product classification needs no human — its claim backs nothing, so it blocks nothing.
+ */
+const claimsHumanTriage = (e: { kind: string; payload?: Record<string, unknown>; superseded_by?: string }): boolean =>
+  e.kind === TRIAGE_DECISION_KIND && !e.superseded_by && e.payload?.humanConfirmed === true
+  && HUMAN_ONLY_TRIAGE.has(e.payload?.class as ManualTriageClass);
+
+/** In-run decisions among `scopes`, judged against one run start (null: HEAD membership only) and the committed set. */
+export function inRunDecisions(projectRoot: string, scopes: string[], runStart: string | null, committed: Set<string> | null): InRunDecision[] {
+  const out: InRunDecision[] = [];
+  const after = (t: string): boolean => !!runStart && Date.parse(t) > Date.parse(runStart);
+  const migratedReview = committed ? migratedWaiverReview(projectRoot) : null;
+  for (const scope of scopes) {
+    for (const e of readDecisions(projectRoot, scope).entries) {
+      const rel = path.relative(projectRoot, e.path).split(path.sep).join('/');
+      if (claimsHumanTriage(e) && !committed?.has(rel)) {
+        out.push({ id: e.id, kind: e.kind, path: rel, visibility: e.visibility, why: [committed
+          ? 'a classification by hand that claims a human typed it, not in git HEAD (never committed through review)'
+          : 'a classification by hand that claims a human typed it, and no git to show it was committed through review'] });
+      }
+      if (!isInRunKind(e.kind)) continue;
+      // A migrated waiver re-confirmed on a terminal is replaced: the new decision is judged on its own.
+      if (e.superseded_by && e.source?.where === 'migrated') continue;
+      const why: string[] = [];
+      const migrated = migratedReview?.reviewOf(scope, e) ?? null;
+      if (migrated?.at) {
+        if (after(migrated.at)) why.push(`migrated: its legacy record was committed at ${migrated.at}, after the run started ${runStart}`);
+        if (migrated.notImported) why.push(migrated.notImported);
+      } else if (committed && !committed.has(rel)) {
+        why.push('not in git HEAD (never committed through review)');
+      } else if (committed && runStart) {
+        const at = commitTimeOf(projectRoot, rel);
+        if (at ? after(at) : after(e.valid_from)) {
+          why.push(at ? `committed at ${at}, after the run started ${runStart}` : `recorded ${e.valid_from} (commit time unavailable), after the run started ${runStart}`);
+        }
+      } else if (!committed && after(e.valid_from)) {
+        why.push(`recorded ${e.valid_from}, after the run started ${runStart}`);
+      }
+      if (why.length && migrated?.unvouched) why.push(migrated.unvouched);
+      if (why.length) out.push({ id: e.id, kind: e.kind, path: rel, visibility: e.visibility, why });
+    }
+  }
+  return out;
+}
+
+/** Release decisions (override / waiver / approval) in reach that git HEAD does not hold — what `gate deliver` refuses. */
+export function uncommittedReleaseDecisions(projectRoot: string, scopes: string[]): InRunDecision[] {
+  return inRunDecisions(projectRoot, scopes, null, committedDecisionPaths(projectRoot));
+}
+
+/** Whether any decision of an in-run kind is in reach at all — the no-git notes are printed only then. */
+export function hasInRunKindDecisions(projectRoot: string, scopes: string[]): boolean {
+  return scopes.some((s) => readDecisions(projectRoot, s).entries.some((e) => isInRunKind(e.kind)));
+}

package/src/harness/gates/journey-gate-inputs.ts

@@ -0,0 +1,89 @@
+/**
+ * What the journey board and `runGate` take from the gate registry (OES-11.2/11.4, phase-03 review).
+ *
+ *   readJourneyAudit       the audit report, read through the T3 checks — a stale or untrusted one
+ *                          counts as never audited
+ *   applyAuditOverrides    an OB-* whose rule the AUDIT recorded as overridden is accepted
+ *                          (`overridden`); journey never re-applies an override itself (red-team #12)
+ *   journeyDecisionFindings the decision files in the unit's reach that do not verify, edits/deletes
+ *                          of committed entries (checkDecisionIntegrity), and rejected overrides — each
+ *                          a finding the board shows and the gate blocks on, never a crash
+ */
+import { checkDecisionIntegrity } from '../../decisions/decision-integrity-check';
+import { resolveUnitCandidates } from '../../cli/resolve-unit';
+import { auditCounts, auditNotCountedReason, AuditVerification, verifyAuditReport } from './audit-report-verification';
+import { GateOverrideReport } from './gate-override-report';
+import { ActiveOverride } from './resolve-rule';
+import { loadUnitGateOverrides, unitScopeOfDir, UnitGateOverrides } from './unit-gate-overrides';
+
+export interface JourneyAuditInput {
+  audit: Record<string, unknown> | null;
+  verification: AuditVerification;
+  /** Set when a report exists but does not count (stale / invalid). */
+  notCountedReason?: string;
+}
+
+export function readJourneyAudit(projectRoot: string, unit: string): JourneyAuditInput {
+  const verification = verifyAuditReport(projectRoot, unit);
+  if (auditCounts(verification)) return { audit: verification.report, verification };
+  return {
+    audit: null,
+    verification,
+    ...(verification.state !== 'absent' ? { notCountedReason: auditNotCountedReason(verification, unit) } : {}),
+  };
+}
+
+/** The audit rule each design obligation stands for. */
+export const OBLIGATION_RULE: Readonly<Record<string, string>> = {
+  'OB-spec': 'audit.spec-coverage',
+  'OB-coverage': 'audit.viewpoint-coverage',
+  'OB-depth': 'audit.assertion-depth',
+  'OB-trace': 'audit.taxonomy-mismatch',
+};
+
+interface OverridableObligation { id: string; status: string; detail: string; overriddenBy?: string }
+
+/**
+ * Mark needs-work obligations whose rule the audit recorded as overridden (applied). audit.json is
+ * output too: an `applied` entry counts only when the same override (decision id AND rule) is in
+ * force for the unit today (review M3); the others are ignored and returned for the board.
+ */
+export function applyAuditOverrides<T extends OverridableObligation>(obligations: T[], audit: Record<string, unknown>, inForce: ActiveOverride[]): GateOverrideReport[] {
+  const recorded = (Array.isArray(audit.gateOverrides) ? audit.gateOverrides as GateOverrideReport[] : [])
+    .filter((g) => g && g.status === 'applied');
+  const real = (g: GateOverrideReport): boolean => inForce.some((o) => o.decisionId === g.decisionId && o.rule === g.rule);
+  const applied = recorded.filter(real);
+  for (const ob of obligations) {
+    const o = applied.find((g) => g.rule === OBLIGATION_RULE[ob.id]);
+    if (!o || ob.status !== 'needs-work') continue;
+    ob.status = 'overridden';
+    ob.overriddenBy = o.decisionId;
+    ob.detail = `overridden by ${o.decisionId} (${o.rule} → ${o.severity}) — ${o.reason}. Was: ${ob.detail}`;
+  }
+  return recorded.filter((g) => !real(g));
+}
+
+export function ignoredOverrideText(g: GateOverrideReport): string {
+  return `⚠️ audit.json says override ${String(g.decisionId)} (${String(g.rule)}) applied, but it is not in force for this unit — ignored. Re-run the audit; never edit its report.`;
+}
+
+export interface DecisionGateFinding { rule: 'decision.id-reuse' | 'decision.mutated' | 'gate.override-rejected'; path: string; message: string }
+
+export function unitOverrides(projectRoot: string, unit: string): UnitGateOverrides {
+  const found = resolveUnitCandidates(unit, projectRoot);
+  return loadUnitGateOverrides(projectRoot, found.length === 1 ? unitScopeOfDir(projectRoot, found[0].dir) : null);
+}
+
+/** Integrity of every decision in the unit's reach (project + unit dirs) plus its rejected overrides. */
+export function journeyDecisionFindings(projectRoot: string, overrides: UnitGateOverrides): DecisionGateFinding[] {
+  const reach = ['qa/decisions/', ...(overrides.unitScope ? [`qa/${overrides.unitScope}/decisions/`] : [])];
+  const integrity: DecisionGateFinding[] = checkDecisionIntegrity(projectRoot)
+    .filter((f) => reach.some((r) => f.path.startsWith(r)))
+    .map((f) => ({ rule: f.rule, path: f.path, message: f.message }));
+  const rejected: DecisionGateFinding[] = overrides.rejected.map((r) => ({ rule: 'gate.override-rejected', path: r.path, message: `${r.decisionId}: ${r.reason}` }));
+  return [...integrity, ...rejected];
+}
+
+export function decisionFindingText(f: DecisionGateFinding): string {
+  return `⛔ ${f.rule}: ${f.path} — ${f.message}. Hard rule: restore the file from git, or record a superseding decision on a terminal.`;
+}

package/src/harness/gates/migrated-waiver-import-bounds.ts

@@ -0,0 +1,103 @@
+/**
+ * Could a migrated waiver's legacy record have been the source of the import that wrote it? (#925)
+ *
+ * The one-time import (legacy-waiver-migration.ts) reads a record git HEAD ALREADY holds, and only
+ * before 3.3 takes over. So a genuine record was committed strictly before each of:
+ *   1. the decision file's first appearance — its first commit, else its creation on disk;
+ *   2. the unit's import marker `.sungen/migrations/<slug>.waivers-imported.json` — the commit that
+ *      added the one HEAD holds (an agent can delete or recreate the file, not that commit), else its
+ *      creation on disk; once it exists the import never reads that unit's legacy file again;
+ *   3. the project's adoption of 3.3 — the first commit that added any 3.3-only file: an import marker
+ *      or other `.sungen/migrations/` file, a decision file (`qa/**\/decisions/*.yaml`) or a contract lock
+ *      (`qa/**\/contracts.lock.yaml`). Only the 3.3 CLI writes them, and only committed ones count: a
+ *      legacy waiver is one written before the project's first reviewed 3.3 change. Mixed versions pay
+ *      for it: a waiver a pre-3.3 CLI writes after that commit must be re-confirmed on a terminal.
+ * A record failing any bound claims a migration that never happened: the decision is in-run.
+ *
+ * What stays open (the limit of any time-based check, as for ordinary decisions): a record forged and
+ * committed before the project's first 3.3 commit — indistinguishable from a real legacy waiver, as on
+ * a project adopting 3.3 for the very first time — and commit times forged with GIT_COMMITTER_DATE.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { committedText, gitOutput } from '../../decisions/git-head-trust';
+import { formatCommand } from '../../decisions/human-confirmation';
+import { importMarkerPath } from '../../decisions/legacy-waiver-migration';
+import type { ReadDecision } from '../../decisions/read-decisions';
+
+/** Files only the 3.3 CLI writes, as pathspecs relative to the project. */
+const ADOPTION_PATHSPECS = ['.sungen/migrations', ':(glob)qa/**/decisions/*.yaml', ':(glob)qa/**/contracts.lock.yaml'];
+
+/**
+ * What a human does about a migrated waiver its legacy record cannot vouch for: record it anew on a
+ * terminal (a `cli` decision that supersedes it — the superseded one is no longer judged), or accept it
+ * for one delivery.
+ */
+export const migratedWaiverRemedy = (scope: string, ob: string): string =>
+  `re-confirm it on a terminal: ${formatCommand(['sungen', 'journey', '--screen', scope.split('/').pop() ?? scope, '--waive', ob, '--reason', '…'])}, `
+  + 'then commit the new decision; or accept it once with `sungen delivery --accept-in-run`';
+
+const validMs = (iso: string | undefined): number | null => (iso && !Number.isNaN(Date.parse(iso)) ? Date.parse(iso) : null);
+const createdMs = (abs: string): number | null => {
+  try { const s = fs.statSync(abs); return s.birthtimeMs || s.mtimeMs; } catch { return null; }
+};
+
+/** One run's bounds: each decision's first appearance, each unit's marker and the project's adoption, read once. */
+export function migratedWaiverImportBounds(projectRoot: string) {
+  const relOf = (abs: string): string => path.relative(projectRoot, abs).split(path.sep).join('/');
+  const firstSeen = new Map<string, number>();
+  const markers = new Map<string, number | null>();
+  let adoption: number | null | undefined;
+
+  /** When a decision file first appeared: its first commit, else its creation (or last change) on disk. */
+  const decisionMs = (e: ReadDecision): number => {
+    if (!firstSeen.has(e.path)) {
+      const added = gitOutput(projectRoot, ['log', '--diff-filter=A', '--format=%cI', '--', relOf(e.path)])?.trim().split('\n').filter(Boolean).pop();
+      firstSeen.set(e.path, validMs(added) ?? createdMs(e.path) ?? Number.NEGATIVE_INFINITY);
+    }
+    return firstSeen.get(e.path)!;
+  };
+  const markerMs = (slug: string): number | null => {
+    if (!markers.has(slug)) {
+      const abs = importMarkerPath(projectRoot, slug);
+      const added = committedText(projectRoot, abs) !== null
+        ? validMs(gitOutput(projectRoot, ['log', '-1', '--diff-filter=A', '--format=%cI', '--', relOf(abs)])?.trim()) : null;
+      markers.set(slug, added ?? createdMs(abs));
+    }
+    return markers.get(slug)!;
+  };
+  const adoptionMs = (): number | null => {
+    if (adoption === undefined) {
+      const added = (gitOutput(projectRoot, ['log', '--diff-filter=A', '--format=%cI', '--', ...ADOPTION_PATHSPECS]) ?? '')
+        .split('\n').map((l) => validMs(l.trim())).filter((t): t is number => t !== null);
+      adoption = added.length ? Math.min(...added) : null;
+    }
+    return adoption;
+  };
+
+  /** The first bound a record committed at `legacy` (ms) crosses, or undefined. */
+  const boundCrossed = (slug: string, e: ReadDecision, legacy: number): string | undefined => {
+    const decision = decisionMs(e);
+    if (legacy > decision) return 'after this decision first appeared';
+    if (legacy === decision) return 'when this decision first appeared, not before it — an import only reads a record already committed';
+    const marker = markerMs(slug);
+    if (marker !== null && legacy >= marker) {
+      return `after this unit's waivers were imported (${relOf(importMarkerPath(projectRoot, slug))}, ${new Date(marker).toISOString()}) `
+        + '— from then on the import never reads the legacy file';
+    }
+    const adopted = adoptionMs();
+    if (adopted !== null && legacy >= adopted) {
+      return `after this project adopted sungen 3.3 (${new Date(adopted).toISOString()}: the first commit adding a .sungen/migrations/ file, `
+        + 'a decision or a contract lock) — a legacy waiver is one written before that';
+    }
+    return undefined;
+  };
+
+  return {
+    /** Why a record committed at `at` (state file of `slug`) cannot have been the source of `e`'s import; undefined when it can. */
+    notImported(slug: string, e: ReadDecision, at: string): string | undefined {
+      const why = boundCrossed(slug, e, Date.parse(at));
+      return why && `migrated: its legacy record was committed at ${at}, ${why}; ${migratedWaiverRemedy(e.scope, String(e.payload?.obligation))}`;
+    },
+  };
+}

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

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