@sun-asterisk/sungen 3.2.34-beta.1 → 3.3.0-alpha.1

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

@@ -0,0 +1,111 @@
+/**
+ * The decision checks `sungen delivery` runs before it writes anything (OES-11.3–11.6):
+ *
+ *   hard, block   a decision in reach that does not verify or a committed one edited/deleted
+ *                 (decision.id-reuse / decision.mutated); a rejected override (gate.override-rejected);
+ *                 a decision recorded during the run (decision.in-run) — unless a human accepts it
+ *                 on a TTY with `--accept-in-run`
+ *   no trusted    no audit report, or one that does not count (stale, invalid, verdict-mismatch):
+ *   audit         a real delivery stops and asks for `sungen audit` (owner decision 2026-10-22);
+ *                 `--preview` / `--check` go on with a warning — the caller decides (`untrustedAudits`)
+ * It also hands each target its gate rules (catalog + overrides) for the matrix gates, and the
+ * override rows the XLSX may show. With no decision in reach nothing here changes the delivery.
+ */
+import { checkDecisionIntegrity, DecisionFinding } from '../../decisions/decision-integrity-check';
+import { PROJECT_SCOPE } from '../../decisions/decision-file';
+import { auditCounts, verifyAuditReport } from './audit-report-verification';
+import { GateOverrideReport, gateOverrideReports, gateOverrideSummaryLine, InRunAcceptance } from './gate-override-report';
+import { unitsCoveredByScope } from './gate-override-scope';
+import { committedDecisionPaths, hasInRunKindDecisions, inRunDecisions, InRunDecision, IN_RUN_RULE, runStartOf } from './in-run-decision-check';
+import { resolveRule, trackGateRules, TrackedGateRules } from './resolve-rule';
+import { loadUnitGateOverrides, unitScopeOfDir, UnitGateOverrides } from './unit-gate-overrides';
+
+export interface DeliveryUnitRef { label: string; unitName: string; unitDir: string; resultsPath: string | null }
+
+interface UnitState {
+  ref: DeliveryUnitRef;
+  /** Every delivered run of the unit (one per feature file); a decision after ANY of their starts is in-run. */
+  resultsPaths: Array<string | null>;
+  overrides: UnitGateOverrides;
+  rules: TrackedGateRules;
+  auditTriggered: Set<string>;
+}
+
+export interface DeliveryDecisionGate {
+  blocking: string[];
+  /** Units with no trusted audit — a real delivery stops on them, --preview / --check warn. */
+  untrustedAudits: string[];
+  notes: string[];
+  inRun: Array<InRunDecision & { unit: string }>;
+  /** The unit's tracked gate rules, for the matrix gates of its targets. */
+  rulesFor(unitDir: string): TrackedGateRules | undefined;
+  /** Every override touching the unit, with what changed an outcome (audit or matrix). */
+  overridesFor(unitDir: string): GateOverrideReport[];
+  summaryLines(): string[];
+  /** Set when a human accepted the in-run decisions on a terminal (--accept-in-run) — goes into the deliverable. */
+  acceptedInRun?: InRunAcceptance;
+}
+
+const reachOf = (scope: string | null): string[] => [`qa/decisions/`, ...(scope ? [`qa/${scope}/decisions/`] : [])];
+
+export function evaluateDeliveryDecisions(projectRoot: string, refs: DeliveryUnitRef[]): DeliveryDecisionGate {
+  const blocking: string[] = [];
+  const untrustedAudits: string[] = [];
+  const notes: string[] = [];
+  const inRun: DeliveryDecisionGate['inRun'] = [];
+  const units = new Map<string, UnitState>();
+  for (const ref of refs) {
+    const known = units.get(ref.unitDir);
+    if (known) { known.resultsPaths.push(ref.resultsPath); continue; }
+    const overrides = loadUnitGateOverrides(projectRoot, unitScopeOfDir(projectRoot, ref.unitDir));
+    const audit = verifyAuditReport(projectRoot, ref.unitName);
+    const auditTriggered = new Set(auditCounts(audit) && Array.isArray(audit.report?.gateOverrides)
+      ? (audit.report!.gateOverrides as GateOverrideReport[]).filter((g) => g?.triggered).map((g) => g.rule) : []);
+    units.set(ref.unitDir, { ref, resultsPaths: [ref.resultsPath], overrides, rules: trackGateRules(overrides.context), auditTriggered });
+    for (const r of overrides.rejected) blocking.push(`${ref.label}: gate.override-rejected — ${r.decisionId} (${r.path}): ${r.reason}`);
+    if (!auditCounts(audit)) {
+      const why = audit.state === 'absent' ? 'no audit report' : `the audit is ${audit.state === 'stale' ? 'stale' : 'not trusted'}: ${audit.problems.map((p) => p.message).join('; ')}`;
+      const flag = /[\\/]qa[\\/]api[\\/]/.test(ref.unitDir) ? '--api' : '--screen';
+      untrustedAudits.push(`${ref.label}: ${why} — re-run \`sungen audit ${flag} ${ref.unitName}\``);
+    }
+    for (const n of audit.notes) notes.push(`${ref.label}: ${n}`);
+  }
+
+  const reach = new Set([...units.values()].flatMap((u) => reachOf(u.overrides.unitScope)));
+  const integrity: DecisionFinding[] = checkDecisionIntegrity(projectRoot).filter((f) => [...reach].some((r) => f.path.startsWith(r)));
+  for (const f of integrity) if (resolveRule(f.rule).blocking) blocking.push(`${f.rule} — ${f.path}: ${f.message}`);
+
+  const committed = committedDecisionPaths(projectRoot);
+  for (const u of units.values()) {
+    const scopes = [PROJECT_SCOPE, ...(u.overrides.unitScope ? [u.overrides.unitScope] : [])];
+    const starts = u.resultsPaths.map(runStartOf).filter((t): t is string => !!t).sort((x, y) => Date.parse(x) - Date.parse(y));
+    const runStart = starts[0] ?? null;
+    if (!committed && hasInRunKindDecisions(projectRoot, scopes)) {
+      notes.push(runStart
+        ? `${u.ref.label}: no git repository — ${IN_RUN_RULE} is judged by the run start time only (lower confidence)`
+        : `${u.ref.label}: no git repository and no run results — ${IN_RUN_RULE} cannot be judged for its decisions`);
+    }
+    for (const d of inRunDecisions(projectRoot, scopes, runStart, committed)) {
+      if (!inRun.some((x) => x.id === d.id)) inRun.push({ ...d, unit: u.ref.label });
+    }
+  }
+
+  const reportsFor = (u: UnitState): GateOverrideReport[] =>
+    gateOverrideReports(u.overrides, new Set([...u.auditTriggered, ...u.rules.triggered()]));
+  return {
+    blocking,
+    untrustedAudits,
+    notes,
+    inRun,
+    rulesFor: (dir) => units.get(dir)?.rules,
+    overridesFor: (dir) => { const u = units.get(dir); return u ? reportsFor(u) : []; },
+    summaryLines: () => [...units.values()]
+      .map((u) => gateOverrideSummaryLine(u.ref.label, reportsFor(u), (scope) => unitsCoveredByScope(projectRoot, scope)))
+      .filter((l): l is string => !!l),
+  };
+}
+
+/** The in-run decisions, one line each, for the refusal or the TTY confirmation. */
+export function inRunLines(inRun: DeliveryDecisionGate['inRun']): string[] {
+  return inRun.map((d) => `${d.unit}: ${d.kind} ${d.id} (${d.path}) — ${d.why.join('; ')}`);
+}

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

@@ -0,0 +1,73 @@
+/**
+ * The `sungen delivery` step for decisions (OES-11.5): evaluate, print, and either stop or go.
+ * In-run decisions stop the delivery unless a human passes `--accept-in-run` AND confirms on a TTY
+ * (DOS-13.4) — without a TTY the refusal prints the exact command for a human to run.
+ */
+import { gitUserName } from '../../decisions/decision-source';
+import { ConfirmationIO, formatCommand, HumanConfirmationRefused, requireTypedConfirmation } from '../../decisions/human-confirmation';
+import { DeliveryDecisionGate, DeliveryUnitRef, evaluateDeliveryDecisions, inRunLines } from './delivery-decision-gate';
+import { IN_RUN_RULE } from './in-run-decision-check';
+
+export interface DeliveryDecisionStepInput {
+  projectRoot: string;
+  refs: DeliveryUnitRef[];
+  acceptInRun: boolean;
+  /** The delivery command line to print for a human, without `--accept-in-run`. */
+  argv: string[];
+  io: ConfirmationIO;
+  log: (line: string) => void;
+  /** A real export needs a trusted audit per unit (owner decision 2026-10-22); false for --preview / --check. */
+  requireTrustedAudit: boolean;
+}
+
+/** The gate when the delivery may proceed; null when it must stop (already explained on `log`). */
+export async function runDeliveryDecisionStep(i: DeliveryDecisionStepInput): Promise<DeliveryDecisionGate | null> {
+  const gate = evaluateDeliveryDecisions(i.projectRoot, i.refs);
+  for (const n of gate.notes) i.log(`  · ${n}`);
+  if (gate.blocking.length) {
+    i.log(`✗ Delivery blocked by ${gate.blocking.length} decision problem(s) (hard rules):`);
+    for (const b of gate.blocking) i.log(`  - ${b}`);
+    return null;
+  }
+  if (gate.untrustedAudits.length) {
+    i.log(i.requireTrustedAudit
+      ? `✗ Delivery blocked — ${gate.untrustedAudits.length} unit(s) without a trusted audit (a delivery stands on an audit that matches today's suite):`
+      : `⚠ Rendering ${gate.untrustedAudits.length} unit(s) without a trusted audit — a draft, not an official delivery:`);
+    for (const u of gate.untrustedAudits) i.log(`  - ${u}`);
+    if (i.requireTrustedAudit) {
+      i.log('  Or render a watermarked draft with --preview.');
+      return null;
+    }
+  }
+  if (gate.inRun.length === 0) return gate;
+  const acceptCommand = formatCommand([...i.argv, '--accept-in-run']);
+  if (!i.acceptInRun) {
+    i.log(`✗ Delivery blocked — ${gate.inRun.length} decision(s) recorded during the run (${IN_RUN_RULE}, hard):`);
+    for (const l of inRunLines(gate.inRun)) i.log(`  - ${l}`);
+    i.log('  Commit them through review and re-run the tests, or have a human accept them on a terminal:');
+    i.log(`    ${acceptCommand}`);
+    return null;
+  }
+  try {
+    await requireTypedConfirmation({
+      what: `deliver with ${gate.inRun.length} decision(s) recorded during the run (${IN_RUN_RULE})`,
+      phrase: 'accept-in-run',
+      command: acceptCommand,
+      summary: [...inRunLines(gate.inRun), `accepted by: ${gitUserName(i.projectRoot)}`],
+      io: i.io,
+    });
+  } catch (err) {
+    if (!(err instanceof HumanConfirmationRefused)) throw err;
+    i.log(`✗ ${err.message}`);
+    return null;
+  }
+  const by = gitUserName(i.projectRoot);
+  i.log(`  ✓ ${gate.inRun.length} in-run decision(s) accepted by ${by} on a terminal.`);
+  // Persisted into the deliverable's manifest (L5): who, when, which — internal ones only counted.
+  gate.acceptedInRun = {
+    by, at: new Date().toISOString(),
+    ids: gate.inRun.filter((d) => d.visibility === 'client').map((d) => d.id),
+    internalCount: gate.inRun.filter((d) => d.visibility !== 'client').length,
+  };
+  return gate;
+}

package/src/harness/gates/gate-override-report.ts

@@ -0,0 +1,114 @@
+/**
+ * How gate overrides are SHOWN (OES-11.6, red-team #14): `audit.json` `gateOverrides[]`, the
+ * delivery's one-line summary, the XLSX "Gate overrides" sheet and the CSV manifest line, with the
+ * `PASS (overridden)` status. A `visibility: internal` decision is counted everywhere and exported
+ * nowhere (XLSX/CSV) — not even its id.
+ */
+import { GateSeverity, findGateRule } from './gate-rule-catalog';
+import { OverrideIssue, UnitGateOverrides } from './unit-gate-overrides';
+import { ActiveOverride } from './resolve-rule';
+
+export type GateOverrideStatus = 'applied' | 'ineffective' | 'rejected';
+
+export interface GateOverrideReport {
+  decisionId: string;
+  rule: string;
+  severity: string;
+  catalogSeverity: GateSeverity | null;
+  scope: string;
+  reason: string;
+  visibility: 'internal' | 'client';
+  by: string;
+  validFrom: string;
+  status: GateOverrideStatus;
+  /** An applied override that changed an outcome here (it lowered a condition that was met). */
+  triggered: boolean;
+  /** In git HEAD when this was written; null outside git. False = counted here, refused at release. */
+  committed: boolean | null;
+  detail?: string;
+}
+
+const fromActive = (o: ActiveOverride, triggered: boolean): GateOverrideReport => ({
+  decisionId: o.decisionId, rule: o.rule, severity: o.severity, catalogSeverity: findGateRule(o.rule)?.severity ?? null,
+  scope: o.scope, reason: o.reason, visibility: o.visibility, by: o.by, validFrom: o.validFrom, status: 'applied', triggered,
+  committed: o.committed,
+});
+
+function fromIssue(i: OverrideIssue, status: GateOverrideStatus): GateOverrideReport {
+  const p = (i.entry.payload ?? {}) as Record<string, unknown>;
+  const rule = typeof p.rule === 'string' ? p.rule : String(p.rule ?? '');
+  return {
+    decisionId: i.decisionId, rule, severity: String(p.severity ?? ''), catalogSeverity: findGateRule(rule)?.severity ?? null,
+    scope: String(p.scope ?? ''), reason: i.entry.reason, visibility: i.entry.visibility, by: i.entry.source.by,
+    validFrom: i.entry.valid_from, status, triggered: false, committed: i.committed, detail: i.reason,
+  };
+}
+
+/** Every override that touches the unit, in a stable order: applied, then ineffective, then rejected. */
+export function gateOverrideReports(o: UnitGateOverrides, triggered: ReadonlySet<string>): GateOverrideReport[] {
+  return [
+    ...o.inForce.map((x) => fromActive(x, triggered.has(x.rule))),
+    ...o.ineffective.map((x) => fromIssue(x, 'ineffective')),
+    ...o.rejected.map((x) => fromIssue(x, 'rejected')),
+  ];
+}
+
+/** `PASS (overridden)` when a pass leaned on at least one applied override. */
+export function gateStatusLabel(status: 'PASS' | 'FAIL', reports: GateOverrideReport[]): string {
+  return status === 'PASS' && reports.some((r) => r.status === 'applied' && r.triggered) ? 'PASS (overridden)' : status;
+}
+
+/** What a deliverable may carry: client-visible rows only, plus how many internal ones were withheld. */
+export function exportableOverrides(reports: GateOverrideReport[]): { rows: GateOverrideReport[]; internalCount: number } {
+  return {
+    rows: reports.filter((r) => r.visibility === 'client'),
+    internalCount: reports.filter((r) => r.visibility !== 'client').length,
+  };
+}
+
+/**
+ * One line for the delivery summary, or null when nothing touches the unit. With `unitsCovered`, each
+ * applied glob override also says how many units it reaches (L1) — a glob is easy to underestimate.
+ */
+export function gateOverrideSummaryLine(unit: string, reports: GateOverrideReport[], unitsCovered?: (scope: string) => number): string | null {
+  if (reports.length === 0) return null;
+  const count = (s: GateOverrideStatus) => reports.filter((r) => r.status === s).length;
+  const { rows, internalCount } = exportableOverrides(reports);
+  const globs = unitsCovered
+    ? reports.filter((r) => r.status === 'applied' && /[*?]/.test(r.scope)).map((r) => ` · ${r.decisionId} (${r.scope}) covers ${unitsCovered(r.scope)} units`)
+    : [];
+  return `${unit}: gate overrides — ${count('applied')} applied (${reports.filter((r) => r.triggered).length} changed an outcome), `
+    + `${count('ineffective')} ineffective, ${count('rejected')} rejected · ${rows.length} client-visible, ${internalCount} internal (counted, never exported)`
+    + globs.join('');
+}
+
+/** Who accepted in-run decisions on a terminal for this delivery (L5) — ids of client-visible ones only. */
+export interface InRunAcceptance { by: string; at: string; ids: string[]; internalCount: number }
+
+/** What a matrix deliverable carries about overrides: client rows only, the internal count, and the status. */
+export interface DeliverableGateOverrides {
+  status: string;
+  rows: GateOverrideReport[];
+  internalCount: number;
+  acceptedInRun?: InRunAcceptance;
+}
+
+/** The XLSX sheet / CSV manifest payload, or undefined when nothing touches the unit (no sheet at all). */
+export function deliverableGateOverrides(reports: GateOverrideReport[], reviewPending: boolean, acceptedInRun?: InRunAcceptance): DeliverableGateOverrides | undefined {
+  if (reports.length === 0 && !acceptedInRun) return undefined;
+  const { rows, internalCount } = exportableOverrides(reports);
+  return {
+    status: reviewPending ? 'REVIEW PENDING (draft)' : gateStatusLabel('PASS', reports), rows, internalCount,
+    ...(acceptedInRun ? { acceptedInRun } : {}),
+  };
+}
+
+/** The CSV manifest lines (L4/L5): a CSV-only reader still learns what the delivery leaned on. */
+export function overrideManifestLines(o: DeliverableGateOverrides | undefined): string[] {
+  if (!o) return [];
+  const rows = o.rows.map((r) => `${r.rule} ${r.catalogSeverity ?? '?'} → ${r.severity} (${r.decisionId}, ${r.scope})`).join('; ');
+  const lines = [`# gate overrides: ${o.status}${rows ? ` · ${rows}` : ''} · ${o.internalCount} internal not listed`];
+  const a = o.acceptedInRun;
+  if (a) lines.push(`# accepted in-run decisions: by ${a.by} at ${a.at}${a.ids.length ? ` — ${a.ids.join(', ')}` : ''}${a.internalCount ? ` (${a.internalCount} internal, ids withheld)` : ''}`);
+  return lines;
+}

package/src/harness/gates/gate-override-scope.ts

@@ -0,0 +1,66 @@
+/**
+ * The `scope` of a gate override (OES-11.3, red-team #15): one unit, or a glob inside ONE kind.
+ *
+ *   screens/login       one unit                        api/flows/signup   one api flow
+ *   screens/log*        every screen whose name matches  flows/*            every flow
+ *   **  ·  screens/**   rejected — a switch that turns the gate off for everything
+ *   * /login · s*s/x    rejected — the kind must be literal, so a scope never crosses kinds
+ *
+ * Only `*` and `?` are glob characters, and neither crosses a `/`; so `api/*` never reaches an api
+ * flow (`api/flows/<f>`), which is its own kind.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export const OVERRIDE_SCOPE_KINDS =['screens', 'flows', 'api', 'api/flows'] as const;
+export type OverrideScopeKind = typeof OVERRIDE_SCOPE_KINDS[number];
+
+export interface OverrideScope {
+  kind: OverrideScopeKind;
+  unit: string;
+  glob: boolean;
+  text: string;
+}
+
+const UNIT_RE = /^[A-Za-z0-9._*?-]+$/;
+
+export function parseOverrideScope(scope: unknown): { scope: OverrideScope } | { error: string } {
+  if (typeof scope !== 'string' || !scope.trim()) return { error: 'scope is required: one unit (screens/login) or a glob inside one kind (screens/log*)' };
+  const text = scope.trim();
+  if (text.includes('**')) return { error: `scope "${text}" uses \`**\` — an override covers one unit or a glob inside one kind, never everything` };
+  const kind = text.startsWith('api/flows/') ? 'api/flows' : text.split('/')[0];
+  if (/[*?]/.test(kind)) return { error: `scope "${text}" globs the unit kind — a scope must stay inside one kind (screens, flows, api, api/flows)` };
+  if (!(OVERRIDE_SCOPE_KINDS as readonly string[]).includes(kind)) {
+    return { error: `scope "${text}" names no unit kind — start it with screens/, flows/, api/ or api/flows/` };
+  }
+  const unit = text.slice(kind.length + 1);
+  if (!unit || unit === '.' || unit === '..' || !UNIT_RE.test(unit)) {
+    return { error: `scope "${text}" must name one unit (or a glob of unit names with * and ?) after "${kind}/"` };
+  }
+  return { scope: { kind: kind as OverrideScopeKind, unit, glob: /[*?]/.test(unit), text } };
+}
+
+function globRegex(glob: string): RegExp {
+  const body = glob.replace(/[.+^${}()|[\]\\-]/g, '\\$&').replace(/\*/g, '[^/]*').replace(/\?/g, '[^/]');
+  return new RegExp(`^${body}$`);
+}
+
+/** How many of the project's units a (valid) scope reaches — 0 for an unparseable one. */
+export function unitsCoveredByScope(projectRoot: string, scope: string): number {
+  const parsed = parseOverrideScope(scope);
+  if ('error' in parsed) return 0;
+  let names: string[] = [];
+  try {
+    names = fs.readdirSync(path.join(projectRoot, 'qa', ...parsed.scope.kind.split('/')), { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !(parsed.scope.kind === 'api' && e.name === 'flows')).map((e) => e.name);
+  } catch { /* the project has no unit of that kind */ }
+  return names.filter((n) => overrideScopeMatches(parsed.scope, `${parsed.scope.kind}/${n}`)).length;
+}
+
+/** Does the override scope cover the unit whose decision scope is `unitScope` (e.g. `screens/login`)? */
+export function overrideScopeMatches(s: OverrideScope, unitScope: string): boolean {
+  const kind = unitScope.startsWith('api/flows/') ? 'api/flows' : unitScope.split('/')[0];
+  if (kind !== s.kind) return false;
+  const unit = unitScope.slice(kind.length + 1);
+  return s.glob ? globRegex(s.unit).test(unit) : unit === s.unit;
+}

package/src/harness/gates/gate-override-validation.ts

@@ -0,0 +1,75 @@
+/**
+ * Is a `gate-override` decision admissible, and for which unit? (OES-11.3, red-team #15, takumi T5)
+ *
+ * Shape: payload `{rule, severity: warning|info|off, scope, humanAccepted?}` + the entry's `reason`.
+ *   rejected   (gate.override-rejected, hard) — unknown rule or key, hard rule, severity outside
+ *              warning|info|off, `off` on a rule without `offAllowed`, reason under 15 characters,
+ *              a bad scope, a unit's own decision reaching another unit, humanAccepted not `true`
+ *   ineffective — well-formed but `humanAccepted` absent: present means effective, so it relaxes
+ *              nothing; and its absence alone blocks nothing either
+ *   irrelevant — a valid scope that does not cover the unit being judged
+ * An unparseable scope cannot be placed, so it is rejected for every unit.
+ */
+import { PROJECT_SCOPE } from '../../decisions/decision-file';
+import { ReadDecision } from '../../decisions/read-decisions';
+import { findGateRule } from './gate-rule-catalog';
+import { overrideScopeMatches, parseOverrideScope } from './gate-override-scope';
+import { ActiveOverride, OverrideSeverity } from './resolve-rule';
+
+export const OVERRIDE_SEVERITIES: readonly OverrideSeverity[] = ['warning', 'info', 'off'];
+export const MIN_OVERRIDE_REASON = 15;
+const PAYLOAD_KEYS = new Set(['rule', 'severity', 'scope', 'humanAccepted']);
+
+export type OverrideJudgement =
+  | { status: 'irrelevant' }
+  | { status: 'rejected'; reason: string }
+  | { status: 'ineffective'; reason: string; override: ActiveOverride }
+  | { status: 'accepted'; override: ActiveOverride };
+
+/**
+ * Everything that makes an override inadmissible regardless of the unit being judged — the checks
+ * `journey --decide gate-override` runs BEFORE the prompt, so a human never confirms a rejected one.
+ * `humanAccepted` is checked separately: the confirmation sets it, a caller never supplies it.
+ */
+export function overridePayloadErrors(payload: unknown, reason: string, fileScope: string): string[] {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return ['payload must be {rule, severity, scope}'];
+  const p = payload as Record<string, unknown>;
+  const errors: string[] = [];
+  for (const k of Object.keys(p)) if (!PAYLOAD_KEYS.has(k)) errors.push(`unknown payload key "${k}" (allowed: rule, severity, scope)`);
+  const parsed = parseOverrideScope(p.scope);
+  if ('error' in parsed) errors.push(parsed.error);
+  else if (fileScope !== PROJECT_SCOPE && (parsed.scope.glob || parsed.scope.text !== fileScope)) {
+    errors.push(`a decision recorded under qa/${fileScope}/ can only override ${fileScope} (scope is "${parsed.scope.text}") — record a wider one in qa/decisions/`);
+  }
+  const rule = typeof p.rule === 'string' ? findGateRule(p.rule) : undefined;
+  if (!rule) errors.push(`unknown rule "${String(p.rule)}" — it must be an id from harness/catalog/gate-rules.yaml`);
+  else if (rule.kind === 'hard') errors.push(`${rule.id} is a hard rule — it can never be overridden (${rule.rationale})`);
+  if (!OVERRIDE_SEVERITIES.includes(p.severity as OverrideSeverity)) errors.push(`severity must be warning | info | off (got ${JSON.stringify(p.severity)})`);
+  else if (p.severity === 'off' && rule && rule.kind === 'soft' && !rule.offAllowed) errors.push(`${rule.id} cannot be switched off (offAllowed: false) — lower it to warning or info instead`);
+  if (reason.trim().length < MIN_OVERRIDE_REASON) errors.push(`the reason must say why in at least ${MIN_OVERRIDE_REASON} characters`);
+  return errors;
+}
+
+function asOverride(e: ReadDecision, p: Record<string, unknown>): ActiveOverride {
+  return {
+    decisionId: e.id, rule: String(p.rule), severity: p.severity as OverrideSeverity, scope: String(p.scope).trim(),
+    reason: e.reason, visibility: e.visibility, by: e.source.by, validFrom: e.valid_from, path: e.path, committed: null,
+  };
+}
+
+export function judgeOverride(e: ReadDecision, unitScope: string | null): OverrideJudgement {
+  const p = (e.payload ?? {}) as Record<string, unknown>;
+  const parsed = parseOverrideScope(p.scope);
+  if ('scope' in parsed && (!unitScope || !overrideScopeMatches(parsed.scope, unitScope))) {
+    // A unit's own decision that names another unit is still that unit's problem.
+    if (e.scope === PROJECT_SCOPE || e.scope !== unitScope) return { status: 'irrelevant' };
+  }
+  const errors = overridePayloadErrors(p, e.reason, e.scope);
+  if (p.humanAccepted !== undefined && p.humanAccepted !== true) errors.push('humanAccepted is set only by a TTY confirmation, and only to true');
+  if (errors.length) return { status: 'rejected', reason: errors.join('; ') };
+  const override = asOverride(e, p);
+  if (p.humanAccepted !== true) {
+    return { status: 'ineffective', reason: 'not confirmed by a human on a TTY (humanAccepted absent) — it relaxes nothing', override };
+  }
+  return { status: 'accepted', override };
+}

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';
+}