@sun-asterisk/sungen 3.2.28 → 3.2.30

package/src/exporters/api-testcase-formatter.ts

@@ -16,6 +16,7 @@
  */
 
 import { ApiCatalogEntry } from './types';
+import { SENSITIVE_NAME, isSensitiveKey } from './sensitive-key';
 
 /** A single `@api:<name>(k=v,…)` invocation parsed from a scenario's tags. */
 export interface ApiCall {
@@ -372,12 +373,6 @@ function formatBodyFile(bodyFile: unknown, args: Record<string, string>, localiz
   return `${p} (${spec.mimeType || 'application/octet-stream'})`;
 }
 
-/**
- * Credential name matcher (substring, not anchored) for both body-field keys and
- * test-data keys — catches variants like confirmPassword / new_password /
- * password_confirmation / access_token / client_secret / otp / passcode.
- */
-export const SENSITIVE_NAME = /pass(word|code)?|passwd|pwd|secret|token|otp|api[-_]?key|apikey|credential|authorization|signature/i;
 function isSensitiveField(key: string): boolean {
   return SENSITIVE_NAME.test(key);
 }
@@ -387,11 +382,14 @@ function isSensitiveField(key: string): boolean {
  * over the finished Steps/Expected cells, closing the paths key-based masking misses
  * (nested request bodies, query-string credentials, and the Expected assertion cell).
  * Values shorter than 3 chars are skipped to avoid masking trivial/coincidental text.
+ * Sensitivity is judged by the key segment that NAMES the value (see isSensitiveKey): the
+ * test-data map also carries per-index array leaves (`tokens.0.label`), and matching the
+ * whole key would redact every field under a list whose name happens to be a credential word.
  */
 export function collectSecretValues(testData: Record<string, string>): string[] {
   const secrets: string[] = [];
   for (const [k, v] of Object.entries(testData)) {
-    if (typeof v === 'string' && v.length >= 3 && SENSITIVE_NAME.test(k)) secrets.push(v);
+    if (typeof v === 'string' && v.length >= 3 && isSensitiveKey(k)) secrets.push(v);
   }
   // Longest-first so a longer secret is redacted before any shorter substring of it.
   return [...new Set(secrets)].sort((a, b) => b.length - a.length);

package/src/exporters/feature-parser.ts

@@ -125,7 +125,7 @@ export function extractPriority(tags: string[]): string {
 
 /**
  * Extract testcase type from scenario tags.
- * Matches the bare `@manual` AND the reason-coded form `@manual:M1`..`@manual:M9`
+ * Matches the bare `@manual` AND the reason-coded form `@manual:M1`..`@manual:M11`
  * (the canonical way to tag manual scenarios). Without the `startsWith` check a
  * `@manual:M1` scenario was misclassified as `Auto` → rendered "Not compiled"/"N/A"
  * in the report instead of "Manual"/"Pending".

package/src/exporters/matrix/build.ts

@@ -18,6 +18,7 @@ import {
 } from '../feature-parser';
 import { getCasesDatasetRows, resolveResultVariants } from '../result-variants';
 import { renderDynamicTokens } from '../test-data-resolver';
+import { maskCredentialValue } from '../sensitive-key';
 import { classifyManualComments, renderAction, renderExpected, renderPrecondition, renderSetupInstruction, runtimeVarsOf } from './wording';
 import { scenarioFingerprint, combinedFingerprint, mapContentFingerprint } from './fingerprint';
 import {
@@ -100,12 +101,13 @@ function resolveDataPairs(
   if (row) {
     for (const [k, v] of Object.entries(row)) {
       if (k.startsWith('__') || k === 'case' || k === 'name' || k === 'label') continue;
-      pairs.push(`${k}: ${displayValue(String(v))}`);
+      pairs.push(`${k}: ${displayValue(maskCredentialValue(k, String(v)))}`);
     }
   }
   for (const v of vars) {
     const val = row && v in row ? undefined : testData?.[v]; // row columns already listed
-    if (val !== undefined) pairs.push(`${v}: ${displayValue(val)}`);
+    // Credential-named refs (`accounts.0.password`) render `***` — this column is read outside the run.
+    if (val !== undefined) pairs.push(`${v}: ${displayValue(maskCredentialValue(v, val))}`);
   }
   return pairs;
 }
@@ -168,8 +170,16 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
     // Values the scenario itself produces during the run — captured from the page
     // or bound by a capability precondition. The compiler registers these as
     // "captured" and skips YAML validation; the matrix does the same.
+    // Background steps count too: scenario-merger keeps them OUT of resolvedSteps
+    // (they render as Pre-condition, not Steps), so a Background `remember … as
+    // {{v}}` registered nowhere — its token then survived into every scenario's
+    // shared precondition cell and Gate D blocked the entire unit (#684).
     const runtimeVars = runtimeVarsOf(
-      [...m.resolvedSteps.map((st) => st.text), ...m.resolvedExpected.map((st) => st.text)],
+      [
+        ...inputs.feature.backgroundOrderedSteps.map((st) => st.text),
+        ...m.resolvedSteps.map((st) => st.text),
+        ...m.resolvedExpected.map((st) => st.text),
+      ],
       tags,
     );
 
@@ -500,6 +510,10 @@ export function varyingTriggerNote(dimensions: string | undefined, count: number
   // before the dash is the axis name.
   const axis = dimensions?.split('—')[0].trim();
   const where = axis && axis.length > 0 && axis.length <= 60 ? ` by ${axis}` : '';
+  // A single variant is reachable when an item is projected onto one execution
+  // mode (the Auto / Manual split) and only one of its variants lands there —
+  // nothing "differs" any more, so point at the one row that carries the steps.
+  if (count === 1) return `The action is the variant's own — see the row below.`;
   return `The action differs${where} — run each of the ${count} variants below with its own steps.`;
 }
 

package/src/exporters/matrix/item-labels.ts

@@ -0,0 +1,78 @@
+/**
+ * Cell-text derivation shared by the XLSX and CSV matrix renderers — the
+ * parent-row summaries (mode, result, coverage) and the small formatters that
+ * turn model arrays into readable cell content.
+ */
+
+import { DeliveryItem } from './types';
+
+/** 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}`;
+}
+
+/**
+ * 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.
+ *
+ * On a projected item (the Auto / Manual split) the count reflects the variants
+ * present in THAT sheet — a mixed item reads "1 variant" on each side, never
+ * the item's full total.
+ */
+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(' · ')}`;
+}
+
+/** ISO date (2026-08-04) — unambiguous across locales (review §9). */
+export 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 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');
+}
+
+/** Expected cell = observable outcomes; the HOW moves under a separate heading. */
+export function expectedWithVerification(oracle: string[], verification: string[]): string {
+  const expected = numbered(oracle);
+  if (verification.length === 0) return expected;
+  return `${expected}\nVerification method: ${verification.join(' ')}`;
+}
+
+/** The Testcase type cell (column K) — mode plus why it is what it is. */
+export function variantTypeLabel(v: DeliveryItem['variants'][number]): string {
+  if (v.mode === 'manual') return `Manual${v.manualReason ? ` (${v.manualReason})` : ''}`;
+  return v.mocked ? 'Auto · Mocked' : 'Auto';
+}

package/src/exporters/matrix/render-coverage-sheet.ts

@@ -0,0 +1,170 @@
+/**
+ * Sheet 4 — Coverage: requirement coverage (id ↔ items ↔ status), the
+ * target × category grid (with explicit `—` gaps), the mock-verified case
+ * tracker, dispositions, and the generation manifest.
+ *
+ * Reports on the WHOLE model — it is deliberately not split by execution mode,
+ * because a requirement is covered or not regardless of who runs the case.
+ *
+ * Moved out of `render-xlsx.ts` unchanged when the workbook grew to four sheets.
+ */
+
+import * as ExcelJS from 'exceljs';
+import { renderReportHeaderBand } from '../xlsx-report-builder';
+import { variantState } from './build';
+import { MatrixModel, MapCategory } from './types';
+import { formatTestOutcome, resultTotals } from './result-totals';
+import { GAP_FILL, SOFT_BLUE, dataCell, headerCell, draftBanner } from './xlsx-cells';
+
+const CATEGORY_ORDER: MapCategory[] = ['normal', 'abnormal', 'security', 'nfr'];
+
+export 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],
+    ['Review state (design approval)', m.approvalState],
+    ['Test outcome', formatTestOutcome(resultTotals(model.items))],
+    ['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);
+  }
+}

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

@@ -10,6 +10,7 @@ import { clipNoteField } from '../playwright-report-parser';
 import { variantState } from './build';
 import { coverageSummary, itemModeLabel, itemResultLabel } from './render-xlsx';
 import { MatrixModel } from './types';
+import { formatTestOutcome, resultTotals } from './result-totals';
 
 const HEADERS = [
   'Level', 'ID', 'Target', 'Test Intent / Condition', 'Category', 'Priority',
@@ -33,7 +34,8 @@ 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}`);
+  // 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))}`);
   lines.push(HEADERS.map(esc).join(','));
 
   for (const item of model.items) {

package/src/exporters/matrix/render-overview-sheet.ts

@@ -0,0 +1,51 @@
+/**
+ * Sheet 1 — Overview: the roll-up table over the Auto and Manual sheets.
+ *
+ * Thin adapter. The table itself is `addOverviewSheet` in the shared report
+ * builder — the same one the legacy path uses — so both delivery formats show
+ * the customer one identical summary. All this module does is turn the matrix
+ * model plus the per-sheet item projections into the summary shape it wants.
+ *
+ * Every count in that table is a LIVE reference into the detail sheet's band
+ * (`'Auto'!D7`), never a frozen number, so it recomputes when QA edits results.
+ */
+
+import * as ExcelJS from 'exceljs';
+import { addOverviewSheet } from '../xlsx-report-builder';
+import { DeliveryItem, MatrixModel } from './types';
+import { resultTotals } from './result-totals';
+
+/** One detail sheet: its tab name and the items projected onto it. */
+export interface SheetProjection {
+  sheetName: string;
+  items: DeliveryItem[];
+}
+
+/**
+ * `total` counts VARIANTS only — parent rows are delivery items, not executable
+ * cases. It must match what the detail band's `C7=COUNTA(K14:K…)` counts, since
+ * a cached value and the live formula beside it have to tell one story. See
+ * `testcase-summary-band.ts` for why the count anchors on column K.
+ */
+function summaryOf(unit: string, items: DeliveryItem[]): {
+  screen: string; total: number; passed: number; failed: number; pending: number; na: number;
+} {
+  // The Overview form has no Blocked column: a blocked variant stays inside `Remain` (total − passed − N/A),
+  // exactly as the sheet's live band counts it.
+  const t = resultTotals(items);
+  return { screen: unit, total: t.total, passed: t.passed, failed: t.failed, pending: t.pending, na: t.na };
+}
+
+export function addMatrixOverviewSheet(
+  wb: ExcelJS.Workbook,
+  model: MatrixModel,
+  sheets: SheetProjection[],
+  sungenVersion?: string,
+): void {
+  addOverviewSheet(
+    wb,
+    sheets.map((s) => ({ sheetName: s.sheetName, summary: summaryOf(model.unit, s.items) })),
+    sungenVersion,
+    { titleLabel: `${model.unit.toUpperCase()} TEST CASE & COVERAGE MATRIX`, formNo: model.formNo },
+  );
+}

package/src/exporters/matrix/render-testcase-sheet.ts

@@ -0,0 +1,178 @@
+/**
+ * One BM-2-901-13 testcase sheet of the matrix workbook (Auto or Manual).
+ *
+ * Layout is the company template, cell for cell: masthead rows 1-4, the summary
+ * band on rows 6/7/8, the `*: Mandatory` legend on row 12, the 16 column headers
+ * `A..P` on row 13, and data from row 14.
+ *
+ * Two row levels: one parent row per delivery item, each followed by its 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).
+ * Variant Result cells carry the state dropdown; the parent Result is a live
+ * formula over its children, so a parent can never contradict its variants even
+ * after QA edits results by hand.
+ */
+
+import * as ExcelJS from 'exceljs';
+import { renderReportHeaderBand, ARIAL_FONT } from '../xlsx-report-builder';
+import { redactSecrets } from '../api-testcase-formatter';
+import { clipNoteField } from '../playwright-report-parser';
+import { variantState } from './build';
+import { DeliveryItem, MatrixModel } from './types';
+import { SOFT_BLUE, DRAFT_RED, RESULT_STATES, dataCell, headerCell, draftBanner } from './xlsx-cells';
+import { addSummaryBand } from './testcase-summary-band';
+import {
+  coverageSummary, expectedWithVerification, isoDate, itemResultLabel, numbered, variantTypeLabel,
+} from './item-labels';
+
+/** Column headers on row 13 — `A..P`, matching the template exactly. */
+export const TESTCASE_HEADERS = [
+  'ID*', 'Target', 'Test Intent / Condition', 'Category', 'Priority', 'Precondition',
+  'Coverage / Test Data', 'Action / Trigger*', 'Expected results*', 'Trace', 'Testcase type',
+  'Test Result*', 'Executed Date*', 'Test Executor*', 'Test Environment',
+  'Note\n(Test evidence, DefectID, Actual result)',
+];
+
+/** Column widths `A..P`, from the template (H widened — Action / Trigger is the longest cell). */
+const COLUMN_WIDTHS = [20, 12.5, 15.38, 16.25, 17, 25.51, 24.88, 50, 41, 12, 13.5, 15.88, 13.5, 16.5, 23, 29];
+
+export const HEADER_ROW = 13;
+/** Column L — the one the band's COUNTIFs and the parent roll-ups read. */
+export const RESULT_COL = 12;
+
+/** Variant sub-row — only what distinguishes it from its parent (review GAP-01). */
+function variantValues(item: DeliveryItem, v: DeliveryItem['variants'][number], model: MatrixModel): ExcelJS.CellValue[] {
+  return [
+    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.traces.join(', '),
+    variantTypeLabel(v),
+    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)) : '',
+  ];
+}
+
+/**
+ * Live parent roll-up over 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 → "All N/A".
+ * The range covers only the children present in THIS sheet, so a mixed item's
+ * two parent rows legitimately report two different numbers.
+ */
+function rollUpFormula(n: number, firstChild: number, lastChild: number): string {
+  const rng = `L${firstChild}:L${lastChild}`;
+  const EFF = `(${n}-COUNTIF(${rng},"N/A"))`;
+  const NA = `IF(COUNTIF(${rng},"N/A")>0," · "&COUNTIF(${rng},"N/A")&" N/A","")`;
+  return (
+    `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})))`
+  );
+}
+
+/** Parent row — only values genuinely COMMON to the whole item (review M-04). */
+function parentValues(item: DeliveryItem, formula: string): ExcelJS.CellValue[] {
+  return [
+    item.id,
+    item.target,
+    item.intent,
+    item.category,
+    item.priority,
+    numbered(item.precondition),
+    coverageSummary(item),
+    // The shared leading steps; each variant's remaining steps sit on its sub-row.
+    numbered(item.trigger),
+    item.oracle,
+    item.traces.join(', '),
+    // K (Testcase type) stays blank on a parent — it is not an executable case.
+    '',
+    { formula, result: itemResultLabel(item) } as ExcelJS.CellValue,
+    '',
+    '',
+    '',
+    item.review === 'proposed' ? 'REVIEW REQUIRED' : '',
+  ];
+}
+
+/**
+ * Append one testcase sheet holding `items` (already projected onto this sheet's
+ * execution mode). Always called for both Auto and Manual, even when one side is
+ * empty: Overview then always has exactly two rows, and QA has somewhere to add
+ * hand-written cases. An empty sheet's band reads 0 and its percentages resolve
+ * through IFERROR — never `#DIV/0!`.
+ */
+export function addTestcaseSheet(
+  wb: ExcelJS.Workbook,
+  sheetName: string,
+  model: MatrixModel,
+  items: DeliveryItem[],
+  sungenVersion?: string,
+): void {
+  const ws = wb.addWorksheet(sheetName);
+  ws.properties.outlineLevelRow = 1;
+  ws.columns = COLUMN_WIDTHS.map((width) => ({ width }));
+
+  renderReportHeaderBand(wb, ws, `${model.unit.toUpperCase()} TEST CASE & COVERAGE MATRIX`, sungenVersion, model.formNo);
+  draftBanner(ws, model);
+  addSummaryBand(ws, items);
+
+  const legend = ws.getCell('A12');
+  legend.value = '*: Mandatory';
+  legend.font = { italic: true, size: 10, name: ARIAL_FONT, color: { argb: 'FF808080' } };
+
+  const hr = ws.getRow(HEADER_ROW);
+  hr.height = 38;
+  TESTCASE_HEADERS.forEach((label, i) => headerCell(hr.getCell(1 + i), label));
+
+  let rowIdx = HEADER_ROW + 1;
+  for (const item of items) {
+    const parentRowIdx = rowIdx++;
+
+    // Variant sub-rows FIRST — the parent's formula needs their cell range.
+    const firstChild = rowIdx;
+    for (const v of item.variants) {
+      const vr = ws.getRow(rowIdx++);
+      vr.outlineLevel = 1;
+      variantValues(item, v, model).forEach((val, i) => dataCell(vr.getCell(1 + i), val, { center: i === 10 }));
+      // Manual-execution entry: constrain the Result cell to the known states.
+      vr.getCell(RESULT_COL).dataValidation = {
+        type: 'list', allowBlank: true, formulae: [`"${RESULT_STATES}"`],
+      };
+    }
+
+    const pr = ws.getRow(parentRowIdx);
+    const values = parentValues(item, rollUpFormula(item.variants.length, firstChild, rowIdx - 1));
+    values.forEach((v, i) => dataCell(pr.getCell(1 + i), v, {
+      bold: true,
+      fill: SOFT_BLUE,
+      center: i === 3 || i === 4,
+      ...(i === 15 && item.review === 'proposed' ? { color: DRAFT_RED } : {}),
+    }));
+  }
+
+  const lastRow = Math.max(rowIdx - 1, HEADER_ROW);
+  ws.autoFilter = { from: { row: HEADER_ROW, column: 1 }, to: { row: lastRow, column: 16 } };
+  ws.views = [{ state: 'frozen', xSplit: 0, ySplit: HEADER_ROW }];
+  // Print: landscape, fit width only (never squash all rows into one page),
+  // repeat the masthead + band + header rows on every page (review GAP-08).
+  ws.pageSetup = {
+    orientation: 'landscape',
+    fitToPage: true,
+    fitToWidth: 1,
+    fitToHeight: 0,
+    printTitlesRow: `1:${HEADER_ROW}`,
+  };
+}