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

package/dist/exporters/matrix/wording.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * Wording normalization — deterministic rendering step AFTER semantic
+ * normalization (review feedback §10): turn sungen DSL steps into controlled
+ * manual-test English without changing the target, condition, trigger,
+ * precondition, oracle, or trace.
+ *
+ * - Actions render in the imperative:      "User fill [Email] field with X"
+ *                                        →  "Enter X in the Email field."
+ * - Expected results render as observable assertions (never tester actions):
+ *   "User see [Jobs] page" → "The Jobs page is displayed."
+ * - Manual `# Tester verifies:` labels (Setup:/Action:/Observable:/Oracle:)
+ *   become structured fields instead of prose: Setup → precondition,
+ *   Action → action, Observable → expected, Oracle → verification method.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderAction = renderAction;
+exports.renderExpected = renderExpected;
+exports.renderPrecondition = renderPrecondition;
+exports.classifyManualComments = classifyManualComments;
+// `[Email] field` → `Email field` (the visible label + its element type).
+function deRef(text) {
+    return text.replace(/\[([^\]]+)\]/g, '$1');
+}
+function sentence(text) {
+    let s = text.trim().replace(/\s+/g, ' ');
+    if (!s)
+        return s;
+    s = s.charAt(0).toUpperCase() + s.slice(1);
+    if (!/[.!?…]$/.test(s))
+        s += '.';
+    return s;
+}
+/**
+ * Render one action step in the imperative. Pattern table covers the common
+ * sungen step verbs; anything unmatched falls back to actor-stripped text —
+ * still readable, never a raw `User fill`.
+ */
+function renderAction(raw) {
+    let s = raw.trim().replace(/^(User|The user)\s+/i, '');
+    const rules = [
+        // fill [X] field with V
+        [/^fills? \[([^\]]+)\][a-z ]* with (.+)$/i, (m) => `Enter ${m[2]} in the ${m[1]} field`],
+        // clear [X] field
+        [/^clears? \[([^\]]+)\](.*)$/i, (m) => `Clear the ${m[1]}${m[2] || ' field'}`],
+        // click [X] <type>
+        [/^clicks? \[([^\]]+)\]\s*(\w+)?$/i, (m) => `Click the ${m[1]}${m[2] ? ` ${m[2]}` : ''}`],
+        // press <Key> at/in [X] field
+        [/^press(?:es)? (.+?) (?:at|in|inside) \[([^\]]+)\](?: field)?$/i, (m) => `Press ${m[1]} in the ${m[2]} field`],
+        [/^press(?:es)? (.+)$/i, (m) => `Press ${m[1]}`],
+        // select V in/from [X] dropdown
+        [/^selects? (.+?) (?:in|from) \[([^\]]+)\]\s*(\w+)?$/i, (m) => `Select ${m[1]} in the ${m[2]}${m[3] ? ` ${m[3]}` : ''}`],
+        // check/uncheck [X] checkbox
+        [/^(un)?checks? \[([^\]]+)\]\s*(\w+)?$/i, (m) => `${m[1] ? 'Uncheck' : 'Check'} the ${m[2]}${m[3] ? ` ${m[3]}` : ''}`],
+        // hover [X]
+        [/^hovers? (?:over )?\[([^\]]+)\]\s*(\w+)?$/i, (m) => `Hover over the ${m[1]}${m[2] ? ` ${m[2]}` : ''}`],
+        // upload V to [X]
+        [/^uploads? (.+?) (?:to|into) \[([^\]]+)\]\s*(\w+)?$/i, (m) => `Upload ${m[1]} to the ${m[2]}${m[3] ? ` ${m[3]}` : ''}`],
+        // is on [X] page (as an action = navigate)
+        [/^is on \[([^\]]+)\] page(.*)$/i, (m) => `Open the ${m[1]} page${m[2] ?? ''}`],
+        // wait for [X] <type> (is )?visible
+        [/^waits? for \[([^\]]+)\]\s*(\w+)?(?: is)?(?: visible)?$/i, (m) => `Wait until the ${m[1]}${m[2] ? ` ${m[2]}` : ''} is visible`],
+        // scroll to [X]
+        [/^scrolls? (?:to|into) \[([^\]]+)\]\s*(\w+)?$/i, (m) => `Scroll to the ${m[1]}${m[2] ? ` ${m[2]}` : ''}`],
+    ];
+    for (const [re, out] of rules) {
+        const m = s.match(re);
+        if (m)
+            return sentence(deRef(out(m)));
+    }
+    return sentence(deRef(s));
+}
+/**
+ * Render one expected step as an observable assertion (no tester action, no
+ * `should`, no DSL `User see`).
+ */
+function renderExpected(raw) {
+    let s = raw.trim().replace(/^(User|The user)\s+/i, '');
+    const rules = [
+        // see [X] page
+        [/^sees? \[([^\]]+)\] page$/i, (m) => `The ${m[1]} page is displayed`],
+        // see [X] <type> with V
+        [/^sees? \[([^\]]+)\]\s*(\w+)? with (.+)$/i, (m) => `The ${m[1]}${m[2] ? ` ${m[2]}` : ''} shows ${m[3]}`],
+        // see [X] <type> contains V
+        [/^sees? \[([^\]]+)\]\s*(\w+)? contains (.+)$/i, (m) => `The ${m[1]}${m[2] ? ` ${m[2]}` : ''} contains ${m[3]}`],
+        // see [X] <type> has text V
+        [/^sees? \[([^\]]+)\]\s*(\w+)? has text (.+)$/i, (m) => `The ${m[1]}${m[2] ? ` ${m[2]}` : ''} shows ${m[3]}`],
+        // see [X] <type> is hidden / is disabled / is enabled / …
+        [/^sees? \[([^\]]+)\]\s*(\w+)? is (.+)$/i, (m) => `The ${m[1]}${m[2] ? ` ${m[2]}` : ''} is ${m[3]}`],
+        // not see [X] <type>
+        [/^(?:do(?:es)? )?not sees? \[([^\]]+)\]\s*(\w+)?$/i, (m) => `The ${m[1]}${m[2] ? ` ${m[2]}` : ''} is not displayed`],
+        // see [X] <type>
+        [/^sees? \[([^\]]+)\]\s*(\w+)?$/i, (m) => `The ${m[1]}${m[2] ? ` ${m[2]}` : ''} is visible`],
+    ];
+    for (const [re, out] of rules) {
+        const m = s.match(re);
+        if (m)
+            return sentence(deRef(out(m)));
+    }
+    return sentence(deRef(s));
+}
+/** Precondition wording: a state, not an action ("The user is signed out."). */
+function renderPrecondition(raw) {
+    const s = raw.trim().replace(/^(User|The user)\s+/i, '');
+    const m = s.match(/^is on \[([^\]]+)\] page(.*)$/i);
+    if (m)
+        return sentence(`The user is on the ${m[1]} page${m[2] ?? ''}`);
+    return sentence(deRef(`The user ${s.charAt(0).toLowerCase()}${s.slice(1)}`));
+}
+/**
+ * Split a manual scenario's numbered comment lines into the four structured
+ * fields. Labels are consumed (structured), never left inside the prose —
+ * review feedback §10.2(3). Continuation lines append to the previous item;
+ * pre-amble (rationale/header/dividers) is skipped.
+ */
+function classifyManualComments(comments) {
+    const out = { preconditions: [], actions: [], expected: [], verification: [] };
+    let last = null;
+    const bucketOf = (label) => {
+        if (/setup|precondition|arrange|given/i.test(label))
+            return 'preconditions';
+        if (/oracle|verify|verification|how to check/i.test(label))
+            return 'verification';
+        if (/observ|expect|result|then|assert/i.test(label))
+            return 'expected';
+        return 'actions';
+    };
+    for (const raw of comments) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        if (/^[-=*_]{2,}/.test(line)) {
+            last = null;
+            continue;
+        }
+        const m = line.match(/^\d+[.)]\s*(?:([A-Za-z][A-Za-z /]*?):\s*)?(.+)$/);
+        if (m) {
+            const label = (m[1] || '').trim();
+            const text = m[2].trim();
+            const list = out[bucketOf(label)];
+            list.push(text);
+            last = { list, idx: list.length - 1 };
+        }
+        else if (last) {
+            last.list[last.idx] += ' ' + line;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=wording.js.map

package/dist/exporters/matrix/wording.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wording.js","sourceRoot":"","sources":["../../../src/exporters/matrix/wording.ts"],"names":[],"mappings":"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"}

package/dist/orchestrator/templates/ai-src/commands/delivery.md

@@ -66,19 +66,55 @@ dispositions:                      # scenarios intentionally NOT delivered as te
   # as: excluded | blocked | covered_elsewhere | accepted_risk
 ```
 
-**Grouping rules (the aggregation signature):**
-- One group = **one target + one intent + one oracle family**. When unsure, keep items separate —
-  the gates and QA decide, never guess-merge.
-- MAY share a group (become coverage dimensions): equivalence partitions, boundary values,
-  different data (`@cases` rows), a different trigger with the same oracle (blur vs submit),
-  locales.
-- MUST split: different target, intent, oracle family, category, execution mode (`@manual` vs
-  auto), test layer (`@api`/`@query`), or priority tag; sequence-sensitive flows (re-Given/When
-  after a Then) stay solo.
+**Grouping rules (the aggregation signature) — group COMPACTLY.** The matrix exists to be
+substantially shorter than the scenario list, so a reviewer can see missing viewpoints at a
+glance. Merge whenever the cases share ALL of: target · test intent/business rule ·
+precondition/condition · trigger or procedure shape · **the way the expected result is
+determined** (its oracle *family*, not its exact message).
+
+- **Oracle family = the determination method, parameterized.** All validation branches of ONE
+  field belong to ONE item — required, format, length, character-class are *expected branches*
+  (parameters) of "the field shows the validation message defined for the violated rule", shown
+  per variant, never separate items.
+- MAY vary inside one item (coverage dimensions, visible on the sub-rows): data values, boundary
+  points, **account states** (a seeded/locked/deleted account next to a wrong-password case),
+  provider/browser/locale, `@cases` rows, a different trigger with the same oracle (blur vs
+  submit), **execution mode** (auto + manual mix — the parent shows `Auto n · Manual m`), and
+  **priority** (the item takes the highest; per-variant priorities stay visible).
+- MUST split: different target, different intent/business rule, different way of determining the
+  expected result (a field-error family ≠ a session-established family), different test layer
+  (`@api`/`@query`), materially different precondition, or a different procedure shape —
+  sequence-sensitive flows (re-Given/When after a Then) stay solo. **Different risk classes never
+  merge**: XSS and SQL injection are separate items (different risk and determination), even on
+  the same field.
+- When unsure, keep items separate — the gates and QA decide, never guess-merge.
 - Every scenario must land in exactly one group **or** one disposition (Gate B enforces 100%
   disposition). Data-setup blocks (`@manual:data-setup`) → `excluded`; SPEC-GAP placeholders →
   `blocked`.
 
+**Wording rules for `intent`/`oracle` (customer-facing — Gate W lints these):**
+- Plain product language, present simple, ~10–20 words, one behavior:
+  "A user can sign in with valid credentials and is redirected to the Jobs page."
+- Oracle = the observable outcome as a definite assertion ("The Jobs page is displayed and the
+  Logout link is visible.") — no `should`, no tester actions.
+- NEVER: `{{tokens}}`, `[Selector]` references, DSL phrasing (`User fill/click/see`), generator
+  labels (`Setup:`/`Observable:`/`Oracle:`), or vague verbs (`handles`, `surfaces`) when a precise
+  behavior exists. Use the visible UI label (the Login button, the Email field).
+- **Preserve the source meaning exactly** — never strengthen, weaken, or reinterpret an oracle
+  (a security assertion especially: if the source says "the password appears ONLY in the HTTPS
+  POST body", do not write "no plaintext password on the network").
+
+**Requirement coverage (`requirements:` section, optional):** `sungen delivery` scans
+`requirements/spec.md` for FR-/TR-/NFR- ids; ids traced by `@spec:` tags are `covered`, the rest
+are `gap` (Gate R warning). Record the reviewed status for genuine non-gaps:
+
+```yaml
+requirements:
+  TR-007: { status: planned, note: Performance needs Lighthouse-style tooling }
+  TR-004: { status: partially_covered, note: client-side covered by VP-SEC-003; hashing needs DB verify }
+  # status: covered | partially_covered | covered_elsewhere | planned | gap | not_applicable
+```
+
 Then validate and fix any ERROR findings:
 
 ```bash

package/dist/orchestrator/templates/ai-src/skills/sungen-delivery/SKILL.md

@@ -29,19 +29,44 @@ fingerprints). Schema + grouping rules live in the delivery command instructions
 spec is `docs/spec/delivery-coverage-matrix-spec.md`.
 
 **Gates** (CLI `--check`): A source (VP-ids unique, oracle present, Background setup-only) ·
-B mapping (every scenario in exactly one group XOR one disposition) · C aggregation (mode/layer/
-priority recomputed and equal within a group — heuristic oracle-shape/precondition mismatches are
-review-level, silenced once approved and unchanged) · D executability (precondition · condition+
-data · trigger · oracle all renderable; every `{{var}}` resolves) · E drift (fingerprint mismatch
-→ back to review) · G review state (proposed groups block the official render; `--preview` renders
-a DRAFT watermark).
-
-**Workbook**: `Testcases` sheet (parent rows + outline-level-1 variant sub-rows — collapse for the
-customer view, expand to execute; result roll-up failed→blocked→not_run→partial→passed, counts like
-`7/8 Passed · 1 Failed`) + `Coverage` sheet (target × category grid with explicit `—` gaps,
-dispositions, generation manifest). CSV is flat with a `Level` column (`item`/`variant`).
+B mapping (every scenario in exactly one group XOR one disposition) · C aggregation (test layer
+recomputed and equal within a group — **execution mode and priority are coverage dimensions, not
+splits**: mixed items show `Auto n · Manual m` and take the highest variant priority; heuristic
+oracle-shape/precondition mismatches are review-level, silenced once approved and unchanged) ·
+D executability (precondition · condition+
+data · trigger · oracle all renderable; every `{{var}}` resolves; **no template token may survive
+into a rendered cell** — test-data cross-references are resolved for display) · E drift
+(fingerprint mismatch → back to review) · G review state (proposed groups block the official
+render; `--preview` renders a DRAFT watermark) · R requirement coverage (spec FR/TR/NFR ids with
+no trace and no `requirements:` status → warning) · W wording lint (map intent/oracle containing
+tokens, `[Selector]` refs, DSL phrasing, or generator labels → warning).
+
+**Wording normalization (deterministic, after semantic normalization):** DSL steps render as
+controlled manual-test English without changing meaning — actions in the imperative (`User fill
+[Email] field with X` → `Enter X in the Email field.`), expected results as observable assertions
+(`User see [Jobs] page` → `The Jobs page is displayed.`), preconditions as states (`The user is
+signed out.`). Manual `# Tester verifies:` labels become structured fields: `Setup:` →
+Precondition, `Action:` → Action, `Observable:` → Expected Result, `Oracle:` → a separate
+`Verification method:` line. Sequence-sensitive flows keep event order: actions numbered with
+mid-flow assertions inline as `Verify: …`; only the final Then block is the Expected Result.
+Empty test values render as `(empty)`.
+
+**Workbook**: `Testcases` sheet — parent rows + outline-level-1 variant sub-rows for **every**
+item (single-variant included: the sub-row carries the source VP-id, resolved data, and the
+result/evidence entry). Collapse outline for the customer view, expand to execute. Variant Result
+cells have a dropdown (Passed/Failed/Blocked/Pending/N/A) and the parent Result is a **live Excel
+formula** over its children (failed→blocked→pending→partial→passed, e.g. `2/3 Passed · 1 Failed`)
+— a parent can never contradict its variants, even after manual edits. ID + Target columns are
+frozen; dates are ISO (`2026-08-04`). `Coverage` sheet — requirement coverage table (every FR/TR/
+NFR id with an explicit status), target × category grid with explicit `—` gaps, dispositions,
+manifest. CSV is flat with a `Level` column (`item`/`variant`) + a requirement-coverage appendix.
 `delivery_item_count` ≠ progress — variants are the execution metric.
 
+**Authoring guidance the matrix rewards** (create-test side): payload/provider matrices (SQLi
+payload lists, OAuth provider sets) belong in `@cases` datasets so each case is an atomic,
+independently-reportable variant; keep dataset `case:` labels short and stable (`CHK-EMAIL-I1`),
+with descriptions in other columns — the label is part of the variant's identity.
+
 ---
 
 ## Legacy mode (--legacy / --full)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.16-beta.1",
+  "version": "3.2.16-beta.3",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -39,8 +39,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.2.16-beta.1",
-    "@sungen/driver-ui": "3.2.16-beta.1",
+    "@sungen/driver-data-factory": "3.2.16-beta.3",
+    "@sungen/driver-ui": "3.2.16-beta.3",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

package/src/cli/commands/delivery.ts

@@ -621,6 +621,7 @@ function matrixPathsFor(cwd: string, target: DeliveryTarget): MatrixTargetPaths
     featureFile: path.join(base, 'features', `${target.featureBaseName}.feature`),
     testDataFile: resolveTestDataPathForTarget(cwd, target),
     specFile: path.join(genBase, `${target.featureBaseName}.spec.ts`),
+    specMdFile: path.join(base, 'requirements', 'spec.md'),
     resultsPath: resolveResultsPath(cwd, target),
     mapFile: mapFilePath(base, target.featureBaseName),
   };

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,7 +14,7 @@ import {
   splitVpAndName,
 } from '../feature-parser';
 import { getCasesDatasetRows, resolveResultVariants } from '../result-variants';
-import { substituteTestDataVars } from '../test-data-resolver';
+import { classifyManualComments, renderAction, renderExpected, renderPrecondition } from './wording';
 import { scenarioFingerprint, combinedFingerprint, mapContentFingerprint } from './fingerprint';
 import {
   CoverageVariant,
@@ -24,6 +24,7 @@ import {
   MatrixDisposition,
   MatrixLayer,
   MatrixModel,
+  RequirementCoverage,
   MAX_VARIANTS_PER_ITEM,
 } from './types';
 import { runGates } from './gates';
@@ -89,6 +90,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 +100,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) {
@@ -107,26 +113,36 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
     const mode = extractTestcaseType(tags) === 'Manual' ? 'manual' : 'auto';
     const authRole = extractAuthRole(tags);
     const vpCategory = vpId.replace(/^VP-/, '').replace(/-\d+[a-zA-Z]?$/, '');
+    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);
 
     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) => renderPrecondition(t)),
+    ]));
 
     const base = {
       vpId,
@@ -136,11 +152,46 @@ 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),
+      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);
+      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 +201,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 +209,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 +237,77 @@ 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>): string {
+  return text.replace(/\{\{\s*([^}\s]+)\s*\}\}/g, (m, key: string) => {
+    if (!(key in vars)) return m; // unknown stays literal → Gate D flags it
+    const v = vars[key];
+    return v === '' ? '(empty)' : 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>();
+  for (const m of specText.matchAll(/\b(?:FR|TR|NFR)-\d+\b/g)) {
+    if (!seen.has(m[0])) { seen.add(m[0]); ids.push(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;
 }
 
@@ -243,6 +368,12 @@ export function buildMatrix(inputs: BuildInputs): MatrixModel {
     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));
+    // 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,8 +382,8 @@ 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 ?? [],
@@ -270,6 +401,18 @@ 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`,
+    });
+  }
+
   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 +422,7 @@ export function buildMatrix(inputs: BuildInputs): MatrixModel {
     formNo: map.formNo ?? 'BM-2-901-13',
     items,
     dispositions,
+    requirements,
     findings,
     manifest: {
       unit,