@sun-asterisk/sungen 3.2.17 → 3.2.18

package/src/exporters/matrix/export.ts

@@ -0,0 +1,149 @@
+/**
+ * Matrix export orchestration — the piece `sungen delivery` calls.
+ *
+ * Composes the existing parsing seams (feature-parser, spec-parser, test-data,
+ * playwright report) with the map loader, builder, gates, and renderers. All
+ * inputs arrive as resolved paths so the CLI's discovery logic stays the single
+ * owner of unit-kind layout rules.
+ */
+
+import * as fs from 'fs';
+import { parseFeatureMetadata } from '../feature-parser';
+import { parseSpecFile } from '../spec-parser';
+import { loadTestData } from '../test-data-resolver';
+import { loadPlaywrightReport } from '../playwright-report-parser';
+import { mergeFeatureAndSpec } from '../scenario-merger';
+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';
+import { DeliveryMap, MatrixFinding, MatrixModel } from './types';
+
+export interface MatrixTargetPaths {
+  cwd: string;
+  /** Feature basename — names the deliverable files. */
+  unit: string;
+  /** Display label (flow/… prefix for flows). */
+  label: string;
+  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;
+  /** No map file → the caller prints the guidance path (AI proposal or --legacy). */
+  mapMissing?: boolean;
+  /** Structural map problems (bad YAML/shape) — fix the file before anything else. */
+  mapErrors: string[];
+}
+
+export function loadMatrixModel(paths: MatrixTargetPaths): MatrixLoadResult {
+  const { map, errors } = loadDeliveryMap(paths.mapFile);
+  if (!map) {
+    return errors.length === 0 ? { mapMissing: true, mapErrors: [] } : { mapErrors: errors };
+  }
+
+  const feature = parseFeatureMetadata(paths.featureFile);
+  const spec = parseSpecFile(paths.specFile);
+  const merged = mergeFeatureAndSpec(feature, spec);
+  const testData = fs.existsSync(paths.testDataFile) ? loadTestData(paths.testDataFile, process.env.SUNGEN_ENV ?? null) : null;
+  const results = paths.resultsPath ? loadPlaywrightReport(paths.resultsPath) : null;
+
+  const model = buildMatrix({
+    unit: paths.unit,
+    feature,
+    merged,
+    testData,
+    results,
+    map,
+    transformerVersion: getPackageVersion(),
+    specText: readSpecText(paths),
+  });
+  return { model, map, mapErrors: [] };
+}
+
+export const hasErrors = (f: MatrixFinding[]): boolean => f.some((x) => x.severity === 'error');
+export const hasReview = (f: MatrixFinding[]): boolean => f.some((x) => x.severity === 'review');
+
+/**
+ * Stamp fingerprints + flip groups to `approved` (all groups, or just `groupIds`).
+ * Refuses when gate ERRORs remain — an invalid map must not be frozen as approved.
+ * Returns the findings so the caller reports what blocked or what was approved.
+ */
+export function approveMatrix(paths: MatrixTargetPaths, groupIds?: string[]): { findings: MatrixFinding[]; approved: string[] } {
+  const { map, errors } = loadDeliveryMap(paths.mapFile);
+  if (!map) throw new Error(errors.length > 0 ? `map is invalid:\n  - ${errors.join('\n  - ')}` : `no delivery map at ${paths.mapFile}`);
+
+  const feature = parseFeatureMetadata(paths.featureFile);
+  const spec = parseSpecFile(paths.specFile);
+  const merged = mergeFeatureAndSpec(feature, spec);
+  const testData = fs.existsSync(paths.testDataFile) ? loadTestData(paths.testDataFile, process.env.SUNGEN_ENV ?? null) : null;
+
+  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: [] };
+
+  const variants = deriveVariants({ feature, merged, testData, results: null });
+  const byRef = new Map(variants.map((v) => [v.ref, v] as const));
+  const byVp = new Map<string, typeof variants>();
+  for (const v of variants) {
+    const list = byVp.get(v.vpId) ?? [];
+    list.push(v);
+    byVp.set(v.vpId, list);
+  }
+
+  const approved: string[] = [];
+  for (const g of map.groups) {
+    if (groupIds && groupIds.length > 0 && !groupIds.includes(g.id)) continue;
+    for (const ref of g.variants) {
+      const expanded = ref.includes('#') ? [byRef.get(ref)].filter(Boolean) : (byVp.get(ref) ?? []);
+      for (const v of expanded) map.fingerprints[(v as NonNullable<typeof expanded[number]>).ref] = (v as NonNullable<typeof expanded[number]>).fingerprint;
+    }
+    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 };
+}
+
+export type MatrixFormat = 'xlsx' | 'csv' | 'both';
+
+/** Render + write the requested format(s). Caller has already enforced the gate policy. */
+export async function writeMatrixDeliverables(
+  paths: MatrixTargetPaths,
+  model: MatrixModel,
+  format: MatrixFormat = 'xlsx',
+): Promise<{ csvPath?: string; xlsxPath?: string }> {
+  const out: { csvPath?: string; xlsxPath?: string } = {};
+  if (format === 'csv' || format === 'both') {
+    out.csvPath = writeCsv(paths.cwd, paths.unit, renderMatrixCsv(model));
+  }
+  if (format === 'xlsx' || format === 'both') {
+    const wb = renderMatrixXlsx(model, getPackageVersion());
+    out.xlsxPath = await writeXlsx(paths.cwd, paths.unit, wb);
+  }
+  return out;
+}

package/src/exporters/matrix/fingerprint.ts

@@ -0,0 +1,49 @@
+/**
+ * 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

@@ -0,0 +1,400 @@
+/**
+ * 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 -------------------------
+
+/**
+ * Viewpoint classes whose delivery category is not a judgement call — the source
+ * decides it. Matched on the id's category segment, so a project scheme without
+ * the `VP-` prefix (`SEC-123`, `PER-345`) classifies the same as `VP-SEC-001`.
+ */
+const VP_CATEGORY_RULE: Array<[RegExp, string, string]> = [
+  [/^(SEC|SECURITY)$/i, 'security', 'SEC'],
+  [/^(NFR|PERF|PER|PERFORMANCE|A11Y|ACCESSIBILITY)$/i, 'nfr', 'NFR/PERF/A11Y'],
+];
+
+/**
+ * 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 [re, expected, label] of VP_CATEGORY_RULE) {
+      const hits = vs.filter((v) => re.test(v.vpCategory));
+      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 ${label} scenarios (${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;
+    // Values produced during the run (`remember … as {{v}}`, capability bindings)
+    // are provided by the test itself — demanding a test-data entry for them
+    // blocked 14 scenarios of a real suite that compiles and runs fine.
+    const runtime = new Set(vs.flatMap((v) => v.runtimeVars));
+    for (const varName of scenario.feature.referencedVars) {
+      const inRows = vs.some((v) => v.caseLabel !== undefined); // dataset rows carry their own columns
+      const atRuntime = runtime.has(varName) || runtime.has(varName.split(/[.[]/)[0]);
+      if (!inRows && !atRuntime && (!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`,
+    });
+  }
+}