@sun-asterisk/sungen 3.2.32 → 3.2.34

package/src/exporters/matrix/carry-manual-results.ts

@@ -0,0 +1,229 @@
+/**
+ * Carry a tester's hand-entered Manual results across a `sungen delivery` re-run (#756).
+ *
+ * The matrix workbook is rebuilt from scratch on every run, and a manual variant has no
+ * run-report entry, so its Result cell renders `Pending` and M–P render blank. Without
+ * this step the re-run overwrote the file and the tester's record was gone.
+ *
+ * Before the new workbook is written, the existing file's Manual sheet is read, and each
+ * variant sub-row's L–P cells (Test Result, Executed Date, Test Executor, Test Environment,
+ * Note) are carried into the new workbook by `v.ref` — column A.
+ *
+ * A result is only true of the procedure it was executed against, so every write stamps
+ * `ref → fingerprint` into a veryHidden sheet. The next run carries a result only while the
+ * stamp still matches; a changed procedure resets it to `Pending` and keeps the previous
+ * values in Note. Spec: docs/spec/delivery-coverage-matrix-spec.md §8.4.
+ *
+ * Manual sheet only: on Auto the run report is the source of truth for Result.
+ */
+
+import * as fs from 'fs';
+import * as ExcelJS from 'exceljs';
+import { MatrixModel } from './types';
+import { HEADER_ROW, RESULT_COL } from './render-testcase-sheet';
+
+const MANUAL_SHEET = 'Manual';
+/** veryHidden: Excel's UI cannot unhide it, so a tester cannot edit the guard by accident. */
+export const STAMP_SHEET = '_sungen_manual';
+/** L..P — the tester-owned columns of a variant sub-row. */
+const CARRIED_COLS = [RESULT_COL, RESULT_COL + 1, RESULT_COL + 2, RESULT_COL + 3, RESULT_COL + 4];
+const NOTE_INDEX = 4;
+const RESET_MARKER = '[sungen] Procedure changed since this result was recorded';
+
+interface CarriedCell { value: ExcelJS.CellValue; numFmt?: string }
+
+interface PriorRow { cells: CarriedCell[] }
+
+export interface PriorManualResults {
+  rows: Map<string, PriorRow>;
+  /** Later copies of a ref already read — only the first is carried, so these are reported. */
+  duplicates: { ref: string; result: string }[];
+  /** `ref → fingerprint` from the stamp sheet; null when the file predates #756. */
+  stamps: Map<string, string> | null;
+}
+
+export interface ManualCarryReport {
+  /** Carried with a matching fingerprint. */
+  carried: number;
+  /** Carried from a file with no stamp — no drift check was possible. */
+  unchecked: number;
+  /** Result reset to Pending because the procedure changed. */
+  reset: string[];
+  /** Prior rows with an entry that no longer match any manual variant. */
+  notPlaced: { ref: string; result: string }[];
+  /** Prior rows with an entry that repeat a ref above them — not carried. */
+  duplicates: { ref: string; result: string }[];
+}
+
+function isFormula(v: ExcelJS.CellValue): boolean {
+  return typeof v === 'object' && v !== null && ('formula' in v || 'sharedFormula' in v);
+}
+
+function cellText(v: ExcelJS.CellValue): string {
+  if (v === null || v === undefined) return '';
+  if (v instanceof Date) return isNaN(v.getTime()) ? '' : v.toISOString().slice(0, 10);
+  if (typeof v === 'object') {
+    if ('richText' in v) return v.richText.map((r) => r.text).join('').trim();
+    if ('text' in v) return String(v.text).trim();
+    if ('result' in v) return cellText(v.result as ExcelJS.CellValue);
+  }
+  return String(v).trim();
+}
+
+/**
+ * ExcelJS reads a formula's text result under a date format as an Invalid Date. Drop that
+ * cached result — Excel recomputes it on open — instead of writing NaN back into the file.
+ */
+function readable(v: ExcelJS.CellValue): ExcelJS.CellValue {
+  if (isFormula(v)) {
+    const { result, ...formula } = v as ExcelJS.CellFormulaValue;
+    if (result instanceof Date && isNaN(result.getTime())) return formula as ExcelJS.CellValue;
+  }
+  return v;
+}
+
+/** A row still at the rendered default carries nothing. */
+function isUntouched(cells: CarriedCell[]): boolean {
+  const [result, ...rest] = cells.map((c) => cellText(c.value));
+  return (result === '' || result === 'Pending') && rest.every((t) => t === '');
+}
+
+/**
+ * Variant sub-rows of a Manual sheet, in row order: `[ref, row]`. Either signal is enough:
+ * the renderer puts variants on outline level 1, and a parent's Result is a roll-up formula.
+ * Outline levels are lost by some spreadsheet tools on save, and a tester can paste a
+ * formula into a variant's Result, so relying on one alone would hide the row silently.
+ */
+function variantRows(ws: ExcelJS.Worksheet): [string, ExcelJS.Row][] {
+  const out: [string, ExcelJS.Row][] = [];
+  for (let r = HEADER_ROW + 1; r <= ws.rowCount; r++) {
+    const row = ws.getRow(r);
+    const ref = cellText(row.getCell(1).value);
+    if (ref && (row.outlineLevel === 1 || !isFormula(row.getCell(RESULT_COL).value))) out.push([ref, row]);
+  }
+  return out;
+}
+
+/**
+ * Read the Manual results of the workbook about to be overwritten. Returns null when there is
+ * no such file. A file that exists but cannot be read THROWS: overwriting it would destroy the
+ * very record this step exists to keep.
+ */
+export async function readPriorManualResults(file: string): Promise<PriorManualResults | null> {
+  if (!fs.existsSync(file)) return null;
+  const wb = new ExcelJS.Workbook();
+  try {
+    await wb.xlsx.readFile(file);
+  } catch (e) {
+    throw new Error(
+      `cannot read ${file} to carry its Manual results (${(e as Error).message}). ` +
+      'Close it in Excel, or move it aside to start a fresh workbook, then re-run.',
+    );
+  }
+
+  // Every workbook sungen writes has a Manual sheet, even an empty one. Without it the
+  // tester's results cannot be located — carrying nothing would look like a clean run.
+  const ws = wb.getWorksheet(MANUAL_SHEET);
+  if (!ws) {
+    throw new Error(
+      `${file} has no "${MANUAL_SHEET}" sheet, so its Manual results cannot be carried. ` +
+      `Rename the sheet back to "${MANUAL_SHEET}", or move the file aside to start a fresh workbook, then re-run.`,
+    );
+  }
+
+  const rows = new Map<string, PriorRow>();
+  const duplicates: PriorManualResults['duplicates'] = [];
+  for (const [ref, row] of variantRows(ws)) {
+    const cells = CARRIED_COLS.map((c) => {
+      const cell = row.getCell(c);
+      return { value: readable(cell.value), ...(cell.numFmt ? { numFmt: cell.numFmt } : {}) };
+    });
+    if (!rows.has(ref)) rows.set(ref, { cells });
+    else if (!isUntouched(cells)) duplicates.push({ ref, result: cellText(cells[0].value) || '(no result)' });
+  }
+
+  const stampWs = wb.getWorksheet(STAMP_SHEET);
+  let stamps: Map<string, string> | null = null;
+  if (stampWs) {
+    stamps = new Map();
+    stampWs.eachRow((row, n) => {
+      if (n > 1) stamps!.set(cellText(row.getCell(1).value), cellText(row.getCell(2).value));
+    });
+  }
+  return { rows, duplicates, stamps };
+}
+
+/**
+ * Note for a reset row: what was invalidated, then whatever the tester had written. A note
+ * that is a hyperlink (evidence, a defect ticket) stays one — only its text gains the marker.
+ */
+function resetNote(prior: CarriedCell[]): ExcelJS.CellValue {
+  const [result, date, executor] = prior.map((c) => cellText(c.value));
+  const was = [result, date, executor].filter(Boolean).join(' · ');
+  const header = `${RESET_MARKER} — previous: ${was}. Re-run required.`;
+  const note = prior[NOTE_INDEX].value;
+  const own = cellText(note);
+  if (typeof note === 'object' && note !== null && 'hyperlink' in note) {
+    return { ...note, text: `${header}\n${own}` };
+  }
+  return own ? `${header}\n${own}` : header;
+}
+
+/**
+ * Carry `prior` into the freshly rendered `wb`, then stamp every manual variant's fingerprint.
+ * Only the Manual sheet's variant sub-rows are touched.
+ */
+export function carryManualResults(
+  wb: ExcelJS.Workbook,
+  model: MatrixModel,
+  prior: PriorManualResults | null,
+): ManualCarryReport {
+  const report: ManualCarryReport = { carried: 0, unchecked: 0, reset: [], notPlaced: [], duplicates: prior?.duplicates ?? [] };
+  const fingerprints = new Map(
+    model.items.flatMap((i) => i.variants).filter((v) => v.mode === 'manual').map((v) => [v.ref, v.fingerprint]),
+  );
+
+  const ws = wb.getWorksheet(MANUAL_SHEET);
+  const placed = new Set<string>();
+  if (ws && prior) {
+    for (const [ref, row] of variantRows(ws)) {
+      const before = prior.rows.get(ref);
+      if (!before) continue;
+      placed.add(ref);
+      if (isUntouched(before.cells)) continue;
+
+      const stamped = prior.stamps?.get(ref);
+      // Only a recorded result is a claim about the procedure. A row with no result (a
+      // blocker note, or one already reset) is carried as-is, so a second procedure
+      // change does not stack a second marker on it.
+      const hasResult = !['', 'Pending'].includes(cellText(before.cells[0].value));
+      if (stamped !== undefined && stamped !== fingerprints.get(ref) && hasResult) {
+        row.getCell(RESULT_COL).value = 'Pending';
+        row.getCell(CARRIED_COLS[NOTE_INDEX]).value = resetNote(before.cells);
+        report.reset.push(ref);
+        continue;
+      }
+
+      CARRIED_COLS.forEach((c, i) => {
+        const cell = row.getCell(c);
+        cell.value = before.cells[i].value;
+        if (before.cells[i].numFmt) cell.numFmt = before.cells[i].numFmt!;
+      });
+      if (stamped === undefined) report.unchecked++;
+      else report.carried++;
+    }
+  }
+
+  if (prior) {
+    for (const [ref, before] of prior.rows) {
+      if (!placed.has(ref) && !isUntouched(before.cells)) {
+        report.notPlaced.push({ ref, result: cellText(before.cells[0].value) || '(no result)' });
+      }
+    }
+  }
+
+  const stampWs = wb.addWorksheet(STAMP_SHEET, { state: 'veryHidden' });
+  stampWs.addRow(['ref', 'fingerprint']);
+  for (const [ref, fp] of fingerprints) stampWs.addRow([ref, fp]);
+  return report;
+}

package/src/exporters/matrix/export.ts

@@ -16,7 +16,8 @@ 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 { deliverableXlsxPath, writeXlsx } from '../xlsx-exporter';
+import { carryManualResults, ManualCarryReport, readPriorManualResults } from './carry-manual-results';
 import { loadPerfConfig, perfVerdict } from '../../harness/perf';
 import { loadDeliveryMap, writeDeliveryMap } from './map-loader';
 import { mapContentFingerprint } from './fingerprint';
@@ -25,6 +26,7 @@ import { renderMatrixXlsx } from './render-xlsx';
 import { renderMatrixCsv } from './render-csv';
 import { DeliveryMap, MatrixFinding, MatrixModel } from './types';
 import { ApiCatalogEntry } from '../types';
+import { RunEnvironment } from '../run-environment';
 
 export interface MatrixTargetPaths {
   cwd: string;
@@ -45,6 +47,8 @@ export interface MatrixTargetPaths {
   specMdFile?: string;
   resultsPath: string | null;
   mapFile: string;
+  /** Executor + environment of the run (#850) — absent for gates-only callers (inspect, approve). */
+  runEnv?: RunEnvironment;
 }
 
 function readSpecText(paths: MatrixTargetPaths): string {
@@ -90,6 +94,7 @@ export function loadMatrixModel(paths: MatrixTargetPaths): MatrixLoadResult {
     specText: readSpecText(paths),
     apiCatalog: catalogFor(paths),
   });
+  model.runEnv = paths.runEnv;
   // Perf verdict (#569): budgets are config (qa/perf.yaml), samples are the run's
   // per-test durations. Advisory — reported here because delivery is where runs
   // are read; the audit's score stays a pure function of the design artifacts.
@@ -163,13 +168,18 @@ export async function writeMatrixDeliverables(
   paths: MatrixTargetPaths,
   model: MatrixModel,
   format: MatrixFormat = 'xlsx',
-): Promise<{ csvPath?: string; xlsxPath?: string }> {
-  const out: { csvPath?: string; xlsxPath?: string } = {};
+): Promise<{ csvPath?: string; xlsxPath?: string; manualCarry?: ManualCarryReport }> {
+  const out: { csvPath?: string; xlsxPath?: string; manualCarry?: ManualCarryReport } = {};
+  const xlsx = format === 'xlsx' || format === 'both';
+  // Read the workbook about to be overwritten BEFORE writing anything, so the tester's Manual
+  // results survive (#756) and a refusal leaves no half-written target behind.
+  const prior = xlsx ? await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit)) : null;
   if (format === 'csv' || format === 'both') {
     out.csvPath = writeCsv(paths.cwd, paths.unit, renderMatrixCsv(model));
   }
-  if (format === 'xlsx' || format === 'both') {
+  if (xlsx) {
     const wb = renderMatrixXlsx(model, getPackageVersion());
+    out.manualCarry = carryManualResults(wb, model, prior);
     out.xlsxPath = await writeXlsx(paths.cwd, paths.unit, wb);
   }
   return out;

package/src/exporters/matrix/gates.ts

@@ -102,6 +102,12 @@ function gateASource(ctx: GateContext, findings: MatrixFinding[]): void {
           : `scenario ${vpId} has no Then step — a variant without an observable oracle cannot be delivered`,
       });
     }
+    if (m.unlabeledManualOracle) {
+      findings.push({
+        gate: 'A', severity: 'warning', ref: vpId,
+        message: `manual oracle found only in an unlabeled comment — exported verbatim into Expected; write the \`# Tester verifies:\` block as numbered "N. Observable: …" lines`,
+      });
+    }
   }
   for (const [vpId, n] of seen) {
     if (n > 1) findings.push({ gate: 'A', severity: 'error', ref: vpId, message: `duplicate VP-id ${vpId} (${n} scenarios)` });

package/src/exporters/matrix/render-testcase-sheet.ts

@@ -17,6 +17,7 @@ import * as ExcelJS from 'exceljs';
 import { renderReportHeaderBand, ARIAL_FONT } from '../xlsx-report-builder';
 import { redactSecrets } from '../api-testcase-formatter';
 import { clipNoteField } from '../playwright-report-parser';
+import { runCells } from '../run-environment';
 import { variantState } from './build';
 import { DeliveryItem, MatrixModel } from './types';
 import { SOFT_BLUE, DRAFT_RED, RESULT_STATES, dataCell, headerCell, draftBanner } from './xlsx-cells';
@@ -42,6 +43,9 @@ export const RESULT_COL = 12;
 
 /** Variant sub-row — only what distinguishes it from its parent (review GAP-01). */
 function variantValues(item: DeliveryItem, v: DeliveryItem['variants'][number], model: MatrixModel): ExcelJS.CellValue[] {
+  // Who ran it and against what — the same cells the legacy workbook fills (#850); blank
+  // until the variant has actually run.
+  const run = runCells(model.runEnv, v.result);
   return [
     v.ref,
     '',
@@ -50,15 +54,17 @@ function variantValues(item: DeliveryItem, v: DeliveryItem['variants'][number],
     numbered(item.preconditionDeltas[v.ref] ?? []),
     numbered(v.data),
     // Only the steps after the parent's shared prefix, numbered so the parent's
-    // steps + these read as one continuous procedure.
-    numbered(item.triggerDeltas[v.ref] ?? [], item.trigger.length + 1),
+    // steps + these read as one continuous procedure. Counted from the REAL shared
+    // steps, not `trigger.length`: with nothing shared the parent shows a generated
+    // "the action differs…" note, and the variant's first step read "2." (#848).
+    numbered(item.triggerDeltas[v.ref] ?? [], item.sharedTriggerSteps + 1),
     expectedWithVerification(v.oracle, v.verification),
     v.traces.join(', '),
     variantTypeLabel(v),
     variantState(v),
     isoDate(v.result?.startTime),
-    '',
-    '',
+    run.executor,
+    run.environment,
     // Redact BEFORE clipping — same denylist as the testcases CSV Note column.
     v.result?.error ? clipNoteField(redactSecrets(String(v.result.error), model.secretValues)) : '',
   ];

package/src/exporters/matrix/types.ts

@@ -176,8 +176,12 @@ export interface DeliveryItem {
   /** Preconditions shared by EVERY variant (the intersection) — written once here. */
   precondition: string[];
   /** Leading trigger steps shared by every variant — written once here; each
-   *  variant renders only its remaining steps (`triggerDeltas`). */
+   *  variant renders only its remaining steps (`triggerDeltas`). When nothing is shared this
+   *  holds a generated "the action differs…" note instead, which is NOT a step. */
   trigger: string[];
+  /** How many of `trigger` are real steps hoisted from the variants (0 when it is only the
+   *  note) — the variants' steps are numbered from this + 1 (#848). */
+  sharedTriggerSteps: number;
   variants: CoverageVariant[];
   /** variant ref → its precondition lines that are not on the parent. */
   preconditionDeltas: Record<string, string[]>;
@@ -253,6 +257,9 @@ export interface MatrixModel {
    * the deliverable ships to the client.
    */
   secretValues: string[];
+  /** Who ran the suite and against what — fills Test Executor / Test Environment on rows that
+   *  ran (#850). Absent when the caller has no run context (gates-only paths). */
+  runEnv?: import('../run-environment').RunEnvironment;
 }
 
 /** Complexity warning threshold (rules draft Gate I; raised for compact grouping) — echoed in the manifest. */

package/src/exporters/matrix/wording.ts

@@ -13,6 +13,8 @@
  *   Action → action, Observable → expected, Oracle → verification method.
  */
 
+import { extractUnlabeledOracle, onlyPresenceAssertions } from '../manual-hybrid-oracle';
+
 /** A step that CAPTURES a runtime value: `User remember [X] text as {{var}}`. */
 export const RUNTIME_CAPTURE = /\bremember\b/i;
 
@@ -40,8 +42,25 @@ export function runtimeVarsOf(stepTexts: string[], tags: string[]): Set<string>
 }
 
 // `[Email] field` → `Email field` (the visible label + its element type).
+// Only the DSL's own refs: a `"quoted literal"` and a `{{token}}` are data, so their
+// brackets stay (#772) — `"[DRAFT] report"`, `{{q.rows[0].id}}`. Callers render BEFORE
+// substituting values, so a value's brackets (`^[A-Za-z]{3}`) never reach this.
+// A literal opens only where a word does not end: in free text (manual procedures) `5"`
+// is an inch mark, and two of them must not shield the `[Ref]` between them.
 function deRef(text: string): string {
-  return text.replace(/\[([^\]]+)\]/g, '$1');
+  return text.replace(/(?<![\p{L}\p{N}])"[^"]*"|\{\{[^}]*\}\}|\[([^\]]+)\]/gu, (m, ref?: string) => ref ?? m);
+}
+
+/**
+ * Finish a cell rendered with `{{tokens}}` still in it, once the values are substituted
+ * (#772: render first, substitute after, so deRef never sees a value). Keeps what
+ * `sentence()` did when values went in first: a leading value is capitalised, and a
+ * value that already ends a sentence does not gain a second mark (`value..`).
+ */
+export function afterSubstitution(text: string): string {
+  if (!text) return text;
+  const s = text.charAt(0).toUpperCase() + text.slice(1);
+  return s.replace(/([.!?…"])\.$/, '$1');
 }
 
 function sentence(text: string): string {
@@ -115,7 +134,15 @@ export function renderExpected(raw: string): string {
   if (RUNTIME_CAPTURE.test(raw) && /\bas\s+\{\{/.test(raw)) return renderAction(raw);
   let s = raw.trim().replace(/^(User|The user)\s+/i, '');
 
+  // `table match data:` rows (folded in by feature-parser, #771) are the EXPECTED VALUES —
+  // `[E2E-01] Q1` is data, not a ref — so only the table's own ref is de-ref'd (#772).
+  const md = s.match(/^sees? \[([^\]]+)\]\s*table match(?:es)? data: (.+)$/i);
+  if (md) return sentence(`The ${md[1]} table shows these rows: ${md[2]}`);
+
   const rules: Array<[RegExp, (m: RegExpMatchArray) => string]> = [
+    // tab order: (#771) row 1 is the focused origin, each later row is one Tab press —
+    // its cells ARE refs, so they are de-ref'd like any step's.
+    [/^sees? tab order: (.+)$/i, (m) => `Pressing Tab moves focus in this order: ${m[1]}`],
     // expect A is (not) B — comparing two captured values (order matters: "is not" first)
     [/^expects? (.+?) is not (.+)$/i, (m) => `${m[1]} differs from ${m[2]}`],
     [/^expects? (.+?) is (.+)$/i, (m) => `${m[1]} equals ${m[2]}`],
@@ -204,7 +231,7 @@ export interface ManualProcedure {
  * 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 {
+export function classifyManualComments(comments: string[], thenTexts: string[] = []): ManualProcedure {
   const out: ManualProcedure = { preconditions: [], actions: [], expected: [], verification: [] };
   let last: { list: string[]; idx: number } | null = null;
 
@@ -230,5 +257,12 @@ export function classifyManualComments(comments: string[]): ManualProcedure {
       last.list[last.idx] += ' ' + line;
     }
   }
+  // #810 — an oracle written as unlabelled `Tester verifies:` prose is still the oracle: with no
+  // labelled Observable line and no Then beyond presence (`thenTexts`), export it rather than fall
+  // back to a presence-placeholder Then. A real Then stays the oracle.
+  if (!out.expected.length && onlyPresenceAssertions(thenTexts)) {
+    const prose = extractUnlabeledOracle(comments);
+    if (prose) out.expected.push(prose);
+  }
   return out;
 }

package/src/exporters/run-environment.ts

@@ -0,0 +1,89 @@
+/**
+ * Who ran the tests, and against what — the Test Executor / Test Environment columns of every
+ * deliverable (legacy workbook, matrix workbook) and the dashboard.
+ *
+ * One module so the surfaces cannot drift: the matrix format shipped with both cells hard-coded
+ * blank on every Auto row while the legacy exporter filled them (#850).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import { resolveWebBaseUrl } from './env-qa';
+import { statusToTestResult } from './playwright-report-parser';
+import { EnvironmentInfo, PlaywrightResult } from './types';
+
+/**
+ * The executor, most explicit source first: `SUNGEN_EXECUTOR` (a CI job names the person or
+ * pipeline that ran the suite — whoever runs `sungen delivery` there is not that person), then
+ * git user.name, then `CI_USER` / `USER`.
+ */
+export function resolveExecutor(cwd: string): string {
+  const explicit = process.env.SUNGEN_EXECUTOR?.trim();
+  if (explicit) return explicit;
+  try {
+    const gitUser = execSync('git config user.name', { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (gitUser) return gitUser;
+  } catch { /* not a git checkout, or no user.name */ }
+  return process.env.CI_USER || process.env.USER || '';
+}
+
+/** baseURL + browser project from playwright.config.ts, executor from {@link resolveExecutor}. */
+export function getEnvironment(cwd: string): EnvironmentInfo {
+  let baseURL = '';
+  let projectName = 'chromium';
+  const configPath = path.join(cwd, 'playwright.config.ts');
+  if (fs.existsSync(configPath)) {
+    const c = fs.readFileSync(configPath, 'utf-8');
+    // Every config shape sungen has scaffolded: the literal `baseURL: 'x'`, the env-aware
+    // `baseURL: resolveBaseUrl('x')`, and the older `baseURL: process.env.SUNGEN_BASE_URL || 'x'`
+    // (the quoted value is the static fallback in both wrappers).
+    const baseMatch = c.match(/baseURL:\s*(?:resolveBaseUrl\(\s*|process\.env\.\w+\s*\|\|\s*)?['"]([^'"]+)['"]/);
+    if (baseMatch) baseURL = baseMatch[1];
+    const projMatch = c.match(/name:\s*['"]([^'"]+)['"]/);
+    if (projMatch) projectName = projMatch[1];
+  }
+  // SUNGEN_BASE_URL (shell > .env.qa.<SUNGEN_ENV> > .env.qa) overrides the static
+  // value — the Test Environment column must show the host the run actually hit.
+  baseURL = resolveWebBaseUrl(cwd, baseURL);
+  return { baseURL, projectName, executor: resolveExecutor(cwd) };
+}
+
+/** `https://host/path (project)` — or, on mobile (no baseURL), the bare app id `(project)`. */
+export function formatEnv(baseURL: string, featurePath: string | undefined, projectName: string): string {
+  const base = (baseURL || '').replace(/\/+$/, '');
+  const p = (featurePath || '').replace(/^\/+/, '');
+  // Join with '/' only when there is a baseURL (web). For mobile baseURL is empty
+  // and `p` is an app id (e.g. com.kngroup.media.converter) — emit it bare, no '/'.
+  const url = base && p ? `${base}/${p}` : (p || base);
+  return `${url} (${projectName})`;
+}
+
+/**
+ * The platform a result file belongs to — `<f>-test-result.<os>[.<env>].json` → `<os>`. It names
+ * the run actually being read, so it outranks `MOBILE_PLATFORM` / `SUNGEN_ENV`, and SUNGEN_ENV
+ * is usually an environment (`staging`, `ja`), not an OS. A web locale file yields its locale,
+ * which is harmless: only a dual-id mobile `Path:` (`android | ios`) reads the platform.
+ */
+export function platformOfResultFile(resultsPath: string | null | undefined): string | undefined {
+  return resultsPath ? path.basename(resultsPath).match(/-test-result\.([^.]+)\./)?.[1] : undefined;
+}
+
+/** What a run-result row needs to fill its executor/environment cells. */
+export interface RunEnvironment extends EnvironmentInfo {
+  /** The unit's `Path:` (flows: their page selector; mobile: the OS-precise app id). */
+  featurePath?: string;
+}
+
+/**
+ * The Test Executor / Test Environment cells for one result — blank unless the test actually
+ * ran (a Pending or N/A row has nobody who executed it and no environment it ran against).
+ */
+export function runCells(env: RunEnvironment | undefined, result: PlaywrightResult | undefined): { executor: string; environment: string } {
+  if (!env || !result) return { executor: '', environment: '' };
+  const outcome = statusToTestResult(result.status);
+  if (outcome === 'Pending' || outcome === 'N/A') return { executor: '', environment: '' };
+  return {
+    executor: env.executor,
+    environment: formatEnv(env.baseURL, env.featurePath, result.projectName || env.projectName),
+  };
+}

package/src/exporters/scenario-merger.ts

@@ -11,6 +11,7 @@
 import { FeatureMetadata, OrderedStep, ScenarioMetadata, SpecFileData, SpecTest } from './types';
 import { isStepsBaseScenario, isSampleScaffoldScenario, extractTestcaseType } from './feature-parser';
 import { SCENARIO_ID } from './feature-parser';
+import { extractUnlabeledOracle, onlyPresenceAssertions } from './manual-hybrid-oracle';
 
 /**
  * Parse a @manual scenario's `# Tester verifies:` comment block into procedure vs
@@ -21,8 +22,12 @@ import { SCENARIO_ID } from './feature-parser';
  * (Setup/Action/Precondition/unlabelled) → Steps. A non-numbered line following a
  * numbered item is a continuation (e.g. a wrapped URL) and is appended to it. Pre-amble
  * lines (the `MANUAL:` rationale, the `Tester verifies:` header, separators) are ignored.
+ *
+ * `unlabeledOracle` is the prose a `Tester verifies:` header carries OUTSIDE numbered lines
+ * (#810). It is not part of `expected` — the gates judge the numbered shape — but the exporter
+ * must never drop it: when no labelled oracle line exists it becomes the Expected cell.
  */
-export function parseManualComments(comments: string[]): { steps: OrderedStep[]; expected: OrderedStep[] } {
+export function parseManualComments(comments: string[]): { steps: OrderedStep[]; expected: OrderedStep[]; unlabeledOracle: string | null } {
   const steps: OrderedStep[] = [];
   const expected: OrderedStep[] = [];
   let last: OrderedStep | null = null;
@@ -45,7 +50,31 @@ export function parseManualComments(comments: string[]): { steps: OrderedStep[];
     }
     // else: pre-amble before any numbered item (rationale / header) → skip
   }
-  return { steps, expected };
+  return { steps, expected, unlabeledOracle: extractUnlabeledOracle(comments) };
+}
+
+/**
+ * The reason a @manual scenario is manual — the text of its `# MANUAL…: <reason>` comment
+ * (`MANUAL:`, `MANUAL (2026-09-16, run-test):`, `MANUAL/ENV:` …) plus its indented continuation
+ * lines, up to the `Tester verifies:` header, a numbered item or a divider. '' when absent.
+ * Rendered in the deliverable's Note so a tester sees why the case is not automated (#810).
+ */
+export function extractManualReason(comments: string[]): string {
+  const parts: string[] = [];
+  let inReason = false;
+  for (const raw of comments) {
+    const line = raw.trim();
+    if (!inReason) {
+      const m = line.match(/^MANUAL\b[^:]*:\s*(.*)$/i);
+      if (m) { inReason = true; if (m[1].trim()) parts.push(m[1].trim()); }
+      continue;
+    }
+    // A wrapped reason continues on an INDENTED comment line (`#   automate once seeded.`); the
+    // comment list carries no line numbers, so an unindented line is a separate note, not more reason.
+    if (!line || !/^\s/.test(raw) || /^tester verifies\b/i.test(line) || /^\d+[.)]\s/.test(line) || /^[-=*_]{2,}/.test(line)) break;
+    parts.push(line);
+  }
+  return parts.join(' ').replace(/\s+/g, ' ').trim();
 }
 
 export interface MergedScenario {
@@ -84,6 +113,12 @@ export interface MergedScenario {
    * so counting them would falsely mark @manual scenarios as interleaved.
    */
   resolvedAnchorActionCount: number;
+  /**
+   * Set when this @manual scenario's oracle exists ONLY as unlabelled `Tester verifies:` prose
+   * (#810). The prose is exported verbatim into `resolvedExpected`; delivery warns so the author
+   * rewrites it as numbered `Observable:` lines.
+   */
+  unlabeledManualOracle?: string;
 }
 
 /**
@@ -147,7 +182,16 @@ export function mergeFeatureAndSpec(
     const manualParsed =
       extractTestcaseType(scenario.tags) === 'Manual' && scenario.comments?.length
         ? parseManualComments(scenario.comments)
-        : { steps: [] as OrderedStep[], expected: [] as OrderedStep[] };
+        : { steps: [] as OrderedStep[], expected: [] as OrderedStep[], unlabeledOracle: null };
+    // Never drop a manual oracle (#810): with no labelled Observable/Oracle line and no Then that
+    // checks more than presence, the unlabelled `Tester verifies:` prose IS what the case checks —
+    // export it rather than let a presence placeholder stand in for it. A real Then keeps the cell.
+    const unlabeledOracle = !manualParsed.expected.length && onlyPresenceAssertions(ownAssertions.map((s) => s.text))
+      ? manualParsed.unlabeledOracle
+      : null;
+    const manualExpected: OrderedStep[] = unlabeledOracle
+      ? [{ text: unlabeledOracle, bucket: 'then' }]
+      : manualParsed.expected;
 
     result.push({
       feature: scenario,
@@ -158,8 +202,9 @@ export function mergeFeatureAndSpec(
         ...ownActions,
         ...manualParsed.steps,
       ],
-      resolvedExpected: [...ownAssertions, ...manualParsed.expected],
+      resolvedExpected: [...ownAssertions, ...manualExpected],
       resolvedAnchorActionCount: baseLen + ownActions.length,
+      ...(unlabeledOracle ? { unlabeledManualOracle: unlabeledOracle } : {}),
     });
   }
 

package/src/exporters/test-data-resolver.ts

@@ -190,9 +190,3 @@ export function renderDynamicTokens(text: string): string {
   });
 }
 
-/**
- * Resolve the test-data file path for a given screen.
- */
-export function resolveTestDataPath(cwd: string, screen: string): string {
-  return path.join(cwd, 'qa', 'screens', screen, 'test-data', `${screen}.yaml`);
-}

package/src/exporters/xlsx-exporter.ts

@@ -113,15 +113,20 @@ export function buildApiDetailRows(
  * used by the multi-locale delivery aggregator. Pass `null` / empty string
  * to force the base (no suffix) variant.
  */
+/** Where `writeXlsx` puts a unit's workbook — shared so a reader targets the identical file. */
+export function deliverableXlsxPath(cwd: string, screen: string, locale?: string | null): string {
+  return path.join(cwd, 'qa', 'deliverables', `${deliverableBasename(screen, locale)}.xlsx`);
+}
+
 export async function writeXlsx(
   cwd: string,
   screen: string,
   wb: ExcelJS.Workbook,
   locale?: string | null,
 ): Promise<string> {
-  const outDir = path.join(cwd, 'qa', 'deliverables');
+  const outPath = deliverableXlsxPath(cwd, screen, locale);
+  const outDir = path.dirname(outPath);
   if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
-  const outPath = path.join(outDir, `${deliverableBasename(screen, locale)}.xlsx`);
   const buffer = await wb.xlsx.writeBuffer();
   const locked = await lockEmbeddedImages(Buffer.from(buffer as ArrayBuffer));
   fs.writeFileSync(outPath, locked);