@sun-asterisk/sungen 3.2.15 → 3.2.16-beta.2

package/src/exporters/matrix/gates.ts

@@ -0,0 +1,325 @@
+/**
+ * Deterministic quality gates for the Test Case & Coverage Matrix
+ * (docs/spec/delivery-coverage-matrix-spec.md §6).
+ *
+ * Severity behavior:
+ *   error   → blocks any render
+ *   review  → blocks the official render; `--preview` renders with a DRAFT watermark
+ *   warning → prints + renders
+ *
+ * The gates recompute every signature part from the .feature — the map is never
+ * trusted for derivable facts, only for the semantic fields (target/intent/oracle).
+ */
+
+import { splitVpAndName, extractTestcaseType } from '../feature-parser';
+import { CoverageVariant, MatrixFinding, MAX_VARIANTS_PER_ITEM } from './types';
+import { expandMapRef, BuildInputs } from './build';
+
+export interface GateContext {
+  inputs: BuildInputs;
+  variants: CoverageVariant[];
+  variantsByVp: Map<string, CoverageVariant[]>;
+}
+
+export function runGates(ctx: GateContext): MatrixFinding[] {
+  const findings: MatrixFinding[] = [];
+  gateASource(ctx, findings);
+  gateBMapping(ctx, findings);
+  gateCAggregation(ctx, findings);
+  gateDExecutability(ctx, findings);
+  gateEDrift(ctx, findings);
+  gateGReviewState(ctx, findings);
+  gateWWording(ctx, findings);
+  return findings;
+}
+
+// --- Gate A — source quality ------------------------------------------------
+
+function gateASource(ctx: GateContext, findings: MatrixFinding[]): void {
+  const { feature, merged } = ctx.inputs;
+
+  if (feature.backgroundWhenSteps.length > 0 || feature.backgroundThenSteps.length > 0) {
+    findings.push({
+      gate: 'A', severity: 'error',
+      message: 'Background contains When/Then steps — setup only; move the action/oracle into scenarios',
+    });
+  }
+
+  const seen = new Map<string, number>();
+  for (const m of merged) {
+    const { vpId } = splitVpAndName(m.feature.name);
+    if (!vpId) {
+      findings.push({
+        gate: 'A', severity: 'error', ref: m.feature.name,
+        message: `scenario "${m.feature.name}" has no VP-id prefix — matrix variants must be addressable`,
+      });
+      continue;
+    }
+    seen.set(vpId, (seen.get(vpId) ?? 0) + 1);
+
+    const isManual = extractTestcaseType(m.feature.tags) === 'Manual';
+    if (m.resolvedExpected.length === 0) {
+      findings.push({
+        gate: 'A', severity: 'error', ref: vpId,
+        message: isManual
+          ? `manual scenario ${vpId} has no observable oracle (no Then steps and no Observable/Oracle comment lines)`
+          : `scenario ${vpId} has no Then step — a variant without an observable oracle cannot be delivered`,
+      });
+    }
+  }
+  for (const [vpId, n] of seen) {
+    if (n > 1) findings.push({ gate: 'A', severity: 'error', ref: vpId, message: `duplicate VP-id ${vpId} (${n} scenarios)` });
+  }
+}
+
+// --- Gate B — mapping completeness -------------------------------------------
+
+function gateBMapping(ctx: GateContext, findings: MatrixFinding[]): void {
+  const { map } = ctx.inputs;
+  const { variants, variantsByVp } = ctx;
+
+  // Where each derived variant landed: 0 → unmapped, >1 → double-mapped.
+  const owners = new Map<string, string[]>();
+  for (const g of map.groups) {
+    for (const ref of g.variants) {
+      const expanded = expandMapRef(ref, variantsByVp);
+      if (expanded.length === 0) {
+        findings.push({
+          gate: 'B', severity: 'error', ref: g.id,
+          message: `group ${g.id} references ${ref} which matches no scenario/@cases row in the .feature`,
+        });
+        continue;
+      }
+      for (const v of expanded) {
+        const list = owners.get(v.ref) ?? [];
+        list.push(g.id);
+        owners.set(v.ref, list);
+      }
+    }
+  }
+
+  for (const [ref, groups] of owners) {
+    if (groups.length > 1) {
+      findings.push({
+        gate: 'B', severity: 'error', ref,
+        message: `variant ${ref} belongs to ${groups.length} groups (${groups.join(', ')}) — exactly one required`,
+      });
+    }
+  }
+
+  for (const v of variants) {
+    const grouped = owners.has(v.ref);
+    const disposed = v.vpId in map.dispositions;
+    if (!grouped && !disposed) {
+      findings.push({
+        gate: 'B', severity: 'error', ref: v.ref,
+        message: `variant ${v.ref} is in no group and has no disposition — 100% source disposition is required`,
+      });
+    }
+    if (grouped && disposed) {
+      findings.push({
+        gate: 'B', severity: 'error', ref: v.ref,
+        message: `variant ${v.ref} is grouped AND disposed (${map.dispositions[v.vpId].as}) — pick one`,
+      });
+    }
+  }
+
+  for (const vpId of Object.keys(map.dispositions)) {
+    if (!variantsByVp.has(vpId)) {
+      findings.push({
+        gate: 'B', severity: 'warning', ref: vpId,
+        message: `disposition for ${vpId} matches no scenario (stale entry?)`,
+      });
+    }
+  }
+}
+
+// --- Gate C — aggregation safety ---------------------------------------------
+
+function gateCAggregation(ctx: GateContext, findings: MatrixFinding[]): void {
+  const { map } = ctx.inputs;
+  const { variantsByVp } = ctx;
+
+  for (const g of map.groups) {
+    const vs = g.variants.flatMap((ref) => expandMapRef(ref, variantsByVp));
+    if (vs.length <= 1) continue;
+
+    // Approval IS the QA confirmation of the heuristic parts (oracle family,
+    // precondition equivalence, sequence safety) — once approved AND unchanged
+    // (fingerprints intact), only the hard signature checks keep firing. A
+    // drifted variant re-opens the heuristics (Gate E flips the item to
+    // proposed at the same time).
+    const stale = vs.some((v) => {
+      const stamped = map.fingerprints[v.ref] ?? map.fingerprints[v.vpId];
+      return !stamped || stamped !== v.fingerprint;
+    });
+    const heuristicsConfirmed = g.review === 'approved' && !stale;
+
+    // Hard signature parts — recomputed, never trusted from the map. ERROR on mismatch.
+    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));
+      if (distinct.size > 1) {
+        findings.push({
+          gate: 'C', severity: 'error', ref: g.id,
+          message: `group ${g.id} mixes ${label}s (${[...distinct].join(' vs ')}) — mandatory split`,
+        });
+      }
+    }
+
+    // Heuristic signature parts — REVIEW_REQUIRED (equivalence was inferred, not declared).
+    const preProfiles = new Set(vs.map((v) => v.preconditionProfile));
+    if (!heuristicsConfirmed && preProfiles.size > 1) {
+      findings.push({
+        gate: 'C', severity: 'review', ref: g.id,
+        message: `group ${g.id} variants have different precondition profiles — confirm the grouping is safe or split`,
+      });
+    }
+    const oracleShapes = new Set(vs.map((v) => v.oracleShape.join(' ; ')));
+    if (!heuristicsConfirmed && oracleShapes.size > 1) {
+      findings.push({
+        gate: 'C', severity: 'review', ref: g.id,
+        message: `group ${g.id} variants assert different oracle shapes (${oracleShapes.size} shapes) — confirm they are one oracle family`,
+      });
+    }
+    if (!heuristicsConfirmed && vs.some((v) => v.procedureProfile === 'sequence')) {
+      findings.push({
+        gate: 'C', severity: 'review', ref: g.id,
+        message: `group ${g.id} contains a sequence-sensitive scenario — ordered flows stay solo items unless QA confirms`,
+      });
+    }
+
+    if (vs.length > MAX_VARIANTS_PER_ITEM) {
+      findings.push({
+        gate: 'C', severity: 'warning', ref: g.id,
+        message: `group ${g.id} has ${vs.length} variants (> ${MAX_VARIANTS_PER_ITEM}) — consider splitting for reviewability`,
+      });
+    }
+  }
+}
+
+// --- Gate D — manual executability -------------------------------------------
+
+function gateDExecutability(ctx: GateContext, findings: MatrixFinding[]): void {
+  const { map, testData, feature } = ctx.inputs;
+  const { variantsByVp } = ctx;
+
+  for (const g of map.groups) {
+    const vs = g.variants.flatMap((ref) => expandMapRef(ref, variantsByVp));
+    for (const v of vs) {
+      const hasPrecondition = v.precondition.length > 0 || feature.backgroundGivenSteps.length > 0;
+      if (!hasPrecondition) {
+        findings.push({
+          gate: 'D', severity: 'error', ref: v.ref,
+          message: `${v.ref}: no precondition (no Background, auth tag, or Given) — a tester cannot establish the start state`,
+        });
+      }
+      if (v.trigger.length === 0) {
+        findings.push({
+          gate: 'D', severity: 'error', ref: v.ref,
+          message: `${v.ref}: no action/trigger (no When steps${v.mode === 'manual' ? ' and no Setup/Action comment lines' : ''})`,
+        });
+      }
+      // Oracle emptiness is Gate A (source) — not repeated here.
+    }
+  }
+
+  // Every {{var}} must resolve — data the tester cannot obtain is not executable.
+  for (const [vpId, vs] of variantsByVp) {
+    const scenario = ctx.inputs.merged.find((m) => splitVpAndName(m.feature.name).vpId === vpId);
+    if (!scenario) continue;
+    for (const varName of scenario.feature.referencedVars) {
+      const inRows = vs.some((v) => v.caseLabel !== undefined); // dataset rows carry their own columns
+      if (!inRows && (!testData || !(varName in testData))) {
+        findings.push({
+          gate: 'D', severity: 'error', ref: vpId,
+          message: `${vpId}: {{${varName}}} does not resolve in test-data — the variant is not reproducible`,
+        });
+      }
+    }
+  }
+
+  // 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) ------------------------------------------
+
+function gateEDrift(ctx: GateContext, findings: MatrixFinding[]): void {
+  const { map } = ctx.inputs;
+  const { variantsByVp } = ctx;
+
+  for (const g of map.groups) {
+    if (g.review !== 'approved') continue; // proposed groups are already under review
+    for (const ref of g.variants) {
+      const vs = expandMapRef(ref, variantsByVp);
+      for (const v of vs) {
+        const stamped = map.fingerprints[v.ref] ?? map.fingerprints[v.vpId];
+        if (!stamped) {
+          findings.push({
+            gate: 'E', severity: 'review', ref: g.id,
+            message: `group ${g.id}: ${v.ref} has no stamped fingerprint — run \`sungen delivery --approve\` after review`,
+          });
+        } else if (stamped !== v.fingerprint) {
+          findings.push({
+            gate: 'E', severity: 'review', ref: g.id,
+            message: `group ${g.id}: ${v.ref} changed since approval (fingerprint drift) — re-review the grouping`,
+          });
+        }
+      }
+    }
+  }
+}
+
+// --- 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 {
+  const proposed = ctx.inputs.map.groups.filter((g) => g.review !== 'approved');
+  if (proposed.length > 0) {
+    findings.push({
+      gate: 'G', severity: 'review',
+      message: `${proposed.length} group(s) still \`proposed\` (${proposed.slice(0, 5).map((g) => g.id).join(', ')}${proposed.length > 5 ? ', …' : ''}) — approve them or render with --preview`,
+    });
+  }
+}

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

@@ -0,0 +1,161 @@
+/**
+ * Delivery Map loader — `qa/<kind>/<unit>/delivery/<unit>.map.yaml`.
+ *
+ * Structural validation only (shape, required fields, enum values, duplicate ids).
+ * Semantic validation against the .feature is the gates' job (gates.ts) — the loader
+ * never reads the feature.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+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;
+  /** Structural problems — any entry blocks the matrix path (fix the file first). */
+  errors: string[];
+}
+
+/** Path of the map file for a unit directory (qa/<kind>/<screen>) + feature basename. */
+export function mapFilePath(unitDir: string, featureBaseName: string): string {
+  return path.join(unitDir, 'delivery', `${featureBaseName}.map.yaml`);
+}
+
+export function loadDeliveryMap(file: string): MapLoadResult {
+  if (!fs.existsSync(file)) return { map: null, errors: [] };
+  const errors: string[] = [];
+  let raw: unknown;
+  try {
+    raw = parseYaml(fs.readFileSync(file, 'utf-8'));
+  } catch (e) {
+    return { map: null, errors: [`map YAML does not parse: ${e instanceof Error ? e.message : e}`] };
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { map: null, errors: ['map root must be a YAML mapping'] };
+  }
+  const doc = raw as Record<string, unknown>;
+
+  const groups: MapGroup[] = [];
+  const seenIds = new Set<string>();
+  const rawGroups = doc.groups;
+  if (!Array.isArray(rawGroups) || rawGroups.length === 0) {
+    errors.push('map has no `groups` list');
+  } else {
+    rawGroups.forEach((g, i) => {
+      if (!g || typeof g !== 'object') { errors.push(`groups[${i}] is not a mapping`); return; }
+      const grp = g as Record<string, unknown>;
+      const where = `groups[${i}]${typeof grp.id === 'string' ? ` (${grp.id})` : ''}`;
+      for (const field of ['id', 'target', 'intent', 'oracle'] as const) {
+        if (typeof grp[field] !== 'string' || !(grp[field] as string).trim()) {
+          errors.push(`${where}: missing/empty \`${field}\``);
+        }
+      }
+      if (!CATEGORIES.includes(grp.category as MapCategory)) {
+        errors.push(`${where}: \`category\` must be one of ${CATEGORIES.join(' | ')}`);
+      }
+      const review = (grp.review ?? 'proposed') as ReviewState;
+      if (!REVIEW_STATES.includes(review)) {
+        errors.push(`${where}: \`review\` must be proposed | approved`);
+      }
+      const variants = grp.variants;
+      if (!Array.isArray(variants) || variants.length === 0 || variants.some((v) => typeof v !== 'string' || !v.trim())) {
+        errors.push(`${where}: \`variants\` must be a non-empty list of VP refs`);
+      }
+      const id = String(grp.id ?? '');
+      if (id) {
+        if (seenIds.has(id)) errors.push(`duplicate group id \`${id}\``);
+        seenIds.add(id);
+      }
+      groups.push({
+        id,
+        target: String(grp.target ?? ''),
+        intent: String(grp.intent ?? ''),
+        oracle: String(grp.oracle ?? ''),
+        category: grp.category as MapCategory,
+        review,
+        variants: Array.isArray(variants) ? variants.map(String) : [],
+      });
+    });
+  }
+
+  const dispositions: Record<string, MapDisposition> = {};
+  if (doc.dispositions !== undefined) {
+    if (!doc.dispositions || typeof doc.dispositions !== 'object' || Array.isArray(doc.dispositions)) {
+      errors.push('`dispositions` must be a mapping of VP-id → { as, reason }');
+    } else {
+      for (const [vpId, d] of Object.entries(doc.dispositions as Record<string, unknown>)) {
+        const dd = (d && typeof d === 'object' ? d : {}) as Record<string, unknown>;
+        if (!DISPOSITIONS.includes(String(dd.as))) {
+          errors.push(`dispositions.${vpId}: \`as\` must be one of ${DISPOSITIONS.join(' | ')}`);
+        }
+        dispositions[vpId] = { as: dd.as as MapDisposition['as'], reason: dd.reason ? String(dd.reason) : undefined };
+      }
+    }
+  }
+
+  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>)) {
+      fingerprints[k] = String(v);
+    }
+  }
+
+  const map: DeliveryMap = {
+    version: Number(doc.version ?? 1),
+    unit: String(doc.unit ?? ''),
+    formNo: doc.form_no !== undefined ? String(doc.form_no) : undefined,
+    groups,
+    dispositions,
+    requirements,
+    fingerprints,
+  };
+  return { map: errors.length > 0 ? null : map, errors };
+}
+
+/**
+ * Write the map back (used by `--approve` to flip review states + stamp fingerprints).
+ * Field order is kept stable so approve-diffs stay minimal and reviewable.
+ */
+export function writeDeliveryMap(file: string, map: DeliveryMap): void {
+  const doc: Record<string, unknown> = {
+    version: map.version,
+    unit: map.unit,
+    ...(map.formNo !== undefined ? { form_no: map.formNo } : {}),
+    groups: map.groups.map((g) => ({
+      id: g.id,
+      target: g.target,
+      intent: g.intent,
+      oracle: g.oracle,
+      category: g.category,
+      review: g.review,
+      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 });
+  fs.writeFileSync(file, stringifyYaml(doc, { lineWidth: 0 }), 'utf-8');
+}

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

@@ -0,0 +1,91 @@
+/**
+ * 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`;
+ * 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 } from '../playwright-report-parser';
+import { 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',
+];
+
+function esc(value: string): string {
+  if (/[",\n]/.test(value)) return `"${value.replace(/"/g, '""')}"`;
+  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[] = [];
+  lines.push(`# Test Case & Coverage Matrix — ${model.unit}`);
+  lines.push(`# delivery items: ${model.manifest.itemCount} · coverage variants: ${model.manifest.variantCount} · state: ${model.manifest.approvalState}`);
+  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,
+      item.target,
+      item.intent,
+      item.category,
+      item.priority,
+      item.precondition.join('\n'),
+      `${item.variants.length} variant(s): ${item.variants.map((v) => v.condition).join(' · ')}`,
+      commonTrigger,
+      item.oracle,
+      item.mode === 'manual' ? 'Manual' : 'Auto',
+      item.traces.join(' '),
+      itemResultLabel(item),
+      '',
+      item.review === 'proposed' ? 'REVIEW REQUIRED' : '',
+    ].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';
+}