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

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,99 @@
+/**
+ * `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, with no run to compare,
+ * after the decision file 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 — is judged as any other.
+ */
+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 { decisionFirstSeenMs, migratedWaiverReviewedAt } 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);
+
+/** 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);
+  for (const scope of scopes) {
+    for (const e of readDecisions(projectRoot, scope).entries) {
+      if (!isInRunKind(e.kind)) continue;
+      const rel = path.relative(projectRoot, e.path).split(path.sep).join('/');
+      const why: string[] = [];
+      const legacyAt = committed ? migratedWaiverReviewedAt(projectRoot, scope, e) : null;
+      if (legacyAt) {
+        if (runStart ? after(legacyAt) : Date.parse(legacyAt) > decisionFirstSeenMs(projectRoot, rel, e.path)) {
+          why.push(runStart
+            ? `migrated: its legacy record was committed at ${legacyAt}, after the run started ${runStart}`
+            : `migrated: its legacy record was committed at ${legacyAt}, after this decision first appeared`);
+        }
+      } 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) 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-review.ts

@@ -0,0 +1,68 @@
+/**
+ * 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
+ *   with a run start   in-run when reviewedAt is after it (the same test as any committed decision)
+ *   without one        in-run when reviewedAt is after the decision file first appeared (its first
+ *             commit, else its creation time): a genuine import always follows the commit it read
+ * 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).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { committedText, gitOutput } 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';
+
+/** Commits of one state file the walk reads at most (each is one `git show`). */
+const MAX_COMMITS = 200;
+
+const parse = (text: string | null): { waivers?: Record<string, unknown> } | null => {
+  if (text === null) return null;
+  try { return JSON.parse(text.replace(/^/, '')); } catch { return null; }
+};
+
+function holds(state: { waivers?: Record<string, unknown> } | null, e: ReadDecision, ob: string): boolean {
+  const w = state?.waivers?.[ob];
+  return isLegacyWaiver(w) && w.at === e.valid_from && sameWaiver(w, asLegacyWaiver(e));
+}
+
+/** The commit time of the oldest commit, in the unbroken run back from HEAD, whose state file holds the record. */
+function introducedAt(projectRoot: string, rel: string, e: ReadDecision, ob: string): string | null {
+  const log = gitOutput(projectRoot, ['log', `--max-count=${MAX_COMMITS}`, '--format=%H %cI', '--', rel]) ?? '';
+  let oldest: string | null = null;
+  for (const line of log.split('\n').filter(Boolean)) {
+    const [sha, at] = line.split(' ');
+    if (!holds(parse(gitOutput(projectRoot, ['show', `${sha}:./${rel}`])), e, ob)) break;
+    oldest = at;
+  }
+  return oldest && !Number.isNaN(Date.parse(oldest)) ? oldest : null;
+}
+
+/** When a migrated waiver's legacy record was committed, or null when nothing in git HEAD vouches for it. */
+export function migratedWaiverReviewedAt(projectRoot: string, scope: string, e: ReadDecision): string | 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)\//, ''))]);
+  for (const slug of slugs) {
+    const file = path.join(projectRoot, '.sungen', 'journey', `${slug}.state.json`);
+    if (!holds(parse(committedText(projectRoot, file)), e, ob)) continue;
+    const at = introducedAt(projectRoot, path.relative(projectRoot, file).split(path.sep).join('/'), e, ob);
+    if (at) return at;
+  }
+  return null;
+}
+
+/** When a decision file first appeared: its first commit, else its creation (or last change) on disk. */
+export function decisionFirstSeenMs(projectRoot: string, rel: string, abs: string): number {
+  const added = gitOutput(projectRoot, ['log', '--diff-filter=A', '--format=%cI', '--', rel])?.trim().split('\n').filter(Boolean).pop();
+  if (added && !Number.isNaN(Date.parse(added))) return Date.parse(added);
+  try { const s = fs.statSync(abs); return s.birthtimeMs || s.mtimeMs; } catch { return Number.NEGATIVE_INFINITY; }
+}

package/src/harness/gates/resolve-rule.ts

@@ -0,0 +1,94 @@
+/**
+ * One `resolveRule` (OES-11.2). Code keeps computing a gate's CONDITION; what the condition costs —
+ * its severity, and whether that blocks — comes from here and nowhere else, so audit, sensors,
+ * script-check, matrix gates and journey cannot disagree about a rule (red-team #12).
+ *
+ * Two axes, never merged (takumi T5):
+ *   block vs advisory   follows severity — error|review block; warning|info|off never block
+ *   overridable or not  follows kind     — a hard rule ignores every override
+ * With no override in force the result IS the catalog row, which equals today's behavior.
+ */
+import { DecisionVisibility } from '../../decisions/decision-schema';
+import { GateKind, GateSeverity, gateRule, listRules, GateRule } from './gate-rule-catalog';
+
+export type OverrideSeverity = 'warning' | 'info' | 'off';
+export type ResolvedSeverity = GateSeverity | 'off';
+
+/** A gate-override decision that passed validation and is in force for one unit. */
+export interface ActiveOverride {
+  decisionId: string;
+  rule: string;
+  severity: OverrideSeverity;
+  scope: string;
+  reason: string;
+  visibility: DecisionVisibility;
+  by: string;
+  validFrom: string;
+  path: string;
+  /** In git HEAD? null outside git. An uncommitted override still counts here, but release refuses it (decision.in-run). */
+  committed: boolean | null;
+}
+
+export interface GateRuleContext {
+  /** rule id → the override in force for the unit being judged. */
+  overrides: ReadonlyMap<string, ActiveOverride>;
+}
+
+export const NO_OVERRIDES: GateRuleContext = Object.freeze({ overrides: new Map<string, ActiveOverride>() });
+
+export interface ResolvedRule {
+  id: string;
+  severity: ResolvedSeverity;
+  catalogSeverity: GateSeverity;
+  kind: GateKind;
+  blocking: boolean;
+  /** The decision id of the override that set `severity`, when one did. */
+  overriddenBy?: string;
+}
+
+export const isBlockingSeverity = (s: ResolvedSeverity): boolean => s === 'error' || s === 'review';
+
+/** Whether an override may apply to this rule at all (defense in depth behind validation). */
+function admissible(rule: GateRule, o: ActiveOverride | undefined): o is ActiveOverride {
+  if (!o || rule.kind === 'hard') return false;
+  return o.severity !== 'off' || rule.offAllowed;
+}
+
+export function resolveRule(id: string, ctx: GateRuleContext = NO_OVERRIDES): ResolvedRule {
+  const rule = gateRule(id);
+  const o = ctx.overrides.get(id);
+  if (!admissible(rule, o)) {
+    return { id, severity: rule.severity, catalogSeverity: rule.severity, kind: rule.kind, blocking: isBlockingSeverity(rule.severity) };
+  }
+  return { id, severity: o.severity, catalogSeverity: rule.severity, kind: rule.kind, blocking: isBlockingSeverity(o.severity), overriddenBy: o.decisionId };
+}
+
+export { listRules };
+
+/** What a gate site holds: resolve a rule whose condition it found met. */
+export interface GateRules {
+  resolve(id: string): ResolvedRule;
+}
+
+/** The catalog alone — today's behavior; the default wherever no unit context is known. */
+export const CATALOG_GATE_RULES: GateRules = Object.freeze({ resolve: (id: string) => resolveRule(id, NO_OVERRIDES) });
+
+export interface TrackedGateRules extends GateRules {
+  readonly context: GateRuleContext;
+  /** Rules whose override changed an outcome during this evaluation. */
+  triggered(): ReadonlySet<string>;
+}
+
+/** Resolve against one unit's overrides and remember which of them actually changed something. */
+export function trackGateRules(context: GateRuleContext): TrackedGateRules {
+  const fired = new Set<string>();
+  return {
+    context,
+    resolve(id: string): ResolvedRule {
+      const r = resolveRule(id, context);
+      if (r.overriddenBy) fired.add(id);
+      return r;
+    },
+    triggered: () => fired,
+  };
+}

package/src/harness/gates/unit-gate-overrides.ts

@@ -0,0 +1,99 @@
+/**
+ * The gate overrides in force for ONE unit, read from the decision layer (OES-11.2/11.3, DOS-13).
+ *
+ * Sources: `qa/decisions/` (project) and `qa/<kind>/<unit>/decisions/` (the unit). Only entries that
+ * verify against themselves are considered (readDecisions); superseded ones are out of force. Per
+ * rule the override in force is the most specific — an exact unit beats a glob — then the latest, then
+ * the higher decision id (deterministic). Each carries whether git HEAD holds it: an uncommitted one
+ * still counts (the author sees its effect), release refuses it (decision.in-run, review H1).
+ * Never throws: a bad file is a `problem`, a bad override is `rejected`.
+ */
+import * as path from 'path';
+import { isValidScope, PROJECT_SCOPE, DecisionProblem } from '../../decisions/decision-file';
+import { readDecisions, ReadDecision } from '../../decisions/read-decisions';
+import { judgeOverride } from './gate-override-validation';
+import { ActiveOverride, GateRuleContext } from './resolve-rule';
+import { computeDecisionsHash, DecisionsHashItem, problemHashItem } from './decisions-hash';
+import { committedDecisionPaths } from './in-run-decision-check';
+
+export interface OverrideIssue {
+  decisionId: string;
+  path: string;
+  rule?: string;
+  reason: string;
+  entry: ReadDecision;
+  committed: boolean | null;
+}
+
+export interface UnitGateOverrides {
+  unitScope: string | null;
+  context: GateRuleContext;
+  inForce: ActiveOverride[];
+  rejected: OverrideIssue[];
+  ineffective: OverrideIssue[];
+  /** Files in the two directories that do not verify (DOS-13.3) — reported, never skipped. */
+  problems: DecisionProblem[];
+  decisionsHash: string;
+}
+
+/** The decision scope of a unit directory (`screens/login`, `api/flows/signup`), or null. */
+export function unitScopeOfDir(projectRoot: string, unitDir: string): string | null {
+  const rel = path.relative(path.join(projectRoot, 'qa'), unitDir).split(path.sep).join('/');
+  return rel && !rel.startsWith('..') && isValidScope(rel) && rel !== PROJECT_SCOPE ? rel : null;
+}
+
+const specificity = (o: ActiveOverride, unitScope: string | null): number => (o.scope === unitScope ? 1 : 0);
+
+/** Does `a` take precedence over `b` for the same rule? valid_from is schema-checked ISO; NaN never orders. */
+function wins(a: ActiveOverride, b: ActiveOverride, unitScope: string | null): boolean {
+  const s = specificity(a, unitScope) - specificity(b, unitScope);
+  if (s !== 0) return s > 0;
+  const t = (Date.parse(a.validFrom) || 0) - (Date.parse(b.validFrom) || 0);
+  return t !== 0 ? t > 0 : a.decisionId > b.decisionId;
+}
+
+export function loadUnitGateOverrides(projectRoot: string, unitScope: string | null): UnitGateOverrides {
+  const scopes = unitScope ? [PROJECT_SCOPE, unitScope] : [PROJECT_SCOPE];
+  const entries: ReadDecision[] = [];
+  const problems: DecisionProblem[] = [];
+  for (const s of scopes) {
+    const r = readDecisions(projectRoot, s);
+    entries.push(...r.entries);
+    problems.push(...r.problems);
+  }
+  const rel = (p: string): string => path.relative(projectRoot, p).split(path.sep).join('/');
+  const hashItems: DecisionsHashItem[] = problems.map((p) => problemHashItem(projectRoot, p));
+  const byRule = new Map<string, ActiveOverride>();
+  const rejected: OverrideIssue[] = [];
+  const ineffective: OverrideIssue[] = [];
+  // HEAD membership is read once, and only when an override is in reach (two git calls).
+  let head: Set<string> | null | undefined;
+  const inHead = (p: string): boolean | null => {
+    if (head === undefined) head = committedDecisionPaths(projectRoot);
+    return head ? head.has(p) : null;
+  };
+
+  for (const e of entries.filter((x) => x.kind === 'gate-override')) {
+    const j = judgeOverride(e, unitScope);
+    if (j.status === 'irrelevant') continue;
+    const p = rel(e.path);
+    hashItems.push({ path: p, entryHash: e.entry_hash });
+    if (e.superseded_by) continue;
+    const rule = typeof e.payload?.rule === 'string' ? e.payload.rule : undefined;
+    const issue = { decisionId: e.id, path: p, rule, entry: e, committed: inHead(p) };
+    if (j.status === 'rejected') { rejected.push({ ...issue, reason: j.reason }); continue; }
+    if (j.status === 'ineffective') { ineffective.push({ ...issue, reason: j.reason }); continue; }
+    const o: ActiveOverride = { ...j.override, committed: issue.committed };
+    const current = byRule.get(o.rule);
+    if (!current || wins(o, current, unitScope)) byRule.set(o.rule, o);
+  }
+  return {
+    unitScope,
+    context: { overrides: byRule },
+    inForce: [...byRule.values()].sort((a, b) => a.rule.localeCompare(b.rule, 'en')),
+    rejected,
+    ineffective,
+    problems,
+    decisionsHash: computeDecisionsHash(hashItems),
+  };
+}