@sun-asterisk/sungen 3.2.34 → 3.3.0-alpha.1

package/src/decisions/legacy-waiver-migration.ts

@@ -0,0 +1,135 @@
+/**
+ * Waivers move from `.sungen/journey/<slug>.state.json` into the decision layer (DOS-13.5, red-team
+ * #2) — without laundering an agent-forged waiver into a hash-valid decision (review H1).
+ *
+ * The state file is agent-writable, so a legacy waiver is TRUSTED only when its record equals the
+ * one committed in git HEAD (a commit went through review; a local edit did not). Per obligation,
+ * with L = the legacy waiver and D = the decision in force:
+ *   L same as D                 → nothing to do (same reason against the same evidence)
+ *   L untrusted                 → not imported, not counted; needs-you says UNTRUSTED and how to confirm it
+ *   L trusted, no D             → import L (`where: migrated`, idempotent by content id)
+ *   L trusted, newer than D     → import L superseding D — an `at` in the future never counts as newer
+ *   L trusted, not newer than D → D wins; the dual-write corrects the legacy file
+ * The import runs ONCE per unit: when nothing untrusted remains, a marker is written and from then on
+ * the legacy file is only a dual-write target (so the previous CLI still reads the waivers), never a source.
+ *
+ * plan is read-only, so the board is the same whether or not the writes succeed. commit writes under
+ * the write-ahead sentinel; only an unwritable checkout is tolerated silently — a conflict is raised.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { withMigrationSentinel } from '../basis/migration-sentinel';
+import { appendDecision, AppendResult } from './append-decision';
+import { canonicalJson, computeDecisionId } from './decision-identity';
+import { decisionsDirFor, unitDecisionScope } from './decision-file';
+import { DecisionDraft } from './decision-schema';
+import { gitUserName } from './decision-source';
+import { committedJson } from './git-head-trust';
+import { formatCommand } from './human-confirmation';
+import { readDecisions } from './read-decisions';
+import { asLegacyWaiver, effectiveWaiverEntries, isLegacyWaiver, LegacyWaiver, sameWaiver, waiverDraft } from './waiver-decisions';
+
+export interface UntrustedWaiver { obligation: string; waiver: LegacyWaiver }
+
+export interface WaiverSyncPlan {
+  scope: string | null;
+  /** obligation → waiver in force (legacy shape): what the board counts. */
+  waivers: Record<string, LegacyWaiver>;
+  untrusted: UntrustedWaiver[];
+  /** What the dual-write puts back in the legacy file: legacy key order, unknown records kept verbatim. */
+  stateWaivers: Record<string, unknown>;
+  imports: DecisionDraft[];
+  /** Write the import marker on commit: nothing untrusted is left to decide. */
+  markDone: boolean;
+}
+
+export const importMarkerPath = (projectRoot: string, slug: string): string =>
+  path.join(projectRoot, '.sungen', 'migrations', `${slug}.waivers-imported.json`);
+
+const asRecord = (v: unknown): Record<string, unknown> => (v && typeof v === 'object' && !Array.isArray(v) ? v as Record<string, unknown> : {});
+const newer = (w: LegacyWaiver, validFrom: string): boolean => {
+  const at = Date.parse(w.at);
+  return at > Date.parse(validFrom) && at <= Date.now();
+};
+
+export function planWaiverSync(projectRoot: string, unit: string, slug: string, statePath: string, legacy: unknown): WaiverSyncPlan {
+  const legacyWaivers = asRecord(legacy);
+  const scope = unitDecisionScope(projectRoot, unit);
+  const inForce = scope ? effectiveWaiverEntries(readDecisions(projectRoot, scope, { kind: 'waiver' }).entries) : new Map();
+  const stateWaivers: Record<string, unknown> = { ...legacyWaivers };
+  const waivers: Record<string, LegacyWaiver> = {};
+  const untrusted: UntrustedWaiver[] = [];
+  const imports: DecisionDraft[] = [];
+
+  if (scope && fs.existsSync(importMarkerPath(projectRoot, slug))) {
+    for (const [ob, d] of inForce) stateWaivers[ob] = waivers[ob] = asLegacyWaiver(d);
+    return { scope, waivers, untrusted, stateWaivers, imports, markDone: false };
+  }
+
+  const head = asRecord(asRecord(committedJson(projectRoot, statePath)).waivers);
+  for (const [ob, w] of Object.entries(legacyWaivers)) {
+    if (!isLegacyWaiver(w)) continue;                                 // unreadable record: kept in the file, never counted
+    const d = inForce.get(ob);
+    if (d && sameWaiver(asLegacyWaiver(d), w)) { waivers[ob] = w; continue; }
+    if (!(ob in head) || canonicalJson(head[ob]) !== canonicalJson(w)) { untrusted.push({ obligation: ob, waiver: w }); continue; }
+    if (d && !newer(w, d.valid_from)) { stateWaivers[ob] = waivers[ob] = asLegacyWaiver(d); continue; }
+    if (scope) imports.push(waiverDraft(ob, w, { by: 'unknown', where: 'migrated' }, d?.id));
+    waivers[ob] = w;
+  }
+  for (const [ob, d] of inForce) if (!(ob in waivers)) stateWaivers[ob] = waivers[ob] = asLegacyWaiver(d);
+  return { scope, waivers, untrusted, stateWaivers, imports, markDone: !!scope && untrusted.length === 0 };
+}
+
+/** The needs-you line for a waiver that is not in git HEAD: not counted, and how a human confirms it. */
+export function untrustedWaiverText(unit: string, slug: string, title: string, u: UntrustedWaiver): string {
+  const confirm = formatCommand(['sungen', 'journey', '--screen', unit, '--waive', u.obligation, '--reason', u.waiver.reason]);
+  return `⚠️ Waiver on "${title}" is UNTRUSTED — not counted (decision.in-run: it is in .sungen/journey/${slug}.state.json `
+    + `but not in git HEAD). If it is yours, confirm it on a terminal: ${confirm}`;
+}
+
+const UNWRITABLE = new Set(['EACCES', 'EROFS', 'ENOSPC', 'EPERM']);
+
+function writeFile(file: string, text: string): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text, 'utf-8');
+}
+
+/**
+ * Persist a plan: imports, the dual-written legacy file, the import marker. Returns false when the
+ * checkout cannot be written (read-only, full disk); any other failure — a decision that does not
+ * verify, a migration in progress or interrupted — is raised, never swallowed.
+ */
+export function commitWaiverSync(projectRoot: string, unit: string, slug: string, plan: WaiverSyncPlan, statePath: string, stateText: string): boolean {
+  const marker = importMarkerPath(projectRoot, slug);
+  const writeMarker = plan.markDone && !fs.existsSync(marker);
+  const markerText = (ids: string[]) => `${JSON.stringify({ schema: 1, unit, importedAt: new Date().toISOString(), imported: ids }, null, 2)}\n`;
+  try {
+    if (!plan.scope || plan.imports.length === 0) {
+      writeFile(statePath, stateText);
+      if (writeMarker) writeFile(marker, markerText([]));
+      return true;
+    }
+    const scope = plan.scope;
+    const dir = decisionsDirFor(projectRoot, scope);
+    const targets = plan.imports.map((d) => path.join(dir, `${computeDecisionId(d, scope)}.yaml`));
+    withMigrationSentinel(projectRoot, unit, slug, `import ${plan.imports.length} legacy waiver(s) into the decision layer`,
+      [statePath, ...(writeMarker ? [marker] : []), ...targets], () => {
+        const ids = plan.imports.map((d) => appendDecision(projectRoot, scope, d).entry.id);
+        writeFile(statePath, stateText);
+        if (writeMarker) writeFile(marker, markerText(ids));
+      });
+    return true;
+  } catch (err) {
+    if (UNWRITABLE.has((err as NodeJS.ErrnoException)?.code ?? '')) return false;
+    throw err;
+  }
+}
+
+/** Record a waiver given now on the CLI; supersedes the waiver in force for that obligation, if any. */
+export function recordWaiver(projectRoot: string, unit: string, obligation: string, w: LegacyWaiver): AppendResult {
+  const scope = unitDecisionScope(projectRoot, unit);
+  if (!scope) throw new Error(`Cannot record a waiver: "${unit}" does not name exactly one unit under qa/screens, qa/flows or qa/api.`);
+  const current = effectiveWaiverEntries(readDecisions(projectRoot, scope, { kind: 'waiver' }).entries).get(obligation);
+  if (current && sameWaiver(asLegacyWaiver(current), w)) return { status: 'already-recorded', entry: current, path: current.path };
+  return appendDecision(projectRoot, scope, waiverDraft(obligation, w, { by: gitUserName(projectRoot), where: 'cli' }, current?.id));
+}

package/src/decisions/read-decisions.ts

@@ -0,0 +1,61 @@
+/**
+ * Read the decisions of one scope (DOS-13.1 – 13.3). Best-effort by contract: a missing directory
+ * reads as empty, a bad file becomes a `problem` — a read-only or half-broken checkout never throws.
+ *
+ * Only entries that verify against themselves take effect; an entry whose content no longer matches
+ * its id, or whose entry_hash no longer matches the entry, is reported and ignored (trust nothing
+ * written). Computed on read, never stored:
+ *   - `superseded_by` — the latest visible entry that names this one in `supersedes`
+ *   - `stale`         — with `auditHash` given: `evidence_hash ≠ auditHash` (the waiver rule, DOS-13.5)
+ * `asOf` hides entries whose `valid_from` is later, so a later superseder does not supersede yet.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { DecisionEntry, DecisionKind } from './decision-schema';
+import { DecisionProblem, decisionsDirFor, verifyDecisionFile } from './decision-file';
+
+export interface ReadDecision extends DecisionEntry {
+  scope: string;
+  path: string;
+  superseded_by?: string;
+  stale?: boolean;
+}
+
+export interface ReadDecisionsOptions { asOf?: string; auditHash?: string; kind?: DecisionKind }
+export interface ReadDecisionsResult { entries: ReadDecision[]; problems: DecisionProblem[] }
+
+const byTime = (a: DecisionEntry, b: DecisionEntry): number =>
+  Date.parse(a.valid_from) - Date.parse(b.valid_from) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
+export function readDecisions(projectRoot: string, scope: string, opts: ReadDecisionsOptions = {}): ReadDecisionsResult {
+  const problems: DecisionProblem[] = [];
+  let dir: string;
+  let names: string[];
+  try {
+    dir = decisionsDirFor(projectRoot, scope);
+    names = fs.readdirSync(dir).filter((f) => f.endsWith('.yaml')).sort();
+  } catch {
+    return { entries: [], problems };
+  }
+
+  const cutoff = opts.asOf ? Date.parse(opts.asOf) : Infinity;
+  const entries: ReadDecision[] = [];
+  for (const name of names) {
+    const file = path.join(dir, name);
+    const v = verifyDecisionFile(file, scope);
+    if (v.problem) { problems.push(v.problem); continue; }
+    if (Date.parse(v.entry.valid_from) > cutoff) continue;
+    entries.push({ ...v.entry, scope, path: file });
+  }
+  entries.sort(byTime);
+
+  const byId = new Map(entries.map((e) => [e.id, e]));
+  for (const e of entries) {
+    const target = e.supersedes ? byId.get(e.supersedes) : undefined;
+    if (target) target.superseded_by = e.id;   // ascending time: the latest superseder wins
+  }
+  if (opts.auditHash !== undefined) {
+    for (const e of entries) if (e.evidence_hash !== undefined) e.stale = e.evidence_hash !== opts.auditHash;
+  }
+  return { entries: opts.kind ? entries.filter((e) => e.kind === opts.kind) : entries, problems };
+}

package/src/decisions/viewpoint-baseline-adapter.ts

@@ -0,0 +1,74 @@
+/**
+ * The accepted viewpoint baseline, seen as decisions — read-only (DOS-11.4; storage moves in P1).
+ *
+ * `sungen audit --accept-viewpoint` records `.sungen/viewpoint-baseline.json` (harness/viewpoint-
+ * baseline.ts). Each unit in it is projected as one `viewpoint-acceptance` decision, without moving or
+ * rewriting anything: no file is written here, ever.
+ *
+ * The file is agent-writable, so a unit is projected only while its record equals the one committed
+ * in git HEAD (review H1) — otherwise it would turn a local edit into a hash-valid decision. Anything
+ * not projected is reported: an `untrusted` unit, an `invalid` unit record, an `unreadable` file.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { canonicalJson, sealDecision } from './decision-identity';
+import { DecisionProblem, PROJECT_SCOPE } from './decision-file';
+import { committedJson } from './git-head-trust';
+import { ReadDecision } from './read-decisions';
+
+/** Same location harness/viewpoint-baseline.ts writes. */
+const baselineFile = (projectRoot: string): string => path.join(projectRoot, '.sungen', 'viewpoint-baseline.json');
+const EPOCH = '1970-01-01T00:00:00.000Z';
+
+interface UnitRecord { hash: string; ids: string[]; recordedAt?: string; fileHash?: string }
+
+function isUnitRecord(v: unknown): v is UnitRecord {
+  const r = v as UnitRecord;
+  return !!r && typeof r === 'object' && typeof r.hash === 'string' && Array.isArray(r.ids) && r.ids.every((i) => typeof i === 'string');
+}
+const unitsOf = (raw: unknown): Record<string, unknown> | null => {
+  const u = (raw as { units?: unknown } | null)?.units;
+  return u && typeof u === 'object' && !Array.isArray(u) ? u as Record<string, unknown> : null;
+};
+
+function project(unit: string, r: UnitRecord, file: string): ReadDecision {
+  const at = typeof r.recordedAt === 'string' && !Number.isNaN(Date.parse(r.recordedAt)) ? new Date(r.recordedAt).toISOString() : EPOCH;
+  const entry = sealDecision({
+    kind: 'viewpoint-acceptance',
+    anchors: [],
+    text: `Accept the test-viewpoint declaration of ${unit} as the baseline`,
+    reason: 'Accepted with sungen audit --accept-viewpoint (legacy .sungen/viewpoint-baseline.json)',
+    payload: { unit, hash: r.hash, ids: r.ids, ...(typeof r.fileHash === 'string' ? { fileHash: r.fileHash } : {}) },
+    source: { by: 'unknown', where: 'legacy:viewpoint-baseline' },
+    valid_from: at,
+    visibility: 'internal',
+  }, PROJECT_SCOPE);
+  return { ...entry, scope: PROJECT_SCOPE, path: file };
+}
+
+export function viewpointAcceptanceDecisions(projectRoot: string): { entries: ReadDecision[]; problems: DecisionProblem[] } {
+  const file = baselineFile(projectRoot);
+  const entries: ReadDecision[] = [];
+  const problems: DecisionProblem[] = [];
+  if (!fs.existsSync(file)) return { entries, problems };
+  let units: Record<string, unknown> | null;
+  try {
+    units = unitsOf(JSON.parse(fs.readFileSync(file, 'utf8')));
+  } catch (err) {
+    problems.push({ path: file, code: 'unreadable', message: `viewpoint baseline cannot be read: ${err instanceof Error ? err.message : String(err)}` });
+    return { entries, problems };
+  }
+  if (!units) return { entries, problems: [{ path: file, code: 'unreadable', message: 'viewpoint baseline has no `units` mapping' }] };
+
+  const committed = unitsOf(committedJson(projectRoot, file)) ?? {};
+  for (const unit of Object.keys(units).sort()) {
+    const r = units[unit];
+    if (!isUnitRecord(r)) { problems.push({ path: file, code: 'invalid', message: `viewpoint baseline record for ${unit} is malformed; not projected` }); continue; }
+    if (!(unit in committed) || canonicalJson(committed[unit]) !== canonicalJson(r)) {
+      problems.push({ path: file, code: 'untrusted', message: `viewpoint baseline for ${unit} is not the one in git HEAD — not taken as a decision (decision.in-run); commit it through review` });
+      continue;
+    }
+    entries.push(project(unit, r, file));
+  }
+  return { entries, problems };
+}

package/src/decisions/waiver-decisions.ts

@@ -0,0 +1,56 @@
+/**
+ * Journey waivers as decisions (DOS-13.5).
+ *
+ * A waiver entry is `kind: waiver`, `payload.obligation`, `evidence_hash` = the audit hash the waiver
+ * was given against (legacy `auditHashAtWaive`). Per obligation the waiver in force is the latest
+ * (by `valid_from`) entry that nothing supersedes. Whether it COUNTS is the old rule, unchanged: only
+ * while `evidence_hash` equals the current audit hash; otherwise it is STALE and goes back to a human.
+ */
+import { DecisionDraft, DecisionEntry, DecisionSource } from './decision-schema';
+import { ReadDecision } from './read-decisions';
+
+/** The legacy shape in `.sungen/journey/<slug>.state.json` — still dual-written for one release. */
+export interface LegacyWaiver { reason: string; at: string; auditHashAtWaive: string }
+
+const norm = (s: string): string => s.normalize('NFC').replace(/\r\n?/g, '\n').trim();
+
+export function isLegacyWaiver(w: unknown): w is LegacyWaiver {
+  const x = w as LegacyWaiver;
+  return !!x && typeof x === 'object' && typeof x.reason === 'string' && norm(x.reason).length > 0
+    && typeof x.at === 'string' && !Number.isNaN(Date.parse(x.at)) && typeof x.auditHashAtWaive === 'string';
+}
+
+/** Same decision: same reason against the same evidence (the time it was recorded does not matter). */
+export function sameWaiver(a: LegacyWaiver, b: LegacyWaiver): boolean {
+  return norm(a.reason) === norm(b.reason) && a.auditHashAtWaive === b.auditHashAtWaive;
+}
+
+export function waiverDraft(obligation: string, w: LegacyWaiver, source: DecisionSource, supersedes?: string): DecisionDraft {
+  return {
+    kind: 'waiver',
+    anchors: [],
+    text: `Waive ${obligation}`,
+    reason: w.reason,
+    payload: { obligation },
+    source,
+    valid_from: w.at,
+    ...(supersedes ? { supersedes } : {}),
+    visibility: 'internal',
+    evidence_hash: w.auditHashAtWaive,
+  };
+}
+
+export function asLegacyWaiver(e: DecisionEntry): LegacyWaiver {
+  return { reason: e.reason, at: e.valid_from, auditHashAtWaive: e.evidence_hash ?? '' };
+}
+
+/** obligation → the waiver entry in force. `entries` come from readDecisions (sorted by time). */
+export function effectiveWaiverEntries(entries: ReadDecision[]): Map<string, ReadDecision> {
+  const out = new Map<string, ReadDecision>();
+  for (const e of entries) {
+    const ob = e.payload?.obligation;
+    if (e.kind !== 'waiver' || e.superseded_by || typeof ob !== 'string') continue;
+    out.set(ob, e);   // ascending time: the latest wins
+  }
+  return out;
+}

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

@@ -34,6 +34,7 @@ import {
   MAX_VARIANTS_PER_ITEM,
 } from './types';
 import { runGates } from './gates';
+import { CATALOG_GATE_RULES, GateRules } from '../../harness/gates/resolve-rule';
 import { capabilityRegistry } from '../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 
@@ -96,6 +97,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 +109,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;
 }
@@ -124,6 +129,8 @@ export interface BuildInputs {
   specText?: string;
   /** apis.yaml endpoint catalog (api units) — renders `@api:` calls as request blocks. */
   apiCatalog?: Record<string, ApiCatalogEntry>;
+  /** The unit's gate rules (catalog + gate-overrides, OES-11.2); the catalog alone when absent. */
+  gateRules?: GateRules;
 }
 
 /**
@@ -136,6 +143,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 +316,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 +333,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 +371,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 +443,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 +507,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) {
@@ -552,7 +597,7 @@ export function buildMatrix(inputs: BuildInputs): MatrixModel {
     variantsByVp.set(v.vpId, list);
   }
 
-  const findings = runGates({ inputs, variants, variantsByVp });
+  const findings = runGates({ inputs, variants, variantsByVp, rules: inputs.gateRules });
   const stale = new Set(findings.filter((f) => f.gate === 'E' && f.ref).map((f) => f.ref as string));
 
   const items: DeliveryItem[] = map.groups.map((g) => {
@@ -618,22 +663,21 @@ export function buildMatrix(inputs: BuildInputs): MatrixModel {
   // requirements/spec.md; @spec: traces mark `covered`; the map's `requirements:`
   // section carries the reviewed overrides (partially_covered / not_applicable / …).
   const requirements = computeRequirements(inputs.specText ?? '', map, items);
+  // Gate R levels come from the catalog like every other matrix gate (OES-11.2); `off` drops the finding.
+  const gateR = (rule: string, message: string): void => {
+    const { severity } = (inputs.gateRules ?? CATALOG_GATE_RULES).resolve(rule);
+    if (severity !== 'off') findings.push({ gate: 'R', severity, message });
+  };
   const gaps = requirements.filter((r) => r.status === 'gap');
   if (gaps.length > 0) {
-    findings.push({
-      gate: 'R', severity: 'warning',
-      message: `${gaps.length} requirement id(s) with no coverage or disposition: ${gaps.map((g) => g.id).join(', ')} — trace them, or record a status in the map \`requirements:\` section`,
-    });
+    gateR('matrix.gate-r.requirement-gap', `${gaps.length} requirement id(s) with no coverage or disposition: ${gaps.map((g) => g.id).join(', ')} — trace them, or record a status in the map \`requirements:\` section`);
   }
   // A `covered` claim with no traced variant is prose, not traceability: nothing
   // detects it when the proving scenario is later changed or deleted. Either tag
   // the scenario that proves it (`@spec:<id>`) or say where it IS covered.
   const unbacked = requirements.filter((r) => r.status === 'covered' && r.items.length === 0);
   if (unbacked.length > 0) {
-    findings.push({
-      gate: 'R', severity: 'warning',
-      message: `${unbacked.length} requirement id(s) declared \`covered\` with no variant tracing to them: ${unbacked.map((r) => r.id).join(', ')} — add \`@spec:<id>\` to the scenario that proves each, or use covered_elsewhere / partially_covered with a named reference`,
-    });
+    gateR('matrix.gate-r.covered-unbacked', `${unbacked.length} requirement id(s) declared \`covered\` with no variant tracing to them: ${unbacked.map((r) => r.id).join(', ')} — add \`@spec:<id>\` to the scenario that proves each, or use covered_elsewhere / partially_covered with a named reference`);
   }
 
   const variantCount = items.reduce((a, i) => a + i.variants.length, 0);