@sun-asterisk/sungen 3.2.32 → 3.2.34-beta.1

package/src/exporters/matrix/build.ts

@@ -19,7 +19,7 @@ import {
 import { getCasesDatasetRows, resolveResultVariants } from '../result-variants';
 import { renderDynamicTokens } from '../test-data-resolver';
 import { maskCredentialValue } from '../sensitive-key';
-import { classifyManualComments, renderAction, renderExpected, renderPrecondition, renderSetupInstruction, runtimeVarsOf } from './wording';
+import { afterSubstitution, classifyManualComments, renderAction, renderExpected, renderPrecondition, renderSetupInstruction, runtimeVarsOf } from './wording';
 import { scenarioFingerprint, combinedFingerprint, mapContentFingerprint } from './fingerprint';
 import {
   CoverageVariant,
@@ -96,6 +96,7 @@ function resolveDataPairs(
   vars: string[],
   testData: Record<string, string> | null,
   row?: Record<string, unknown>,
+  runtimeVars: Set<string> = new Set(),
 ): string[] {
   const pairs: string[] = [];
   if (row) {
@@ -107,7 +108,10 @@ function resolveDataPairs(
   for (const v of vars) {
     const val = row && v in row ? undefined : testData?.[v]; // row columns already listed
     // Credential-named refs (`accounts.0.password`) render `***` — this column is read outside the run.
-    if (val !== undefined) pairs.push(`${v}: ${displayValue(maskCredentialValue(v, val))}`);
+    // A value may embed a var the scenario captures at run time (`Total ({{stat}})`) or a
+    // dataset column — expanded with the same vars as the cells, so both columns agree (#879).
+    const scope = row ? { ...(testData ?? {}), ...rowAsStrings(row) } : (testData ?? {});
+    if (val !== undefined) pairs.push(`${v}: ${displayValue(maskCredentialValue(v, expandValue(String(val), scope, runtimeVars, new Set([v]))))}`);
   }
   return pairs;
 }
@@ -136,6 +140,10 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
   // 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);
+  // Display cells expand from the RAW values, per scenario — with its row and its runtime vars —
+  // in the runtime's order (captured var > row column > test-data key). The pre-resolved copy above
+  // only serves row discovery and result matching, which render nothing (#879).
+  const rawTestData = inputs.testData ?? {};
   const apiCatalog = inputs.apiCatalog ?? {};
   const variants: CoverageVariant[] = [];
 
@@ -158,11 +166,14 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
     // 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
-      ? classifyManualComments(m.feature.comments)
+      ? classifyManualComments(m.feature.comments, bucketTexts(m.feature.orderedSteps, 'then'))
       : null;
 
     // Raw (pre-wording) step texts — these feed shapes + Gate C, never the cells.
-    const rawTrigger = manual ? manual.actions : bucketTexts(m.feature.orderedSteps, 'when');
+    // A manual with no numbered action lines keeps its Gherkin When steps as the trigger — the
+    // same fallback the oracle uses for Then. Taking comment actions only rendered "No action —
+    // the state is checked on page load." for a manual whose When clicks something (#810).
+    const rawTrigger = manual && manual.actions.length > 0 ? manual.actions : bucketTexts(m.feature.orderedSteps, 'when');
     const rawOracle = manual
       ? (manual.expected.length > 0 ? manual.expected : bucketTexts(m.feature.orderedSteps, 'then'))
       : m.resolvedExpected.filter((s) => s.bucket === 'then').map((s) => s.text);
@@ -251,10 +262,16 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
       verification: manual?.verification.map((t) => sentenceOf(t)) ?? [],
     };
 
-    /** Render the display cells for one data context (vars resolved first). */
+    /**
+     * Render the display cells for one data context. Steps are worded FIRST and values
+     * substituted AFTER (#772): wording strips the DSL's `[Ref]` brackets, and a value
+     * such as `^[A-Za-z]{3}` or `[E2E-01] title` must never be mistaken for one.
+     * Preconditions (rendered at build time above) already went in this order.
+     */
     const renderCells = (vars: Record<string, string>): { trigger: string[]; oracle: string[]; precondition: string[]; verification: string[] } => {
       const sub = (s: string): string => substituteDisplayVars(s, vars, runtimeVars);
-      const preconditionOut = precondition.map(sub);
+      const fill = (rendered: string): string => afterSubstitution(sub(rendered));
+      const preconditionOut = precondition.map(fill);
       const verificationOut = base.verification.map(sub);
       if (procedureProfile === 'sequence' && !manual) {
         // Ordered flow (review B-03): keep the event order — actions stay numbered in
@@ -266,9 +283,9 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
         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)));
+          if (i > lastActionIdx) oracle.push(fill(renderExpected(s.text)));           // trailing Then block
+          else if (s.bucket === 'then') trigger.push(`Verify: ${fill(renderExpected(s.text))}`);
+          else if (s.bucket === 'when') trigger.push(fill(renderAction(s.text)));
           // leading given steps already live in the precondition
         });
         return { trigger, oracle, precondition: preconditionOut, verification: verificationOut };
@@ -277,8 +294,8 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
       // Method/API/Header/Body lines are already reader-facing, not step DSL).
       const trigger = apiCallsAreTrigger
         ? apiRequestLines.map(sub)
-        : rawTrigger.map((s) => renderAction(sub(s)));
-      const oracle = rawOracle.map((s) => renderExpected(sub(s)));
+        : rawTrigger.map((s) => fill(renderAction(s)));
+      const oracle = rawOracle.map((s) => fill(renderExpected(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).
@@ -296,14 +313,14 @@ 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) });
+        const cells = renderCells({ ...rawTestData, ...rowAsStrings(row) });
         variants.push({
           ...base,
           ref: `${vpId}#${label}`,
           caseLabel: label,
           title: `${category1} — ${label}`,
           condition: label,
-          data: resolveDataPairs(m.feature.referencedVars, testData, row),
+          data: resolveDataPairs(m.feature.referencedVars, rawTestData, row, runtimeVars),
           trigger: cells.trigger,
           oracle: cells.oracle,
           precondition: cells.precondition,
@@ -313,13 +330,13 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
         });
       });
     } else {
-      const cells = renderCells(testData ?? {});
+      const cells = renderCells(rawTestData);
       variants.push({
         ...base,
         ref: vpId,
         title: category1,
         condition: category1,
-        data: resolveDataPairs(m.feature.referencedVars, testData),
+        data: resolveDataPairs(m.feature.referencedVars, rawTestData, undefined, runtimeVars),
         trigger: cells.trigger,
         oracle: cells.oracle,
         precondition: cells.precondition,
@@ -351,9 +368,9 @@ function substituteDisplayVars(
     if (isCapture && /\bas\s+$/i.test(text.slice(0, offset))) return m;
     // A value the test produces at run time has no static form — name it so the
     // tester knows to compare against what the earlier step captured.
-    if (runtimeVars.has(key) || runtimeVars.has(key.split(/[.[]/)[0])) return `the captured ${key}`;
+    if (isRuntimeVar(key, runtimeVars)) return `the captured ${key}`;
     if (!(key in vars)) return m; // unknown stays literal → Gate D flags it
-    return displayValue(vars[key]);
+    return displayValue(expandValue(vars[key], vars, runtimeVars, new Set([key])));
   });
   // A dynamic token written straight into a step (`{{$uuid}}`) never reaches
   // displayValue — name it here so the same wording covers both routes.
@@ -423,12 +440,45 @@ export function computeRequirements(
   });
 }
 
-/** Resolve one level of {{key}} cross-references inside test-data VALUES. */
+const isRuntimeVar = (key: string, runtimeVars: Set<string>): boolean =>
+  runtimeVars.has(key) || runtimeVars.has(key.split(/[.[]/)[0]);
+
+/**
+ * Expand the `{{refs}}` inside a test-data VALUE the way the runtime's `interpolate()` does
+ * (specs/generated/test-data.ts): recursively, depth-capped against reference cycles, and a var
+ * the scenario captures at run time is named, not looked up. An unknown ref (or a cycle) stays
+ * literal, so Gate D still refuses it; a nested value renders through displayValue, as it did
+ * when this resolved one level (an empty one reads `(empty)`).
+ *
+ * Delivery used to resolve ONE level, before any scenario's runtime vars were known: both
+ * `heading_expected: "Total ({{stat}})"` with `remember … as {{stat}}`, and a plain chain
+ * (`a: "{{b}}"`, `b: "x {{c}}"`), left a token that blocked the export of a suite the runtime
+ * runs fine (#879).
+ */
+function expandValue(
+  value: string, vars: Record<string, string>, runtimeVars: Set<string>,
+  expanding: ReadonlySet<string> = new Set(), depth = 0,
+): string {
+  if (depth > 10 || !value.includes('{{')) return value;
+  return value.replace(/\{\{\s*([^}\s]+)\s*\}\}/g, (m, key: string) => {
+    if (isRuntimeVar(key, runtimeVars)) return `the captured ${key}`;
+    const v = vars[key];
+    // A key already being expanded is a cycle: keep the token (Gate D names it) instead of
+    // re-entering — `a: "{{a}}{{a}}"` doubled per level and exhausted the heap.
+    if (v === undefined || v === null || expanding.has(key)) return m;
+    return displayValue(expandValue(String(v), vars, runtimeVars, new Set([...expanding, key]), depth + 1));
+  });
+}
+
+/**
+ * Pre-resolve test-data cross-references before any scenario is known — every static level.
+ * A runtime var is not known yet and stays a token here; each scenario's cells expand it.
+ */
 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;
+    out[k] = typeof v === 'string' && v.includes('{{') ? renderDynamicTokens(expandValue(v, testData, new Set(), new Set([k]))) : v;
   }
   return out;
 }
@@ -454,6 +504,7 @@ function rowAsStrings(row: Record<string, unknown>): Record<string, string> {
  * as blocked), which silently skewed the derived parent result.
  */
 export function variantState(v: CoverageVariant): VariantState {
+  if (v.manualState) return v.manualState;   // a carried Manual result (#891)
   const r = v.result;
   if (!r) return 'Pending';
   switch (r.status) {
@@ -587,6 +638,7 @@ export function buildMatrix(inputs: BuildInputs): MatrixModel {
         [v.ref, v.precondition.filter((line) => !commonPre.includes(line))])),
       triggerDeltas: Object.fromEntries(groupVariants.map((v) =>
         [v.ref, v.trigger.slice(prefixLen)])),
+      sharedTriggerSteps: prefixLen,
       // Nothing shared to hoist → say what varies rather than leaving the cell blank.
       trigger: prefixLen > 0 || groupVariants.length === 0
         ? (first?.trigger ?? []).slice(0, prefixLen)

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

@@ -0,0 +1,292 @@
+/**
+ * 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, VariantState } from './types';
+import { rollUp } from './build';
+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;
+}
+
+/**
+ * What happens to each Manual variant's prior row: `carry` its cells, or `reset` it to Pending
+ * because the procedure changed since the result was recorded. A row with nothing recorded has
+ * no entry. The ONE decision both the model (totals, #891) and the workbook cells read.
+ */
+export function planManualCarry(model: MatrixModel, prior: PriorManualResults | null): Map<string, 'carry' | 'reset'> {
+  const plan = new Map<string, 'carry' | 'reset'>();
+  if (!prior) return plan;
+  for (const v of model.items.flatMap((i) => i.variants)) {
+    if (v.mode !== 'manual') continue;
+    const before = prior.rows.get(v.ref);
+    if (!before || isUntouched(before.cells)) continue;
+    const stamped = prior.stamps?.get(v.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));
+    plan.set(v.ref, stamped !== undefined && stamped !== v.fingerprint && hasResult ? 'reset' : 'carry');
+  }
+  return plan;
+}
+
+/** A typed Result → its state word, case-insensitively (Excel's COUNTIF ignores case too). */
+const STATE_BY_LOWER = new Map<string, VariantState>(
+  (['Passed', 'Failed', 'Blocked', 'Pending', 'N/A'] as VariantState[]).map((s) => [s.toLowerCase(), s]),
+);
+
+/**
+ * Put the carried Manual results into the MODEL, before anything is rendered or counted.
+ *
+ * The workbook's totals, Overview and group roll-ups are formulas with a cached result computed
+ * from the model, and the CSV and the CLI summary read the model too. Carrying only the cells
+ * after rendering left all of them counting the recorded Manual results as Pending: a preview
+ * of the file, and the CLI, reported "5 Pending" for cases the tester had run (#891).
+ * A reset row counts as Pending, as its cell reads. A Result that is not a state word (a tester's
+ * "OK") counts as Pending too; the cell keeps the text, and its date still reaches the CSV.
+ * Idempotent: every Manual variant's carried fields are cleared first, so the result depends only
+ * on `prior`.
+ */
+export function applyManualCarry(model: MatrixModel, prior: PriorManualResults | null): void {
+  const plan = planManualCarry(model, prior);
+  for (const item of model.items) {
+    let touched = false;
+    for (const v of item.variants) {
+      if (v.mode !== 'manual') continue;
+      if (v.manualState !== undefined || v.manualDate !== undefined) touched = true;
+      delete v.manualState;
+      delete v.manualDate;
+      const decision = plan.get(v.ref);
+      if (!decision) continue;
+      touched = true;
+      if (decision === 'reset') { v.manualState = 'Pending'; continue; }
+      const [result, date] = prior!.rows.get(v.ref)!.cells.map((c) => cellText(c.value));
+      if (date) v.manualDate = date;
+      v.manualState = STATE_BY_LOWER.get(result.toLowerCase()) ?? 'Pending';
+    }
+    if (touched) {
+      const { result, counts } = rollUp(item.variants);
+      item.result = result;
+      item.resultCounts = counts;
+    }
+  }
+}
+
+/**
+ * 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 plan = planManualCarry(model, prior);
+  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);
+      const decision = plan.get(ref);
+      if (!decision) continue;
+
+      const stamped = prior.stamps?.get(ref);
+      if (decision === 'reset') {
+        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,9 @@ 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 { applyManualCarry, carryManualResults, ManualCarryReport, PriorManualResults, readPriorManualResults } from './carry-manual-results';
+export { readPriorManualResults } from './carry-manual-results';
 import { loadPerfConfig, perfVerdict } from '../../harness/perf';
 import { loadDeliveryMap, writeDeliveryMap } from './map-loader';
 import { mapContentFingerprint } from './fingerprint';
@@ -25,6 +27,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 +48,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 +95,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 +169,27 @@ export async function writeMatrixDeliverables(
   paths: MatrixTargetPaths,
   model: MatrixModel,
   format: MatrixFormat = 'xlsx',
-): Promise<{ csvPath?: string; xlsxPath?: string }> {
-  const out: { csvPath?: string; xlsxPath?: string } = {};
+  /** The prior workbook's Manual results, when the caller already read them; read here if absent. */
+  priorRead?: PriorManualResults | null,
+): 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.
+  // A CSV-only export overwrites no workbook, so an unreadable one is no reason to refuse it — but a
+  // readable one still holds the Manual results the CSV should show.
+  const prior = priorRead !== undefined ? priorRead
+    : xlsx ? await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit))
+      : await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit)).catch(() => null);
+  // Into the model first: the CSV, every cached total and roll-up, and the caller's summary
+  // all read it (#891).
+  applyManualCarry(model, prior);
   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-csv.ts

@@ -78,7 +78,7 @@ export function renderMatrixCsv(model: MatrixModel): string {
         v.mode === 'manual' ? 'Manual' : 'Auto',
         v.traces.join(' '),
         variantState(v),
-        isoDate(v.result?.startTime),
+        v.manualDate ?? isoDate(v.result?.startTime),
         // Redact BEFORE clipping — a clip boundary must never split a secret in
         // a way that lets its prefix through. Same denylist as the Note column.
         v.result?.error ? clipNoteField(redactSecrets(String(v.result.error), model.secretValues)) : '',

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/render-xlsx.ts

@@ -74,6 +74,9 @@ export function projectItems(model: MatrixModel, mode: 'auto' | 'manual'): Deliv
 
 export function renderMatrixXlsx(model: MatrixModel, sungenVersion?: string): ExcelJS.Workbook {
   const wb = new ExcelJS.Workbook();
+  // Every total and roll-up is a formula with a cached result. The cache is what a preview
+  // (GitHub, Drive, QuickLook) shows; a spreadsheet app recomputes on open as well (#891).
+  wb.calcProperties.fullCalcOnLoad = true;
   const sheets: SheetProjection[] = [
     { sheetName: 'Auto', items: projectItems(model, 'auto') },
     { sheetName: 'Manual', items: projectItems(model, 'manual') },