@sun-asterisk/sungen 3.2.16-beta.3 → 3.2.16-beta.5

package/src/exporters/matrix/build.ts

@@ -14,13 +14,14 @@ import {
   splitVpAndName,
 } from '../feature-parser';
 import { getCasesDatasetRows, resolveResultVariants } from '../result-variants';
-import { classifyManualComments, renderAction, renderExpected, renderPrecondition } from './wording';
+import { classifyManualComments, renderAction, renderExpected, renderPrecondition, renderSetupInstruction } from './wording';
 import { scenarioFingerprint, combinedFingerprint, mapContentFingerprint } from './fingerprint';
 import {
   CoverageVariant,
   DeliveryItem,
   DeliveryMap,
   ItemResult,
+  VariantState,
   MatrixDisposition,
   MatrixLayer,
   MatrixModel,
@@ -72,12 +73,12 @@ 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}: ${String(v)}`);
+      pairs.push(`${k}: ${displayValue(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}: ${val}`);
+    if (val !== undefined) pairs.push(`${v}: ${displayValue(val)}`);
   }
   return pairs;
 }
@@ -141,7 +142,7 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
       ...(authRole ? [authRole === 'no-auth' ? 'The user is signed out.' : `The user is signed in as ${authRole}.`] : []),
       ...inputs.feature.backgroundGivenSteps.map(renderPrecondition),
       ...m.feature.rawGivenSteps.map(renderPrecondition),
-      ...(manual?.preconditions ?? []).map((t) => renderPrecondition(t)),
+      ...(manual?.preconditions ?? []).map((t) => renderSetupInstruction(t)),
     ]));
 
     const base = {
@@ -247,11 +248,22 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
 function substituteDisplayVars(text: string, vars: Record<string, string>): string {
   return text.replace(/\{\{\s*([^}\s]+)\s*\}\}/g, (m, key: string) => {
     if (!(key in vars)) return m; // unknown stays literal → Gate D flags it
-    const v = vars[key];
-    return v === '' ? '(empty)' : v;
+    return displayValue(vars[key]);
   });
 }
 
+/**
+ * Make invisible test data VISIBLE instead of losing it (review GAP-04):
+ * '' → (empty) · whitespace-only → (N spaces) · padded → quoted verbatim.
+ * The canonical value is never changed — only its presentation.
+ */
+export function displayValue(v: string): string {
+  if (v === '') return '(empty)';
+  if (/^\s+$/.test(v)) return `(${v.length} space${v.length > 1 ? 's' : ''})`;
+  if (v !== v.trim()) return `"${v}"`;
+  return v;
+}
+
 function sentenceOf(text: string): string {
   const s = text.trim();
   if (!s) return s;
@@ -315,28 +327,57 @@ function rowAsStrings(row: Record<string, unknown>): Record<string, string> {
 // Item assembly + roll-up
 // ---------------------------------------------------------------------------
 
-function classifyResult(r: PlaywrightResult | undefined): 'passed' | 'failed' | 'blocked' | 'notRun' {
-  if (!r) return 'notRun';
-  if (r.status === 'passed') return 'passed';
-  if (r.status === 'failed' || r.status === 'timedOut') return 'failed';
-  if (r.status === 'interrupted') return 'blocked';
-  return 'notRun'; // skipped / unknown
+/**
+ * The exact word rendered in a variant's Result cell. This is the SINGLE
+ * vocabulary both the renderers and the parent's COUNTIF roll-up use — the
+ * legacy exporter's statusToTestResult disagreed on two statuses (`skipped`
+ * showed N/A but counted as not-run; `interrupted` showed Pending but counted
+ * as blocked), which silently skewed the derived parent result.
+ */
+export function variantState(v: CoverageVariant): VariantState {
+  const r = v.result;
+  if (!r) return 'Pending';
+  switch (r.status) {
+    case 'passed': return 'Passed';
+    case 'failed':
+    case 'timedOut': return 'Failed';
+    case 'interrupted': return 'Blocked';
+    case 'skipped': return 'N/A';
+    default: return 'Pending';
+  }
 }
 
-/** Derived parent result — precedence: failed → blocked → not_run → partial → passed. */
+const STATE_TO_COUNT: Record<VariantState, keyof DeliveryItem['resultCounts']> = {
+  Passed: 'passed', Failed: 'failed', Blocked: 'blocked', Pending: 'notRun', 'N/A': 'na',
+};
+
+/**
+ * Derived parent result — precedence failed → blocked → all-N/A → not_run →
+ * partial → passed. `N/A` variants leave the denominator (an intentionally
+ * skipped case must not make the parent look incomplete).
+ */
 export function rollUp(variants: CoverageVariant[]): { result: ItemResult; counts: DeliveryItem['resultCounts'] } {
-  const counts = { passed: 0, failed: 0, blocked: 0, notRun: 0 };
-  for (const v of variants) counts[classifyResult(v.result)]++;
-  const run = counts.passed + counts.failed + counts.blocked;
+  const counts = { passed: 0, failed: 0, blocked: 0, notRun: 0, na: 0 };
+  for (const v of variants) counts[STATE_TO_COUNT[variantState(v)]]++;
+  const effective = variants.length - counts.na;
   let result: ItemResult;
   if (counts.failed > 0) result = 'failed';
   else if (counts.blocked > 0) result = 'blocked';
-  else if (run === 0) result = 'not_run';
-  else if (counts.notRun > 0) result = 'partial';
-  else result = 'passed';
+  else if (effective === 0) result = 'na';
+  else if (counts.passed === 0) result = 'not_run';
+  else if (counts.passed === effective) result = 'passed';
+  else result = 'partial';
   return { result, counts };
 }
 
+/** Longest shared leading run of steps — hoisted onto the parent row. */
+function commonPrefix(lists: string[][]): number {
+  if (lists.length === 0) return 0;
+  let n = 0;
+  while (lists.every((l) => l.length > n) && new Set(lists.map((l) => l[n])).size === 1) n++;
+  return n;
+}
+
 /**
  * Expand one map variant ref to concrete variant refs:
  * a bare VP-id whose scenario has a dataset means ALL its rows.
@@ -367,8 +408,13 @@ export function buildMatrix(inputs: BuildInputs): MatrixModel {
     const groupVariants = g.variants.flatMap((ref) => expandMapRef(ref, variantsByVp));
     const { result, counts } = rollUp(groupVariants);
     const first = groupVariants[0];
-    const triggerShapes = new Set(groupVariants.map((v) => v.triggerShape.join(' ; ')));
     const modes = new Set(groupVariants.map((v) => v.mode));
+    const commonPre = (first?.precondition ?? []).filter((line) =>
+      groupVariants.every((v) => v.precondition.includes(line)));
+    // Steps every variant starts with belong on the parent once; each variant
+    // renders only its remaining steps (review: the shared prefix was repeated
+    // on every child while the parent cell sat empty).
+    const prefixLen = commonPrefix(groupVariants.map((v) => v.trigger));
     // Item priority = highest variant priority (per-variant priorities stay visible).
     const priorityRank: Record<string, number> = { High: 0, Normal: 1, Low: 2 };
     const priority = groupVariants
@@ -386,8 +432,17 @@ export function buildMatrix(inputs: BuildInputs): MatrixModel {
       mode: modes.size > 1 ? 'mixed' : (first?.mode ?? 'auto'),
       layers: Array.from(new Set(groupVariants.flatMap((v) => v.layers))),
       traces: Array.from(new Set(groupVariants.flatMap((v) => v.traces))),
-      precondition: first?.precondition ?? [],
-      trigger: triggerShapes.size === 1 ? (first?.trigger ?? []) : ['(per variant)'],
+      dimensions: g.dimensions,
+      // Only the preconditions COMMON to every variant belong on the parent —
+      // copying the first variant's setup mis-states the start state of the
+      // others (review GAP-03). Variant-specific lines render as the sub-row's
+      // precondition delta.
+      precondition: commonPre,
+      preconditionDeltas: Object.fromEntries(groupVariants.map((v) =>
+        [v.ref, v.precondition.filter((line) => !commonPre.includes(line))])),
+      triggerDeltas: Object.fromEntries(groupVariants.map((v) =>
+        [v.ref, v.trigger.slice(prefixLen)])),
+      trigger: (first?.trigger ?? []).slice(0, prefixLen),
       variants: groupVariants,
       result,
       resultCounts: counts,

package/src/exporters/matrix/export.ts

@@ -17,6 +17,7 @@ import { getPackageVersion } from '../package-info';
 import { writeCsv } from '../csv-exporter';
 import { writeXlsx } from '../xlsx-exporter';
 import { loadDeliveryMap, writeDeliveryMap } from './map-loader';
+import { mapContentFingerprint } from './fingerprint';
 import { buildMatrix, deriveVariants } from './build';
 import { renderMatrixXlsx } from './render-xlsx';
 import { renderMatrixCsv } from './render-csv';
@@ -121,14 +122,28 @@ export function approveMatrix(paths: MatrixTargetPaths, groupIds?: string[]): {
     g.review = 'approved';
     approved.push(g.id);
   }
+  // Freeze the reviewed map semantics as well (GAP-09) — computed AFTER the
+  // review flips so re-running approve on an unchanged map is idempotent.
+  map.fingerprints.__map__ = mapContentFingerprint(map.groups, map.dispositions);
   writeDeliveryMap(paths.mapFile, map);
   return { findings: model.findings.filter((f) => f.severity !== 'error'), approved };
 }
 
-/** Render + write both artifacts. Caller has already enforced the gate policy. */
-export async function writeMatrixDeliverables(paths: MatrixTargetPaths, model: MatrixModel): Promise<{ csvPath: string; xlsxPath: string }> {
-  const csvPath = writeCsv(paths.cwd, paths.unit, renderMatrixCsv(model));
-  const wb = renderMatrixXlsx(model, getPackageVersion());
-  const xlsxPath = await writeXlsx(paths.cwd, paths.unit, wb);
-  return { csvPath, xlsxPath };
+export type MatrixFormat = 'xlsx' | 'csv' | 'both';
+
+/** Render + write the requested format(s). Caller has already enforced the gate policy. */
+export async function writeMatrixDeliverables(
+  paths: MatrixTargetPaths,
+  model: MatrixModel,
+  format: MatrixFormat = 'xlsx',
+): Promise<{ csvPath?: string; xlsxPath?: string }> {
+  const out: { csvPath?: string; xlsxPath?: string } = {};
+  if (format === 'csv' || format === 'both') {
+    out.csvPath = writeCsv(paths.cwd, paths.unit, renderMatrixCsv(model));
+  }
+  if (format === 'xlsx' || format === 'both') {
+    const wb = renderMatrixXlsx(model, getPackageVersion());
+    out.xlsxPath = await writeXlsx(paths.cwd, paths.unit, wb);
+  }
+  return out;
 }

package/src/exporters/matrix/gates.ts

@@ -12,6 +12,7 @@
  */
 
 import { splitVpAndName, extractTestcaseType } from '../feature-parser';
+import { mapContentFingerprint } from './fingerprint';
 import { CoverageVariant, MatrixFinding, MAX_VARIANTS_PER_ITEM } from './types';
 import { expandMapRef, BuildInputs } from './build';
 
@@ -266,6 +267,25 @@ function gateEDrift(ctx: GateContext, findings: MatrixFinding[]): void {
   const { map } = ctx.inputs;
   const { variantsByVp } = ctx;
 
+  // The map's own semantics (targets/intents/oracles/grouping) are part of what
+  // was approved — an edit after approval must be re-reviewed, not silently
+  // published (review GAP-09).
+  const stampedMap = map.fingerprints.__map__;
+  const liveMap = mapContentFingerprint(map.groups, map.dispositions);
+  if (map.groups.some((g) => g.review === 'approved')) {
+    if (!stampedMap) {
+      findings.push({
+        gate: 'E', severity: 'review',
+        message: 'the delivery map has no stamped content fingerprint — run `sungen delivery --approve` to record the reviewed wording',
+      });
+    } else if (stampedMap !== liveMap) {
+      findings.push({
+        gate: 'E', severity: 'review',
+        message: 'the delivery map wording/grouping changed since approval — re-review, then `sungen delivery --approve`',
+      });
+    }
+  }
+
   for (const g of map.groups) {
     if (g.review !== 'approved') continue; // proposed groups are already under review
     for (const ref of g.variants) {
@@ -300,7 +320,22 @@ const WORDING_SMELLS: Array<[RegExp, string]> = [
 
 function gateWWording(ctx: GateContext, findings: MatrixFinding[]): void {
   for (const g of ctx.inputs.map.groups) {
-    for (const [field, text] of [['intent', g.intent], ['oracle', g.oracle]] as const) {
+    const variantCount = g.variants.flatMap((ref) => expandMapRef(ref, ctx.variantsByVp)).length;
+    // Without a digest the parent row can only list variant refs — a reviewer
+    // then has to expand the item to learn which dimensions it covers.
+    if (variantCount > 3 && !g.dimensions) {
+      findings.push({
+        gate: 'W', severity: 'warning', ref: g.id,
+        message: `group ${g.id} has ${variantCount} variants and no \`dimensions:\` digest — add a short one (e.g. "required ×3 · format ×9") so the collapsed view stays informative`,
+      });
+    }
+    if (g.dimensions && g.dimensions.length > 120) {
+      findings.push({
+        gate: 'W', severity: 'warning', ref: g.id,
+        message: `group ${g.id} \`dimensions:\` is ${g.dimensions.length} chars — keep the digest short (≤120)`,
+      });
+    }
+    for (const [field, text] of ([['intent', g.intent], ['oracle', g.oracle], ...(g.dimensions ? [['dimensions', g.dimensions] as const] : [])] as const)) {
       for (const [re, what] of WORDING_SMELLS) {
         if (re.test(text)) {
           findings.push({

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

@@ -78,6 +78,7 @@ export function loadDeliveryMap(file: string): MapLoadResult {
         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) : [],
@@ -148,6 +149,7 @@ export function writeDeliveryMap(file: string, map: DeliveryMap): void {
       target: g.target,
       intent: g.intent,
       oracle: g.oracle,
+      ...(g.dimensions !== undefined ? { dimensions: g.dimensions } : {}),
       category: g.category,
       review: g.review,
       variants: g.variants,

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

@@ -5,14 +5,14 @@
  * and result), so downstream pipelines can re-derive both views from one file.
  */
 
-import { statusToTestResult } from '../playwright-report-parser';
-import { itemModeLabel, itemResultLabel } from './render-xlsx';
+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',
+  'Mode', 'Trace', 'Result', 'Executed Date', 'Note / Evidence', 'Defect ID',
 ];
 
 function esc(value: string): string {
@@ -35,8 +35,6 @@ export function renderMatrixCsv(model: MatrixModel): string {
   lines.push(HEADERS.map(esc).join(','));
 
   for (const item of model.items) {
-    const triggerTexts = new Set(item.variants.map((v) => v.trigger.join('\n')));
-    const commonTrigger = triggerTexts.size === 1 ? item.variants[0].trigger.join('\n') : '(differs per variant — see variant rows)';
     lines.push([
       'item',
       item.id,
@@ -45,14 +43,16 @@ export function renderMatrixCsv(model: MatrixModel): string {
       item.category,
       item.priority,
       item.precondition.join('\n'),
-      `${item.variants.length} variant(s): ${item.variants.map((v) => v.condition).join(' · ')}`,
-      commonTrigger,
+      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) {
@@ -65,15 +65,18 @@ export function renderMatrixCsv(model: MatrixModel): string {
         '',
         v.condition,
         '', '',
-        '',
+        // Precondition DELTA — variant-specific setup only (review GAP-03).
+        (item.preconditionDeltas[v.ref] ?? []).join('\n'),
         v.data.join('\n'),
-        v.trigger.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(' '),
-        v.result ? statusToTestResult(v.result.status) : 'Pending',
+        variantState(v),
         isoDate(v.result?.startTime),
         v.result?.error ? String(v.result.error).slice(0, 200) : '',
+        '',
       ].map(esc).join(','));
     }
   }

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

@@ -27,8 +27,8 @@ import {
   BLACK,
   LAVENDER,
 } from '../xlsx-report-builder';
-import { statusToTestResult } 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' };
@@ -63,22 +63,21 @@ export function itemModeLabel(item: DeliveryItem): string {
   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, 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];
-}
-
-function variantResultLabel(v: CoverageVariant): string {
-  if (!v.result) return 'Pending';
-  return statusToTestResult(v.result.status);
+  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). */
@@ -89,10 +88,24 @@ function isoDate(startTime: string | undefined): string {
   return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
 }
 
-function numbered(lines: string[]): string {
+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. */
@@ -120,7 +133,7 @@ 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 Result', 'Mode', 'Trace',
-  'Result', 'Executed Date', 'Executor', 'Note\n(Evidence, DefectID)',
+  'Result', 'Executed Date', 'Executor', 'Note / Evidence', 'Defect ID',
 ];
 const RESULT_COL = 13; // column M
 
@@ -144,25 +157,40 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
     { 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;
@@ -178,6 +206,10 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
     // 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;
@@ -185,16 +217,20 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
         v.ref,
         '',
         v.condition,
-        '', '', '',
+        '', '',
+        numbered(item.preconditionDeltas[v.ref] ?? []),
         numbered(v.data),
-        numbered(v.trigger),
+        // 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(', '),
-        variantResultLabel(v),
+        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.
@@ -207,19 +243,21 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
     // --- 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 triggerTexts = new Set(item.variants.map((v) => v.trigger.join('\n')));
-    const commonTrigger = triggerTexts.size === 1 ? item.variants[0].trigger : null;
-    const coverage = `${item.variants.length} variant(s): ${item.variants.map((v) => v.condition).join(' · ')}`;
+    const coverage = coverageSummary(item);
 
-    // Live roll-up: derived from the child Result cells so hand-entered results
-    // recompute the parent — precedence failed → blocked → pending → partial → passed.
+    // 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")&"/${n} Passed · "&COUNTIF(${rng},"Failed")&" Failed",` +
-      `IF(COUNTIF(${rng},"Blocked")>0,"Blocked",` +
-      `IF(COUNTIF(${rng},"Passed")=${n},"${n}/${n} Passed",` +
-      `IF(COUNTIF(${rng},"Passed")=0,"Pending",COUNTIF(${rng},"Passed")&"/${n} Passed · pending"))))`;
+      `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,
@@ -229,7 +267,8 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
       item.priority,
       numbered(item.precondition),
       coverage,
-      commonTrigger ? numbered(commonTrigger) : '(differs per variant — see sub-rows)',
+      // The shared leading steps; each variant's remaining steps sit on its sub-row.
+      numbered(item.trigger),
       item.oracle,
       itemModeLabel(item),
       item.traces.join(', '),
@@ -237,6 +276,7 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
       '',
       '',
       item.review === 'proposed' ? 'REVIEW REQUIRED' : '',
+      '',
     ];
     values.forEach((v, i) => dataCell(pr.getCell(2 + i), v, {
       bold: true,
@@ -246,9 +286,18 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
     }));
   }
 
-  ws.autoFilter = { from: { row: HEADER_ROW, column: 2 }, to: { row: rowIdx - 1, column: 16 } };
+  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',
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -270,8 +319,14 @@ function addCoverageSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersio
   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++);
-    ['Requirement', 'Status', 'Delivery items', 'Variants', 'Note'].forEach((l, i) => headerCell(rh.getCell(2 + i), l));
+    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 });