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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.16-beta.3",
+  "version": "3.2.16-beta.4",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -39,8 +39,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.2.16-beta.3",
-    "@sungen/driver-ui": "3.2.16-beta.3",
+    "@sungen/driver-data-factory": "3.2.16-beta.4",
+    "@sungen/driver-ui": "3.2.16-beta.4",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

package/src/cli/commands/delivery.ts

@@ -31,6 +31,7 @@ import {
   loadMatrixModel,
   approveMatrix,
   writeMatrixDeliverables,
+  MatrixFormat,
   hasErrors,
   hasReview,
 } from '../../exporters/matrix/export';
@@ -651,7 +652,7 @@ interface MatrixRunSummary {
 async function exportMatrixTarget(
   cwd: string,
   target: DeliveryTarget,
-  opts: { check?: boolean; preview?: boolean },
+  opts: { check?: boolean; preview?: boolean; format?: MatrixFormat },
 ): Promise<MatrixRunSummary | null> {
   const paths = matrixPathsFor(cwd, target);
   const { model, mapMissing, mapErrors } = loadMatrixModel(paths);
@@ -689,24 +690,25 @@ async function exportMatrixTarget(
     return null;
   }
 
-  const { csvPath, xlsxPath } = await writeMatrixDeliverables(paths, model);
+  const { csvPath, xlsxPath } = await writeMatrixDeliverables(paths, model, opts.format ?? 'xlsx');
   const passed = model.items.reduce((a, i) => a + i.resultCounts.passed, 0);
   const failed = model.items.reduce((a, i) => a + i.resultCounts.failed, 0);
-  log(`  ${COLOR.green}→ ${path.relative(cwd, xlsxPath)}${COLOR.reset} ${COLOR.gray}(+ ${path.relative(cwd, csvPath)})${COLOR.reset}`);
+  const written = [xlsxPath, csvPath].filter((p): p is string => !!p).map((p) => path.relative(cwd, p));
+  for (const rel of written) log(`  ${COLOR.green}→ ${rel}${COLOR.reset}`);
   return {
     label: paths.label,
     items: model.manifest.itemCount,
     variants: model.manifest.variantCount,
     passed,
     failed,
-    file: path.relative(cwd, xlsxPath),
+    file: written.join(' + '),
   };
 }
 
 function printMatrixSummaryTable(summaries: MatrixRunSummary[]): void {
   log(`\n${COLOR.bold}Delivery matrix export complete${COLOR.reset}\n`);
   const colWidth = Math.max(20, ...summaries.map((s) => s.label.length)) + 1;
-  log(`  ${'Feature'.padEnd(colWidth)}Items  Variants  Passed  Failed  File`);
+  log(`  ${'Feature'.padEnd(colWidth)}Items  Variants  Passed  Failed  File(s)`);
   log('  ' + '-'.repeat(colWidth + 50));
   for (const s of summaries) {
     log(
@@ -796,9 +798,11 @@ export function registerDeliveryCommand(program: Command): void {
     .option('--check', 'Matrix gates only — validate the delivery map, write nothing')
     .option('--approve [ids]', 'Approve proposed groups (all, or a comma-separated id list) + stamp fingerprints')
     .option('--preview', 'Render the matrix despite review-required findings (DRAFT watermark)')
+    .option('--format <format>', 'Matrix output format: xlsx (default) | csv | both', 'xlsx')
     .action(async (names: string[], options: {
       skipPreflight?: boolean; continueOnMissing?: boolean; env?: string;
       legacy?: boolean; full?: boolean; check?: boolean; approve?: boolean | string; preview?: boolean;
+      format?: string;
     }) => {
       try {
         // Same effect as running with SUNGEN_ENV=<env> — result-file resolution,
@@ -806,6 +810,13 @@ export function registerDeliveryCommand(program: Command): void {
         if (options.env) process.env.SUNGEN_ENV = options.env;
         const cwd = process.cwd();
 
+        // Matrix output format — one artifact by default (xlsx); csv/both on request.
+        const format = (options.format ?? 'xlsx').toLowerCase();
+        if (!['xlsx', 'csv', 'both'].includes(format)) {
+          console.error(`${COLOR.red}Invalid --format "${options.format}"${COLOR.reset} — use xlsx | csv | both`);
+          process.exit(1);
+        }
+
         // 1. Scope detection — each positional name expands into one target
         //    per `.feature` file inside that screen/flow. Passing a specific
         //    feature basename (e.g. `home-modal`) narrows to that one file.
@@ -886,7 +897,9 @@ export function registerDeliveryCommand(program: Command): void {
           const matrixSummaries: MatrixRunSummary[] = [];
           let failedTargets = 0;
           for (const target of toExport) {
-            const s = await exportMatrixTarget(cwd, target, { check: options.check, preview: options.preview });
+            const s = await exportMatrixTarget(cwd, target, {
+              check: options.check, preview: options.preview, format: format as MatrixFormat,
+            });
             if (s) matrixSummaries.push(s);
             else failedTargets++;
           }

package/src/exporters/matrix/build.ts

@@ -14,7 +14,7 @@ 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,
@@ -72,12 +72,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 +141,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 +247,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;
@@ -386,7 +397,12 @@ 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 ?? [],
+      // 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: (first?.precondition ?? []).filter((line) =>
+        groupVariants.every((v) => v.precondition.includes(line))),
       trigger: triggerShapes.size === 1 ? (first?.trigger ?? []) : ['(per variant)'],
       variants: groupVariants,
       result,

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) {

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

@@ -12,7 +12,7 @@ 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 {
@@ -36,7 +36,8 @@ export function renderMatrixCsv(model: MatrixModel): string {
 
   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)';
+    const triggerIsCommon = triggerTexts.size === 1;
+    const commonPre = new Set(item.precondition);
     lines.push([
       'item',
       item.id,
@@ -46,13 +47,15 @@ export function renderMatrixCsv(model: MatrixModel): string {
       item.priority,
       item.precondition.join('\n'),
       `${item.variants.length} variant(s): ${item.variants.map((v) => v.condition).join(' · ')}`,
-      commonTrigger,
+      // No placeholder text: when triggers differ the variant rows carry them (GAP-01).
+      triggerIsCommon ? item.variants[0].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 +68,17 @@ export function renderMatrixCsv(model: MatrixModel): string {
         '',
         v.condition,
         '', '',
-        '',
+        // Precondition DELTA — variant-specific setup only (review GAP-03).
+        v.precondition.filter((line) => !commonPre.has(line)).join('\n'),
         v.data.join('\n'),
-        v.trigger.join('\n'),
+        triggerIsCommon ? '' : v.trigger.join('\n'),
         expected,
         v.mode === 'manual' ? 'Manual' : 'Auto',
         v.traces.join(' '),
         v.result ? statusToTestResult(v.result.status) : 'Pending',
         isoDate(v.result?.startTime),
         v.result?.error ? String(v.result.error).slice(0, 200) : '',
+        '',
       ].map(esc).join(','));
     }
   }

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

@@ -120,7 +120,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 +144,35 @@ 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.
+  // 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; parent cells hold composed labels — exact-match COUNTIF
+  // therefore counts variants only.
   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);
+  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: 0' } 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: 0' } 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,16 +188,25 @@ 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.
+    const commonPre = new Set(item.precondition);
+    const triggerTextsAll = new Set(item.variants.map((v) => v.trigger.join('\n')));
+    const triggerIsCommon = triggerTextsAll.size === 1;
     for (const v of item.variants) {
       const vr = ws.getRow(rowIdx++);
       vr.outlineLevel = 1;
+      const preDelta = v.precondition.filter((line) => !commonPre.has(line));
       const vValues: ExcelJS.CellValue[] = [
         v.ref,
         '',
         v.condition,
-        '', '', '',
+        '', '',
+        numbered(preDelta),
         numbered(v.data),
-        numbered(v.trigger),
+        triggerIsCommon ? '' : numbered(v.trigger),
         expectedWithVerification(v.oracle, v.verification),
         v.mode === 'manual' ? `Manual${v.manualReason ? ` (${v.manualReason})` : ''}` : 'Auto',
         v.traces.join(', '),
@@ -195,6 +214,7 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
         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 +227,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 commonTrigger = triggerIsCommon ? item.variants[0].trigger : null;
     const coverage = `${item.variants.length} variant(s): ${item.variants.map((v) => v.condition).join(' · ')}`;
 
-    // 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 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",` +
+      `IF(COUNTIF(${rng},"Blocked")>0,COUNTIF(${rng},"Passed")&"/"&${EFF}&" Passed · "&COUNTIF(${rng},"Blocked")&" Blocked",` +
+      `IF(${EFF}=0,"N/A",` +
+      `IF(COUNTIF(${rng},"Passed")=${EFF},${EFF}&"/"&${EFF}&" Passed",` +
+      `IF(COUNTIF(${rng},"Passed")=0,"Pending",COUNTIF(${rng},"Passed")&"/"&${EFF}&" Passed · pending")))))`;
 
     const values: ExcelJS.CellValue[] = [
       item.id,
@@ -229,7 +251,8 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
       item.priority,
       numbered(item.precondition),
       coverage,
-      commonTrigger ? numbered(commonTrigger) : '(differs per variant — see sub-rows)',
+      // No placeholder text: when triggers differ the sub-rows carry them (GAP-01).
+      commonTrigger ? numbered(commonTrigger) : '',
       item.oracle,
       itemModeLabel(item),
       item.traces.join(', '),
@@ -237,6 +260,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 +270,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 +303,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 });

package/src/exporters/matrix/types.ts

@@ -57,7 +57,9 @@ export interface DeliveryMap {
   /** Requirement-id → reviewed status override (partially_covered / not_applicable / …).
    *  Without an override a requirement is `covered` when a variant traces to it, else `gap`. */
   requirements: Record<string, RequirementOverride>;
-  /** VP-id → scenario fingerprint stamped at approval time (drift detector input). */
+  /** VP-id → scenario fingerprint stamped at approval time (drift detector input).
+   *  The reserved key `__map__` holds the fingerprint of the map's own semantic
+   *  content (groups + dispositions) so edited wording re-opens review (GAP-09). */
   fingerprints: Record<string, string>;
 }
 

package/src/exporters/matrix/wording.ts

@@ -19,10 +19,13 @@ function deRef(text: string): string {
 }
 
 function sentence(text: string): string {
-  let s = text.trim().replace(/\s+/g, ' ');
+  // Trim the ENDS only — internal whitespace may be the test data itself
+  // (a padded email, a spaces-only value); collapsing it would silently
+  // change what the tester types (review GAP-04).
+  let s = text.trim();
   if (!s) return s;
   s = s.charAt(0).toUpperCase() + s.slice(1);
-  if (!/[.!?…]$/.test(s)) s += '.';
+  if (!/[.!?…"]$/.test(s)) s += '.';
   return s;
 }
 
@@ -42,7 +45,7 @@ export function renderAction(raw: string): string {
     // click [X] <type>
     [/^clicks? \[([^\]]+)\]\s*(\w+)?$/i, (m) => `Click the ${m[1]}${m[2] ? ` ${m[2]}` : ''}`],
     // press <Key> at/in [X] field
-    [/^press(?:es)? (.+?) (?:at|in|inside) \[([^\]]+)\](?: field)?$/i, (m) => `Press ${m[1]} in the ${m[2]} field`],
+    [/^press(?:es)? (.+?) (?:at|in|on|inside) \[([^\]]+)\](?: field)?$/i, (m) => `Press ${m[1]} in the ${m[2]} field`],
     [/^press(?:es)? (.+)$/i, (m) => `Press ${m[1]}`],
     // select V in/from [X] dropdown
     [/^selects? (.+?) (?:in|from) \[([^\]]+)\]\s*(\w+)?$/i, (m) => `Select ${m[1]} in the ${m[2]}${m[3] ? ` ${m[3]}` : ''}`],
@@ -103,9 +106,23 @@ export function renderPrecondition(raw: string): string {
   const s = raw.trim().replace(/^(User|The user)\s+/i, '');
   const m = s.match(/^is on \[([^\]]+)\] page(.*)$/i);
   if (m) return sentence(`The user is on the ${m[1]} page${m[2] ?? ''}`);
+  // "wait for [X] <type> (is) visible" is a STATE once established, not an action.
+  const w = s.match(/^waits? for \[([^\]]+)\]\s*(\w+)?(?: is)?(?: visible)?$/i);
+  if (w) return sentence(`The ${w[1]}${w[2] ? ` ${w[2]}` : ''} is visible`);
+  const auth = s.match(/^is (signed|logged) (in|out)(.*)$/i);
+  if (auth) return sentence(`The user is ${auth[1]} ${auth[2]}${auth[3] ?? ''}`);
   return sentence(deRef(`The user ${s.charAt(0).toLowerCase()}${s.slice(1)}`));
 }
 
+/**
+ * A manual `Setup:` line is an INSTRUCTION the tester performs to establish the
+ * state — imperative reads correctly ("Seed the locked account."), while
+ * "The user seed …" is broken grammar (review GAP-08).
+ */
+export function renderSetupInstruction(raw: string): string {
+  return renderAction(raw);
+}
+
 // ---------------------------------------------------------------------------
 // Manual `# Tester verifies:` comment classification (structured, label-free)
 // ---------------------------------------------------------------------------

package/src/orchestrator/templates/ai-src/commands/delivery.md

@@ -1,7 +1,7 @@
 ---
 name: delivery
 description: "Export the Test Case & Coverage Matrix (review/manual/customer deliverable) from Gherkin + Playwright results. --legacy exports the classic per-scenario CSV/XLSX."
-argument-hint: "[name...] [--env <locale>] [--legacy] (omit names for all; --env for locale-specific export)"
+argument-hint: "[name...] [--format csv] [--env <locale>] [--legacy] (omit names for all)"
 order: 50
 claude-tools: "Bash, Read, Write, AskUserQuestion"
 copilot-tools: "[read, execute, edit, vscode/askQuestions]"
@@ -27,6 +27,8 @@ review → approve → official render.
 
 Parse from `$ARGUMENTS`:
 - **names** — zero or more screen/flow/api names. Empty → all targets.
+- **`--format <xlsx|csv|both>`** — output format. **Default `xlsx` — one artifact only.** Pass
+  `--format csv` when the user wants the flat CSV (pipelines/diffing), `--format both` for both.
 - **`--env <locale>`** — sets `SUNGEN_ENV=<locale>` for the run (accept `--locale` as alias).
 - **`--legacy` / `--full`** — pass through to the CLI and skip the map flow entirely.
 
@@ -37,8 +39,8 @@ Parse from `$ARGUMENTS`:
 ```bash
 [ -x ./bin/sungen.js ] && ./bin/sungen.js delivery <names> || npx sungen delivery <names>
 ```
-(prepend `SUNGEN_ENV=<locale>` when `--env` was given; append `--legacy` when requested — then skip
-to step 5.)
+(prepend `SUNGEN_ENV=<locale>` when `--env` was given; append `--format <fmt>` when the user asked
+for a non-default format; append `--legacy` when requested — then skip to step 5.)
 
 Three outcomes per target:
 - **Rendered** → done, go to step 5.
@@ -151,6 +153,7 @@ counted in variants, never items**). Then `AskUserQuestion`:
 - **Open the workbook** — inspect `qa/deliverables/<unit>-testcases.xlsx` (Testcases sheet:
   collapse outline level 1 for the customer view; Coverage sheet: target × category grid + gaps).
 - **Run tests to refresh results** — `/sungen:run-test <unit>`, then re-run delivery.
+- **Also export CSV** — `sungen delivery <unit> --format csv` (flat `item`/`variant` rows for pipelines).
 - **Export the legacy workbook too** — `sungen delivery <unit> --legacy`.
 - **Done**
 
@@ -168,7 +171,8 @@ counted in variants, never items**). Then `AskUserQuestion`:
 ## CLI reference
 
 ```
-sungen delivery [names...]        # matrix (default; needs the map)
+sungen delivery [names...]        # matrix (default; needs the map) → XLSX only
+  --format <xlsx|csv|both>        # output format; default xlsx (one artifact)
   --check                         # gates only — validate the map, write nothing
   --approve [DI-a,DI-b]           # flip proposed→approved (+ stamp fingerprints); all groups when bare
   --preview                       # render despite review findings (DRAFT watermark)
@@ -176,5 +180,6 @@ sungen delivery [names...]        # matrix (default; needs the map)
   --skip-preflight | --continue-on-missing | --env <env>   # as before
 ```
 
-Outputs: `qa/deliverables/<unit>-testcases.xlsx` (Testcases + Coverage sheets) + `.csv`
-(flat, `Level` column `item|variant`). Legacy mode writes the classic files instead.
+Outputs: `qa/deliverables/<unit>-testcases.xlsx` (Testcases + Coverage sheets) by default;
+`--format csv` writes `<unit>-testcases.csv` instead (flat, `Level` column `item|variant`),
+`--format both` writes both. Legacy mode writes the classic files instead.