@sun-asterisk/sungen 3.2.34 → 3.2.35

package/src/cli/commands/audit.ts

@@ -180,7 +180,7 @@ export function registerAuditCommand(program: Command): void {
         const dir = findUnitDir(name);
         if (!dir) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
 
-        const report = runAudit(dir, name);
+        let report = runAudit(dir, name);
 
         // The baseline is only ever written HERE, never by the measurement itself:
         // a first sighting has nothing to compare against, and any later change is
@@ -201,9 +201,14 @@ export function registerAuditCommand(program: Command): void {
         if (vb.reparsed) acceptViewpointBaseline(process.cwd(), unitId, { hash: vb.hash, ids: vb.ids, fileHash: vb.fileHash });
         if ((vb.status === 'new' && !postHoc) || (options.acceptViewpoint && (vb.status === 'changed' || postHoc))) {
           acceptViewpointBaseline(process.cwd(), unitId, { hash: vb.hash, ids: vb.ids, fileHash: vb.fileHash });
-          if (options.acceptViewpoint && !options.json) {
-            console.log(`\n  ✓ test-viewpoint.md accepted as the baseline for ${name} (${vb.ids.length} viewpoint id(s)).`);
-            console.log('    Re-run the audit to score atomicLedger + traceability against it.\n');
+          if (options.acceptViewpoint) {
+            // Measure again against what was just accepted: the report printed and saved below (the
+            // one `sungen next` reads) must not be the pre-accept one, still holding the axes (#867).
+            report = runAudit(dir, name);
+            if (!options.json) {
+              console.log(`\n  ✓ test-viewpoint.md accepted as the baseline for ${name} (${vb.ids.length} viewpoint id(s)).`);
+              console.log('    The report below is measured against it.\n');
+            }
           }
         } else if (options.acceptViewpoint && !options.json) {
           // `absent` covers a file with no readable viewpoint id too — say which (#832).

package/src/cli/commands/capability.ts

@@ -265,7 +265,9 @@ export function registerCapabilityCommand(program: Command): void {
           else console.log('  – skipped  appium-environment/ (already exists)');
 
           // Best-effort driver install — non-fatal so capability add still succeeds offline.
-          installMobileDriver(cwd);
+          // --skip-install promises no npm install; the driver + wdio/appium runtime is ~290 MB.
+          if (o.skipInstall) console.log('  – skipped  mobile driver install (--skip-install) — later: sungen capability add mobile');
+          else installMobileDriver(cwd);
 
           // --skip-install means "record only" — then provisioning the machine is not wanted either.
           runAppiumEnvironmentSetup(cwd, { skip: !!(o.skipEnvSetup || o.skipInstall) });

package/src/cli/commands/defect.ts

@@ -0,0 +1,49 @@
+import { Command } from 'commander';
+import { resolveUnit } from '../resolve-unit';
+import { draftDefects } from '../../harness/defect-draft';
+import { readDefects } from '../../harness/defects';
+
+/**
+ * `sungen defect draft|list` — defect records under qa/defects/ (see harness/defects.ts).
+ * `draft` writes one record per product-candidate row of the unit's last `sungen triage`.
+ */
+export function registerDefectCommand(program: Command): void {
+  const defect = program.command('defect').description('Draft and list defect records (qa/defects/DEF-NNN-*.md) from red scenarios');
+
+  defect
+    .command('draft')
+    .description('Draft a defect record for each product-candidate row of the last `sungen triage`')
+    .option('-s, --screen <name>', 'Screen or flow name')
+    .option('--api <name>', 'API-first area or api flow (qa/api/<name>)')
+    .option('--scenario <title|id>', 'Only the scenario whose title contains this text, or that carries this VP id')
+    .option('--json', 'Output raw JSON')
+    .action((o: { screen?: string; api?: string; scenario?: string; json?: boolean }) => {
+      try {
+        const name = o.screen || o.api;
+        if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
+        const unit = resolveUnit(name, process.cwd());
+        if (!unit) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
+        const r = draftDefects(process.cwd(), unit, { scenario: o.scenario });
+        if (o.json) { console.log(JSON.stringify(r, null, 2)); return; }
+        if (r.missingTriage) { console.log(`\n  ${name}: no triage yet — run \`sungen triage --screen ${name}\` after the tests.\n`); return; }
+        for (const f of r.written) console.log(`  ✎ ${f}`);
+        for (const s of r.skipped) console.log(`  ○ already recorded as ${s.id}: ${s.scenario}`);
+        if (!r.written.length && !r.skipped.length) console.log(`  ✓ ${name}: no product-candidate rows to draft.`);
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+      }
+    });
+
+  defect
+    .command('list')
+    .description('List defect records (id, severity, status, units, scenario count)')
+    .option('--status <status>', 'Only records with this status (open, fixed, verified, closed, wont-fix)')
+    .option('--json', 'Output raw JSON')
+    .action((o: { status?: string; json?: boolean }) => {
+      const rows = readDefects(process.cwd()).filter((r) => !o.status || r.status === o.status);
+      if (o.json) { console.log(JSON.stringify(rows, null, 2)); return; }
+      if (!rows.length) { console.log('  (no defect records)'); return; }
+      for (const r of rows) console.log(`  ${r.id}  ${r.severity.padEnd(8)} ${r.status.padEnd(9)} ${r.units.join(',')}  ${r.scenarios.length} scenario(s)  ${r.title}`);
+    });
+}

package/src/cli/commands/delivery.ts

@@ -7,7 +7,7 @@ import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
 import { parse as parseYaml } from 'yaml';
-import { parseFeatureMetadata } from '../../exporters/feature-parser';
+import { isHookScenario, parseFeatureMetadata } from '../../exporters/feature-parser';
 import { parseSpecFile } from '../../exporters/spec-parser';
 import { loadTestData } from '../../exporters/test-data-resolver';
 import { loadSelectorKeyMap } from '../../exporters/selector-key-resolver';
@@ -20,7 +20,7 @@ import {
   renderCsv,
   writeCsv,
 } from '../../exporters/csv-exporter';
-import { renderXlsxMultiSheet, writeXlsx, buildApiDetailRows, addApiDetailSheet } from '../../exporters/xlsx-exporter';
+import { renderXlsxMultiSheet, writeXlsx, buildApiDetailRows, addApiDetailSheet, deliverableXlsxPath } from '../../exporters/xlsx-exporter';
 import { loadApiCatalog } from '../../exporters/api-catalog-loader';
 import { resolveApiEnvironment } from '../../exporters/api-environment';
 import { getEnvironment, platformOfResultFile, RunEnvironment } from '../../exporters/run-environment';
@@ -38,7 +38,7 @@ import {
   hasReview,
 } from '../../exporters/matrix/export';
 import { MatrixFinding } from '../../exporters/matrix/types';
-import { ManualCarryReport } from '../../exporters/matrix/carry-manual-results';
+import { applyManualCarry, ManualCarryReport, PriorManualResults, readPriorManualResults } from '../../exporters/matrix/carry-manual-results';
 import { formatTestOutcome, resultTotals } from '../../exporters/matrix/result-totals';
 import { readCapabilities } from '../../harness/capability';
 
@@ -85,6 +85,12 @@ export interface DeliveryTarget {
   isFlow: boolean;
 }
 
+/** The command that regenerates a target's unit — flag by kind, the unit (not feature) name. */
+function generateCommandFor(target: DeliveryTarget): string {
+  const flag = target.kind === 'flow' ? '--flow' : target.kind === 'api' ? '--api' : '--screen';
+  return `sungen generate ${flag} ${target.screen}`;
+}
+
 function makeTarget(screen: string, featureBaseName: string, kind: UnitKind): DeliveryTarget {
   return { screen, featureBaseName, name: featureBaseName, kind, isFlow: kind === 'flow' };
 }
@@ -464,6 +470,7 @@ async function exportTarget(
       if (isMobileProject(cwd)) removeBaseDeliverables(cwd, target.featureBaseName);
       const rows = buildTestCaseRows({
         screen: label,
+        generateCommand: generateCommandFor(target),
         featureName: feature.featureName,
         // OS-precise env column: a mobile dual-id Path resolves to just the
         // android package / ios bundle id for SUNGEN_ENV=android|ios.
@@ -522,6 +529,7 @@ async function exportTarget(
         for (const variant of osVariants) {
           const variantRows = buildTestCaseRows({
             screen: label,
+            generateCommand: generateCommandFor(target),
             featureName: feature.featureName,
             featurePath: resolvePlatformAppId(featurePath, variant.locale), // OS-precise app id
             merged,
@@ -574,6 +582,7 @@ async function exportTarget(
       const variantResults = variant.resultsPath ? loadPlaywrightReport(variant.resultsPath) : null;
       const variantRows = buildTestCaseRows({
         screen: label,
+        generateCommand: generateCommandFor(target),
         featureName: feature.featureName,
         // No-op for web (URL Path); for a mobile fall-through (a no-suffix result
         // json) this collapses the dual-id to the android package so the combined
@@ -685,9 +694,11 @@ async function exportMatrixTarget(
   // probes that are, by contract, outside the official suite.
   {
     const featureMeta = parseFeatureMetadata(paths.featureFile);
-    const deliverable = featureMeta.scenarios.filter((s) => !s.tags.some((t) => /^@exploration\b/i.test(t)));
-    if (featureMeta.scenarios.length > 0 && deliverable.length === 0) {
-      log(`${COLOR.gray}${paths.label}: nothing to deliver — all ${featureMeta.scenarios.length} scenario(s) are @exploration probes (outside the official suite).${COLOR.reset}`);
+    // Hooks are setup/teardown, never test cases — they neither need nor make a deliverable (#880).
+    const scenarios = featureMeta.scenarios.filter((s) => !isHookScenario(s));
+    const deliverable = scenarios.filter((s) => !s.tags.some((t) => /^@exploration\b/i.test(t)));
+    if (scenarios.length > 0 && deliverable.length === 0) {
+      log(`${COLOR.gray}${paths.label}: nothing to deliver — all ${scenarios.length} scenario(s) are @exploration probes (outside the official suite).${COLOR.reset}`);
       return 'skipped';
     }
   }
@@ -707,6 +718,17 @@ async function exportMatrixTarget(
     return null;
   }
 
+  // The tester's recorded Manual results are part of the outcome: read them BEFORE anything is
+  // counted, so this line, the workbook's totals and the summary table all agree (#891). A file
+  // that cannot be read is reported where it matters — when it would be overwritten.
+  const format = opts.format ?? 'xlsx';
+  let prior: PriorManualResults | null = null;
+  let priorError: Error | null = null;
+  try { prior = await readPriorManualResults(deliverableXlsxPath(cwd, paths.unit)); }
+  // A CSV-only export overwrites no workbook, so an unreadable one only means "nothing to carry".
+  catch (e) { if (format !== 'csv') priorError = e as Error; }
+  applyManualCarry(model, prior);
+
   log(`${COLOR.bold}${paths.label}${COLOR.reset} — ${model.manifest.itemCount} delivery item(s), ${model.manifest.variantCount} coverage variant(s), review: ${model.manifest.approvalState} (design), test outcome: ${formatTestOutcome(resultTotals(model.items))}`);
   {
     const mocked = model.items.flatMap((it) => it.variants.filter((v) => v.mocked));
@@ -741,7 +763,8 @@ async function exportMatrixTarget(
 
   let deliverables: Awaited<ReturnType<typeof writeMatrixDeliverables>>;
   try {
-    deliverables = await writeMatrixDeliverables(paths, model, opts.format ?? 'xlsx');
+    if (priorError) throw priorError;
+    deliverables = await writeMatrixDeliverables(paths, model, format, prior);
   } catch (e) {
     // The existing workbook could not be read, so writing would destroy its Manual results.
     log(`  ${COLOR.red}not written:${COLOR.reset} ${(e as Error).message}`);
@@ -981,9 +1004,9 @@ export function registerDeliveryCommand(program: Command): void {
               // Same contract as the export path: an all-@exploration feature has no
               // deliverable variants, so there is no map to approve — skip, not an error.
               {
-                const featureMeta = parseFeatureMetadata(paths.featureFile);
-                if (featureMeta.scenarios.length > 0
-                  && featureMeta.scenarios.every((s) => s.tags.some((t) => /^@exploration\b/i.test(t)))) {
+                const scenarios = parseFeatureMetadata(paths.featureFile).scenarios.filter((s) => !isHookScenario(s));
+                if (scenarios.length > 0
+                  && scenarios.every((s) => s.tags.some((t) => /^@exploration\b/i.test(t)))) {
                   log(`${COLOR.gray}${paths.label}: nothing to approve — all scenario(s) are @exploration probes.${COLOR.reset}`);
                   continue;
                 }

package/src/cli/commands/triage.ts

@@ -0,0 +1,57 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import { resolveUnit } from '../resolve-unit';
+import { triageUnit, writeTriageReport } from '../../harness/triage-unit';
+import type { TriageClass } from '../../harness/triage';
+
+/** Display order: what needs a decision first, green last. */
+const ORDER: TriageClass[] = ['product-candidate', 'unclassified', 'test-defect', 'environment', 'blocked-capability', 'known-defect', 'flaky'];
+
+/**
+ * `sungen triage` — classify every red or flaky scenario of the latest run (see harness/triage.ts).
+ * Reports, never gates: always exits 0 once the unit is found.
+ */
+export function registerTriageCommand(program: Command): void {
+  program
+    .command('triage')
+    .description('Classify each red or flaky scenario of the latest run: known-defect, blocked, environment, test-defect, product-candidate, unclassified')
+    .option('-s, --screen <name>', 'Screen or flow name')
+    .option('--api <name>', 'API-first area or api flow (qa/api/<name>)')
+    .option('--area <name>', 'Alias of --api')
+    .option('--json', 'Output the raw JSON report')
+    .action((o: { screen?: string; api?: string; area?: string; json?: boolean }) => {
+      try {
+        const name = o.screen || o.api || o.area;
+        if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
+        const cwd = process.cwd();
+        const unit = resolveUnit(name, cwd);
+        if (!unit) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
+
+        const report = triageUnit(cwd, unit);
+        if (report.resultFiles.length === 0) {
+          if (o.json) console.log(JSON.stringify(report, null, 2));
+          else console.log(`\n  ${name}: no results — run the tests first.\n`);
+          return;
+        }
+        const saved = writeTriageReport(cwd, report);
+        if (o.json) { console.log(JSON.stringify(report, null, 2)); return; }
+
+        const L = console.log;
+        L(`\n━━━ Triage: ${name} ━━━`);
+        if (report.rows.length === 0) L('  ✓ every scenario passed on its first attempt');
+        for (const cls of ORDER) {
+          const rows = report.rows.filter((r) => r.class === cls);
+          if (rows.length === 0) continue;
+          L(`\n  ${cls} (${rows.length})`);
+          for (const r of rows) {
+            L(`    • ${r.scenario}${r.variant ? ` [${r.variant}]` : ''}${r.defectId ? ` → ${r.defectId}` : ''}`);
+            L(`      ${r.ruleId}: ${r.evidence}`);
+          }
+        }
+        L(`\n  Report: ${path.relative(cwd, saved)}\n`);
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+      }
+    });
+}

package/src/cli/index.ts

@@ -37,6 +37,8 @@ import { registerCapabilityCommand } from './commands/capability';
 import { registerFlowCheckCommand } from './commands/flow-check';
 import { registerContextCommand } from './commands/context';
 import { registerRepairCommand } from './commands/repair';
+import { registerTriageCommand } from './commands/triage';
+import { registerDefectCommand } from './commands/defect';
 import { registerResultsCommand } from './commands/results-merge';
 import { registerLoginCommand } from './commands/login';
 import { capabilityRegistry } from '../capabilities/registry';
@@ -89,6 +91,8 @@ registerSetupMobileEnvCommand(program);
   registerFlowCheckCommand(program);
   registerContextCommand(program);
   registerRepairCommand(program);
+  registerTriageCommand(program);
+  registerDefectCommand(program);
   registerResultsCommand(program);
   registerIngestCommand(program);
   registerEvalCommand(program);

package/src/exporters/csv-exporter.ts

@@ -32,6 +32,10 @@ import { formatEnv } from './run-environment';
 export interface BuildCsvInput {
   screen: string;
   featureName: string;
+  /** The exact command that regenerates this unit (`sungen generate --flow checkout`). `screen`
+   *  is the deliverable label — the FEATURE basename, `flow/<x>` for a flow — so a note built from
+   *  it named a command that fails (#880). */
+  generateCommand?: string;
   /** URL path for the screen/flow entry point — concatenated onto baseURL
    *  when building the Test Environment column so QA can see the exact URL
    *  the test targets. */
@@ -207,7 +211,7 @@ export function buildTestCaseRows(input: BuildCsvInput): TestCaseRow[] {
       // No execution record AND no compiled test → Manual if @manual, else genuinely not compiled.
       testResult = testcaseType === 'Manual' ? 'Pending' : 'N/A';
       if (testcaseType !== 'Manual') {
-        note = 'Scenario not compiled — re-run `sungen generate --screen ' + input.screen + '`';
+        note = `Scenario not compiled — re-run \`${input.generateCommand ?? `sungen generate --screen ${input.screen}`}\``;
       } else {
         // Why the case is manual — the `# MANUAL: …` comment — so the tester reading the
         // deliverable knows what blocks automation (#810). Empty when no reason is written.

package/src/exporters/feature-parser.ts

@@ -117,6 +117,7 @@ export function parseFeatureMetadata(featureFilePath: string): FeatureMetadata {
     referencedVars: extractReferencedVars(sc, extractTestcaseType([...parsed.tags, ...sc.tags]) === 'Manual'),
     orderedSteps: classifySteps(sc),
     comments: sc.comments,
+    hookType: sc.hookType,
   }));
 
   return {
@@ -136,6 +137,17 @@ export function isStepsBaseScenario(sc: ScenarioMetadata): boolean {
   return !!sc.stepsName;
 }
 
+/**
+ * A hook (`@beforeAll` / `@afterEach` / `@afterAll`) — setup or teardown around the tests, compiled
+ * to `test.beforeAll()` etc. Read from the scenario's OWN tag (the parser's `hookType`), never from
+ * the feature+scenario tag union. It is not a test case: counted as one, it blocked the matrix at
+ * Gate A (a hook carries no VP id, as the gherkin skill tells authors) and showed in the legacy
+ * workbook and the dashboard as a "Not compiled" row (#880).
+ */
+export function isHookScenario(sc: ScenarioMetadata): boolean {
+  return !!sc.hookType;
+}
+
 /**
  * Return true if this is the default scaffold sample scenario (not real).
  */

package/src/exporters/matrix/build.ts

@@ -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[] = [];
 
@@ -305,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,
@@ -322,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,
@@ -360,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.
@@ -432,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;
 }
@@ -463,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) {

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

@@ -19,7 +19,8 @@
 
 import * as fs from 'fs';
 import * as ExcelJS from 'exceljs';
-import { MatrixModel } from './types';
+import { MatrixModel, VariantState } from './types';
+import { rollUp } from './build';
 import { HEADER_ROW, RESULT_COL } from './render-testcase-sheet';
 
 const MANUAL_SHEET = 'Manual';
@@ -169,6 +170,70 @@ function resetNote(prior: CarriedCell[]): ExcelJS.CellValue {
   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.
@@ -178,6 +243,7 @@ export function carryManualResults(
   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]),
@@ -190,14 +256,11 @@ export function carryManualResults(
       const before = prior.rows.get(ref);
       if (!before) continue;
       placed.add(ref);
-      if (isUntouched(before.cells)) continue;
+      const decision = plan.get(ref);
+      if (!decision) 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) {
+      if (decision === 'reset') {
         row.getCell(RESULT_COL).value = 'Pending';
         row.getCell(CARRIED_COLS[NOTE_INDEX]).value = resetNote(before.cells);
         report.reset.push(ref);

package/src/exporters/matrix/export.ts

@@ -17,7 +17,8 @@ import { mergeFeatureAndSpec } from '../scenario-merger';
 import { getPackageVersion } from '../package-info';
 import { writeCsv } from '../csv-exporter';
 import { deliverableXlsxPath, writeXlsx } from '../xlsx-exporter';
-import { carryManualResults, ManualCarryReport, readPriorManualResults } from './carry-manual-results';
+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';
@@ -168,12 +169,21 @@ export async function writeMatrixDeliverables(
   paths: MatrixTargetPaths,
   model: MatrixModel,
   format: MatrixFormat = 'xlsx',
+  /** 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.
-  const prior = xlsx ? await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit)) : null;
+  // 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));
   }

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-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') },

package/src/exporters/matrix/types.ts

@@ -147,6 +147,11 @@ export interface CoverageVariant {
   fingerprint: string;
   /** Execution result, when the run report has one for this variant. */
   result?: PlaywrightResult;
+  /** A Manual variant's result as the tester recorded it in the previous workbook, carried
+   *  BEFORE rendering so every total, roll-up, the CSV and the CLI count it (#891). */
+  manualState?: VariantState;
+  /** The Executed Date the tester recorded with it (yyyy-mm-dd, or as typed). */
+  manualDate?: string;
 }
 
 export type ItemResult = 'passed' | 'failed' | 'blocked' | 'partial' | 'not_run' | 'na';