@sun-asterisk/sungen 3.2.17 → 3.2.18

package/src/exporters/matrix/map-loader.ts

@@ -0,0 +1,163 @@
+/**
+ * Delivery Map loader — `qa/<kind>/<unit>/delivery/<unit>.map.yaml`.
+ *
+ * Structural validation only (shape, required fields, enum values, duplicate ids).
+ * Semantic validation against the .feature is the gates' job (gates.ts) — the loader
+ * never reads the feature.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { DeliveryMap, MapCategory, MapDisposition, MapGroup, RequirementOverride, RequirementStatus, ReviewState } from './types';
+
+const CATEGORIES: MapCategory[] = ['normal', 'abnormal', 'security', 'nfr'];
+const REVIEW_STATES: ReviewState[] = ['proposed', 'approved'];
+const DISPOSITIONS = ['excluded', 'blocked', 'covered_elsewhere', 'accepted_risk'];
+const REQUIREMENT_STATUSES: RequirementStatus[] =
+  ['covered', 'partially_covered', 'covered_elsewhere', 'planned', 'gap', 'not_applicable'];
+
+export interface MapLoadResult {
+  map: DeliveryMap | null;
+  /** Structural problems — any entry blocks the matrix path (fix the file first). */
+  errors: string[];
+}
+
+/** Path of the map file for a unit directory (qa/<kind>/<screen>) + feature basename. */
+export function mapFilePath(unitDir: string, featureBaseName: string): string {
+  return path.join(unitDir, 'delivery', `${featureBaseName}.map.yaml`);
+}
+
+export function loadDeliveryMap(file: string): MapLoadResult {
+  if (!fs.existsSync(file)) return { map: null, errors: [] };
+  const errors: string[] = [];
+  let raw: unknown;
+  try {
+    raw = parseYaml(fs.readFileSync(file, 'utf-8'));
+  } catch (e) {
+    return { map: null, errors: [`map YAML does not parse: ${e instanceof Error ? e.message : e}`] };
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { map: null, errors: ['map root must be a YAML mapping'] };
+  }
+  const doc = raw as Record<string, unknown>;
+
+  const groups: MapGroup[] = [];
+  const seenIds = new Set<string>();
+  const rawGroups = doc.groups;
+  if (!Array.isArray(rawGroups) || rawGroups.length === 0) {
+    errors.push('map has no `groups` list');
+  } else {
+    rawGroups.forEach((g, i) => {
+      if (!g || typeof g !== 'object') { errors.push(`groups[${i}] is not a mapping`); return; }
+      const grp = g as Record<string, unknown>;
+      const where = `groups[${i}]${typeof grp.id === 'string' ? ` (${grp.id})` : ''}`;
+      for (const field of ['id', 'target', 'intent', 'oracle'] as const) {
+        if (typeof grp[field] !== 'string' || !(grp[field] as string).trim()) {
+          errors.push(`${where}: missing/empty \`${field}\``);
+        }
+      }
+      if (!CATEGORIES.includes(grp.category as MapCategory)) {
+        errors.push(`${where}: \`category\` must be one of ${CATEGORIES.join(' | ')}`);
+      }
+      const review = (grp.review ?? 'proposed') as ReviewState;
+      if (!REVIEW_STATES.includes(review)) {
+        errors.push(`${where}: \`review\` must be proposed | approved`);
+      }
+      const variants = grp.variants;
+      if (!Array.isArray(variants) || variants.length === 0 || variants.some((v) => typeof v !== 'string' || !v.trim())) {
+        errors.push(`${where}: \`variants\` must be a non-empty list of VP refs`);
+      }
+      const id = String(grp.id ?? '');
+      if (id) {
+        if (seenIds.has(id)) errors.push(`duplicate group id \`${id}\``);
+        seenIds.add(id);
+      }
+      groups.push({
+        id,
+        target: String(grp.target ?? ''),
+        intent: String(grp.intent ?? ''),
+        oracle: String(grp.oracle ?? ''),
+        ...(grp.dimensions !== undefined ? { dimensions: String(grp.dimensions) } : {}),
+        category: grp.category as MapCategory,
+        review,
+        variants: Array.isArray(variants) ? variants.map(String) : [],
+      });
+    });
+  }
+
+  const dispositions: Record<string, MapDisposition> = {};
+  if (doc.dispositions !== undefined) {
+    if (!doc.dispositions || typeof doc.dispositions !== 'object' || Array.isArray(doc.dispositions)) {
+      errors.push('`dispositions` must be a mapping of VP-id → { as, reason }');
+    } else {
+      for (const [vpId, d] of Object.entries(doc.dispositions as Record<string, unknown>)) {
+        const dd = (d && typeof d === 'object' ? d : {}) as Record<string, unknown>;
+        if (!DISPOSITIONS.includes(String(dd.as))) {
+          errors.push(`dispositions.${vpId}: \`as\` must be one of ${DISPOSITIONS.join(' | ')}`);
+        }
+        dispositions[vpId] = { as: dd.as as MapDisposition['as'], reason: dd.reason ? String(dd.reason) : undefined };
+      }
+    }
+  }
+
+  const requirements: Record<string, RequirementOverride> = {};
+  if (doc.requirements !== undefined) {
+    if (!doc.requirements || typeof doc.requirements !== 'object' || Array.isArray(doc.requirements)) {
+      errors.push('`requirements` must be a mapping of requirement-id → { status, note }');
+    } else {
+      for (const [reqId, r] of Object.entries(doc.requirements as Record<string, unknown>)) {
+        const rr = (r && typeof r === 'object' ? r : {}) as Record<string, unknown>;
+        if (!REQUIREMENT_STATUSES.includes(String(rr.status) as RequirementStatus)) {
+          errors.push(`requirements.${reqId}: \`status\` must be one of ${REQUIREMENT_STATUSES.join(' | ')}`);
+        }
+        requirements[reqId] = { status: rr.status as RequirementStatus, note: rr.note ? String(rr.note) : undefined };
+      }
+    }
+  }
+
+  const fingerprints: Record<string, string> = {};
+  if (doc.fingerprints && typeof doc.fingerprints === 'object' && !Array.isArray(doc.fingerprints)) {
+    for (const [k, v] of Object.entries(doc.fingerprints as Record<string, unknown>)) {
+      fingerprints[k] = String(v);
+    }
+  }
+
+  const map: DeliveryMap = {
+    version: Number(doc.version ?? 1),
+    unit: String(doc.unit ?? ''),
+    formNo: doc.form_no !== undefined ? String(doc.form_no) : undefined,
+    groups,
+    dispositions,
+    requirements,
+    fingerprints,
+  };
+  return { map: errors.length > 0 ? null : map, errors };
+}
+
+/**
+ * Write the map back (used by `--approve` to flip review states + stamp fingerprints).
+ * Field order is kept stable so approve-diffs stay minimal and reviewable.
+ */
+export function writeDeliveryMap(file: string, map: DeliveryMap): void {
+  const doc: Record<string, unknown> = {
+    version: map.version,
+    unit: map.unit,
+    ...(map.formNo !== undefined ? { form_no: map.formNo } : {}),
+    groups: map.groups.map((g) => ({
+      id: g.id,
+      target: g.target,
+      intent: g.intent,
+      oracle: g.oracle,
+      ...(g.dimensions !== undefined ? { dimensions: g.dimensions } : {}),
+      category: g.category,
+      review: g.review,
+      variants: g.variants,
+    })),
+    ...(Object.keys(map.dispositions).length > 0 ? { dispositions: map.dispositions } : {}),
+    ...(Object.keys(map.requirements).length > 0 ? { requirements: map.requirements } : {}),
+    ...(Object.keys(map.fingerprints).length > 0 ? { fingerprints: map.fingerprints } : {}),
+  };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, stringifyYaml(doc, { lineWidth: 0 }), 'utf-8');
+}

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

@@ -0,0 +1,94 @@
+/**
+ * Flat CSV rendering of the matrix — same model as the workbook, one row per
+ * delivery item (`Level: item`) followed by its variant rows (`Level: variant`;
+ * every item has them — the variant row carries the source scenario id, data,
+ * and result), so downstream pipelines can re-derive both views from one file.
+ */
+
+import { variantState } from './build';
+import { coverageSummary, itemModeLabel, itemResultLabel } from './render-xlsx';
+import { MatrixModel } from './types';
+
+const HEADERS = [
+  'Level', 'ID', 'Target', 'Test Intent / Condition', 'Category', 'Priority',
+  'Precondition', 'Coverage / Test Data', 'Action / Trigger', 'Expected Result',
+  'Mode', 'Trace', 'Result', 'Executed Date', 'Note / Evidence', 'Defect ID',
+];
+
+function esc(value: string): string {
+  if (/[",\n]/.test(value)) return `"${value.replace(/"/g, '""')}"`;
+  return value;
+}
+
+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')}`;
+}
+
+export function renderMatrixCsv(model: MatrixModel): string {
+  const BOM = '\ufeff'; // Excel compatibility (Vietnamese/Japanese content)
+  const lines: string[] = [];
+  lines.push(`# Test Case & Coverage Matrix — ${model.unit}`);
+  lines.push(`# delivery items: ${model.manifest.itemCount} · coverage variants: ${model.manifest.variantCount} · state: ${model.manifest.approvalState}`);
+  lines.push(HEADERS.map(esc).join(','));
+
+  for (const item of model.items) {
+    lines.push([
+      'item',
+      item.id,
+      item.target,
+      item.intent,
+      item.category,
+      item.priority,
+      item.precondition.join('\n'),
+      coverageSummary(item),
+      // Shared leading steps only; each variant row carries its remaining steps.
+      item.trigger.join('\n'),
+      item.oracle,
+      itemModeLabel(item),
+      item.traces.join(' '),
+      itemResultLabel(item),
+      '',
+      item.review === 'proposed' ? 'REVIEW REQUIRED' : '',
+      '',
+    ].map(esc).join(','));
+
+    for (const v of item.variants) {
+      const expected = v.verification.length > 0
+        ? `${v.oracle.join('\n')}\nVerification method: ${v.verification.join(' ')}`
+        : v.oracle.join('\n');
+      lines.push([
+        'variant',
+        v.ref,
+        '',
+        v.condition,
+        '', '',
+        // Precondition DELTA — variant-specific setup only (review GAP-03).
+        (item.preconditionDeltas[v.ref] ?? []).join('\n'),
+        v.data.join('\n'),
+        // Steps after the parent's shared prefix only.
+        (item.triggerDeltas[v.ref] ?? []).join('\n'),
+        expected,
+        v.mode === 'manual' ? 'Manual' : 'Auto',
+        v.traces.join(' '),
+        variantState(v),
+        isoDate(v.result?.startTime),
+        v.result?.error ? String(v.result.error).slice(0, 200) : '',
+        '',
+      ].map(esc).join(','));
+    }
+  }
+
+  // Requirement coverage appendix — keeps the CSV self-contained for pipelines.
+  if (model.requirements.length > 0) {
+    lines.push('');
+    lines.push('# Requirement coverage');
+    lines.push(['Requirement', 'Status', 'Delivery items', 'Variants', 'Note'].join(','));
+    for (const r of model.requirements) {
+      lines.push([r.id, r.status, r.items.join(' '), String(r.variantCount), r.note].map(esc).join(','));
+    }
+  }
+  return BOM + lines.join('\n') + '\n';
+}

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

@@ -0,0 +1,420 @@
+/**
+ * Render the Test Case & Coverage Matrix workbook.
+ *
+ * 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.
+ *
+ * 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';
+import {
+  renderReportHeaderBand,
+  allBordersBlack,
+  ARIAL_FONT,
+  BLACK,
+  LAVENDER,
+} from '../xlsx-report-builder';
+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;
+}
+
+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';
+}
+
+/**
+ * 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.
+ */
+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})` : ''}` : '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,
+      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',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 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;
+
+  // --- 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);
+  }
+}
+
+// ---------------------------------------------------------------------------
+
+export function renderMatrixXlsx(model: MatrixModel, sungenVersion?: string): ExcelJS.Workbook {
+  const wb = new ExcelJS.Workbook();
+  addMatrixSheet(wb, model, sungenVersion);
+  addCoverageSheet(wb, model, sungenVersion);
+  return wb;
+}