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

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

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

package/src/harness/gates/delivery-checklist.ts

@@ -0,0 +1,120 @@
+/**
+ * The delivery checklist (P0 phase 09, takumi T6) — `sungen delivery` prints one block per delivered
+ * unit, and every box is read off a result REBUILT NOW, never from a report file and never by hand:
+ *
+ *   audit           verifyAuditReport: a report that counts and its gateStatus   (`sungen audit` 0 | 2)
+ *   script-check    runScriptCheck: OK | FAIL                                    (`sungen script-check` 0 | 2)
+ *   contract check  buildContractVerdict: pass | review | fail                   (`sungen contract check` 0 | 0 | 2)
+ *   decisions       evaluateDeliveryDecisions: problems, in-run decisions        (what this delivery checks)
+ *   triage          testCaseStates: every red case classified, candidates decided
+ * A box that cannot apply is SKIPPED with its reason — never absent, never ticked. The checklist only
+ * reports: the gates before it decide whether the delivery runs, so no exit code moves because of it.
+ */
+import { buildContractVerdict } from '../../contract/build-contract-verdict';
+import { readTextOrNull } from '../../contract/contract-git';
+import { lockPathFor } from '../../contract/contracts-lock-file';
+import { testCaseNeed } from '../../graph/test-case-satisfied';
+import { testCaseStates } from '../../graph/test-case-states';
+import { runScriptCheck, UnitKind } from '../script-check';
+import { auditCounts, auditNotCountedReason, verifyAuditReport } from './audit-report-verification';
+import { evaluateDeliveryDecisions } from './delivery-decision-gate';
+import type { InRunAcceptance } from './gate-override-report';
+
+export type BoxState = 'pass' | 'fail' | 'skipped';
+export interface ChecklistBox { name: string; state: BoxState; evidence: string }
+export interface ChecklistUnit { label: string; unitName: string; unitDir: string; kind: UnitKind; resultsPath: string | null }
+
+/** `sungen contract check` judges traces with a generous deadline; the checklist states what it would say. */
+const CONTRACT_TRACE_BUDGET_MS = 120_000;
+const why = (e: unknown): string => (e instanceof Error ? e.message : String(e)).split('\n')[0].slice(0, 200);
+const box = (name: string, state: BoxState, evidence: string): ChecklistBox => ({ name, state, evidence });
+
+function auditBox(projectRoot: string, u: ChecklistUnit): ChecklistBox {
+  const v = verifyAuditReport(projectRoot, u.unitName);
+  if (!auditCounts(v)) return box('audit', 'fail', auditNotCountedReason(v, u.unitName));
+  const overall = (v.report?.score as { overall?: number } | undefined)?.overall;
+  const how = "verified against today's inputs";
+  return v.report?.gateStatus === 'PASS'
+    ? box('audit', 'pass', `PASS ${overall ?? '?'}/10 — ${how}`)
+    : box('audit', 'fail', `FAIL ${overall ?? '?'}/10 — \`sungen audit\` exits 2 (${how}); an official delivery is blocked until it passes — --preview renders a draft`);
+}
+
+/** The compiler prints progress on stdout; the checklist keeps the delivery output to itself. */
+async function quietly<T>(fn: () => Promise<T>): Promise<T> {
+  const saved = { log: console.log, info: console.info, warn: console.warn };
+  console.log = console.info = console.warn = () => undefined;
+  try { return await fn(); } finally { Object.assign(console, saved); }
+}
+
+async function scriptCheckBox(u: ChecklistUnit): Promise<ChecklistBox> {
+  try {
+    const r = await quietly(() => runScriptCheck(u.unitDir, u.unitName, u.kind));
+    if (!r.specPath) return box('script-check', 'skipped', 'no compiled spec to compare: nothing was compiled for this unit');
+    return r.status === 'OK'
+      ? box('script-check', 'pass', `OK — the spec is a 1:1 of the .feature, no drift (${r.automatedScenarios} automated)`)
+      : box('script-check', 'fail', `FAIL — ${(r.findings[0] ?? 'not faithful').split(/ → |\. /)[0].slice(0, 160)} (\`sungen script-check\` exits 2)`);
+  } catch (e) {
+    return box('script-check', 'fail', `could not run: ${why(e)}`);
+  }
+}
+
+function contractBox(projectRoot: string, u: ChecklistUnit): ChecklistBox {
+  try {
+    const v = buildContractVerdict(projectRoot, { name: u.unitName, dir: u.unitDir }, { traceBudgetMs: CONTRACT_TRACE_BUDGET_MS });
+    if (readTextOrNull(lockPathFor(u.unitDir)) === null) {
+      return box('contract check', 'skipped', `no contracts.lock.yaml: ${v.scenarios.length} scenario(s) proposed, nothing approved to compare (never blocks)`);
+    }
+    const bad = v.scenarios.filter((s) => !['match', 'strengthened', 'proposed', 'nondeterministic'].includes(s.class));
+    if (v.verdict === 'pass') return box('contract check', 'pass', `pass — every approved scenario holds (\`sungen contract check\` exits 0)`);
+    const first = v.uncommitted[0] ? `${v.uncommitted[0].id} lock-uncommitted` : bad[0] ? `${bad[0].id} ${bad[0].class}` : v.verdict;
+    return v.verdict === 'review'
+      ? box('contract check', 'fail', `review — ${bad.length} scenario(s), e.g. ${first}; exits 0 but blocks delivery until QA re-approves`)
+      : box('contract check', 'fail', `FAIL — ${first}${bad.length + v.uncommitted.length > 1 ? ` and ${bad.length + v.uncommitted.length - 1} more` : ''} (\`sungen contract check\` exits 2)`);
+  } catch (e) {
+    return box('contract check', 'fail', `could not be built: ${why(e)} (\`sungen contract check\` exits 1)`);
+  }
+}
+
+function decisionsBox(projectRoot: string, u: ChecklistUnit, accepted?: InRunAcceptance): ChecklistBox {
+  try {
+    const g = evaluateDeliveryDecisions(projectRoot, [{ label: u.label, unitName: u.unitName, unitDir: u.unitDir, resultsPath: u.resultsPath }]);
+    if (g.blocking.length) return box('decisions', 'fail', `${g.blocking.length} decision problem(s) — ${g.blocking[0].slice(0, 160)}`);
+    if (g.inRun.length && !accepted) return box('decisions', 'fail', `${g.inRun.length} decision(s) recorded during the run (decision.in-run) — commit them through review and re-run, or a human passes --accept-in-run`);
+    const overrides = g.overridesFor(u.unitDir).length;
+    return box('decisions', 'pass', `no decision problem${g.inRun.length ? ` · ${g.inRun.length} in-run decision(s) accepted by ${accepted!.by} on a terminal` : ''}${overrides ? ` · ${overrides} gate override(s) in force` : ''}`);
+  } catch (e) {
+    return box('decisions', 'fail', `could not be evaluated: ${why(e)}`);
+  }
+}
+
+function triageBox(projectRoot: string, u: ChecklistUnit): ChecklistBox {
+  try {
+    const cases = testCaseStates(projectRoot, u.unitName, { unitDir: u.unitDir });
+    if (!cases.some((c) => c.result !== 'never-run')) return box('triage', 'skipped', 'no run results to classify');
+    const owed = cases.filter((c) => testCaseNeed(c) === 'triage');
+    const decide = cases.filter((c) => testCaseNeed(c) === 'product-candidate');
+    const flag = u.kind === 'api' ? '--api' : '--screen';
+    if (owed.length) return box('triage', 'fail', `${owed.length} red test case(s) not classified — run \`sungen triage ${flag} ${u.unitName}\``);
+    if (decide.length) return box('triage', 'fail', `${decide.length} product-defect candidate(s) await a QA decision (\`sungen defect draft ${flag} ${u.unitName}\`)`);
+    const reds = cases.filter((c) => c.result === 'failed').length;
+    return box('triage', 'pass', reds ? `${reds} red test case(s), each classified or exempt` : 'no red test case');
+  } catch (e) {
+    return box('triage', 'fail', `could not be read: ${why(e)}`);
+  }
+}
+
+export async function unitChecklist(projectRoot: string, u: ChecklistUnit, accepted?: InRunAcceptance): Promise<ChecklistBox[]> {
+  return [auditBox(projectRoot, u), await scriptCheckBox(u), contractBox(projectRoot, u), decisionsBox(projectRoot, u, accepted), triageBox(projectRoot, u)];
+}
+
+const MARK: Record<BoxState, string> = { pass: '[x]', fail: '[ ]', skipped: '[-]' };
+
+export function renderChecklist(rows: Array<{ label: string; boxes: ChecklistBox[] }>): string[] {
+  const out = ['⚒ Delivery checklist — each box from a real exit code or state, none ticked by hand'];
+  for (const r of rows) {
+    out.push(`  ${r.label}`);
+    for (const b of r.boxes) out.push(`    ${MARK[b.state]} ${b.name.padEnd(15)} ${b.state === 'skipped' ? `skipped — ${b.evidence}` : b.evidence}`);
+  }
+  out.push('  The gates above decided this delivery; the checklist only reports what holds now.');
+  return out;
+}

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

@@ -0,0 +1,139 @@
+/**
+ * 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`)
+ *   failing       a trusted audit whose verdict is FAIL (`sungen audit` exits 2): the same — a real
+ *   audit         delivery stops, naming the failing gate rules (#935, owner decision); `--preview`
+ *                 renders a DRAFT, `--check` reports it (`failingAudits`)
+ * 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 { auditGateTerms, termSourcesOf } from './audit-gate-terms';
+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[];
+  /** Units whose trusted audit FAILs (#935) — a real delivery stops on them, --preview / --check warn. */
+  failingAudits: string[];
+  /** The unit's audit does not let it be delivered officially (untrusted or FAIL): its render is a DRAFT. */
+  auditDraft(unitDir: string): boolean;
+  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/`] : [])];
+
+/** The audit gate rules a FAIL report's own terms violate under the unit's overrides, gaps named. */
+function failingGateRules(report: Record<string, unknown>, overrides: UnitGateOverrides): string {
+  const sources = termSourcesOf(report, true);
+  if (!sources) return 'its gate terms';
+  const gaps = (sources.gate.gaps as Array<{ theme?: unknown; status?: unknown }>)
+    .map((g) => `${g.status === 'shallow' ? 'SHALLOW' : 'MISSING'}: ${String(g.theme)}`);
+  const rules = auditGateTerms(sources).filter((t) => !t.holds && resolveRule(t.rule, overrides.context).blocking)
+    .map((t) => (t.rule === 'audit.viewpoint-coverage' && gaps.length ? `${t.rule} (${gaps.join(', ')})` : t.rule));
+  return rules.join(', ') || 'its gate terms';
+}
+
+export function evaluateDeliveryDecisions(projectRoot: string, refs: DeliveryUnitRef[]): DeliveryDecisionGate {
+  const blocking: string[] = [];
+  const untrustedAudits: string[] = [];
+  const failingAudits: string[] = [];
+  const draftDirs = new Set<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}`);
+    const flag = /[\\/]qa[\\/]api[\\/]/.test(ref.unitDir) ? '--api' : '--screen';
+    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('; ')}`;
+      untrustedAudits.push(`${ref.label}: ${why} — re-run \`sungen audit ${flag} ${ref.unitName}\``);
+      draftDirs.add(ref.unitDir);
+    } else if (audit.report?.gateStatus !== 'PASS') {
+      const overall = (audit.report?.score as { overall?: number } | undefined)?.overall;
+      failingAudits.push(`${ref.label}: FAIL ${overall ?? '?'}/10 on ${failingGateRules(audit.report!, overrides)} — fix the suite, then re-run \`sungen audit ${flag} ${ref.unitName}\``);
+      draftDirs.add(ref.unitDir);
+    }
+    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,
+    failingAudits,
+    auditDraft: (dir) => draftDirs.has(dir),
+    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,89 @@
+/**
+ * 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, per unit, a trusted audit (owner decision 2026-10-22) that PASSes (#935);
+   * false for --preview / --check, which go on with a warning (a DRAFT render / a report).
+   */
+  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;
+  }
+  // Every reason to stop is listed before stopping, so one run names all of them (audit and in-run).
+  let blocked = false;
+  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.');
+      blocked = true;
+    }
+  }
+  if (gate.failingAudits.length) {
+    i.log(i.requireTrustedAudit
+      ? `✗ Delivery blocked — ${gate.failingAudits.length} unit(s) whose audit FAILs (\`sungen audit\` exits 2; an official delivery stands on a passing audit):`
+      : `⚠ Rendering ${gate.failingAudits.length} unit(s) whose audit FAILs — a draft, not an official delivery:`);
+    for (const u of gate.failingAudits) i.log(`  - ${u}`);
+    if (i.requireTrustedAudit) {
+      i.log('  Fix the suite and re-run the audit, or render a watermarked draft with --preview.');
+      blocked = true;
+    }
+  }
+  if (gate.inRun.length === 0) return blocked ? null : 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;
+  }
+  if (blocked) return null;   // nothing to accept on top of a delivery the audit already stops
+  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 };
+}