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

package/src/exporters/matrix/export.ts

@@ -31,10 +31,18 @@ export interface MatrixTargetPaths {
   featureFile: string;
   testDataFile: string;
   specFile: string;
+  /** requirements/spec.md — the requirement-id inventory for coverage (optional). */
+  specMdFile?: string;
   resultsPath: string | null;
   mapFile: string;
 }
 
+function readSpecText(paths: MatrixTargetPaths): string {
+  return paths.specMdFile && fs.existsSync(paths.specMdFile)
+    ? fs.readFileSync(paths.specMdFile, 'utf-8')
+    : '';
+}
+
 export interface MatrixLoadResult {
   model?: MatrixModel;
   map?: DeliveryMap;
@@ -64,6 +72,7 @@ export function loadMatrixModel(paths: MatrixTargetPaths): MatrixLoadResult {
     results,
     map,
     transformerVersion: getPackageVersion(),
+    specText: readSpecText(paths),
   });
   return { model, map, mapErrors: [] };
 }
@@ -88,6 +97,7 @@ export function approveMatrix(paths: MatrixTargetPaths, groupIds?: string[]): {
   const model = buildMatrix({
     unit: paths.unit, feature, merged, testData, results: null, map,
     transformerVersion: getPackageVersion(),
+    specText: readSpecText(paths),
   });
   const blocking = model.findings.filter((f) => f.severity === 'error');
   if (blocking.length > 0) return { findings: blocking, approved: [] };

package/src/exporters/matrix/gates.ts

@@ -29,6 +29,7 @@ export function runGates(ctx: GateContext): MatrixFinding[] {
   gateDExecutability(ctx, findings);
   gateEDrift(ctx, findings);
   gateGReviewState(ctx, findings);
+  gateWWording(ctx, findings);
   return findings;
 }
 
@@ -155,10 +156,11 @@ function gateCAggregation(ctx: GateContext, findings: MatrixFinding[]): void {
     const heuristicsConfirmed = g.review === 'approved' && !stale;
 
     // Hard signature parts — recomputed, never trusted from the map. ERROR on mismatch.
+    // Execution mode and priority are deliberately NOT here: they are coverage
+    // dimensions (account states may need seeded manual variants next to auto ones;
+    // an item takes the highest variant priority) — shown per variant, never split on.
     const hard: Array<[string, (v: CoverageVariant) => string]> = [
-      ['execution mode', (v) => v.mode],
       ['test layer', (v) => [...v.layers].sort().join('+')],
-      ['priority', (v) => v.priority],
     ];
     for (const [label, keyOf] of hard) {
       const distinct = new Set(vs.map(keyOf));
@@ -241,6 +243,21 @@ function gateDExecutability(ctx: GateContext, findings: MatrixFinding[]): void {
       }
     }
   }
+
+  // No template token may survive into a RENDERED cell (review B-04) — this also
+  // catches cross-referencing test-data values the one-level resolver couldn't close.
+  for (const [, vs] of variantsByVp) {
+    for (const v of vs) {
+      const rendered = [...v.precondition, ...v.trigger, ...v.oracle, ...v.verification, ...v.data];
+      const token = rendered.map((t) => t.match(/\{\{[^}]*\}\}/)).find(Boolean);
+      if (token) {
+        findings.push({
+          gate: 'D', severity: 'error', ref: v.ref,
+          message: `${v.ref}: unresolved template token ${token[0]} remains in the rendered output — the export is not deterministic for a tester`,
+        });
+      }
+    }
+  }
 }
 
 // --- Gate E — drift (stale approval) ------------------------------------------
@@ -271,6 +288,31 @@ function gateEDrift(ctx: GateContext, findings: MatrixFinding[]): void {
   }
 }
 
+// --- Gate W — controlled-language lint on the map's semantic fields --------------
+
+/** Patterns that make customer-facing wording read machine-generated (review §10). */
+const WORDING_SMELLS: Array<[RegExp, string]> = [
+  [/\{\{[^}]*\}\}/, 'an unresolved {{token}}'],
+  [/\b(?:Setup|Observable|Oracle):/, 'a generator label (Setup:/Observable:/Oracle:)'],
+  [/\bUser (?:fill|click|press|see|wait)\b/i, 'DSL phrasing ("User fill/click/see…") — write plain product language'],
+  [/\[[^\]]+\]/, 'a [selector-style] reference — use the visible UI label'],
+];
+
+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) {
+      for (const [re, what] of WORDING_SMELLS) {
+        if (re.test(text)) {
+          findings.push({
+            gate: 'W', severity: 'warning', ref: g.id,
+            message: `group ${g.id} ${field} contains ${what}`,
+          });
+        }
+      }
+    }
+  }
+}
+
 // --- Gate G — review state -----------------------------------------------------
 
 function gateGReviewState(ctx: GateContext, findings: MatrixFinding[]): void {

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

@@ -9,11 +9,13 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
-import { DeliveryMap, MapCategory, MapDisposition, MapGroup, ReviewState } from './types';
+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;
@@ -98,6 +100,21 @@ export function loadDeliveryMap(file: string): MapLoadResult {
     }
   }
 
+  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>)) {
@@ -111,6 +128,7 @@ export function loadDeliveryMap(file: string): MapLoadResult {
     formNo: doc.form_no !== undefined ? String(doc.form_no) : undefined,
     groups,
     dispositions,
+    requirements,
     fingerprints,
   };
   return { map: errors.length > 0 ? null : map, errors };
@@ -135,6 +153,7 @@ export function writeDeliveryMap(file: string, map: DeliveryMap): void {
       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 });

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

@@ -1,15 +1,17 @@
 /**
  * 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`),
- * so downstream pipelines can re-derive both views from one file.
+ * 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 { statusToTestResult, formatExecutedDate } from '../playwright-report-parser';
+import { statusToTestResult } from '../playwright-report-parser';
+import { 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 (Oracle)',
+  'Precondition', 'Coverage / Test Data', 'Action / Trigger', 'Expected Result',
   'Mode', 'Trace', 'Result', 'Executed Date', 'Note',
 ];
 
@@ -18,6 +20,13 @@ function esc(value: string): string {
   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[] = [];
@@ -26,8 +35,8 @@ export function renderMatrixCsv(model: MatrixModel): string {
   lines.push(HEADERS.map(esc).join(','));
 
   for (const item of model.items) {
-    const single = item.variants.length === 1;
-    const only = single ? item.variants[0] : undefined;
+    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,
@@ -36,35 +45,46 @@ export function renderMatrixCsv(model: MatrixModel): string {
       item.category,
       item.priority,
       item.precondition.join('\n'),
-      single ? only!.data.join('\n') : `${item.variants.length} variants`,
-      item.trigger.join('\n'),
+      `${item.variants.length} variant(s): ${item.variants.map((v) => v.condition).join(' · ')}`,
+      commonTrigger,
       item.oracle,
-      item.mode === 'manual' ? 'Manual' : 'Auto',
+      itemModeLabel(item),
       item.traces.join(' '),
-      item.result,
-      single ? formatExecutedDate(only!.result?.startTime) : '',
+      itemResultLabel(item),
+      '',
       item.review === 'proposed' ? 'REVIEW REQUIRED' : '',
     ].map(esc).join(','));
 
-    if (!single) {
-      for (const v of item.variants) {
-        lines.push([
-          'variant',
-          v.ref,
-          '',
-          v.condition,
-          '', '',
-          '',
-          v.data.join('\n'),
-          v.trigger.join('\n'),
-          v.oracle.join('\n'),
-          v.mode === 'manual' ? 'Manual' : 'Auto',
-          v.traces.join(' '),
-          v.result ? statusToTestResult(v.result.status) : 'Pending',
-          formatExecutedDate(v.result?.startTime),
-          v.result?.error ? String(v.result.error).slice(0, 200) : '',
-        ].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,
+        '', '',
+        '',
+        v.data.join('\n'),
+        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(','));
+    }
+  }
+
+  // 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

@@ -2,14 +2,21 @@
  * Render the Test Case & Coverage Matrix workbook.
  *
  * Sheets:
- *   1. Testcases — one parent row per delivery item, variant sub-rows grouped with
- *      Excel outline (expanded for execution; the level-1 outline button collapses
- *      to the customer/review view — same sheet, one model, two views).
- *   2. Coverage — target × category grid (items + variants, `—` marks the gaps),
- *      dispositions, and the generation manifest.
+ *   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.
  *
- * Every sheet keeps the company ISO masthead (renderReportHeaderBand). A draft
- * matrix (unapproved groups / review findings) carries a red DRAFT banner.
+ * 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';
@@ -20,13 +27,14 @@ import {
   BLACK,
   LAVENDER,
 } from '../xlsx-report-builder';
-import { statusToTestResult, formatExecutedDate } from '../playwright-report-parser';
+import { statusToTestResult } from '../playwright-report-parser';
 import { CoverageVariant, DeliveryItem, ItemResult, 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;
@@ -37,14 +45,25 @@ function headerCell(c: ExcelJS.Cell, label: string): void {
 }
 
 function dataCell(c: ExcelJS.Cell, value: ExcelJS.CellValue, opts?: { bold?: boolean; fill?: { argb: string }; center?: boolean; color?: { argb: string } }): void {
-  c.value = value;
+  // 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 };
 }
 
-function itemResultLabel(item: DeliveryItem): string {
+/** 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';
+}
+
+export function itemResultLabel(item: DeliveryItem): string {
   const { passed, failed, blocked, notRun } = item.resultCounts;
   const total = item.variants.length;
   const map: Record<ItemResult, string> = {
@@ -62,12 +81,27 @@ function variantResultLabel(v: CoverageVariant): string {
   return statusToTestResult(v.result.status);
 }
 
+/** 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[]): string {
   if (lines.length === 0) return '';
   if (lines.length === 1) return lines[0];
   return lines.map((l, i) => `${i + 1}. ${l}`).join('\n');
 }
 
+/** 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;
@@ -85,9 +119,10 @@ 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 (Oracle)', 'Mode', 'Trace',
+  'Coverage / Test Data', 'Action / Trigger', 'Expected Result', 'Mode', 'Trace',
   'Result', 'Executed Date', 'Executor', 'Note\n(Evidence, DefectID)',
 ];
+const RESULT_COL = 13; // column M
 
 function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?: string): void {
   const ws = wb.addWorksheet('Testcases');
@@ -95,7 +130,7 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
 
   ws.columns = [
     { width: 3 },  // A margin
-    { width: 20 }, // B ID
+    { width: 22 }, // B ID
     { width: 18 }, // C Target
     { width: 42 }, // D Intent / Condition
     { width: 11 }, // E Category
@@ -106,8 +141,8 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
     { width: 42 }, // J Expected
     { width: 11 }, // K Mode
     { width: 13 }, // L Trace
-    { width: 17 }, // M Result
-    { width: 13 }, // N Executed
+    { width: 22 }, // M Result
+    { width: 12 }, // N Executed
     { width: 13 }, // O Executor
     { width: 24 }, // P Note
   ];
@@ -137,13 +172,55 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
 
   let rowIdx = HEADER_ROW + 1;
   for (const item of model.items) {
-    // Parent row — the delivery item (the review unit).
-    const pr = ws.getRow(rowIdx++);
-    const single = item.variants.length === 1;
-    const only = single ? item.variants[0] : undefined;
-    const coverage = single
-      ? numbered(only!.data)
-      : `${item.variants.length} variants: ${item.variants.map((v) => v.condition).join(' · ')}`;
+    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;
+    for (const v of item.variants) {
+      const vr = ws.getRow(rowIdx++);
+      vr.outlineLevel = 1;
+      const vValues: ExcelJS.CellValue[] = [
+        v.ref,
+        '',
+        v.condition,
+        '', '', '',
+        numbered(v.data),
+        numbered(v.trigger),
+        expectedWithVerification(v.oracle, v.verification),
+        v.mode === 'manual' ? `Manual${v.manualReason ? ` (${v.manualReason})` : ''}` : 'Auto',
+        v.traces.join(', '),
+        variantResultLabel(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 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(' · ')}`;
+
+    // Live roll-up: derived from the child Result cells so hand-entered results
+    // recompute the parent — precedence failed → blocked → pending → partial → passed.
+    const rng = `M${firstChild}:M${lastChild}`;
+    const n = item.variants.length;
+    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"))))`;
+
     const values: ExcelJS.CellValue[] = [
       item.id,
       item.target,
@@ -152,12 +229,12 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
       item.priority,
       numbered(item.precondition),
       coverage,
-      numbered(item.trigger),
+      commonTrigger ? numbered(commonTrigger) : '(differs per variant — see sub-rows)',
       item.oracle,
-      item.mode === 'manual' ? `Manual${only?.manualReason ? ` (${only.manualReason})` : ''}` : 'Auto',
+      itemModeLabel(item),
       item.traces.join(', '),
-      itemResultLabel(item),
-      single ? formatExecutedDate(only!.result?.startTime) : '',
+      { formula: rollUpFormula, result: itemResultLabel(item) } as ExcelJS.CellValue,
+      '',
       '',
       item.review === 'proposed' ? 'REVIEW REQUIRED' : '',
     ];
@@ -165,53 +242,52 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
       bold: true,
       fill: SOFT_BLUE,
       center: i === 3 || i === 4 || i === 9,
-      ...(String(values[14]).startsWith('REVIEW') && i === 14 ? { color: DRAFT_RED } : {}),
+      ...(i === 14 && item.review === 'proposed' ? { color: DRAFT_RED } : {}),
     }));
-
-    // Variant sub-rows — the execution units (outline level 1; collapse for review).
-    if (!single) {
-      for (const v of item.variants) {
-        const vr = ws.getRow(rowIdx++);
-        vr.outlineLevel = 1;
-        const vValues: ExcelJS.CellValue[] = [
-          v.ref,
-          '',
-          v.condition,
-          '', '', '',
-          numbered(v.data),
-          numbered(v.trigger),
-          numbered(v.oracle),
-          v.mode === 'manual' ? `Manual${v.manualReason ? ` (${v.manualReason})` : ''}` : 'Auto',
-          v.traces.join(', '),
-          variantResultLabel(v),
-          formatExecutedDate(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 }));
-      }
-    }
   }
 
   ws.autoFilter = { from: { row: HEADER_ROW, column: 2 }, to: { row: rowIdx - 1, column: 16 } };
-  ws.views = [{ state: 'frozen', ySplit: HEADER_ROW }];
+  // Freeze the header band AND the ID + Target columns (review §9).
+  ws.views = [{ state: 'frozen', xSplit: 3, ySplit: HEADER_ROW }];
 }
 
 // ---------------------------------------------------------------------------
-// Sheet 2 — Coverage (overview grid + dispositions + manifest)
+// 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: 30 }, { width: 16 }, { width: 16 }, { width: 16 }, { width: 16 },
-    { width: 16 }, { width: 40 },
+    { 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);
 
-  // --- Target × category grid ---
   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++);
+    ['Requirement', 'Status', 'Delivery items', 'Variants', 'Note'].forEach((l, i) => headerCell(rh.getCell(2 + i), l));
+    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++);

package/src/exporters/matrix/types.ts

@@ -38,6 +38,14 @@ export interface MapDisposition {
   reason?: string;
 }
 
+export type RequirementStatus =
+  | 'covered' | 'partially_covered' | 'covered_elsewhere' | 'planned' | 'gap' | 'not_applicable';
+
+export interface RequirementOverride {
+  status: RequirementStatus;
+  note?: string;
+}
+
 export interface DeliveryMap {
   version: number;
   unit: string;
@@ -46,6 +54,9 @@ export interface DeliveryMap {
   groups: MapGroup[];
   /** VP-id → intentionally-not-grouped disposition. */
   dispositions: Record<string, MapDisposition>;
+  /** 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). */
   fingerprints: Record<string, string>;
 }
@@ -90,6 +101,9 @@ export interface CoverageVariant {
   oracleShape: string[];
   /** Oracle for display. */
   oracle: string[];
+  /** HOW to check (manual `Oracle:` lines — tools, panes, queries). Rendered as
+   *  "Verification method" under the expected result, never inside it. */
+  verification: string[];
   /** Precondition profile: auth role + scenario-level Given shapes — signature input. */
   preconditionProfile: string;
   /** Human preconditions (auth + own Given steps). */
@@ -112,8 +126,11 @@ export interface DeliveryItem {
   oracle: string;
   category: MapCategory;
   review: ReviewState;
+  /** Highest priority among the variants (per-variant priorities stay on the sub-rows). */
   priority: string;
-  mode: 'auto' | 'manual';
+  /** Execution mode is a coverage dimension, not a split — 'mixed' when auto and
+   *  manual variants share one intent (e.g. account states needing seeded data). */
+  mode: 'auto' | 'manual' | 'mixed';
   layers: MatrixLayer[];
   /** Union of variant traces (exact per-variant traces stay on the variants). */
   traces: string[];
@@ -133,11 +150,21 @@ export interface MatrixDisposition {
   reason: string;
 }
 
+/** One row of the requirement-coverage table (Coverage sheet). */
+export interface RequirementCoverage {
+  id: string;                    // FR-003 / TR-001 / NFR-…
+  status: RequirementStatus;
+  /** Delivery items whose variants trace to this requirement. */
+  items: string[];
+  variantCount: number;
+  note: string;
+}
+
 // ---------------------------------------------------------------------------
 // Gate findings
 // ---------------------------------------------------------------------------
 
-export type GateId = 'A' | 'B' | 'C' | 'D' | 'E' | 'G';
+export type GateId = 'A' | 'B' | 'C' | 'D' | 'E' | 'G' | 'R' | 'W';
 export type FindingSeverity = 'error' | 'review' | 'warning';
 
 export interface MatrixFinding {
@@ -168,9 +195,11 @@ export interface MatrixModel {
   formNo: string;
   items: DeliveryItem[];
   dispositions: MatrixDisposition[];
+  /** Requirement coverage — empty when the unit has no requirements/spec.md ids. */
+  requirements: RequirementCoverage[];
   findings: MatrixFinding[];
   manifest: MatrixManifest;
 }
 
-/** Complexity warning threshold (rules draft Gate I) — echoed in the manifest. */
-export const MAX_VARIANTS_PER_ITEM = 12;
+/** Complexity warning threshold (rules draft Gate I; raised for compact grouping) — echoed in the manifest. */
+export const MAX_VARIANTS_PER_ITEM = 20;