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

package/src/exporters/matrix/carry-manual-results.ts

@@ -19,7 +19,8 @@
 
 import * as fs from 'fs';
 import * as ExcelJS from 'exceljs';
-import { MatrixModel } from './types';
+import { MatrixModel, VariantState } from './types';
+import { rollUp } from './build';
 import { HEADER_ROW, RESULT_COL } from './render-testcase-sheet';
 
 const MANUAL_SHEET = 'Manual';
@@ -169,6 +170,70 @@ function resetNote(prior: CarriedCell[]): ExcelJS.CellValue {
   return own ? `${header}\n${own}` : header;
 }
 
+/**
+ * What happens to each Manual variant's prior row: `carry` its cells, or `reset` it to Pending
+ * because the procedure changed since the result was recorded. A row with nothing recorded has
+ * no entry. The ONE decision both the model (totals, #891) and the workbook cells read.
+ */
+export function planManualCarry(model: MatrixModel, prior: PriorManualResults | null): Map<string, 'carry' | 'reset'> {
+  const plan = new Map<string, 'carry' | 'reset'>();
+  if (!prior) return plan;
+  for (const v of model.items.flatMap((i) => i.variants)) {
+    if (v.mode !== 'manual') continue;
+    const before = prior.rows.get(v.ref);
+    if (!before || isUntouched(before.cells)) continue;
+    const stamped = prior.stamps?.get(v.ref);
+    // Only a recorded result is a claim about the procedure. A row with no result (a
+    // blocker note, or one already reset) is carried as-is, so a second procedure
+    // change does not stack a second marker on it.
+    const hasResult = !['', 'Pending'].includes(cellText(before.cells[0].value));
+    plan.set(v.ref, stamped !== undefined && stamped !== v.fingerprint && hasResult ? 'reset' : 'carry');
+  }
+  return plan;
+}
+
+/** A typed Result → its state word, case-insensitively (Excel's COUNTIF ignores case too). */
+const STATE_BY_LOWER = new Map<string, VariantState>(
+  (['Passed', 'Failed', 'Blocked', 'Pending', 'N/A'] as VariantState[]).map((s) => [s.toLowerCase(), s]),
+);
+
+/**
+ * Put the carried Manual results into the MODEL, before anything is rendered or counted.
+ *
+ * The workbook's totals, Overview and group roll-ups are formulas with a cached result computed
+ * from the model, and the CSV and the CLI summary read the model too. Carrying only the cells
+ * after rendering left all of them counting the recorded Manual results as Pending: a preview
+ * of the file, and the CLI, reported "5 Pending" for cases the tester had run (#891).
+ * A reset row counts as Pending, as its cell reads. A Result that is not a state word (a tester's
+ * "OK") counts as Pending too; the cell keeps the text, and its date still reaches the CSV.
+ * Idempotent: every Manual variant's carried fields are cleared first, so the result depends only
+ * on `prior`.
+ */
+export function applyManualCarry(model: MatrixModel, prior: PriorManualResults | null): void {
+  const plan = planManualCarry(model, prior);
+  for (const item of model.items) {
+    let touched = false;
+    for (const v of item.variants) {
+      if (v.mode !== 'manual') continue;
+      if (v.manualState !== undefined || v.manualDate !== undefined) touched = true;
+      delete v.manualState;
+      delete v.manualDate;
+      const decision = plan.get(v.ref);
+      if (!decision) continue;
+      touched = true;
+      if (decision === 'reset') { v.manualState = 'Pending'; continue; }
+      const [result, date] = prior!.rows.get(v.ref)!.cells.map((c) => cellText(c.value));
+      if (date) v.manualDate = date;
+      v.manualState = STATE_BY_LOWER.get(result.toLowerCase()) ?? 'Pending';
+    }
+    if (touched) {
+      const { result, counts } = rollUp(item.variants);
+      item.result = result;
+      item.resultCounts = counts;
+    }
+  }
+}
+
 /**
  * Carry `prior` into the freshly rendered `wb`, then stamp every manual variant's fingerprint.
  * Only the Manual sheet's variant sub-rows are touched.
@@ -178,6 +243,7 @@ export function carryManualResults(
   model: MatrixModel,
   prior: PriorManualResults | null,
 ): ManualCarryReport {
+  const plan = planManualCarry(model, prior);
   const report: ManualCarryReport = { carried: 0, unchecked: 0, reset: [], notPlaced: [], duplicates: prior?.duplicates ?? [] };
   const fingerprints = new Map(
     model.items.flatMap((i) => i.variants).filter((v) => v.mode === 'manual').map((v) => [v.ref, v.fingerprint]),
@@ -190,14 +256,11 @@ export function carryManualResults(
       const before = prior.rows.get(ref);
       if (!before) continue;
       placed.add(ref);
-      if (isUntouched(before.cells)) continue;
+      const decision = plan.get(ref);
+      if (!decision) continue;
 
       const stamped = prior.stamps?.get(ref);
-      // Only a recorded result is a claim about the procedure. A row with no result (a
-      // blocker note, or one already reset) is carried as-is, so a second procedure
-      // change does not stack a second marker on it.
-      const hasResult = !['', 'Pending'].includes(cellText(before.cells[0].value));
-      if (stamped !== undefined && stamped !== fingerprints.get(ref) && hasResult) {
+      if (decision === 'reset') {
         row.getCell(RESULT_COL).value = 'Pending';
         row.getCell(CARRIED_COLS[NOTE_INDEX]).value = resetNote(before.cells);
         report.reset.push(ref);

package/src/exporters/matrix/export.ts

@@ -17,7 +17,8 @@ import { mergeFeatureAndSpec } from '../scenario-merger';
 import { getPackageVersion } from '../package-info';
 import { writeCsv } from '../csv-exporter';
 import { deliverableXlsxPath, writeXlsx } from '../xlsx-exporter';
-import { carryManualResults, ManualCarryReport, readPriorManualResults } from './carry-manual-results';
+import { applyManualCarry, carryManualResults, ManualCarryReport, PriorManualResults, readPriorManualResults } from './carry-manual-results';
+export { readPriorManualResults } from './carry-manual-results';
 import { loadPerfConfig, perfVerdict } from '../../harness/perf';
 import { loadDeliveryMap, writeDeliveryMap } from './map-loader';
 import { mapContentFingerprint } from './fingerprint';
@@ -27,6 +28,7 @@ import { renderMatrixCsv } from './render-csv';
 import { DeliveryMap, MatrixFinding, MatrixModel } from './types';
 import { ApiCatalogEntry } from '../types';
 import { RunEnvironment } from '../run-environment';
+import { GateRules } from '../../harness/gates/resolve-rule';
 
 export interface MatrixTargetPaths {
   cwd: string;
@@ -49,6 +51,8 @@ export interface MatrixTargetPaths {
   mapFile: string;
   /** Executor + environment of the run (#850) — absent for gates-only callers (inspect, approve). */
   runEnv?: RunEnvironment;
+  /** The unit's gate rules (catalog + gate-overrides) — absent means the catalog alone. */
+  gateRules?: GateRules;
 }
 
 function readSpecText(paths: MatrixTargetPaths): string {
@@ -93,6 +97,7 @@ export function loadMatrixModel(paths: MatrixTargetPaths): MatrixLoadResult {
     transformerVersion: getPackageVersion(),
     specText: readSpecText(paths),
     apiCatalog: catalogFor(paths),
+    gateRules: paths.gateRules,
   });
   model.runEnv = paths.runEnv;
   // Perf verdict (#569): budgets are config (qa/perf.yaml), samples are the run's
@@ -131,6 +136,7 @@ export function approveMatrix(paths: MatrixTargetPaths, groupIds?: string[]): {
     transformerVersion: getPackageVersion(),
     specText: readSpecText(paths),
     apiCatalog,
+    gateRules: paths.gateRules,
   });
   const blocking = model.findings.filter((f) => f.severity === 'error');
   if (blocking.length > 0) return { findings: blocking, approved: [] };
@@ -168,12 +174,21 @@ export async function writeMatrixDeliverables(
   paths: MatrixTargetPaths,
   model: MatrixModel,
   format: MatrixFormat = 'xlsx',
+  /** The prior workbook's Manual results, when the caller already read them; read here if absent. */
+  priorRead?: PriorManualResults | null,
 ): Promise<{ csvPath?: string; xlsxPath?: string; manualCarry?: ManualCarryReport }> {
   const out: { csvPath?: string; xlsxPath?: string; manualCarry?: ManualCarryReport } = {};
   const xlsx = format === 'xlsx' || format === 'both';
   // Read the workbook about to be overwritten BEFORE writing anything, so the tester's Manual
   // results survive (#756) and a refusal leaves no half-written target behind.
-  const prior = xlsx ? await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit)) : null;
+  // A CSV-only export overwrites no workbook, so an unreadable one is no reason to refuse it — but a
+  // readable one still holds the Manual results the CSV should show.
+  const prior = priorRead !== undefined ? priorRead
+    : xlsx ? await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit))
+      : await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit)).catch(() => null);
+  // Into the model first: the CSV, every cached total and roll-up, and the caller's summary
+  // all read it (#891).
+  applyManualCarry(model, prior);
   if (format === 'csv' || format === 'both') {
     out.csvPath = writeCsv(paths.cwd, paths.unit, renderMatrixCsv(model));
   }

package/src/exporters/matrix/gates.ts

@@ -2,10 +2,12 @@
  * Deterministic quality gates for the Test Case & Coverage Matrix
  * (docs/spec/delivery-coverage-matrix-spec.md §6).
  *
- * Severity behavior:
+ * Severity behavior (the level of each finding comes from the gate-rule catalog through
+ * `resolveRule`, never from this file — OES-11.2):
  *   error   → blocks any render
  *   review  → blocks the official render; `--preview` renders with a DRAFT watermark
  *   warning → prints + renders
+ *   info    → prints (only when a gate-override lowered a soft rule); `off` drops the finding
  *
  * The gates recompute every signature part from the .feature — the map is never
  * trusted for derivable facts, only for the semantic fields (target/intent/oracle).
@@ -14,25 +16,37 @@
 import { splitVpAndName, extractTestcaseType } from '../feature-parser';
 import { mapContentFingerprint } from './fingerprint';
 import { bucketTexts } from './step-buckets';
-import { CoverageVariant, MatrixFinding, MAX_VARIANTS_PER_ITEM } from './types';
+import { CoverageVariant, GateId, MatrixFinding, MAX_VARIANTS_PER_ITEM } from './types';
 import { expandMapRef, BuildInputs } from './build';
+import { CATALOG_GATE_RULES, GateRules } from '../../harness/gates/resolve-rule';
 
 export interface GateContext {
   inputs: BuildInputs;
   variants: CoverageVariant[];
   variantsByVp: Map<string, CoverageVariant[]>;
+  /** The unit's gate rules (catalog + its gate-overrides); the catalog alone when absent. */
+  rules?: GateRules;
 }
 
+/** A gate site found its condition: the rule decides the finding's severity, or drops it. */
+type ReportFinding = (rule: string, gate: GateId, message: string, ref?: string) => void;
+
 export function runGates(ctx: GateContext): MatrixFinding[] {
   const findings: MatrixFinding[] = [];
-  gateASource(ctx, findings);
-  gateBMapping(ctx, findings);
-  gateCAggregation(ctx, findings);
-  gateDExecutability(ctx, findings);
-  gateEDrift(ctx, findings);
-  gateGReviewState(ctx, findings);
-  gateWWording(ctx, findings);
-  gateKCategory(ctx, findings);
+  const rules = ctx.rules ?? CATALOG_GATE_RULES;
+  const report: ReportFinding = (rule, gate, message, ref) => {
+    const { severity } = rules.resolve(rule);
+    if (severity === 'off') return;
+    findings.push({ gate, severity, ...(ref !== undefined ? { ref } : {}), message });
+  };
+  gateASource(ctx, report);
+  gateBMapping(ctx, report);
+  gateCAggregation(ctx, report);
+  gateDExecutability(ctx, report);
+  gateEDrift(ctx, report);
+  gateGReviewState(ctx, report);
+  gateWWording(ctx, report);
+  gateKCategory(ctx, report);
   return findings;
 }
 
@@ -54,16 +68,13 @@ const VP_CATEGORY_RULE: Array<[RegExp, string, string]> = [
  * have while hiding the security work it does have. Same for `VP-NFR-*`.
  * (normal vs abnormal stays a judgement call and is never checked.)
  */
-function gateKCategory(ctx: GateContext, findings: MatrixFinding[]): void {
+function gateKCategory(ctx: GateContext, report: ReportFinding): void {
   for (const g of ctx.inputs.map.groups) {
     const vs = g.variants.flatMap((ref) => expandMapRef(ref, ctx.variantsByVp));
     for (const [re, expected, label] of VP_CATEGORY_RULE) {
       const hits = vs.filter((v) => re.test(v.vpCategory));
       if (hits.length > 0 && g.category !== expected) {
-        findings.push({
-          gate: 'K', severity: 'warning', ref: g.id,
-          message: `group ${g.id} is \`category: ${g.category}\` but ${hits.length}/${vs.length} of its variants are ${label} scenarios (${hits.slice(0, 3).map((v) => v.vpId).join(', ')}) — use \`category: ${expected}\` or the Coverage grid's ${expected} column stays empty`,
-        });
+        report('matrix.gate-k.category-mismatch', 'K', `group ${g.id} is \`category: ${g.category}\` but ${hits.length}/${vs.length} of its variants are ${label} scenarios (${hits.slice(0, 3).map((v) => v.vpId).join(', ')}) — use \`category: ${expected}\` or the Coverage grid's ${expected} column stays empty`, g.id);
       }
     }
   }
@@ -71,52 +82,40 @@ function gateKCategory(ctx: GateContext, findings: MatrixFinding[]): void {
 
 // --- Gate A — source quality ------------------------------------------------
 
-function gateASource(ctx: GateContext, findings: MatrixFinding[]): void {
+function gateASource(ctx: GateContext, report: ReportFinding): void {
   const { feature, merged } = ctx.inputs;
 
   if (bucketTexts(feature.backgroundOrderedSteps, 'when').length > 0 || bucketTexts(feature.backgroundOrderedSteps, 'then').length > 0) {
-    findings.push({
-      gate: 'A', severity: 'error',
-      message: 'Background contains When/Then steps — setup only; move the action/oracle into scenarios',
-    });
+    report('matrix.gate-a.background-when-then', 'A', 'Background contains When/Then steps — setup only; move the action/oracle into scenarios');
   }
 
   const seen = new Map<string, number>();
   for (const m of merged) {
     const { vpId } = splitVpAndName(m.feature.name);
     if (!vpId) {
-      findings.push({
-        gate: 'A', severity: 'error', ref: m.feature.name,
-        message: `scenario "${m.feature.name}" has no VP-id prefix — matrix variants must be addressable`,
-      });
+      report('matrix.gate-a.no-vp-id', 'A', `scenario "${m.feature.name}" has no VP-id prefix — matrix variants must be addressable`, m.feature.name);
       continue;
     }
     seen.set(vpId, (seen.get(vpId) ?? 0) + 1);
 
     const isManual = extractTestcaseType(m.feature.tags) === 'Manual';
     if (m.resolvedExpected.length === 0) {
-      findings.push({
-        gate: 'A', severity: 'error', ref: vpId,
-        message: isManual
-          ? `manual scenario ${vpId} has no observable oracle (no Then steps and no Observable/Oracle comment lines)`
-          : `scenario ${vpId} has no Then step — a variant without an observable oracle cannot be delivered`,
-      });
+      report('matrix.gate-a.no-oracle', 'A', isManual
+        ? `manual scenario ${vpId} has no observable oracle (no Then steps and no Observable/Oracle comment lines)`
+        : `scenario ${vpId} has no Then step — a variant without an observable oracle cannot be delivered`, vpId);
     }
     if (m.unlabeledManualOracle) {
-      findings.push({
-        gate: 'A', severity: 'warning', ref: vpId,
-        message: `manual oracle found only in an unlabeled comment — exported verbatim into Expected; write the \`# Tester verifies:\` block as numbered "N. Observable: …" lines`,
-      });
+      report('matrix.gate-a.unlabeled-manual-oracle', 'A', `manual oracle found only in an unlabeled comment — exported verbatim into Expected; write the \`# Tester verifies:\` block as numbered "N. Observable: …" lines`, vpId);
     }
   }
   for (const [vpId, n] of seen) {
-    if (n > 1) findings.push({ gate: 'A', severity: 'error', ref: vpId, message: `duplicate VP-id ${vpId} (${n} scenarios)` });
+    if (n > 1) report('matrix.gate-a.duplicate-vp-id', 'A', `duplicate VP-id ${vpId} (${n} scenarios)`, vpId);
   }
 }
 
 // --- Gate B — mapping completeness -------------------------------------------
 
-function gateBMapping(ctx: GateContext, findings: MatrixFinding[]): void {
+function gateBMapping(ctx: GateContext, report: ReportFinding): void {
   const { map } = ctx.inputs;
   const { variants, variantsByVp } = ctx;
 
@@ -126,10 +125,7 @@ function gateBMapping(ctx: GateContext, findings: MatrixFinding[]): void {
     for (const ref of g.variants) {
       const expanded = expandMapRef(ref, variantsByVp);
       if (expanded.length === 0) {
-        findings.push({
-          gate: 'B', severity: 'error', ref: g.id,
-          message: `group ${g.id} references ${ref} which matches no scenario/@cases row in the .feature`,
-        });
+        report('matrix.gate-b.ref-matches-nothing', 'B', `group ${g.id} references ${ref} which matches no scenario/@cases row in the .feature`, g.id);
         continue;
       }
       for (const v of expanded) {
@@ -142,10 +138,7 @@ function gateBMapping(ctx: GateContext, findings: MatrixFinding[]): void {
 
   for (const [ref, groups] of owners) {
     if (groups.length > 1) {
-      findings.push({
-        gate: 'B', severity: 'error', ref,
-        message: `variant ${ref} belongs to ${groups.length} groups (${groups.join(', ')}) — exactly one required`,
-      });
+      report('matrix.gate-b.double-mapped', 'B', `variant ${ref} belongs to ${groups.length} groups (${groups.join(', ')}) — exactly one required`, ref);
     }
   }
 
@@ -153,32 +146,23 @@ function gateBMapping(ctx: GateContext, findings: MatrixFinding[]): void {
     const grouped = owners.has(v.ref);
     const disposed = v.vpId in map.dispositions;
     if (!grouped && !disposed) {
-      findings.push({
-        gate: 'B', severity: 'error', ref: v.ref,
-        message: `variant ${v.ref} is in no group and has no disposition — 100% source disposition is required`,
-      });
+      report('matrix.gate-b.unmapped', 'B', `variant ${v.ref} is in no group and has no disposition — 100% source disposition is required`, v.ref);
     }
     if (grouped && disposed) {
-      findings.push({
-        gate: 'B', severity: 'error', ref: v.ref,
-        message: `variant ${v.ref} is grouped AND disposed (${map.dispositions[v.vpId].as}) — pick one`,
-      });
+      report('matrix.gate-b.grouped-and-disposed', 'B', `variant ${v.ref} is grouped AND disposed (${map.dispositions[v.vpId].as}) — pick one`, v.ref);
     }
   }
 
   for (const vpId of Object.keys(map.dispositions)) {
     if (!variantsByVp.has(vpId)) {
-      findings.push({
-        gate: 'B', severity: 'warning', ref: vpId,
-        message: `disposition for ${vpId} matches no scenario (stale entry?)`,
-      });
+      report('matrix.gate-b.stale-disposition', 'B', `disposition for ${vpId} matches no scenario (stale entry?)`, vpId);
     }
   }
 }
 
 // --- Gate C — aggregation safety ---------------------------------------------
 
-function gateCAggregation(ctx: GateContext, findings: MatrixFinding[]): void {
+function gateCAggregation(ctx: GateContext, report: ReportFinding): void {
   const { map } = ctx.inputs;
   const { variantsByVp } = ctx;
 
@@ -207,47 +191,32 @@ function gateCAggregation(ctx: GateContext, findings: MatrixFinding[]): void {
     for (const [label, keyOf] of hard) {
       const distinct = new Set(vs.map(keyOf));
       if (distinct.size > 1) {
-        findings.push({
-          gate: 'C', severity: 'error', ref: g.id,
-          message: `group ${g.id} mixes ${label}s (${[...distinct].join(' vs ')}) — mandatory split`,
-        });
+        report('matrix.gate-c.mixed-layers', 'C', `group ${g.id} mixes ${label}s (${[...distinct].join(' vs ')}) — mandatory split`, g.id);
       }
     }
 
     // Heuristic signature parts — REVIEW_REQUIRED (equivalence was inferred, not declared).
     const preProfiles = new Set(vs.map((v) => v.preconditionProfile));
     if (!heuristicsConfirmed && preProfiles.size > 1) {
-      findings.push({
-        gate: 'C', severity: 'review', ref: g.id,
-        message: `group ${g.id} variants have different precondition profiles — confirm the grouping is safe or split`,
-      });
+      report('matrix.gate-c.precondition-profiles', 'C', `group ${g.id} variants have different precondition profiles — confirm the grouping is safe or split`, g.id);
     }
     const oracleShapes = new Set(vs.map((v) => v.oracleShape.join(' ; ')));
     if (!heuristicsConfirmed && oracleShapes.size > 1) {
-      findings.push({
-        gate: 'C', severity: 'review', ref: g.id,
-        message: `group ${g.id} variants assert different oracle shapes (${oracleShapes.size} shapes) — confirm they are one oracle family`,
-      });
+      report('matrix.gate-c.oracle-shapes', 'C', `group ${g.id} variants assert different oracle shapes (${oracleShapes.size} shapes) — confirm they are one oracle family`, g.id);
     }
     if (!heuristicsConfirmed && vs.some((v) => v.procedureProfile === 'sequence')) {
-      findings.push({
-        gate: 'C', severity: 'review', ref: g.id,
-        message: `group ${g.id} contains a sequence-sensitive scenario — ordered flows stay solo items unless QA confirms`,
-      });
+      report('matrix.gate-c.sequence-sensitive', 'C', `group ${g.id} contains a sequence-sensitive scenario — ordered flows stay solo items unless QA confirms`, g.id);
     }
 
     if (vs.length > MAX_VARIANTS_PER_ITEM) {
-      findings.push({
-        gate: 'C', severity: 'warning', ref: g.id,
-        message: `group ${g.id} has ${vs.length} variants (> ${MAX_VARIANTS_PER_ITEM}) — consider splitting for reviewability`,
-      });
+      report('matrix.gate-c.too-many-variants', 'C', `group ${g.id} has ${vs.length} variants (> ${MAX_VARIANTS_PER_ITEM}) — consider splitting for reviewability`, g.id);
     }
   }
 }
 
 // --- Gate D — manual executability -------------------------------------------
 
-function gateDExecutability(ctx: GateContext, findings: MatrixFinding[]): void {
+function gateDExecutability(ctx: GateContext, report: ReportFinding): void {
   const { map, testData, feature } = ctx.inputs;
   const { variantsByVp } = ctx;
 
@@ -262,16 +231,10 @@ function gateDExecutability(ctx: GateContext, findings: MatrixFinding[]): void {
         || bucketTexts(feature.backgroundOrderedSteps, 'given').length > 0
         || v.apiCalls > 0;
       if (!hasPrecondition) {
-        findings.push({
-          gate: 'D', severity: 'error', ref: v.ref,
-          message: `${v.ref}: no precondition (no Background, auth tag, or Given) — a tester cannot establish the start state`,
-        });
+        report('matrix.gate-d.no-precondition', 'D', `${v.ref}: no precondition (no Background, auth tag, or Given) — a tester cannot establish the start state`, v.ref);
       }
       if (v.trigger.length === 0) {
-        findings.push({
-          gate: 'D', severity: 'error', ref: v.ref,
-          message: `${v.ref}: no action/trigger (no When steps${v.mode === 'manual' ? ' and no Setup/Action comment lines' : ''})`,
-        });
+        report('matrix.gate-d.no-trigger', 'D', `${v.ref}: no action/trigger (no When steps${v.mode === 'manual' ? ' and no Setup/Action comment lines' : ''})`, v.ref);
       }
       // Oracle emptiness is Gate A (source) — not repeated here.
     }
@@ -289,10 +252,7 @@ function gateDExecutability(ctx: GateContext, findings: MatrixFinding[]): void {
       const inRows = vs.some((v) => v.caseLabel !== undefined); // dataset rows carry their own columns
       const atRuntime = runtime.has(varName) || runtime.has(varName.split(/[.[]/)[0]);
       if (!inRows && !atRuntime && (!testData || !(varName in testData))) {
-        findings.push({
-          gate: 'D', severity: 'error', ref: vpId,
-          message: `${vpId}: {{${varName}}} does not resolve in test-data — the variant is not reproducible`,
-        });
+        report('matrix.gate-d.unresolved-var', 'D', `${vpId}: {{${varName}}} does not resolve in test-data — the variant is not reproducible`, vpId);
       }
     }
   }
@@ -304,10 +264,7 @@ function gateDExecutability(ctx: GateContext, findings: MatrixFinding[]): void {
       const rendered = [...v.precondition, ...v.trigger, ...v.oracle, ...v.verification, ...v.data];
       const token = rendered.map((t) => t.match(/\{\{[^}]*\}\}/)).find(Boolean);
       if (token) {
-        findings.push({
-          gate: 'D', severity: 'error', ref: v.ref,
-          message: `${v.ref}: unresolved template token ${token[0]} remains in the rendered output — the export is not deterministic for a tester`,
-        });
+        report('matrix.gate-d.template-token-remains', 'D', `${v.ref}: unresolved template token ${token[0]} remains in the rendered output — the export is not deterministic for a tester`, v.ref);
       }
     }
   }
@@ -315,7 +272,7 @@ function gateDExecutability(ctx: GateContext, findings: MatrixFinding[]): void {
 
 // --- Gate E — drift (stale approval) ------------------------------------------
 
-function gateEDrift(ctx: GateContext, findings: MatrixFinding[]): void {
+function gateEDrift(ctx: GateContext, report: ReportFinding): void {
   const { map } = ctx.inputs;
   const { variantsByVp } = ctx;
 
@@ -326,15 +283,9 @@ function gateEDrift(ctx: GateContext, findings: MatrixFinding[]): void {
   const liveMap = mapContentFingerprint(map.groups, map.dispositions);
   if (map.groups.some((g) => g.review === 'approved')) {
     if (!stampedMap) {
-      findings.push({
-        gate: 'E', severity: 'review',
-        message: 'the delivery map has no stamped content fingerprint — run `sungen delivery --approve` to record the reviewed wording',
-      });
+      report('matrix.gate-e.map-unstamped', 'E', 'the delivery map has no stamped content fingerprint — run `sungen delivery --approve` to record the reviewed wording');
     } else if (stampedMap !== liveMap) {
-      findings.push({
-        gate: 'E', severity: 'review',
-        message: 'the delivery map wording/grouping changed since approval — re-review, then `sungen delivery --approve`',
-      });
+      report('matrix.gate-e.map-drift', 'E', 'the delivery map wording/grouping changed since approval — re-review, then `sungen delivery --approve`');
     }
   }
 
@@ -345,15 +296,9 @@ function gateEDrift(ctx: GateContext, findings: MatrixFinding[]): void {
       for (const v of vs) {
         const stamped = map.fingerprints[v.ref] ?? map.fingerprints[v.vpId];
         if (!stamped) {
-          findings.push({
-            gate: 'E', severity: 'review', ref: g.id,
-            message: `group ${g.id}: ${v.ref} has no stamped fingerprint — run \`sungen delivery --approve\` after review`,
-          });
+          report('matrix.gate-e.variant-unstamped', 'E', `group ${g.id}: ${v.ref} has no stamped fingerprint — run \`sungen delivery --approve\` after review`, g.id);
         } else if (stamped !== v.fingerprint) {
-          findings.push({
-            gate: 'E', severity: 'review', ref: g.id,
-            message: `group ${g.id}: ${v.ref} changed since approval (fingerprint drift) — re-review the grouping`,
-          });
+          report('matrix.gate-e.variant-drift', 'E', `group ${g.id}: ${v.ref} changed since approval (fingerprint drift) — re-review the grouping`, g.id);
         }
       }
     }
@@ -370,30 +315,21 @@ const WORDING_SMELLS: Array<[RegExp, string]> = [
   [/\[[^\]]+\]/, 'a [selector-style] reference — use the visible UI label'],
 ];
 
-function gateWWording(ctx: GateContext, findings: MatrixFinding[]): void {
+function gateWWording(ctx: GateContext, report: ReportFinding): void {
   for (const g of ctx.inputs.map.groups) {
     const variantCount = g.variants.flatMap((ref) => expandMapRef(ref, ctx.variantsByVp)).length;
     // Without a digest the parent row can only list variant refs — a reviewer
     // then has to expand the item to learn which dimensions it covers.
     if (variantCount > 3 && !g.dimensions) {
-      findings.push({
-        gate: 'W', severity: 'warning', ref: g.id,
-        message: `group ${g.id} has ${variantCount} variants and no \`dimensions:\` digest — add a short one (e.g. "required ×3 · format ×9") so the collapsed view stays informative`,
-      });
+      report('matrix.gate-w.dimensions-missing', 'W', `group ${g.id} has ${variantCount} variants and no \`dimensions:\` digest — add a short one (e.g. "required ×3 · format ×9") so the collapsed view stays informative`, g.id);
     }
     if (g.dimensions && g.dimensions.length > 120) {
-      findings.push({
-        gate: 'W', severity: 'warning', ref: g.id,
-        message: `group ${g.id} \`dimensions:\` is ${g.dimensions.length} chars — keep the digest short (≤120)`,
-      });
+      report('matrix.gate-w.dimensions-long', 'W', `group ${g.id} \`dimensions:\` is ${g.dimensions.length} chars — keep the digest short (≤120)`, g.id);
     }
     for (const [field, text] of ([['intent', g.intent], ['oracle', g.oracle], ...(g.dimensions ? [['dimensions', g.dimensions] as const] : [])] as const)) {
       for (const [re, what] of WORDING_SMELLS) {
         if (re.test(text)) {
-          findings.push({
-            gate: 'W', severity: 'warning', ref: g.id,
-            message: `group ${g.id} ${field} contains ${what}`,
-          });
+          report('matrix.gate-w.wording-smell', 'W', `group ${g.id} ${field} contains ${what}`, g.id);
         }
       }
     }
@@ -402,12 +338,9 @@ function gateWWording(ctx: GateContext, findings: MatrixFinding[]): void {
 
 // --- Gate G — review state -----------------------------------------------------
 
-function gateGReviewState(ctx: GateContext, findings: MatrixFinding[]): void {
+function gateGReviewState(ctx: GateContext, report: ReportFinding): void {
   const proposed = ctx.inputs.map.groups.filter((g) => g.review !== 'approved');
   if (proposed.length > 0) {
-    findings.push({
-      gate: 'G', severity: 'review',
-      message: `${proposed.length} group(s) still \`proposed\` (${proposed.slice(0, 5).map((g) => g.id).join(', ')}${proposed.length > 5 ? ', …' : ''}) — approve them or render with --preview`,
-    });
+    report('matrix.gate-g.groups-proposed', 'G', `${proposed.length} group(s) still \`proposed\` (${proposed.slice(0, 5).map((g) => g.id).join(', ')}${proposed.length > 5 ? ', …' : ''}) — approve them or render with --preview`);
   }
 }

package/src/exporters/matrix/render-csv.ts

@@ -11,6 +11,7 @@ import { variantState } from './build';
 import { coverageSummary, itemModeLabel, itemResultLabel } from './render-xlsx';
 import { MatrixModel } from './types';
 import { formatTestOutcome, resultTotals } from './result-totals';
+import { overrideManifestLines } from '../../harness/gates/gate-override-report';
 
 const HEADERS = [
   'Level', 'ID', 'Target', 'Test Intent / Condition', 'Category', 'Priority',
@@ -36,6 +37,8 @@ export function renderMatrixCsv(model: MatrixModel): string {
   lines.push(`# Test Case & Coverage Matrix — ${model.unit}`);
   // Two different facts, two different words: the map's design REVIEW state, and the runs' OUTCOME.
   lines.push(`# delivery items: ${model.manifest.itemCount} · coverage variants: ${model.manifest.variantCount} · review: ${model.manifest.approvalState} (design) · test outcome: ${formatTestOutcome(resultTotals(model.items))}`);
+  // OES-11.6: a CSV-only reader still learns which client-visible gate overrides the delivery leaned on.
+  lines.push(...overrideManifestLines(model.gateOverrides));
   lines.push(HEADERS.map(esc).join(','));
 
   for (const item of model.items) {
@@ -78,7 +81,7 @@ export function renderMatrixCsv(model: MatrixModel): string {
         v.mode === 'manual' ? 'Manual' : 'Auto',
         v.traces.join(' '),
         variantState(v),
-        isoDate(v.result?.startTime),
+        v.manualDate ?? isoDate(v.result?.startTime),
         // Redact BEFORE clipping — a clip boundary must never split a secret in
         // a way that lets its prefix through. Same denylist as the Note column.
         v.result?.error ? clipNoteField(redactSecrets(String(v.result.error), model.secretValues)) : '',

package/src/exporters/matrix/render-gate-overrides-sheet.ts

@@ -0,0 +1,50 @@
+/**
+ * Sheet 5 — "Gate overrides" (OES-11.6): which quality gate a human relaxed for this unit, why, and
+ * whether the delivery leaned on it (`PASS (overridden)`). Present only when a gate-override touches
+ * the unit, so a workbook without overrides is unchanged.
+ *
+ * `visibility: internal` decisions never reach this sheet — the model carries only client-visible
+ * rows plus a count of the withheld ones (red-team #14).
+ */
+import * as ExcelJS from 'exceljs';
+import { MatrixModel } from './types';
+import { dataCell, headerCell } from './xlsx-cells';
+
+export const GATE_OVERRIDES_SHEET = 'Gate overrides';
+
+const COLUMNS: Array<{ label: string; width: number }> = [
+  { label: 'Rule', width: 34 }, { label: 'Catalog level', width: 13 }, { label: 'Override level', width: 14 },
+  { label: 'Scope', width: 22 }, { label: 'Status', width: 12 }, { label: 'Changed an outcome', width: 12 },
+  { label: 'Reason', width: 60 }, { label: 'Decision', width: 20 }, { label: 'Recorded by', width: 18 }, { label: 'Recorded at', width: 24 },
+];
+
+export function addGateOverridesSheet(wb: ExcelJS.Workbook, model: MatrixModel): void {
+  const o = model.gateOverrides;
+  if (!o) return;
+  const ws = wb.addWorksheet(GATE_OVERRIDES_SHEET);
+  COLUMNS.forEach((c, i) => { ws.getColumn(i + 1).width = c.width; });
+  ws.getCell('A1').value = 'Gate status';
+  ws.getCell('A1').font = { bold: true };
+  ws.getCell('B1').value = o.status;
+  ws.getCell('B1').font = { bold: true };
+  ws.getCell('A2').value = 'Internal decisions (counted, not listed)';
+  ws.getCell('B2').value = o.internalCount;
+  const header = ws.getRow(4);
+  COLUMNS.forEach((c, i) => headerCell(header.getCell(i + 1), c.label));
+  o.rows.forEach((r, n) => {
+    const row = ws.getRow(5 + n);
+    [r.rule, r.catalogSeverity ?? '', r.severity, r.scope, r.status, r.triggered ? 'yes' : 'no', r.reason, r.decisionId, r.by, r.validFrom]
+      .forEach((v, i) => dataCell(row.getCell(i + 1), v));
+  });
+  let next = 5 + o.rows.length;
+  if (o.rows.length === 0) ws.getCell(`A${next++}`).value = 'No client-visible gate override.';
+  const a = o.acceptedInRun;
+  if (a) {
+    // L5: who accepted decisions recorded during the run, on a terminal, for this delivery.
+    ws.getCell(`A${next + 1}`).value = 'In-run decisions accepted';
+    ws.getCell(`A${next + 1}`).font = { bold: true };
+    ws.getCell(`B${next + 1}`).value = `by ${a.by} at ${a.at}`;
+    ws.getCell(`A${next + 2}`).value = 'Decisions';
+    ws.getCell(`B${next + 2}`).value = [a.ids.join(', '), a.internalCount ? `${a.internalCount} internal (ids withheld)` : ''].filter(Boolean).join(' · ') || '—';
+  }
+}