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

package/src/exporters/matrix/build.ts

@@ -6,7 +6,7 @@
  */
 
 import { FeatureMetadata, PlaywrightResult } from '../types';
-import { MergedScenario, parseManualComments } from '../scenario-merger';
+import { MergedScenario } from '../scenario-merger';
 import {
   extractAuthRole,
   extractPriority,
@@ -14,16 +14,18 @@ import {
   splitVpAndName,
 } from '../feature-parser';
 import { getCasesDatasetRows, resolveResultVariants } from '../result-variants';
-import { substituteTestDataVars } from '../test-data-resolver';
+import { classifyManualComments, renderAction, renderExpected, renderPrecondition, renderSetupInstruction, runtimeVarsOf } from './wording';
 import { scenarioFingerprint, combinedFingerprint, mapContentFingerprint } from './fingerprint';
 import {
   CoverageVariant,
   DeliveryItem,
   DeliveryMap,
   ItemResult,
+  VariantState,
   MatrixDisposition,
   MatrixLayer,
   MatrixModel,
+  RequirementCoverage,
   MAX_VARIANTS_PER_ITEM,
 } from './types';
 import { runGates } from './gates';
@@ -71,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;
 }
@@ -89,6 +91,8 @@ export interface BuildInputs {
   results: Map<string, PlaywrightResult> | null;
   map: DeliveryMap;
   transformerVersion: string;
+  /** requirements/spec.md content — source of the requirement-id inventory (FR/TR/NFR). */
+  specText?: string;
 }
 
 /**
@@ -97,7 +101,10 @@ export interface BuildInputs {
  * support tooling see the same universe the builder does.
  */
 export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' | 'testData' | 'results'>): CoverageVariant[] {
-  const { merged, testData, results } = inputs;
+  const { merged, results } = inputs;
+  // Test-data values may cross-reference other keys (email_padded: " {{valid_email}} ") —
+  // resolve one level so display cells never leak a template token (review B-04).
+  const testData = resolveCrossRefs(inputs.testData);
   const variants: CoverageVariant[] = [];
 
   for (const m of merged) {
@@ -106,27 +113,47 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
     const tags = m.feature.tags;
     const mode = extractTestcaseType(tags) === 'Manual' ? 'manual' : 'auto';
     const authRole = extractAuthRole(tags);
-    const vpCategory = vpId.replace(/^VP-/, '').replace(/-\d+[a-zA-Z]?$/, '');
+    // Category segment of the id, whatever the project's scheme:
+    // VP-SEC-001 → SEC · SEC-123 → SEC · MS-HP-001 → MS-HP · PER-345 → PER.
+    const vpCategory = vpId.replace(/^VP-/, '').replace(/-\d+(?:[a-zA-Z]|-[A-Z0-9]+)?$/, '');
+    const procedureProfile = deriveProcedureProfile(m);
 
-    // Manual procedure comes from the parsed comment block; auto from Gherkin buckets.
+    // Manual scenarios: the `# Tester verifies:` block is classified into structured
+    // fields — Setup → precondition (review B-02), Action → trigger, Observable →
+    // expected, Oracle → verification method. Labels never remain inside prose.
     const manual = mode === 'manual' && m.feature.comments?.length
-      ? parseManualComments(m.feature.comments)
+      ? classifyManualComments(m.feature.comments)
       : null;
-    // A pure-render check (Given + Then only) is triggered by the page load itself —
-    // that IS its action, not a Gate-D executability gap.
-    const rawTrigger = manual ? manual.steps.map((s) => s.text) : m.feature.rawWhenSteps;
-    const triggerSteps = rawTrigger.length > 0 ? rawTrigger : ['(on page load)'];
-    const oracleSteps = m.resolvedExpected.map((s) => s.text);
+
+    // Raw (pre-wording) step texts — these feed shapes + Gate C, never the cells.
+    const rawTrigger = manual ? manual.actions : m.feature.rawWhenSteps;
+    const rawOracle = manual
+      ? (manual.expected.length > 0 ? manual.expected : m.feature.rawThenSteps)
+      : m.resolvedExpected.filter((s) => s.bucket === 'then').map((s) => s.text);
+
+    // 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.
+    const runtimeVars = runtimeVarsOf(
+      [...m.resolvedSteps.map((st) => st.text), ...m.resolvedExpected.map((st) => st.text)],
+      tags,
+    );
 
     const preconditionProfile = [
       authRole ?? '-',
       m.feature.extendsName ?? '-',
       ...m.feature.rawGivenSteps.map(normalizeShape),
+      ...(manual?.preconditions ?? []).map(normalizeShape),
     ].join(' | ');
-    const precondition = [
-      ...(authRole ? [authRole === 'no-auth' ? 'Not authenticated' : `Authenticated as ${authRole}`] : []),
-      ...m.feature.rawGivenSteps,
-    ];
+    // Display precondition = auth state + Background Given (shared start state) +
+    // the scenario's own Given steps + manual Setup lines — deduplicated (a manual
+    // scenario often repeats the Background navigation as its own Given).
+    const precondition = Array.from(new Set([
+      ...(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) => renderSetupInstruction(t)),
+    ]));
 
     const base = {
       vpId,
@@ -136,11 +163,47 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
       manualReason: manualReason(tags),
       layers: deriveLayers(tags),
       traces: tags.filter((t) => t.startsWith('@spec:')).map((t) => t.slice('@spec:'.length)),
-      triggerShape: triggerSteps.map(normalizeShape),
-      oracleShape: oracleSteps.map(normalizeShape),
+      runtimeVars: [...runtimeVars],
+      triggerShape: rawTrigger.map(normalizeShape),
+      oracleShape: rawOracle.map(normalizeShape),
       preconditionProfile,
       precondition,
-      procedureProfile: deriveProcedureProfile(m),
+      procedureProfile,
+      verification: manual?.verification.map((t) => sentenceOf(t)) ?? [],
+    };
+
+    /** Render the display cells for one data context (vars resolved first). */
+    const renderCells = (vars: Record<string, string>): { trigger: string[]; oracle: string[]; precondition: string[]; verification: string[] } => {
+      const sub = (s: string): string => substituteDisplayVars(s, vars, runtimeVars);
+      const preconditionOut = precondition.map(sub);
+      const verificationOut = base.verification.map(sub);
+      if (procedureProfile === 'sequence' && !manual) {
+        // Ordered flow (review B-03): keep the event order — actions stay numbered in
+        // the trigger, mid-flow assertions render inline as "Verify:", and only the
+        // FINAL Then block becomes the expected result.
+        const steps = m.feature.orderedSteps;
+        let lastActionIdx = -1;
+        steps.forEach((s, i) => { if (s.bucket !== 'then') lastActionIdx = i; });
+        const trigger: string[] = [];
+        const oracle: string[] = [];
+        steps.forEach((s, i) => {
+          if (i > lastActionIdx) oracle.push(renderExpected(sub(s.text)));           // trailing Then block
+          else if (s.bucket === 'then') trigger.push(`Verify: ${renderExpected(sub(s.text))}`);
+          else if (s.bucket === 'when') trigger.push(renderAction(sub(s.text)));
+          // leading given steps already live in the precondition
+        });
+        return { trigger, oracle, precondition: preconditionOut, verification: verificationOut };
+      }
+      const trigger = rawTrigger.map((s) => renderAction(sub(s)));
+      const oracle = rawOracle.map((s) => renderExpected(sub(s)));
+      return {
+        // A pure-render check (Given + Then only) is checked on page load — say so
+        // in words instead of a placeholder token (review §10.3).
+        trigger: trigger.length > 0 ? trigger : ['No action — the state is checked on page load.'],
+        oracle,
+        precondition: preconditionOut,
+        verification: verificationOut,
+      };
     };
 
     const rows = getCasesDatasetRows(m, testData ?? undefined);
@@ -150,6 +213,7 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
       const resultByLabel = new Map(resultVariants.map((rv) => [rv.nameSuffix.replace(/^ — /, ''), rv.result]));
       rows.forEach((row, i) => {
         const label = String(row.case ?? row.name ?? row.label ?? `row ${i + 1}`);
+        const cells = renderCells({ ...(testData ?? {}), ...rowAsStrings(row) });
         variants.push({
           ...base,
           ref: `${vpId}#${label}`,
@@ -157,21 +221,26 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
           title: `${category1} — ${label}`,
           condition: label,
           data: resolveDataPairs(m.feature.referencedVars, testData, row),
-          trigger: triggerSteps.map((s) => substituteTestDataVars(s, { ...(testData ?? {}), ...rowAsStrings(row) })),
-          oracle: oracleSteps.map((s) => substituteTestDataVars(s, { ...(testData ?? {}), ...rowAsStrings(row) })),
+          trigger: cells.trigger,
+          oracle: cells.oracle,
+          precondition: cells.precondition,
+          verification: cells.verification,
           fingerprint: scenarioFingerprint(m.feature, row),
           result: resultByLabel.get(label),
         });
       });
     } else {
+      const cells = renderCells(testData ?? {});
       variants.push({
         ...base,
         ref: vpId,
         title: category1,
         condition: category1,
         data: resolveDataPairs(m.feature.referencedVars, testData),
-        trigger: triggerSteps.map((s) => substituteTestDataVars(s, testData ?? {})),
-        oracle: oracleSteps.map((s) => substituteTestDataVars(s, testData ?? {})),
+        trigger: cells.trigger,
+        oracle: cells.oracle,
+        precondition: cells.precondition,
+        verification: cells.verification,
         fingerprint: scenarioFingerprint(m.feature),
         result: resolveResultVariants(m, results ?? null, testData ?? undefined)[0]?.result,
       });
@@ -180,9 +249,106 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
   return variants;
 }
 
+/**
+ * Display substitution for matrix cells. Unlike the legacy exporter's
+ * substituteTestDataVars (which keeps EMPTY values literal for the Steps
+ * column), an empty value is a legitimate test input here (an intentionally
+ * empty field) — it renders as `(empty)` so the tester sees the intent and no
+ * `{{token}}` survives into the deliverable (Gate D would reject it).
+ */
+function substituteDisplayVars(
+  text: string,
+  vars: Record<string, string>,
+  runtimeVars: Set<string> = new Set(),
+): string {
+  // `remember … as {{v}}` DECLARES v — leave that token for renderAction, which
+  // turns it into a quoted name ("note it as …"), not a value to look up.
+  const isCapture = /\bremember\b/i.test(text);
+  return text.replace(/\{\{\s*([^}\s]+)\s*\}\}/g, (m, key: string, offset: number) => {
+    if (isCapture && /\bas\s+$/i.test(text.slice(0, offset))) return m;
+    // A value the test produces at run time has no static form — name it so the
+    // tester knows to compare against what the earlier step captured.
+    if (runtimeVars.has(key) || runtimeVars.has(key.split(/[.[]/)[0])) return `the captured ${key}`;
+    if (!(key in vars)) return m; // unknown stays literal → Gate D flags it
+    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;
+  const cap = s.charAt(0).toUpperCase() + s.slice(1);
+  return /[.!?…]$/.test(cap) ? cap : `${cap}.`;
+}
+
+/**
+ * Requirement inventory ∪ traces → coverage table. Ids are scanned from the spec
+ * text (FR-/TR-/NFR-<n>); map overrides win over the derived covered/gap status.
+ */
+export function computeRequirements(
+  specText: string,
+  map: DeliveryMap,
+  items: DeliveryItem[],
+): RequirementCoverage[] {
+  const ids: string[] = [];
+  const seen = new Set<string>();
+  const add = (id: string): void => { if (!seen.has(id)) { seen.add(id); ids.push(id); } };
+  // A spec declares its requirements in bold — `- **FR-001**: …`, `- **REQ-12**: …`.
+  // Reading the DECLARATION (rather than any `PREFIX-123` token in the prose) keeps
+  // a project's own scheme working without matching ISO numbers, dates, or the form
+  // number in a header.
+  for (const m of specText.matchAll(/\*\*([A-Z][A-Z0-9]{1,7}-\d+)\*\*/g)) add(m[1]);
+  // Specs that do not bold their ids still work for the conventional prefixes.
+  if (ids.length === 0) {
+    for (const m of specText.matchAll(/\b(?:FR|TR|NFR)-\d+\b/g)) add(m[0]);
+  }
+  // Overrides may reference ids the spec text doesn't list (e.g. a shared catalog).
+  for (const id of Object.keys(map.requirements ?? {})) {
+    if (!seen.has(id)) { seen.add(id); ids.push(id); }
+  }
+  if (ids.length === 0) return [];
+
+  return ids.map((id) => {
+    const traced = items.filter((it) => it.variants.some((v) => v.traces.includes(id)));
+    const override = (map.requirements ?? {})[id];
+    return {
+      id,
+      status: override?.status ?? (traced.length > 0 ? 'covered' : 'gap'),
+      items: traced.map((it) => it.id),
+      variantCount: traced.reduce((a, it) => a + it.variants.filter((v) => v.traces.includes(id)).length, 0),
+      note: override?.note ?? '',
+    };
+  });
+}
+
+/** Resolve one level of {{key}} cross-references inside test-data VALUES. */
+function resolveCrossRefs(testData: Record<string, string> | null): Record<string, string> | null {
+  if (!testData) return null;
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(testData)) {
+    out[k] = typeof v === 'string' && v.includes('{{') ? substituteDisplayVars(v, testData) : v;
+  }
+  return out;
+}
+
 function rowAsStrings(row: Record<string, unknown>): Record<string, string> {
   const out: Record<string, string> = {};
-  for (const [k, v] of Object.entries(row)) out[k] = String(v);
+  for (const [k, v] of Object.entries(row)) {
+    out[k] = String(v);
+    out[`row.${k}`] = String(v); // steps reference dataset columns as {{row.<col>}}
+  }
   return out;
 }
 
@@ -190,28 +356,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.
@@ -242,7 +437,18 @@ 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
+      .map((v) => v.priority)
+      .sort((a, b) => (priorityRank[a] ?? 1) - (priorityRank[b] ?? 1))[0] ?? 'Normal';
     return {
       id: g.id,
       target: g.target,
@@ -251,12 +457,21 @@ export function buildMatrix(inputs: BuildInputs): MatrixModel {
       category: g.category,
       // A stale (drifted) group presents as proposed regardless of its stored state.
       review: stale.has(g.id) ? 'proposed' : g.review,
-      priority: first?.priority ?? 'Normal',
-      mode: first?.mode ?? 'auto',
+      priority,
+      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,
@@ -270,6 +485,28 @@ export function buildMatrix(inputs: BuildInputs): MatrixModel {
     reason: d.reason ?? '',
   }));
 
+  // Requirement coverage (review §6): the requirement-id inventory comes from
+  // requirements/spec.md; @spec: traces mark `covered`; the map's `requirements:`
+  // section carries the reviewed overrides (partially_covered / not_applicable / …).
+  const requirements = computeRequirements(inputs.specText ?? '', map, items);
+  const gaps = requirements.filter((r) => r.status === 'gap');
+  if (gaps.length > 0) {
+    findings.push({
+      gate: 'R', severity: 'warning',
+      message: `${gaps.length} requirement id(s) with no coverage or disposition: ${gaps.map((g) => g.id).join(', ')} — trace them, or record a status in the map \`requirements:\` section`,
+    });
+  }
+  // A `covered` claim with no traced variant is prose, not traceability: nothing
+  // detects it when the proving scenario is later changed or deleted. Either tag
+  // the scenario that proves it (`@spec:<id>`) or say where it IS covered.
+  const unbacked = requirements.filter((r) => r.status === 'covered' && r.items.length === 0);
+  if (unbacked.length > 0) {
+    findings.push({
+      gate: 'R', severity: 'warning',
+      message: `${unbacked.length} requirement id(s) declared \`covered\` with no variant tracing to them: ${unbacked.map((r) => r.id).join(', ')} — add \`@spec:<id>\` to the scenario that proves each, or use covered_elsewhere / partially_covered with a named reference`,
+    });
+  }
+
   const variantCount = items.reduce((a, i) => a + i.variants.length, 0);
   const approved = items.every((i) => i.review === 'approved')
     && !findings.some((f) => f.severity === 'error' || f.severity === 'review');
@@ -279,6 +516,7 @@ export function buildMatrix(inputs: BuildInputs): MatrixModel {
     formNo: map.formNo ?? 'BM-2-901-13',
     items,
     dispositions,
+    requirements,
     findings,
     manifest: {
       unit,

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';
@@ -31,10 +32,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 +73,7 @@ export function loadMatrixModel(paths: MatrixTargetPaths): MatrixLoadResult {
     results,
     map,
     transformerVersion: getPackageVersion(),
+    specText: readSpecText(paths),
   });
   return { model, map, mapErrors: [] };
 }
@@ -88,6 +98,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: [] };
@@ -111,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;
 }