@sun-asterisk/sungen 3.2.28 → 3.2.30

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

@@ -1,467 +1,86 @@
 /**
- * Render the Test Case & Coverage Matrix workbook.
+ * Render the Test Case & Coverage Matrix workbook (BM-2-901-13).
  *
- * Sheets:
- *   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.
+ * Four sheets, in this order:
+ *   1. Overview — one roll-up row per detail sheet, every cell a live reference
+ *      into that sheet's summary band.
+ *   2. Auto     — the cases the suite runs.
+ *   3. Manual   — the cases a person runs.
+ *   4. Coverage — requirement coverage, the target × category grid,
+ *      dispositions and the generation manifest, over the whole model.
  *
- * 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.
+ * Auto and Manual are always both created, even when one side is empty: the
+ * Overview then always reads the same two rows, and QA has a place to add
+ * hand-written cases.
  */
 
 import * as ExcelJS from 'exceljs';
-import {
-  renderReportHeaderBand,
-  allBordersBlack,
-  ARIAL_FONT,
-  BLACK,
-  LAVENDER,
-} from '../xlsx-report-builder';
-import { redactSecrets } from '../api-testcase-formatter';
-import { clipNoteField } from '../playwright-report-parser';
-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;
-  c.font = { bold: true, size: 10, color: BLACK, name: ARIAL_FONT };
-  c.fill = { type: 'pattern', pattern: 'solid', fgColor: LAVENDER };
-  c.alignment = { horizontal: 'center', vertical: 'middle', wrapText: true };
-  c.border = allBordersBlack;
-}
+import { rollUp, varyingTriggerNote } from './build';
+import { DeliveryItem, MatrixModel } from './types';
+import { addTestcaseSheet } from './render-testcase-sheet';
+import { addCoverageSheet } from './render-coverage-sheet';
+import { addMatrixOverviewSheet, SheetProjection } from './render-overview-sheet';
 
-function dataCell(c: ExcelJS.Cell, value: ExcelJS.CellValue, opts?: { bold?: boolean; fill?: { argb: string }; center?: boolean; color?: { argb: string } }): void {
-  // 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 };
-}
-
-/** 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';
-}
+// The CSV renderer and the tests import these from here — they moved to
+// `item-labels.ts` when this module was split, and stay reachable at the old path.
+export { itemModeLabel, itemResultLabel, coverageSummary } from './item-labels';
 
 /**
- * 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}`;
-}
-
-/** 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 && 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.
+ * Project an item onto one execution mode.
+ *
+ * The split is per VARIANT, not per item: an automated variant belongs on the
+ * Auto sheet even when a sibling variant under the same delivery item has to be
+ * run by hand. A mixed item therefore appears on BOTH sheets, each side carrying
+ * only its own variants. The repeated parent row is deliberate — a variant must
+ * always be readable next to the delivery item it verifies.
+ *
+ * Only the fields that would otherwise LIE about the filtered set are recomputed.
+ *
+ *   `variants` / `resultCounts` / `result` — recounted over what survived.
+ *   `dimensions` — dropped on a partial split. The digest enumerates every
+ *     variant ("keyboard operation ×1 · announced name ×1"); with half of them on
+ *     the other sheet it would contradict the count beside it. Cleared, the
+ *     coverage cell falls back to the surviving variants' own words.
+ *   `trigger` — when the parent has no shared opening step, `build.ts` puts a
+ *     synthesized "run each of the N variants below" note there. N is regenerated
+ *     for this sheet; a genuine step prefix is left alone.
+ *
+ * Everything else is kept as it stands. A precondition or trigger prefix common
+ * to every variant is still common to a subset of them, so the parent stays
+ * true — the children just repeat marginally more than the strict minimum. The
+ * delta maps are keyed by `v.ref`, so each surviving variant still finds its own.
+ *
+ * This is a projection over an assembled model, not a second build: nothing in
+ * `build.ts` is re-run.
  */
-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. */
-function draftBanner(ws: ExcelJS.Worksheet, model: MatrixModel): void {
-  if (model.manifest.approvalState !== 'draft') return;
-  ws.mergeCells('B5:H5');
-  const c = ws.getCell('B5');
-  c.value = 'DRAFT — NOT APPROVED FOR OFFICIAL DELIVERY (review-required findings or proposed groups remain)';
-  c.font = { bold: true, size: 11, name: ARIAL_FONT, color: { argb: 'FFFFFFFF' } };
-  c.fill = { type: 'pattern', pattern: 'solid', fgColor: DRAFT_RED };
-  c.alignment = { horizontal: 'center', vertical: 'middle' };
-}
-
-// ---------------------------------------------------------------------------
-// Sheet 1 — Testcases (the matrix)
-// ---------------------------------------------------------------------------
-
-const MATRIX_HEADERS = [
-  'ID', 'Target', 'Test Intent / Condition', 'Category', 'Priority', 'Precondition',
-  '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');
-  ws.properties.outlineLevelRow = 1;
-
-  ws.columns = [
-    { width: 3 },  // A margin
-    { width: 22 }, // B ID
-    { width: 18 }, // C Target
-    { width: 42 }, // D Intent / Condition
-    { width: 11 }, // E Category
-    { width: 9 },  // F Priority
-    { width: 26 }, // G Precondition
-    { width: 34 }, // H Coverage / Data
-    { width: 34 }, // I Trigger
-    { width: 42 }, // J Expected
-    { width: 11 }, // K Mode
-    { width: 13 }, // L Trace
-    { width: 22 }, // M Result
-    { width: 12 }, // N Executed
-    { width: 13 }, // O Executor
-    { 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 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);
-  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, v, { bold: true, fill: SOFT_BLUE, center: true });
-  });
-
-  const HEADER_ROW = 8;
-  const hr = ws.getRow(HEADER_ROW);
-  hr.height = 28;
-  MATRIX_HEADERS.forEach((label, i) => headerCell(hr.getCell(2 + i), label));
-
-  let rowIdx = HEADER_ROW + 1;
-  for (const item of model.items) {
-    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})` : ''}` : (v.mocked ? 'Auto · Mocked' : 'Auto'),
-        v.traces.join(', '),
-        variantState(v),
-        isoDate(v.result?.startTime),
-        '',
-        // Redact BEFORE clipping — same denylist as the testcases CSV Note column.
-        v.result?.error ? clipNoteField(redactSecrets(String(v.result.error), model.secretValues)) : '',
-        '',
-      ];
-      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,
-      item.intent,
-      item.category,
-      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,
-      itemModeLabel(item),
-      item.traces.join(', '),
-      { 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,
-      ...(i === 14 && item.review === 'proposed' ? { color: DRAFT_RED } : {}),
-    }));
-  }
-
-  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',
-  };
+export function projectItem(item: DeliveryItem, mode: 'auto' | 'manual'): DeliveryItem | null {
+  const kept = item.variants.filter((v) => v.mode === mode);
+  if (kept.length === 0) return null;
+  if (kept.length === item.variants.length) return item;
+
+  const { result, counts } = rollUp(kept);
+  const synthesized = varyingTriggerNote(item.dimensions, item.variants.length);
+  const trigger = item.trigger.length === 1 && item.trigger[0] === synthesized
+    ? [varyingTriggerNote(item.dimensions, kept.length)]
+    : item.trigger;
+
+  return { ...item, variants: kept, result, resultCounts: counts, trigger, dimensions: undefined };
 }
 
-// ---------------------------------------------------------------------------
-// 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: 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);
-
-  let rowIdx = 7;
-
-  // --- Performance budget (#569) — advisory: config (qa/perf.yaml) vs measured runs.
-  if (model.perf) {
-    const p = model.perf;
-    dataCell(ws.getRow(rowIdx).getCell(2), 'Performance budget', { bold: true });
-    rowIdx++;
-    const r = ws.getRow(rowIdx);
-    dataCell(r.getCell(2), `p${p.percentile} ${p.metric.replace('_ms', ' time')}`);
-    dataCell(r.getCell(3), p.pass ? 'PASS' : 'OVER BUDGET', { bold: true });
-    dataCell(r.getCell(4), `measured ${p.measuredMs}ms`);
-    dataCell(r.getCell(5), `budget ${p.budgetMs}ms`);
-    dataCell(r.getCell(6), `${p.samples} runs`);
-    if (!p.pass && p.slowest.length) dataCell(r.getCell(8), `slowest: ${p.slowest.map((x) => `${x.ms}ms ${x.title.slice(0, 40)}`).join(' · ')}`);
-    rowIdx += 2;
-  }
-
-  // --- External Dependency Tracking (#580, ISTQB system-test practice): every case that
-  // ran against a MOCK is listed centrally. Its Result stays in the canonical vocabulary
-  // (the roll-up formulas depend on it); THIS table is where "Pass (Mocked) ≠ Pass (Real)"
-  // is visible — a case verified only against mocks is not Done until re-verified real.
-  {
-    const mockedVars = model.items.flatMap((it) => it.variants.filter((v) => v.mocked).map((v) => ({ it, v })));
-    if (mockedVars.length > 0) {
-      dataCell(ws.getRow(rowIdx).getCell(2), 'External Dependency Tracking — mock-verified cases (Pass here = Pass (Mocked), not Pass (Real))', { bold: true });
-      rowIdx++;
-      const hd = ws.getRow(rowIdx);
-      dataCell(hd.getCell(2), 'Variant');
-      dataCell(hd.getCell(3), 'Mocked dependency');
-      dataCell(hd.getCell(4), 'Delivery item');
-      dataCell(hd.getCell(5), 'Result');
-      dataCell(hd.getCell(8), 'Real-environment re-verify');
-      rowIdx++;
-      for (const { it, v } of mockedVars) {
-        const r = ws.getRow(rowIdx);
-        dataCell(r.getCell(2), v.ref);
-        dataCell(r.getCell(3), (v.mockDeps ?? []).join(', ') || '(scenario-level @mock)');
-        dataCell(r.getCell(4), it.id);
-        dataCell(r.getCell(5), variantState(v));
-        dataCell(r.getCell(8), '');
-        rowIdx++;
-      }
-      rowIdx++;
-    }
-  }
-
-  // --- 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++);
-  headerCell(gridHeader.getCell(2), 'Target');
-  CATEGORY_ORDER.forEach((cat, i) => headerCell(gridHeader.getCell(3 + i), cat));
-  headerCell(gridHeader.getCell(3 + CATEGORY_ORDER.length), 'Total');
-
-  const targets = Array.from(new Set(model.items.map((i) => i.target)));
-  for (const target of targets) {
-    const row = ws.getRow(rowIdx++);
-    dataCell(row.getCell(2), target, { bold: true });
-    let totalItems = 0;
-    let totalVariants = 0;
-    CATEGORY_ORDER.forEach((cat, i) => {
-      const cell = row.getCell(3 + i);
-      const items = model.items.filter((it) => it.target === target && it.category === cat);
-      const variants = items.reduce((a, it) => a + it.variants.length, 0);
-      totalItems += items.length;
-      totalVariants += variants;
-      // `—` is an explicit statement: this target × category cell has NO coverage.
-      dataCell(cell, items.length === 0 ? '—' : `${items.length} (${variants})`, {
-        center: true,
-        ...(items.length === 0 ? { fill: GAP_FILL } : {}),
-      });
-    });
-    dataCell(row.getCell(3 + CATEGORY_ORDER.length), `${totalItems} (${totalVariants})`, { center: true, bold: true });
-  }
-
-  // --- Dispositions ---
-  if (model.dispositions.length > 0) {
-    rowIdx += 1;
-    dataCell(ws.getRow(rowIdx).getCell(2), 'Not in the matrix (explicit dispositions)', { bold: true });
-    rowIdx += 1;
-    const dh = ws.getRow(rowIdx++);
-    ['Source', 'Disposition', 'Reason', 'Title'].forEach((l, i) => headerCell(dh.getCell(2 + i), l));
-    for (const d of model.dispositions) {
-      const row = ws.getRow(rowIdx++);
-      dataCell(row.getCell(2), d.vpId);
-      dataCell(row.getCell(3), d.as, { center: true });
-      dataCell(row.getCell(4), d.reason);
-      dataCell(row.getCell(5), d.title);
-    }
-  }
-
-  // --- Manifest ---
-  rowIdx += 1;
-  dataCell(ws.getRow(rowIdx).getCell(2), 'Generation manifest', { bold: true });
-  rowIdx += 1;
-  const m = model.manifest;
-  const manifestRows: Array<[string, string]> = [
-    ['Unit', m.unit],
-    ['Approval state', m.approvalState],
-    ['Delivery items', String(m.itemCount)],
-    ['Coverage variants', String(m.variantCount)],
-    ['Source fingerprint', m.sourceFingerprint],
-    ['Map fingerprint', m.mapFingerprint],
-    ['Transformer version', m.transformerVersion],
-    ['Max variants / item (warn)', String(m.thresholds.maxVariantsPerItem)],
-  ];
-  for (const [k, v] of manifestRows) {
-    const row = ws.getRow(rowIdx++);
-    dataCell(row.getCell(2), k, { bold: true, fill: SOFT_BLUE });
-    ws.mergeCells(rowIdx - 1, 3, rowIdx - 1, 7);
-    dataCell(row.getCell(3), v);
-  }
+/** Items projected onto one sheet, in model order. */
+export function projectItems(model: MatrixModel, mode: 'auto' | 'manual'): DeliveryItem[] {
+  return model.items.map((i) => projectItem(i, mode)).filter((i): i is DeliveryItem => i !== null);
 }
 
-// ---------------------------------------------------------------------------
-
 export function renderMatrixXlsx(model: MatrixModel, sungenVersion?: string): ExcelJS.Workbook {
   const wb = new ExcelJS.Workbook();
-  addMatrixSheet(wb, model, sungenVersion);
+  const sheets: SheetProjection[] = [
+    { sheetName: 'Auto', items: projectItems(model, 'auto') },
+    { sheetName: 'Manual', items: projectItems(model, 'manual') },
+  ];
+
+  addMatrixOverviewSheet(wb, model, sheets, sungenVersion);
+  for (const s of sheets) addTestcaseSheet(wb, s.sheetName, model, s.items, sungenVersion);
   addCoverageSheet(wb, model, sungenVersion);
   return wb;
 }

package/src/exporters/matrix/result-totals.ts

@@ -0,0 +1,37 @@
+/**
+ * Test-outcome totals of a matrix — the five result buckets plus the variant total.
+ *
+ * "Review state" (`manifest.approvalState`: proposed/approved/draft — a DESIGN fact about the
+ * delivery map) and "test outcome" (how the runs went) used to share one header word, `state:`, so
+ * a client read `state: approved` next to failing rows and asked which was true. Every surface that
+ * prints totals — CSV header, XLSX manifest, Overview roll-up, summary band, CLI — sums the SAME
+ * five buckets from here, so the numbers cannot disagree with each other.
+ */
+import { DeliveryItem } from './types';
+
+export interface ResultTotals {
+  total: number;
+  passed: number;
+  failed: number;
+  blocked: number;
+  pending: number; // not run yet (a variant with no result)
+  na: number;      // intentionally skipped — leaves the denominator
+}
+
+/** Sum the derived per-item roll-ups (Gate F: never entered independently). total = Σ variants. */
+export function resultTotals(items: DeliveryItem[]): ResultTotals {
+  const sum = (k: keyof DeliveryItem['resultCounts']): number => items.reduce((a, i) => a + i.resultCounts[k], 0);
+  return {
+    total: items.reduce((a, i) => a + i.variants.length, 0),
+    passed: sum('passed'),
+    failed: sum('failed'),
+    blocked: sum('blocked'),
+    pending: sum('notRun'),
+    na: sum('na'),
+  };
+}
+
+/** `72 passed / 10 failed / 0 blocked / 3 pending / 1 n/a` — the five buckets, always all five, in this order. */
+export function formatTestOutcome(t: ResultTotals): string {
+  return `${t.passed} passed / ${t.failed} failed / ${t.blocked} blocked / ${t.pending} pending / ${t.na} n/a`;
+}

package/src/exporters/matrix/testcase-summary-band.ts

@@ -0,0 +1,74 @@
+/**
+ * The BM-2-901-13 summary band on rows 6/7/8 of a testcase sheet:
+ * labels, live counts, percentages — matching the company template cell for cell.
+ */
+
+import * as ExcelJS from 'exceljs';
+import { BLACK, ARIAL_FONT, allBordersBlack, WHITE } from '../xlsx-report-builder';
+import { DeliveryItem } from './types';
+import { resultTotals } from './result-totals';
+import { headerCell } from './xlsx-cells';
+
+/** The counted data area — the template's own range, so a QA-appended row counts. */
+export const COUNT_START = 14;
+const COUNT_END = 9948;
+
+const R = (col: string): string => `${col}${COUNT_START}:${col}${COUNT_END}`;
+
+const BAND_LABELS = ['Total TCs', 'Passed', 'Failed', 'Pending', 'N/A', 'Remaining'];
+
+/**
+ * `Total TCs` counts column **K**, not column A.
+ *
+ * The template's own `COUNTA(A14:A…)` counts every row with an ID — which here
+ * means parent rows too, since a delivery item carries one. But `D7..G7` are
+ * `COUNTIF(L…)` over the state vocabulary, and those only ever match VARIANT
+ * rows: a parent's Result cell holds a composed "n/m Passed …" label, never a
+ * bare state word (that is what stops variants being counted twice). Counting A
+ * therefore mixed the two populations: on the `products` example `Total` read 46
+ * against 29 executable cases, the phantom 17 items landing in `Remaining` and
+ * dragging `% Passed` from 93% down to 59%.
+ *
+ * Column K (`Testcase type`) is the one column that is ALWAYS written on a
+ * variant and ALWAYS blank on a parent, so `COUNTA(K14:K…)` counts exactly the
+ * executable cases the state counters count. Every figure in the band — and the
+ * Overview roll-up that references it — now reconciles.
+ *
+ * The one cost: a row QA appends by hand is counted once its `Testcase type`
+ * cell is filled, not merely its ID. See the spec, §8.3.
+ */
+export function addSummaryBand(ws: ExcelJS.Worksheet, items: DeliveryItem[]): void {
+  const { total, passed, failed, pending, na } = resultTotals(items);
+  const remaining = total - passed - na;
+  const denom = Math.max(1, total - na);
+
+  BAND_LABELS.forEach((label, i) => {
+    const c = ws.getRow(6).getCell(3 + i);
+    headerCell(c, label);
+    c.alignment = { horizontal: 'center', vertical: 'top' };
+  });
+
+  const bandCell = (addr: string, value: ExcelJS.CellValue, numFmt?: string): void => {
+    const c = ws.getCell(addr);
+    if (value !== '') c.value = value;
+    c.font = { size: 10, color: BLACK, name: ARIAL_FONT };
+    c.fill = { type: 'pattern', pattern: 'solid', fgColor: WHITE };
+    c.alignment = { horizontal: 'center', vertical: 'top' };
+    c.border = allBordersBlack;
+    if (numFmt) c.numFmt = numFmt;
+  };
+  const f = (formula: string, result: number): ExcelJS.CellFormulaValue => ({ formula, result });
+
+  bandCell('C7', f(`COUNTA(${R('K')})`, total));
+  bandCell('D7', f(`COUNTIF(${R('L')},"Passed")`, passed));
+  bandCell('E7', f(`COUNTIF(${R('L')},"Failed")`, failed));
+  bandCell('F7', f(`COUNTIF(${R('L')},"Pending")`, pending));
+  bandCell('G7', f(`COUNTIF(${R('L')},"N/A")`, na));
+  bandCell('H7', f('C7-D7-G7', remaining), '#,##0');
+  // C8 carries no value in the template but still needs a border, so the band
+  // visually closes underneath "Total TCs".
+  bandCell('C8', '');
+  for (const [col, n] of [['D', passed], ['E', failed], ['F', pending], ['G', na], ['H', remaining]] as const) {
+    bandCell(`${col}8`, f(`IFERROR(${col}7/(C7-G7),0)`, n / denom), '0%');
+  }
+}