@sun-asterisk/sungen 3.2.16-beta.7 → 3.2.17

package/src/exporters/matrix/fingerprint.ts

@@ -1,49 +0,0 @@
-/**
- * Canonical scenario fingerprints for the Delivery Map drift detector (Gate E).
- *
- * A fingerprint hashes what changes the MEANING of a variant: sorted tags + ordered
- * step text (+ the dataset row for a @cases variant). Formatting, comments, and
- * scenario order do NOT change it. `--approve` stamps these into the map; a later
- * mismatch drops the group back to review (stale grouping).
- */
-
-import * as crypto from 'crypto';
-import { ScenarioMetadata } from '../types';
-
-/** Stable stringify: objects get sorted keys so row column order can't shift the hash. */
-function canonical(value: unknown): string {
-  if (value === null || typeof value !== 'object') return JSON.stringify(value);
-  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
-  const obj = value as Record<string, unknown>;
-  const keys = Object.keys(obj).sort();
-  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(obj[k])}`).join(',')}}`;
-}
-
-function sha1(text: string): string {
-  return 'sha1:' + crypto.createHash('sha1').update(text, 'utf-8').digest('hex');
-}
-
-/**
- * Fingerprint one scenario. Tags are sorted (order is presentation); steps keep
- * their order (order is meaning). Manual scenarios include their procedure
- * comments — for them the comments ARE the test.
- */
-export function scenarioFingerprint(sc: ScenarioMetadata, datasetRow?: Record<string, unknown>): string {
-  const body = canonical({
-    tags: [...sc.tags].sort(),
-    steps: sc.orderedSteps.map((s) => `${s.bucket}:${s.text}`),
-    comments: sc.tags.some((t) => t === '@manual' || t.startsWith('@manual:')) ? (sc.comments ?? []) : [],
-    row: datasetRow ?? null,
-  });
-  return sha1(body);
-}
-
-/** Fingerprint of the whole source (all variants) — manifest `sourceFingerprint`. */
-export function combinedFingerprint(parts: string[]): string {
-  return sha1(canonical([...parts].sort()));
-}
-
-/** Fingerprint of the map's semantic content (groups + dispositions, not stamps). */
-export function mapContentFingerprint(groups: unknown, dispositions: unknown): string {
-  return sha1(canonical({ groups, dispositions }));
-}

package/src/exporters/matrix/gates.ts

@@ -1,391 +0,0 @@
-/**
- * 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 { mapContentFingerprint } from './fingerprint';
-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);
-  gateKCategory(ctx, findings);
-  return findings;
-}
-
-// --- Gate K — category vs the source viewpoint class -------------------------
-
-/** VP prefixes whose category is not a judgement call — the source decides it. */
-const VP_CATEGORY_RULE: Array<[string, string]> = [
-  ['SEC', 'security'],
-  ['NFR', 'nfr'],
-];
-
-/**
- * A `VP-SEC-*` scenario filed under `normal`/`abnormal` empties the Coverage
- * sheet's `security` column — the grid then reports a gap the unit does not
- * have while hiding the security work it does have. Same for `VP-NFR-*`.
- * (normal vs abnormal stays a judgement call and is never checked.)
- */
-function gateKCategory(ctx: GateContext, findings: MatrixFinding[]): void {
-  for (const g of ctx.inputs.map.groups) {
-    const vs = g.variants.flatMap((ref) => expandMapRef(ref, ctx.variantsByVp));
-    for (const [prefix, expected] of VP_CATEGORY_RULE) {
-      const hits = vs.filter((v) => v.vpCategory === prefix);
-      if (hits.length > 0 && g.category !== expected) {
-        findings.push({
-          gate: 'K', severity: 'warning', ref: g.id,
-          message: `group ${g.id} is \`category: ${g.category}\` but ${hits.length}/${vs.length} of its variants are VP-${prefix}-* (${hits.slice(0, 3).map((v) => v.vpId).join(', ')}) — use \`category: ${expected}\` or the Coverage grid's ${expected} column stays empty`,
-        });
-      }
-    }
-  }
-}
-
-// --- 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.
-    // 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]> = [
-      ['test layer', (v) => [...v.layers].sort().join('+')],
-    ];
-    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;
-
-  // 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) {
-      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) {
-    const variantCount = g.variants.flatMap((ref) => expandMapRef(ref, ctx.variantsByVp)).length;
-    // Without a digest the parent row can only list variant refs — a reviewer
-    // then has to expand the item to learn which dimensions it covers.
-    if (variantCount > 3 && !g.dimensions) {
-      findings.push({
-        gate: 'W', severity: 'warning', ref: g.id,
-        message: `group ${g.id} has ${variantCount} variants and no \`dimensions:\` digest — add a short one (e.g. "required ×3 · format ×9") so the collapsed view stays informative`,
-      });
-    }
-    if (g.dimensions && g.dimensions.length > 120) {
-      findings.push({
-        gate: 'W', severity: 'warning', ref: g.id,
-        message: `group ${g.id} \`dimensions:\` is ${g.dimensions.length} chars — keep the digest short (≤120)`,
-      });
-    }
-    for (const [field, text] of ([['intent', g.intent], ['oracle', g.oracle], ...(g.dimensions ? [['dimensions', g.dimensions] as const] : [])] as const)) {
-      for (const [re, what] of WORDING_SMELLS) {
-        if (re.test(text)) {
-          findings.push({
-            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

@@ -1,163 +0,0 @@
-/**
- * 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 ?? ''),
-        ...(grp.dimensions !== undefined ? { dimensions: String(grp.dimensions) } : {}),
-        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,
-      ...(g.dimensions !== undefined ? { dimensions: g.dimensions } : {}),
-      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');
-}