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

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

@@ -1,15 +1,17 @@
 /**
  * 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`),
- * so downstream pipelines can re-derive both views from one file.
+ * 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, formatExecutedDate } from '../playwright-report-parser';
+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 (Oracle)',
+  'Precondition', 'Coverage / Test Data', 'Action / Trigger', 'Expected Result',
   'Mode', 'Trace', 'Result', 'Executed Date', 'Note',
 ];
 
@@ -18,6 +20,13 @@ function esc(value: string): string {
   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[] = [];
@@ -26,8 +35,8 @@ export function renderMatrixCsv(model: MatrixModel): string {
   lines.push(HEADERS.map(esc).join(','));
 
   for (const item of model.items) {
-    const single = item.variants.length === 1;
-    const only = single ? item.variants[0] : undefined;
+    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,
@@ -36,35 +45,46 @@ export function renderMatrixCsv(model: MatrixModel): string {
       item.category,
       item.priority,
       item.precondition.join('\n'),
-      single ? only!.data.join('\n') : `${item.variants.length} variants`,
-      item.trigger.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(' '),
-      item.result,
-      single ? formatExecutedDate(only!.result?.startTime) : '',
+      itemResultLabel(item),
+      '',
       item.review === 'proposed' ? 'REVIEW REQUIRED' : '',
     ].map(esc).join(','));
 
-    if (!single) {
-      for (const v of item.variants) {
-        lines.push([
-          'variant',
-          v.ref,
-          '',
-          v.condition,
-          '', '',
-          '',
-          v.data.join('\n'),
-          v.trigger.join('\n'),
-          v.oracle.join('\n'),
-          v.mode === 'manual' ? 'Manual' : 'Auto',
-          v.traces.join(' '),
-          v.result ? statusToTestResult(v.result.status) : 'Pending',
-          formatExecutedDate(v.result?.startTime),
-          v.result?.error ? String(v.result.error).slice(0, 200) : '',
-        ].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';

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

@@ -2,14 +2,21 @@
  * Render the Test Case & Coverage Matrix workbook.
  *
  * Sheets:
- *   1. Testcases — one parent row per delivery item, variant sub-rows grouped with
- *      Excel outline (expanded for execution; the level-1 outline button collapses
- *      to the customer/review view — same sheet, one model, two views).
- *   2. Coverage — target × category grid (items + variants, `—` marks the gaps),
- *      dispositions, and the generation manifest.
+ *   1. Testcases — one parent row per delivery item; EVERY item (including
+ *      single-variant ones) carries variant sub-rows on Excel outline level 1 —
+ *      the sub-row is where source traceability (VP-id), test data, and the
+ *      manual result/evidence entry live (review B-05/B-06). Collapse outline
+ *      level 1 for the customer/review view; expand to execute.
+ *   2. Coverage — requirement coverage (id ↔ items ↔ status), the target ×
+ *      category grid (explicit `—` gaps), dispositions, and the manifest.
  *
- * Every sheet keeps the company ISO masthead (renderReportHeaderBand). A draft
- * matrix (unapproved groups / review findings) carries a red DRAFT banner.
+ * Manual-execution support: variant Result cells carry a dropdown
+ * (Passed/Failed/Blocked/Pending/N/A) and the parent Result is a live Excel
+ * formula derived from its children — a parent can never contradict its
+ * variants, even after QA edits results by hand (review B-06).
+ *
+ * Every sheet keeps the company ISO masthead. A draft matrix (unapproved
+ * groups / review findings) carries a red DRAFT banner.
  */
 
 import * as ExcelJS from 'exceljs';
@@ -20,13 +27,14 @@ import {
   BLACK,
   LAVENDER,
 } from '../xlsx-report-builder';
-import { statusToTestResult, formatExecutedDate } from '../playwright-report-parser';
+import { statusToTestResult } from '../playwright-report-parser';
 import { CoverageVariant, DeliveryItem, ItemResult, MatrixModel, MapCategory } from './types';
 
 const CATEGORY_ORDER: MapCategory[] = ['normal', 'abnormal', 'security', 'nfr'];
 const SOFT_BLUE = { argb: 'FFDCE6F1' };
 const DRAFT_RED = { argb: 'FFC00000' };
 const GAP_FILL = { argb: 'FFFCE4EC' };
+const RESULT_STATES = 'Passed,Failed,Blocked,Pending,N/A';
 
 function headerCell(c: ExcelJS.Cell, label: string): void {
   c.value = label;
@@ -37,14 +45,16 @@ function headerCell(c: ExcelJS.Cell, label: string): void {
 }
 
 function dataCell(c: ExcelJS.Cell, value: ExcelJS.CellValue, opts?: { bold?: boolean; fill?: { argb: string }; center?: boolean; color?: { argb: string } }): void {
-  c.value = value;
+  // An empty value stays a genuinely blank cell — never an empty shared string,
+  // which some renderers display as its string-table index (review M-03).
+  if (value !== '' && value !== undefined && value !== null) c.value = value;
   c.font = { bold: opts?.bold ?? false, size: 10, name: ARIAL_FONT, ...(opts?.color ? { color: opts.color } : {}) };
   c.alignment = { horizontal: opts?.center ? 'center' : 'left', vertical: 'top', wrapText: true };
   c.border = allBordersBlack;
   if (opts?.fill) c.fill = { type: 'pattern', pattern: 'solid', fgColor: opts.fill };
 }
 
-function itemResultLabel(item: DeliveryItem): string {
+export function itemResultLabel(item: DeliveryItem): string {
   const { passed, failed, blocked, notRun } = item.resultCounts;
   const total = item.variants.length;
   const map: Record<ItemResult, string> = {
@@ -62,12 +72,27 @@ function variantResultLabel(v: CoverageVariant): string {
   return statusToTestResult(v.result.status);
 }
 
+/** ISO date (2026-08-04) — unambiguous across locales (review §9). */
+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')}`;
+}
+
 function numbered(lines: string[]): string {
   if (lines.length === 0) return '';
   if (lines.length === 1) return lines[0];
   return lines.map((l, i) => `${i + 1}. ${l}`).join('\n');
 }
 
+/** Expected cell = observable outcomes; the HOW moves under a separate heading. */
+function expectedWithVerification(oracle: string[], verification: string[]): string {
+  const expected = numbered(oracle);
+  if (verification.length === 0) return expected;
+  return `${expected}\nVerification method: ${verification.join(' ')}`;
+}
+
 /** Red DRAFT banner on row 5 when the matrix is not approved for official delivery. */
 function draftBanner(ws: ExcelJS.Worksheet, model: MatrixModel): void {
   if (model.manifest.approvalState !== 'draft') return;
@@ -85,9 +110,10 @@ function draftBanner(ws: ExcelJS.Worksheet, model: MatrixModel): void {
 
 const MATRIX_HEADERS = [
   'ID', 'Target', 'Test Intent / Condition', 'Category', 'Priority', 'Precondition',
-  'Coverage / Test Data', 'Action / Trigger', 'Expected (Oracle)', 'Mode', 'Trace',
+  'Coverage / Test Data', 'Action / Trigger', 'Expected Result', 'Mode', 'Trace',
   'Result', 'Executed Date', 'Executor', 'Note\n(Evidence, DefectID)',
 ];
+const RESULT_COL = 13; // column M
 
 function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?: string): void {
   const ws = wb.addWorksheet('Testcases');
@@ -95,7 +121,7 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
 
   ws.columns = [
     { width: 3 },  // A margin
-    { width: 20 }, // B ID
+    { width: 22 }, // B ID
     { width: 18 }, // C Target
     { width: 42 }, // D Intent / Condition
     { width: 11 }, // E Category
@@ -106,8 +132,8 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
     { width: 42 }, // J Expected
     { width: 11 }, // K Mode
     { width: 13 }, // L Trace
-    { width: 17 }, // M Result
-    { width: 13 }, // N Executed
+    { width: 22 }, // M Result
+    { width: 12 }, // N Executed
     { width: 13 }, // O Executor
     { width: 24 }, // P Note
   ];
@@ -137,13 +163,55 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
 
   let rowIdx = HEADER_ROW + 1;
   for (const item of model.items) {
-    // Parent row — the delivery item (the review unit).
-    const pr = ws.getRow(rowIdx++);
-    const single = item.variants.length === 1;
-    const only = single ? item.variants[0] : undefined;
-    const coverage = single
-      ? numbered(only!.data)
-      : `${item.variants.length} variants: ${item.variants.map((v) => v.condition).join(' · ')}`;
+    const parentRowIdx = rowIdx++;
+
+    // --- Variant sub-rows FIRST (to know their cell range for the parent formula).
+    // Every item gets sub-rows — the sub-row is where the source scenario id, the
+    // resolved data, and the manual result/evidence entry live (review B-05).
+    const firstChild = rowIdx;
+    for (const v of item.variants) {
+      const vr = ws.getRow(rowIdx++);
+      vr.outlineLevel = 1;
+      const vValues: ExcelJS.CellValue[] = [
+        v.ref,
+        '',
+        v.condition,
+        '', '', '',
+        numbered(v.data),
+        numbered(v.trigger),
+        expectedWithVerification(v.oracle, v.verification),
+        v.mode === 'manual' ? `Manual${v.manualReason ? ` (${v.manualReason})` : ''}` : 'Auto',
+        v.traces.join(', '),
+        variantResultLabel(v),
+        isoDate(v.result?.startTime),
+        '',
+        v.result?.error ? String(v.result.error).slice(0, 200) : '',
+      ];
+      vValues.forEach((val, i) => dataCell(vr.getCell(2 + i), val, { center: i === 9 }));
+      // Manual-execution entry: constrain the Result cell to the known states.
+      vr.getCell(2 + 11).dataValidation = {
+        type: 'list', allowBlank: true, formulae: [`"${RESULT_STATES}"`],
+      };
+    }
+    const lastChild = rowIdx - 1;
+
+    // --- Parent row: only values that are genuinely COMMON to the whole item
+    // (review M-04); everything variant-specific stays on the sub-rows.
+    const pr = ws.getRow(parentRowIdx);
+    const triggerTexts = new Set(item.variants.map((v) => v.trigger.join('\n')));
+    const commonTrigger = triggerTexts.size === 1 ? item.variants[0].trigger : null;
+    const coverage = `${item.variants.length} variant(s): ${item.variants.map((v) => v.condition).join(' · ')}`;
+
+    // Live roll-up: derived from the child Result cells so hand-entered results
+    // recompute the parent — precedence failed → blocked → pending → partial → passed.
+    const rng = `M${firstChild}:M${lastChild}`;
+    const n = item.variants.length;
+    const rollUpFormula =
+      `IF(COUNTIF(${rng},"Failed")>0,COUNTIF(${rng},"Passed")&"/${n} Passed · "&COUNTIF(${rng},"Failed")&" Failed",` +
+      `IF(COUNTIF(${rng},"Blocked")>0,"Blocked",` +
+      `IF(COUNTIF(${rng},"Passed")=${n},"${n}/${n} Passed",` +
+      `IF(COUNTIF(${rng},"Passed")=0,"Pending",COUNTIF(${rng},"Passed")&"/${n} Passed · pending"))))`;
+
     const values: ExcelJS.CellValue[] = [
       item.id,
       item.target,
@@ -152,12 +220,12 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
       item.priority,
       numbered(item.precondition),
       coverage,
-      numbered(item.trigger),
+      commonTrigger ? numbered(commonTrigger) : '(differs per variant — see sub-rows)',
       item.oracle,
-      item.mode === 'manual' ? `Manual${only?.manualReason ? ` (${only.manualReason})` : ''}` : 'Auto',
+      item.mode === 'manual' ? 'Manual' : 'Auto',
       item.traces.join(', '),
-      itemResultLabel(item),
-      single ? formatExecutedDate(only!.result?.startTime) : '',
+      { formula: rollUpFormula, result: itemResultLabel(item) } as ExcelJS.CellValue,
+      '',
       '',
       item.review === 'proposed' ? 'REVIEW REQUIRED' : '',
     ];
@@ -165,53 +233,52 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
       bold: true,
       fill: SOFT_BLUE,
       center: i === 3 || i === 4 || i === 9,
-      ...(String(values[14]).startsWith('REVIEW') && i === 14 ? { color: DRAFT_RED } : {}),
+      ...(i === 14 && item.review === 'proposed' ? { color: DRAFT_RED } : {}),
     }));
-
-    // Variant sub-rows — the execution units (outline level 1; collapse for review).
-    if (!single) {
-      for (const v of item.variants) {
-        const vr = ws.getRow(rowIdx++);
-        vr.outlineLevel = 1;
-        const vValues: ExcelJS.CellValue[] = [
-          v.ref,
-          '',
-          v.condition,
-          '', '', '',
-          numbered(v.data),
-          numbered(v.trigger),
-          numbered(v.oracle),
-          v.mode === 'manual' ? `Manual${v.manualReason ? ` (${v.manualReason})` : ''}` : 'Auto',
-          v.traces.join(', '),
-          variantResultLabel(v),
-          formatExecutedDate(v.result?.startTime),
-          '',
-          v.result?.error ? String(v.result.error).slice(0, 200) : '',
-        ];
-        vValues.forEach((val, i) => dataCell(vr.getCell(2 + i), val, { center: i === 9 }));
-      }
-    }
   }
 
   ws.autoFilter = { from: { row: HEADER_ROW, column: 2 }, to: { row: rowIdx - 1, column: 16 } };
-  ws.views = [{ state: 'frozen', ySplit: HEADER_ROW }];
+  // Freeze the header band AND the ID + Target columns (review §9).
+  ws.views = [{ state: 'frozen', xSplit: 3, ySplit: HEADER_ROW }];
 }
 
 // ---------------------------------------------------------------------------
-// Sheet 2 — Coverage (overview grid + dispositions + manifest)
+// Sheet 2 — Coverage (requirements + overview grid + dispositions + manifest)
 // ---------------------------------------------------------------------------
 
 function addCoverageSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?: string): void {
   const ws = wb.addWorksheet('Coverage');
   ws.columns = [
-    { width: 3 }, { width: 30 }, { width: 16 }, { width: 16 }, { width: 16 }, { width: 16 },
-    { width: 16 }, { width: 40 },
+    { width: 3 }, { width: 22 }, { width: 18 }, { width: 16 }, { width: 16 }, { width: 16 },
+    { width: 16 }, { width: 44 },
   ];
   renderReportHeaderBand(wb, ws, `${model.unit.toUpperCase()} COVERAGE OVERVIEW`, sungenVersion, model.formNo);
   draftBanner(ws, model);
 
-  // --- Target × category grid ---
   let rowIdx = 7;
+
+  // --- Requirement coverage (review §6): every requirement id gets ONE explicit status.
+  if (model.requirements.length > 0) {
+    dataCell(ws.getRow(rowIdx).getCell(2), 'Requirement coverage — every id has an explicit status', { bold: true });
+    rowIdx += 1;
+    const rh = ws.getRow(rowIdx++);
+    ['Requirement', 'Status', 'Delivery items', 'Variants', 'Note'].forEach((l, i) => headerCell(rh.getCell(2 + i), l));
+    for (const r of model.requirements) {
+      const row = ws.getRow(rowIdx++);
+      dataCell(row.getCell(2), r.id, { bold: true });
+      dataCell(row.getCell(3), r.status, {
+        center: true,
+        ...(r.status === 'gap' ? { fill: GAP_FILL, bold: true } : {}),
+      });
+      ws.mergeCells(rowIdx - 1, 4, rowIdx - 1, 6);
+      dataCell(row.getCell(4), r.items.join(', '));
+      dataCell(row.getCell(7), r.variantCount > 0 ? String(r.variantCount) : '', { center: true });
+      dataCell(row.getCell(8), r.note);
+    }
+    rowIdx += 1;
+  }
+
+  // --- Target × category grid ---
   dataCell(ws.getRow(rowIdx).getCell(2), 'Coverage matrix — delivery items (coverage variants) per target × category', { bold: true });
   rowIdx += 1;
   const gridHeader = ws.getRow(rowIdx++);

package/src/exporters/matrix/types.ts

@@ -38,6 +38,14 @@ export interface MapDisposition {
   reason?: string;
 }
 
+export type RequirementStatus =
+  | 'covered' | 'partially_covered' | 'covered_elsewhere' | 'planned' | 'gap' | 'not_applicable';
+
+export interface RequirementOverride {
+  status: RequirementStatus;
+  note?: string;
+}
+
 export interface DeliveryMap {
   version: number;
   unit: string;
@@ -46,6 +54,9 @@ export interface DeliveryMap {
   groups: MapGroup[];
   /** VP-id → intentionally-not-grouped disposition. */
   dispositions: Record<string, MapDisposition>;
+  /** Requirement-id → reviewed status override (partially_covered / not_applicable / …).
+   *  Without an override a requirement is `covered` when a variant traces to it, else `gap`. */
+  requirements: Record<string, RequirementOverride>;
   /** VP-id → scenario fingerprint stamped at approval time (drift detector input). */
   fingerprints: Record<string, string>;
 }
@@ -90,6 +101,9 @@ export interface CoverageVariant {
   oracleShape: string[];
   /** Oracle for display. */
   oracle: string[];
+  /** HOW to check (manual `Oracle:` lines — tools, panes, queries). Rendered as
+   *  "Verification method" under the expected result, never inside it. */
+  verification: string[];
   /** Precondition profile: auth role + scenario-level Given shapes — signature input. */
   preconditionProfile: string;
   /** Human preconditions (auth + own Given steps). */
@@ -133,11 +147,21 @@ export interface MatrixDisposition {
   reason: string;
 }
 
+/** One row of the requirement-coverage table (Coverage sheet). */
+export interface RequirementCoverage {
+  id: string;                    // FR-003 / TR-001 / NFR-…
+  status: RequirementStatus;
+  /** Delivery items whose variants trace to this requirement. */
+  items: string[];
+  variantCount: number;
+  note: string;
+}
+
 // ---------------------------------------------------------------------------
 // Gate findings
 // ---------------------------------------------------------------------------
 
-export type GateId = 'A' | 'B' | 'C' | 'D' | 'E' | 'G';
+export type GateId = 'A' | 'B' | 'C' | 'D' | 'E' | 'G' | 'R' | 'W';
 export type FindingSeverity = 'error' | 'review' | 'warning';
 
 export interface MatrixFinding {
@@ -168,6 +192,8 @@ export interface MatrixModel {
   formNo: string;
   items: DeliveryItem[];
   dispositions: MatrixDisposition[];
+  /** Requirement coverage — empty when the unit has no requirements/spec.md ids. */
+  requirements: RequirementCoverage[];
   findings: MatrixFinding[];
   manifest: MatrixManifest;
 }

package/src/exporters/matrix/wording.ts

@@ -0,0 +1,157 @@
+/**
+ * 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.
+ */
+
+// `[Email] field` → `Email field` (the visible label + its element type).
+function deRef(text: string): string {
+  return text.replace(/\[([^\]]+)\]/g, '$1');
+}
+
+function sentence(text: string): string {
+  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`.
+ */
+export function renderAction(raw: string): string {
+  let s = raw.trim().replace(/^(User|The user)\s+/i, '');
+
+  const rules: Array<[RegExp, (m: RegExpMatchArray) => string]> = [
+    // 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`).
+ */
+export function renderExpected(raw: string): string {
+  let s = raw.trim().replace(/^(User|The user)\s+/i, '');
+
+  const rules: Array<[RegExp, (m: RegExpMatchArray) => string]> = [
+    // 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."). */
+export function renderPrecondition(raw: string): string {
+  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)}`));
+}
+
+// ---------------------------------------------------------------------------
+// Manual `# Tester verifies:` comment classification (structured, label-free)
+// ---------------------------------------------------------------------------
+
+export interface ManualProcedure {
+  /** Setup/Precondition/Arrange lines — the state to establish first. */
+  preconditions: string[];
+  /** Action/unlabelled lines — the imperative procedure. */
+  actions: string[];
+  /** Observable/Expect/Result/Assert lines — the observable outcome. */
+  expected: string[];
+  /** Oracle/Verify lines — HOW to check (tools, panes, queries). */
+  verification: string[];
+}
+
+/**
+ * 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.
+ */
+export function classifyManualComments(comments: string[]): ManualProcedure {
+  const out: ManualProcedure = { preconditions: [], actions: [], expected: [], verification: [] };
+  let last: { list: string[]; idx: number } | null = null;
+
+  const bucketOf = (label: string): keyof ManualProcedure => {
+    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;
+}