@sun-asterisk/sungen 3.2.16-beta.1 → 3.2.16-beta.11

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

@@ -2,14 +2,21 @@
  * Render the Test Case & Coverage Matrix workbook.
  *
  * Sheets:
- *   1. Testcases — one parent row per delivery item, variant sub-rows grouped with
- *      Excel outline (expanded for execution; the level-1 outline button collapses
- *      to the customer/review view — same sheet, one model, two views).
- *   2. Coverage — target × category grid (items + variants, `—` marks the gaps),
- *      dispositions, and the generation manifest.
+ *   1. Testcases — one parent row per delivery item; EVERY item (including
+ *      single-variant ones) carries variant sub-rows on Excel outline level 1 —
+ *      the sub-row is where source traceability (VP-id), test data, and the
+ *      manual result/evidence entry live (review B-05/B-06). Collapse outline
+ *      level 1 for the customer/review view; expand to execute.
+ *   2. Coverage — requirement coverage (id ↔ items ↔ status), the target ×
+ *      category grid (explicit `—` gaps), dispositions, and the manifest.
  *
- * Every sheet keeps the company ISO masthead (renderReportHeaderBand). A draft
- * matrix (unapproved groups / review findings) carries a red DRAFT banner.
+ * Manual-execution support: variant Result cells carry a dropdown
+ * (Passed/Failed/Blocked/Pending/N/A) and the parent Result is a live Excel
+ * formula derived from its children — a parent can never contradict its
+ * variants, even after QA edits results by hand (review B-06).
+ *
+ * Every sheet keeps the company ISO masthead. A draft matrix (unapproved
+ * groups / review findings) carries a red DRAFT banner.
  */
 
 import * as ExcelJS from 'exceljs';
@@ -20,13 +27,14 @@ import {
   BLACK,
   LAVENDER,
 } from '../xlsx-report-builder';
-import { statusToTestResult, formatExecutedDate } from '../playwright-report-parser';
-import { CoverageVariant, DeliveryItem, ItemResult, MatrixModel, MapCategory } from './types';
+import { variantState } from './build';
+import { DeliveryItem, MatrixModel, MapCategory } from './types';
 
 const CATEGORY_ORDER: MapCategory[] = ['normal', 'abnormal', 'security', 'nfr'];
 const SOFT_BLUE = { argb: 'FFDCE6F1' };
 const DRAFT_RED = { argb: 'FFC00000' };
 const GAP_FILL = { argb: 'FFFCE4EC' };
+const RESULT_STATES = 'Passed,Failed,Blocked,Pending,N/A';
 
 function headerCell(c: ExcelJS.Cell, label: string): void {
   c.value = label;
@@ -37,35 +45,74 @@ function headerCell(c: ExcelJS.Cell, label: string): void {
 }
 
 function dataCell(c: ExcelJS.Cell, value: ExcelJS.CellValue, opts?: { bold?: boolean; fill?: { argb: string }; center?: boolean; color?: { argb: string } }): void {
-  c.value = value;
+  // An empty value stays a genuinely blank cell — never an empty shared string,
+  // which some renderers display as its string-table index (review M-03).
+  if (value !== '' && value !== undefined && value !== null) c.value = value;
   c.font = { bold: opts?.bold ?? false, size: 10, name: ARIAL_FONT, ...(opts?.color ? { color: opts.color } : {}) };
   c.alignment = { horizontal: opts?.center ? 'center' : 'left', vertical: 'top', wrapText: true };
   c.border = allBordersBlack;
   if (opts?.fill) c.fill = { type: 'pattern', pattern: 'solid', fgColor: opts.fill };
 }
 
-function itemResultLabel(item: DeliveryItem): string {
-  const { passed, failed, blocked, notRun } = item.resultCounts;
-  const total = item.variants.length;
-  const map: Record<ItemResult, string> = {
-    passed: `${passed}/${total} Passed`,
-    failed: `${passed}/${total} Passed · ${failed} Failed`,
-    blocked: `${blocked} Blocked`,
-    partial: `${passed}/${total} Passed · ${notRun} not run`,
-    not_run: 'Pending',
-  };
-  return map[item.result];
+/** Mode is a coverage dimension: mixed items show both counts. */
+export function itemModeLabel(item: DeliveryItem): string {
+  if (item.mode === 'mixed') {
+    const auto = item.variants.filter((v) => v.mode === 'auto').length;
+    return `Auto ${auto} · Manual ${item.variants.length - auto}`;
+  }
+  return item.mode === 'manual' ? 'Manual' : 'Auto';
 }
 
-function variantResultLabel(v: CoverageVariant): string {
-  if (!v.result) return 'Pending';
-  return statusToTestResult(v.result.status);
+/**
+ * Parent roll-up label. It must NEVER be exactly one of the variant state words
+ * (`Passed`/`Failed`/`Blocked`/`Pending`/`N/A`) — the summary band counts the
+ * Result column with exact-match COUNTIF over parent AND child rows, so a parent
+ * reading plain "Pending" was counted as an extra pending variant (109 instead
+ * of 77 on st-login).
+ */
+export function itemResultLabel(item: DeliveryItem): string {
+  const { passed, failed, blocked, na } = item.resultCounts;
+  const eff = item.variants.length - na;
+  const suffix = na > 0 ? ` · ${na} N/A` : '';
+  if (item.result === 'na') return 'All N/A';
+  if (item.result === 'failed') return `${passed}/${eff} Passed · ${failed} Failed${suffix}`;
+  if (item.result === 'blocked') return `${passed}/${eff} Passed · ${blocked} Blocked${suffix}`;
+  return `${passed}/${eff} Passed${suffix}`;
 }
 
-function numbered(lines: string[]): string {
+/** ISO date (2026-08-04) — unambiguous across locales (review §9). */
+function isoDate(startTime: string | undefined): string {
+  if (!startTime) return '';
+  const d = new Date(startTime);
+  if (isNaN(d.getTime())) return '';
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+
+function numbered(lines: string[], start = 1): string {
   if (lines.length === 0) return '';
-  if (lines.length === 1) return lines[0];
-  return lines.map((l, i) => `${i + 1}. ${l}`).join('\n');
+  if (lines.length === 1 && start === 1) return lines[0];
+  return lines.map((l, i) => `${start + i}. ${l}`).join('\n');
+}
+
+/**
+ * Compact coverage summary for the parent row. A declared `dimensions:` digest
+ * wins ("15 variants — required ×3 · format ×9 …"); otherwise a single variant
+ * shows its condition and a group falls back to its variant REFS. Concatenating
+ * every variant's full title turned this cell into an 800-character paragraph.
+ */
+export function coverageSummary(item: DeliveryItem): string {
+  const n = item.variants.length;
+  const head = `${n} variant${n === 1 ? '' : 's'}:`;
+  if (item.dimensions) return `${head} ${item.dimensions}`;
+  if (n === 1) return `${head} ${item.variants[0].condition}`;
+  return `${head} ${item.variants.map((v) => v.ref).join(' · ')}`;
+}
+
+/** Expected cell = observable outcomes; the HOW moves under a separate heading. */
+function expectedWithVerification(oracle: string[], verification: string[]): string {
+  const expected = numbered(oracle);
+  if (verification.length === 0) return expected;
+  return `${expected}\nVerification method: ${verification.join(' ')}`;
 }
 
 /** Red DRAFT banner on row 5 when the matrix is not approved for official delivery. */
@@ -85,9 +132,10 @@ function draftBanner(ws: ExcelJS.Worksheet, model: MatrixModel): void {
 
 const MATRIX_HEADERS = [
   'ID', 'Target', 'Test Intent / Condition', 'Category', 'Priority', 'Precondition',
-  'Coverage / Test Data', 'Action / Trigger', 'Expected (Oracle)', 'Mode', 'Trace',
-  'Result', 'Executed Date', 'Executor', 'Note\n(Evidence, DefectID)',
+  'Coverage / Test Data', 'Action / Trigger', 'Expected Result', 'Mode', 'Trace',
+  'Result', 'Executed Date', 'Executor', 'Note / Evidence', 'Defect ID',
 ];
+const RESULT_COL = 13; // column M
 
 function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?: string): void {
   const ws = wb.addWorksheet('Testcases');
@@ -95,7 +143,7 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
 
   ws.columns = [
     { width: 3 },  // A margin
-    { width: 20 }, // B ID
+    { width: 22 }, // B ID
     { width: 18 }, // C Target
     { width: 42 }, // D Intent / Condition
     { width: 11 }, // E Category
@@ -106,28 +154,43 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
     { width: 42 }, // J Expected
     { width: 11 }, // K Mode
     { width: 13 }, // L Trace
-    { width: 17 }, // M Result
-    { width: 13 }, // N Executed
+    { width: 22 }, // M Result
+    { width: 12 }, // N Executed
     { width: 13 }, // O Executor
-    { width: 24 }, // P Note
+    { width: 22 }, // P Note / Evidence
+    { width: 12 }, // Q Defect ID
   ];
 
   renderReportHeaderBand(wb, ws, `${model.unit.toUpperCase()} TEST CASE & COVERAGE MATRIX`, sungenVersion, model.formNo);
   draftBanner(ws, model);
 
-  // Summary band (row 6) — items vs variants stay separate metrics by design (I8):
-  // the ITEM count is reviewer workload, the VARIANT count is execution workload.
-  const passed = model.items.reduce((a, i) => a + i.resultCounts.passed, 0);
-  const failed = model.items.reduce((a, i) => a + i.resultCounts.failed, 0);
-  const notRun = model.items.reduce((a, i) => a + i.resultCounts.notRun + i.resultCounts.blocked, 0);
+  // Summary band (row 6) — items vs variants stay separate metrics by design (I8).
+  // The execution counters are LIVE formulas over the variant Result cells, so
+  // hand-entered results update the totals (review GAP-06). Variant cells hold the
+  // exact state words and parent cells NEVER do (itemResultLabel + the roll-up
+  // formula always compose a "n/m Passed …" label), so exact-match COUNTIF over
+  // the whole column counts variants only.
+  const sum = (k: 'passed' | 'failed' | 'blocked' | 'notRun' | 'na'): number =>
+    model.items.reduce((a, i) => a + i.resultCounts[k], 0);
+  const passed = sum('passed');
+  const failed = sum('failed');
+  const blocked = sum('blocked');
+  const notRun = sum('notRun');
+  const na = sum('na');
+  const RANGE = 'M9:M10000';
   const band = ws.getRow(6);
-  [
-    `Delivery items: ${model.manifest.itemCount}`,
-    `Coverage variants: ${model.manifest.variantCount}`,
-    `Passed: ${passed}`, `Failed: ${failed}`, `Pending: ${notRun}`,
-  ].forEach((label, i) => {
+  const bandCells: Array<[string, ExcelJS.CellValue]> = [
+    ['items', `Delivery items: ${model.manifest.itemCount}`],
+    ['variants', `Coverage variants: ${model.manifest.variantCount}`],
+    ['passed', { formula: `"Passed: "&COUNTIF(${RANGE},"Passed")`, result: `Passed: ${passed}` } as ExcelJS.CellValue],
+    ['failed', { formula: `"Failed: "&COUNTIF(${RANGE},"Failed")`, result: `Failed: ${failed}` } as ExcelJS.CellValue],
+    ['blocked', { formula: `"Blocked: "&COUNTIF(${RANGE},"Blocked")`, result: `Blocked: ${blocked}` } as ExcelJS.CellValue],
+    ['pending', { formula: `"Pending: "&COUNTIF(${RANGE},"Pending")`, result: `Pending: ${notRun}` } as ExcelJS.CellValue],
+    ['na', { formula: `"N/A: "&COUNTIF(${RANGE},"N/A")`, result: `N/A: ${na}` } as ExcelJS.CellValue],
+  ];
+  bandCells.forEach(([, v], i) => {
     const c = band.getCell(2 + i);
-    dataCell(c, label, { bold: true, fill: SOFT_BLUE, center: true });
+    dataCell(c, v, { bold: true, fill: SOFT_BLUE, center: true });
   });
 
   const HEADER_ROW = 8;
@@ -137,13 +200,65 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
 
   let rowIdx = HEADER_ROW + 1;
   for (const item of model.items) {
-    // Parent row — the delivery item (the review unit).
-    const pr = ws.getRow(rowIdx++);
-    const single = item.variants.length === 1;
-    const only = single ? item.variants[0] : undefined;
-    const coverage = single
-      ? numbered(only!.data)
-      : `${item.variants.length} variants: ${item.variants.map((v) => v.condition).join(' · ')}`;
+    const parentRowIdx = rowIdx++;
+
+    // --- Variant sub-rows FIRST (to know their cell range for the parent formula).
+    // Every item gets sub-rows — the sub-row is where the source scenario id, the
+    // resolved data, and the manual result/evidence entry live (review B-05).
+    const firstChild = rowIdx;
+    // Delta-only sub-rows (review GAP-01): content identical across the whole
+    // item lives ONCE on the parent — a child repeats only what distinguishes it.
+    // The child's Expected Result is always kept: it is the precise source
+    // oracle (the semantic anchor), not a repetition of the parent's summary.
+    for (const v of item.variants) {
+      const vr = ws.getRow(rowIdx++);
+      vr.outlineLevel = 1;
+      const vValues: ExcelJS.CellValue[] = [
+        v.ref,
+        '',
+        v.condition,
+        '', '',
+        numbered(item.preconditionDeltas[v.ref] ?? []),
+        numbered(v.data),
+        // Only the steps after the parent's shared prefix, numbered so the
+        // parent's steps + these read as one continuous procedure.
+        numbered(item.triggerDeltas[v.ref] ?? [], item.trigger.length + 1),
+        expectedWithVerification(v.oracle, v.verification),
+        v.mode === 'manual' ? `Manual${v.manualReason ? ` (${v.manualReason})` : ''}` : 'Auto',
+        v.traces.join(', '),
+        variantState(v),
+        isoDate(v.result?.startTime),
+        '',
+        v.result?.error ? String(v.result.error).slice(0, 200) : '',
+        '',
+      ];
+      vValues.forEach((val, i) => dataCell(vr.getCell(2 + i), val, { center: i === 9 }));
+      // Manual-execution entry: constrain the Result cell to the known states.
+      vr.getCell(2 + 11).dataValidation = {
+        type: 'list', allowBlank: true, formulae: [`"${RESULT_STATES}"`],
+      };
+    }
+    const lastChild = rowIdx - 1;
+
+    // --- Parent row: only values that are genuinely COMMON to the whole item
+    // (review M-04); everything variant-specific stays on the sub-rows.
+    const pr = ws.getRow(parentRowIdx);
+    const coverage = coverageSummary(item);
+
+    // Live roll-up derived from the child Result cells — precedence
+    // failed → blocked → pending → partial → passed. N/A variants leave the
+    // denominator (review GAP-06): eff = n − COUNTIF(N/A); all-N/A → "N/A".
+    const rng = `M${firstChild}:M${lastChild}`;
+    const n = item.variants.length;
+    const EFF = `(${n}-COUNTIF(${rng},"N/A"))`;
+    const NA = `IF(COUNTIF(${rng},"N/A")>0," · "&COUNTIF(${rng},"N/A")&" N/A","")`;
+    // Mirrors itemResultLabel exactly — and never yields a bare state word.
+    const rollUpFormula =
+      `IF(COUNTIF(${rng},"Failed")>0,COUNTIF(${rng},"Passed")&"/"&${EFF}&" Passed · "&COUNTIF(${rng},"Failed")&" Failed"&${NA},` +
+      `IF(COUNTIF(${rng},"Blocked")>0,COUNTIF(${rng},"Passed")&"/"&${EFF}&" Passed · "&COUNTIF(${rng},"Blocked")&" Blocked"&${NA},` +
+      `IF(${EFF}=0,"All N/A",` +
+      `COUNTIF(${rng},"Passed")&"/"&${EFF}&" Passed"&${NA})))`;
+
     const values: ExcelJS.CellValue[] = [
       item.id,
       item.target,
@@ -152,66 +267,82 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
       item.priority,
       numbered(item.precondition),
       coverage,
+      // The shared leading steps; each variant's remaining steps sit on its sub-row.
       numbered(item.trigger),
       item.oracle,
-      item.mode === 'manual' ? `Manual${only?.manualReason ? ` (${only.manualReason})` : ''}` : 'Auto',
+      itemModeLabel(item),
       item.traces.join(', '),
-      itemResultLabel(item),
-      single ? formatExecutedDate(only!.result?.startTime) : '',
+      { formula: rollUpFormula, result: itemResultLabel(item) } as ExcelJS.CellValue,
+      '',
       '',
       item.review === 'proposed' ? 'REVIEW REQUIRED' : '',
+      '',
     ];
     values.forEach((v, i) => dataCell(pr.getCell(2 + i), v, {
       bold: true,
       fill: SOFT_BLUE,
       center: i === 3 || i === 4 || i === 9,
-      ...(String(values[14]).startsWith('REVIEW') && i === 14 ? { color: DRAFT_RED } : {}),
+      ...(i === 14 && item.review === 'proposed' ? { color: DRAFT_RED } : {}),
     }));
-
-    // Variant sub-rows — the execution units (outline level 1; collapse for review).
-    if (!single) {
-      for (const v of item.variants) {
-        const vr = ws.getRow(rowIdx++);
-        vr.outlineLevel = 1;
-        const vValues: ExcelJS.CellValue[] = [
-          v.ref,
-          '',
-          v.condition,
-          '', '', '',
-          numbered(v.data),
-          numbered(v.trigger),
-          numbered(v.oracle),
-          v.mode === 'manual' ? `Manual${v.manualReason ? ` (${v.manualReason})` : ''}` : 'Auto',
-          v.traces.join(', '),
-          variantResultLabel(v),
-          formatExecutedDate(v.result?.startTime),
-          '',
-          v.result?.error ? String(v.result.error).slice(0, 200) : '',
-        ];
-        vValues.forEach((val, i) => dataCell(vr.getCell(2 + i), val, { center: i === 9 }));
-      }
-    }
   }
 
-  ws.autoFilter = { from: { row: HEADER_ROW, column: 2 }, to: { row: rowIdx - 1, column: 16 } };
-  ws.views = [{ state: 'frozen', ySplit: HEADER_ROW }];
+  ws.autoFilter = { from: { row: HEADER_ROW, column: 2 }, to: { row: rowIdx - 1, column: 17 } };
+  // Freeze the header band AND the ID + Target columns (review §9).
+  ws.views = [{ state: 'frozen', xSplit: 3, ySplit: HEADER_ROW }];
+  // Print: landscape, fit width only (never squash all rows into one page),
+  // repeat the masthead + header rows on every page (review GAP-08).
+  ws.pageSetup = {
+    orientation: 'landscape',
+    fitToPage: true,
+    fitToWidth: 1,
+    fitToHeight: 0,
+    printTitlesRow: '1:8',
+  };
 }
 
 // ---------------------------------------------------------------------------
-// Sheet 2 — Coverage (overview grid + dispositions + manifest)
+// Sheet 2 — Coverage (requirements + overview grid + dispositions + manifest)
 // ---------------------------------------------------------------------------
 
 function addCoverageSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?: string): void {
   const ws = wb.addWorksheet('Coverage');
   ws.columns = [
-    { width: 3 }, { width: 30 }, { width: 16 }, { width: 16 }, { width: 16 }, { width: 16 },
-    { width: 16 }, { width: 40 },
+    { width: 3 }, { width: 22 }, { width: 18 }, { width: 16 }, { width: 16 }, { width: 16 },
+    { width: 16 }, { width: 44 },
   ];
   renderReportHeaderBand(wb, ws, `${model.unit.toUpperCase()} COVERAGE OVERVIEW`, sungenVersion, model.formNo);
   draftBanner(ws, model);
 
-  // --- Target × category grid ---
   let rowIdx = 7;
+
+  // --- Requirement coverage (review §6): every requirement id gets ONE explicit status.
+  if (model.requirements.length > 0) {
+    dataCell(ws.getRow(rowIdx).getCell(2), 'Requirement coverage — every id has an explicit status', { bold: true });
+    rowIdx += 1;
+    const rh = ws.getRow(rowIdx);
+    ws.mergeCells(rowIdx, 4, rowIdx, 6);
+    headerCell(rh.getCell(2), 'Requirement');
+    headerCell(rh.getCell(3), 'Status');
+    headerCell(rh.getCell(4), 'Delivery items');
+    headerCell(rh.getCell(7), 'Variants');
+    headerCell(rh.getCell(8), 'Note');
+    rowIdx += 1;
+    for (const r of model.requirements) {
+      const row = ws.getRow(rowIdx++);
+      dataCell(row.getCell(2), r.id, { bold: true });
+      dataCell(row.getCell(3), r.status, {
+        center: true,
+        ...(r.status === 'gap' ? { fill: GAP_FILL, bold: true } : {}),
+      });
+      ws.mergeCells(rowIdx - 1, 4, rowIdx - 1, 6);
+      dataCell(row.getCell(4), r.items.join(', '));
+      dataCell(row.getCell(7), r.variantCount > 0 ? String(r.variantCount) : '', { center: true });
+      dataCell(row.getCell(8), r.note);
+    }
+    rowIdx += 1;
+  }
+
+  // --- Target × category grid ---
   dataCell(ws.getRow(rowIdx).getCell(2), 'Coverage matrix — delivery items (coverage variants) per target × category', { bold: true });
   rowIdx += 1;
   const gridHeader = ws.getRow(rowIdx++);

package/src/exporters/matrix/types.ts

@@ -29,6 +29,10 @@ export interface MapGroup {
   oracle: string;
   category: MapCategory;
   review: ReviewState;
+  /** Optional short digest of the coverage dimensions this item varies over
+   *  (e.g. "required ×3 · format ×9 · full-width ×2"). Rendered on the parent row
+   *  instead of concatenating every variant's title — the compact review view. */
+  dimensions?: string;
   /** Variant refs: `VP-ID` (all @cases rows when the scenario has a dataset) or `VP-ID#label`. */
   variants: string[];
 }
@@ -38,6 +42,14 @@ export interface MapDisposition {
   reason?: string;
 }
 
+export type RequirementStatus =
+  | 'covered' | 'partially_covered' | 'covered_elsewhere' | 'planned' | 'gap' | 'not_applicable';
+
+export interface RequirementOverride {
+  status: RequirementStatus;
+  note?: string;
+}
+
 export interface DeliveryMap {
   version: number;
   unit: string;
@@ -46,7 +58,12 @@ export interface DeliveryMap {
   groups: MapGroup[];
   /** VP-id → intentionally-not-grouped disposition. */
   dispositions: Record<string, MapDisposition>;
-  /** VP-id → scenario fingerprint stamped at approval time (drift detector input). */
+  /** Requirement-id → reviewed status override (partially_covered / not_applicable / …).
+   *  Without an override a requirement is `covered` when a variant traces to it, else `gap`. */
+  requirements: Record<string, RequirementOverride>;
+  /** VP-id → scenario fingerprint stamped at approval time (drift detector input).
+   *  The reserved key `__map__` holds the fingerprint of the map's own semantic
+   *  content (groups + dispositions) so edited wording re-opens review (GAP-09). */
   fingerprints: Record<string, string>;
 }
 
@@ -78,6 +95,9 @@ export interface CoverageVariant {
   layers: MatrixLayer[];
   /** @spec:* requirement traces. */
   traces: string[];
+  /** Variables this scenario produces at RUN TIME (`remember … as {{v}}`, capability
+   *  bindings) — they never exist in test-data, so Gate D must not demand them. */
+  runtimeVars: string[];
   /** Condition summary: differentiating dimension shown on the sub-row. */
   condition: string;
   /** Resolved data pairs (test-data values / dataset-row columns), `key: value` lines. */
@@ -90,6 +110,9 @@ export interface CoverageVariant {
   oracleShape: string[];
   /** Oracle for display. */
   oracle: string[];
+  /** HOW to check (manual `Oracle:` lines — tools, panes, queries). Rendered as
+   *  "Verification method" under the expected result, never inside it. */
+  verification: string[];
   /** Precondition profile: auth role + scenario-level Given shapes — signature input. */
   preconditionProfile: string;
   /** Human preconditions (auth + own Given steps). */
@@ -102,7 +125,11 @@ export interface CoverageVariant {
   result?: PlaywrightResult;
 }
 
-export type ItemResult = 'passed' | 'failed' | 'blocked' | 'partial' | 'not_run';
+export type ItemResult = 'passed' | 'failed' | 'blocked' | 'partial' | 'not_run' | 'na';
+
+/** The exact word rendered in a variant's Result cell — the single vocabulary the
+ *  parent's roll-up formula counts (COUNTIF is exact-match). */
+export type VariantState = 'Passed' | 'Failed' | 'Blocked' | 'Pending' | 'N/A';
 
 /** One summarized row in the matrix — a group of variants sharing the signature. */
 export interface DeliveryItem {
@@ -110,20 +137,31 @@ export interface DeliveryItem {
   target: string;
   intent: string;
   oracle: string;
+  /** Short coverage-dimension digest from the map (compact parent view). */
+  dimensions?: string;
   category: MapCategory;
   review: ReviewState;
+  /** Highest priority among the variants (per-variant priorities stay on the sub-rows). */
   priority: string;
-  mode: 'auto' | 'manual';
+  /** Execution mode is a coverage dimension, not a split — 'mixed' when auto and
+   *  manual variants share one intent (e.g. account states needing seeded data). */
+  mode: 'auto' | 'manual' | 'mixed';
   layers: MatrixLayer[];
   /** Union of variant traces (exact per-variant traces stay on the variants). */
   traces: string[];
+  /** Preconditions shared by EVERY variant (the intersection) — written once here. */
   precondition: string[];
-  /** Common trigger when all variants share one shape, else '(per variant)'. */
+  /** Leading trigger steps shared by every variant — written once here; each
+   *  variant renders only its remaining steps (`triggerDeltas`). */
   trigger: string[];
   variants: CoverageVariant[];
+  /** variant ref → its precondition lines that are not on the parent. */
+  preconditionDeltas: Record<string, string[]>;
+  /** variant ref → its trigger steps after the shared prefix. */
+  triggerDeltas: Record<string, string[]>;
   /** Derived roll-up — never entered independently (Gate F). */
   result: ItemResult;
-  resultCounts: { passed: number; failed: number; blocked: number; notRun: number };
+  resultCounts: { passed: number; failed: number; blocked: number; notRun: number; na: number };
 }
 
 export interface MatrixDisposition {
@@ -133,11 +171,21 @@ export interface MatrixDisposition {
   reason: string;
 }
 
+/** One row of the requirement-coverage table (Coverage sheet). */
+export interface RequirementCoverage {
+  id: string;                    // FR-003 / TR-001 / NFR-…
+  status: RequirementStatus;
+  /** Delivery items whose variants trace to this requirement. */
+  items: string[];
+  variantCount: number;
+  note: string;
+}
+
 // ---------------------------------------------------------------------------
 // Gate findings
 // ---------------------------------------------------------------------------
 
-export type GateId = 'A' | 'B' | 'C' | 'D' | 'E' | 'G';
+export type GateId = 'A' | 'B' | 'C' | 'D' | 'E' | 'G' | 'K' | 'R' | 'W';
 export type FindingSeverity = 'error' | 'review' | 'warning';
 
 export interface MatrixFinding {
@@ -168,9 +216,11 @@ export interface MatrixModel {
   formNo: string;
   items: DeliveryItem[];
   dispositions: MatrixDisposition[];
+  /** Requirement coverage — empty when the unit has no requirements/spec.md ids. */
+  requirements: RequirementCoverage[];
   findings: MatrixFinding[];
   manifest: MatrixManifest;
 }
 
-/** Complexity warning threshold (rules draft Gate I) — echoed in the manifest. */
-export const MAX_VARIANTS_PER_ITEM = 12;
+/** Complexity warning threshold (rules draft Gate I; raised for compact grouping) — echoed in the manifest. */
+export const MAX_VARIANTS_PER_ITEM = 20;