@sun-asterisk/sungen 3.2.14 → 3.2.15

package/src/exporters/locale-variants.ts

@@ -0,0 +1,157 @@
+/**
+ * Locale/env classification for `<feature>-test-result.<suffix>.json` files —
+ * SHARED by the delivery CLI and the dashboard snapshot builder (previously two
+ * hand-mirrored copies that had already drifted into the fake-locale bug).
+ *
+ * Field report (3.2.14): every result-file suffix was treated as a LOCALE. A
+ * team running `SUNGEN_ENV=dev npx playwright test` (the standard .env.qa.dev
+ * convention) then `sungen delivery` without an env got a fabricated two-locale
+ * deliverable: a "VI Auto" sheet (hardcoded base label, all Pending, pointing
+ * at a result file that doesn't exist) next to a "DEV Auto" sheet.
+ *
+ * The file mechanism cannot distinguish an env overlay (`login.dev.yaml`,
+ * per-env credentials) from a locale overlay (`login.ja.yaml`, translated
+ * text) — they are deliberately the same mechanism keyed by SUNGEN_ENV. So
+ * locales are DECLARED, not guessed:
+ *
+ *   # qa/capabilities.yaml
+ *   locales: [ja, en]      # non-base locales (written by /sungen:locale)
+ *   base_locale: en        # language of the base test-data (default: en)
+ *
+ * Suffix classification (first match wins), with E = the delivery env
+ * (SUNGEN_ENV / --env, possibly empty):
+ *   1. ^(android|ios)(.|$)          → OS run (mobile per-OS branch consumes)
+ *   2. suffix === E                 → the base variant's own file (not a variant)
+ *   3. E === '' && suffix ∈ locales → locale variant on the base env
+ *   4. E !== '' && suffix === `${E}-<L>`, L ∈ locales → locale variant on env E
+ *   5. anything else                → env run — EXCLUDED from variants and
+ *      reported in `ignored` so the CLI can hint "run with --env <suffix>".
+ *
+ * Env pairing (rules 2–4) means a delivery only ever mixes results from ONE
+ * environment. Running with `--env ja` (an env named exactly like a declared
+ * locale) is interpreted as "deliver that locale's run" — the documented
+ * SUNGEN_ENV=<locale> convention, not a collision.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
+
+export interface LocaleVariant {
+  /** Result-file suffix as found on disk ('' = base). */
+  locale: string;
+  /** Sheet-name label (used only in multi-locale mode). */
+  displayCode: string;
+  resultsPath: string | null;
+  /**
+   * Test-data overlay code to merge for this variant's Test Data column —
+   * mirrors what the RUNTIME merged (TestDataLoader uses SUNGEN_ENV): the full
+   * suffix on web, the after-OS tail on mobile (`android.ja` ran with
+   * SUNGEN_ENV=ja). `null` = base data only. loadTestData no-ops on a missing
+   * overlay file, so passing an env code whose overlay doesn't exist is safe.
+   */
+  overlay: string | null;
+}
+
+export interface LocaleDiscovery {
+  variants: LocaleVariant[];
+  /** Env-run suffixes with result files, excluded from this delivery (hint material). */
+  ignored: string[];
+}
+
+export interface LocaleConfig {
+  baseLocale: string;
+  locales: string[];
+}
+
+export const DEFAULT_BASE_LOCALE = 'en';
+
+/** Read the i18n declaration from qa/capabilities.yaml (absent → no locales, base 'en'). */
+export function readLocaleConfig(cwd: string): LocaleConfig {
+  try {
+    const p = path.join(cwd, 'qa', 'capabilities.yaml');
+    if (fs.existsSync(p)) {
+      const parsed = parseYaml(fs.readFileSync(p, 'utf-8')) as
+        { locales?: unknown; base_locale?: unknown } | null;
+      const locales = Array.isArray(parsed?.locales)
+        ? parsed!.locales!.filter((l): l is string => typeof l === 'string' && l.length > 0)
+        : [];
+      const baseLocale = typeof parsed?.base_locale === 'string' && parsed.base_locale
+        ? parsed.base_locale
+        : DEFAULT_BASE_LOCALE;
+      return { baseLocale, locales };
+    }
+  } catch { /* malformed yaml → behave as undeclared */ }
+  return { baseLocale: DEFAULT_BASE_LOCALE, locales: [] };
+}
+
+const OS_SUFFIX = /^(android|ios)(\.|$)/;
+
+/** The after-OS tail of a mobile suffix: 'android.ja' → 'ja', 'ios' → ''. */
+export function osSuffixTail(suffix: string): string {
+  return suffix.replace(OS_SUFFIX, '');
+}
+
+/**
+ * Discover the variants of a feature for ONE delivery run.
+ *
+ * `resolveBaseResultsPath` supplies the base variant's results (delivery and
+ * the dashboard share the same env-aware candidate chain via
+ * playwright-report-parser.resolveResultsPath — passed in to avoid a cycle).
+ */
+export function discoverLocaleVariants(
+  cwd: string,
+  genDir: string,
+  featureBaseName: string,
+  resolveBaseResultsPath: () => string | null,
+): LocaleDiscovery {
+  const cfg = readLocaleConfig(cwd);
+  const env = process.env.SUNGEN_ENV || '';
+  const prefix = `${featureBaseName}-test-result`;
+
+  const variants: LocaleVariant[] = [{
+    locale: '',
+    // With --env <locale> (the SUNGEN_ENV=<locale> convention) the base IS that
+    // locale's run; otherwise the base carries the declared base language.
+    displayCode: (cfg.locales.includes(env) ? env : cfg.baseLocale).toUpperCase(),
+    resultsPath: resolveBaseResultsPath(),
+    overlay: env || null,
+  }];
+  const ignored: string[] = [];
+
+  if (fs.existsSync(genDir)) {
+    const suffixes = fs.readdirSync(genDir)
+      .filter((f) => f.startsWith(`${prefix}.`) && f.endsWith('.json') && f !== `${prefix}.json`)
+      .map((f) => f.slice(prefix.length + 1, -'.json'.length))
+      .filter((s) => s.length > 0)
+      .sort();
+    for (const suffix of suffixes) {
+      if (OS_SUFFIX.test(suffix)) {
+        // Mobile per-OS run — kept unconditionally; the mobile branch consumes these.
+        // Overlay = the tail (what SUNGEN_ENV was during that run), never the OS itself.
+        variants.push({
+          locale: suffix,
+          displayCode: suffix.toUpperCase(),
+          resultsPath: path.join(genDir, `${prefix}.${suffix}.json`),
+          overlay: osSuffixTail(suffix) || null,
+        });
+        continue;
+      }
+      if (suffix === env) continue; // the base variant's own file
+      const isLocaleOfThisEnv = env === ''
+        ? cfg.locales.includes(suffix)
+        : suffix.startsWith(`${env}-`) && cfg.locales.includes(suffix.slice(env.length + 1));
+      if (isLocaleOfThisEnv) {
+        variants.push({
+          locale: suffix,
+          displayCode: suffix.toUpperCase(),
+          resultsPath: path.join(genDir, `${prefix}.${suffix}.json`),
+          overlay: suffix,
+        });
+      } else {
+        ignored.push(suffix);
+      }
+    }
+  }
+
+  return { variants, ignored };
+}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-match-data.hbs

@@ -1,15 +1,7 @@
-{{~#if isGiven~}}
 {
-  const rows = {{> locator}}.locator('tbody').getByRole('row', { includeHidden: true }).filter({ visible: true });
+  const table = {{> locator}};
+  const rows = table.locator('tbody').getByRole('row', { includeHidden: true }).filter({ visible: true });
 {{#each assertions}}
-  {{this}}
+  {{{this}}}
 {{/each~}}
 }
-{{~else~}}
-{
-  const rows = {{> locator}}.locator('tbody').getByRole('row', { includeHidden: true }).filter({ visible: true });
-{{#each assertions}}
-  {{this}}
-{{/each~}}
-}
-{{~/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-row-exists.hbs

@@ -1,7 +1,17 @@
+{{~#if rowSelector}}
+{{~#if isGiven}}
+const tableRow = {{> locator}}.locator('{{rowSelector}}');
+await tableRow.filter({ hasText: '{{escapeQuotes filterValue}}' }).waitFor();
+{{~else}}
+const tableRow = {{> locator}}.locator('{{rowSelector}}');
+await expect(tableRow).toContainText('{{escapeQuotes filterValue}}');
+{{~/if}}
+{{~else}}
 {{~#if isGiven}}
 const tableRow = {{> locator}}.getByRole('row', { includeHidden: true }).filter({ hasText: '{{escapeQuotes filterValue}}' }).filter({ visible: true });
 await tableRow.waitFor();
 {{~else}}
 const tableRow = {{> locator}}.getByRole('row', { includeHidden: true }).filter({ hasText: '{{escapeQuotes filterValue}}' }).filter({ visible: true });
 await expect(tableRow).toBeVisible();
-{{~/if}}
+{{~/if}}
+{{~/if}}

package/src/generators/test-generator/code-generator.ts

@@ -908,7 +908,7 @@ export class CodeGenerator {
       // them. Rewrite those to the per-row `rowData` view — each row then fires its own `@api` call
       // with that row's input and asserts that row's expected status/body (the success/failure matrix).
       // `testData.cases()/withRow()` (the global loader, no `.get/.bind/.set`) is intentionally left alone.
-      return transformToRuntimeData(rendered, 'rowData').replace(/\btestData\.(get|bind|set)\(/g, 'rowData.$1(');
+      return transformToRuntimeData(rendered, 'rowData').replace(/\btestData\.(get|bind|set|raw)\(/g, 'rowData.$1(');
     }
     return rendered;
   }

package/src/generators/test-generator/diagnostics.ts

@@ -17,12 +17,15 @@
  *             action line + ≥1 labeled Observable:/Oracle:/Expected: line
  *   SG-W009 — test-data references a `${QA_*}` secret that is declared in neither .env.qa
  *             nor .env.qa.example — the test will throw "not set" the moment the key is used
+ *   SG-W010 — a row step's [Ref] looks POSITIONAL (First/Last/Top/…) but has no selectors.yaml
+ *             entry: the label is display-only, so the step checks existence anywhere in the
+ *             table — an ordering rule would pass even when the row moved
  *
  * Diagnostics never block generation by themselves; `sungen generate --strict`
  * turns any collected diagnostic into a non-zero exit.
  */
 
-export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009';
+export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010';
 
 export interface Diagnostic {
   code: DiagnosticCode;

package/src/generators/test-generator/step-mapper.ts

@@ -37,6 +37,10 @@ export class StepMapper {
   /** Row scope: when active, column assertions are scoped to this row */
   private inRowScope: boolean = false;
   private rowScopeTable: string = '';
+  /** Count of row-scope-entering steps in the current scenario + whether the shared
+   *  `tableRow` binding has been emitted (let-once + reassign when there are ≥2). */
+  private tableRowScopeSteps: number = 0;
+  private tableRowDeclared: boolean = false;
   /** SG-W007: an action step already ran in this scenario (alert handlers registered after it are too late) */
   private sawActionStep: boolean = false;
   /** Compile-time warning channel (SG-W001/W002); optional — absent means silent legacy behavior */
@@ -109,6 +113,12 @@ export class StepMapper {
   /**
    * Set scenario context for path variable resolution
    */
+  /** A `see [Ref] row in [Table] table with {{v}}` step — declares `tableRow` and enters row scope. */
+  private isRowScopeEntryStep(step: ParsedStep): boolean {
+    return step.elementType === 'row' && /\bin\b.*\btable\b/i.test(step.text) &&
+      /\bwith\b/i.test(step.text) && !/\bis\s+hidden\b/i.test(step.text);
+  }
+
   setScenarioContext(steps: ParsedStep[]): void {
     this.currentScenarioSteps = steps;
     // Reset dialog and frame scope at the start of each new scenario
@@ -116,6 +126,16 @@ export class StepMapper {
     this.inFrameScope = false;
     this.inRowScope = false;
     this.rowScopeTable = '';
+    // Row-scope steps declare `const tableRow` at FUNCTION scope on purpose — the
+    // following `[Col] column with {{v}}` steps reference it, so the declaration
+    // can't be block-wrapped like the self-contained row ACTIONS are. But two or
+    // more row steps in one scenario then redeclare the same const → the whole
+    // spec fails to parse ("Identifier 'tableRow' has already been declared").
+    // Count them up front: with ≥2 the first becomes `let` and the rest plain
+    // reassignments (which also correctly REBINDS the row scope); a single
+    // occurrence keeps `const` so existing single-row specs stay byte-identical.
+    this.tableRowScopeSteps = steps.filter((s) => this.isRowScopeEntryStep(s)).length;
+    this.tableRowDeclared = false;
     this.sawActionStep = false;
     this.lastPrimaryKeyword = 'Given';
     this.dataResolver.clearCaptured(); // captured vars are scenario-scoped
@@ -245,13 +265,34 @@ export class StepMapper {
 
     if (mappedStep) {
       // Enter row scope when a row-in-table step is matched
-      if (step.elementType === 'row' && /\bin\b.*\btable\b/i.test(step.text) &&
-          /\bwith\b/i.test(step.text) && !/\bis\s+hidden\b/i.test(step.text)) {
+      if (this.isRowScopeEntryStep(step)) {
         const brackets = step.text.match(/\[([^\]]+)\]/g) || [];
         this.inRowScope = true;
         this.rowScopeTable = brackets.length >= 2
           ? brackets[1].replace(/[\[\]]/g, '')
           : '';
+        // ≥2 row steps in this scenario: turn the duplicate `const tableRow`
+        // declarations into one `let` + reassignments (see setScenarioContext).
+        if (this.tableRowScopeSteps > 1 && mappedStep.code && mappedStep.code.includes('const tableRow')) {
+          if (this.tableRowDeclared) {
+            mappedStep.code = mappedStep.code.replace('const tableRow', 'tableRow');
+          } else {
+            mappedStep.code = mappedStep.code.replace('const tableRow', 'let tableRow');
+            this.tableRowDeclared = true;
+          }
+        }
+        // SG-W010 — a POSITIONAL-looking row label ([First X Row], [Last …]) without a
+        // selectors.yaml entry is display-only: the step degrades to an anywhere-in-the-
+        // table existence check and an ordering rule silently never fails. A resolved
+        // entry compiles to a positioned toContainText — its absence is detectable here.
+        const rowLabel = (brackets[0] || '').replace(/[\[\]]/g, '');
+        if (this.diagnostics && rowLabel &&
+            /\b(first|last|top|bottom|nth|\d+(st|nd|rd|th)?)\b/i.test(rowLabel) &&
+            mappedStep.code && !mappedStep.code.includes('toContainText')) {
+          this.diagnostics.add('SG-W010',
+            `row label "[${rowLabel}]" looks positional but has no selectors.yaml entry — it is a display label only, so this step checks existence ANYWHERE in the table (an ordering rule would pass even when the row moved). Declare it to position the row, e.g. "${rowLabel.toLowerCase()}:\\n  type: locator\\n  value: 'tbody tr:first-child'"`,
+            { feature: this.featureName, step: step.text });
+        }
       }
 
       if (this.verbose) {

package/src/harness/annotation-overrides.ts

@@ -2,10 +2,13 @@
  * Shared annotation-override grammar for precondition annotations (`@query`/`@api`).
  *
  * Parses `name(a={{x}},b="lit",c=3)` overrides into a map of JS expressions, e.g.
- * `{ a: "testData.get('x')", b: "\"lit\"", c: "3" }`. Used by the DB and API capability drivers'
+ * `{ a: "testData.raw('x')", b: "\"lit\"", c: "3" }`. Used by the DB and API capability drivers'
  * precondition codegen; lives in core so both drivers can share it. Gherkin tags carry no whitespace,
  * so values are single tokens — flows thread a prior response via a whole-value ref, e.g.
  * `@api:get_profile(token={{login.body.token}})`, with the auth scheme declared in the catalog header.
+ * A `{{ref}}` override binds into a typed sink (DB query param, JSON request body), so it resolves
+ * via `testData.raw()` (native type, still interpolates embedded refs) rather than `get()`
+ * (Gherkin-text stringify) — a numeric override otherwise reaches the DB/API as a JSON string.
  */
 export function parseQueryOverrides(raw?: string): Record<string, string> {
   const out: Record<string, string> = {};
@@ -18,7 +21,7 @@ export function parseQueryOverrides(raw?: string): Record<string, string> {
     if (!key) continue;
     const v = val.match(/^\{\{\s*([^}]+?)\s*\}\}$/);
     const q = val.match(/^["'](.*)["']$/);
-    if (v) out[key] = `testData.get(${JSON.stringify(v[1])})`;
+    if (v) out[key] = `testData.raw(${JSON.stringify(v[1])})`;
     else if (q) out[key] = JSON.stringify(q[1]);
     else if (/^-?\d+(?:\.\d+)?$/.test(val)) out[key] = val;
     else out[key] = JSON.stringify(val);

package/src/harness/quality-gates.ts

@@ -174,6 +174,10 @@ export interface OwnershipResult { duplicates: { scenario: string; flow: string
 
 /** Scenarios whose step-skeleton also appears in a sibling flow feature → duplicate ownership. */
 export function crossArtifactOwnership(screenDir: string, scenarios: ScenarioInfo[]): OwnershipResult {
+  // A behavior's ownership is judged from the screen side; flow/api units are the owners, so the
+  // gate does not apply to them. Without this guard, auditing qa/flows/<x>, qa/api/<x>, or
+  // qa/api/flows/<x> resolves flowsRoot to the unit's own parent and every scenario self-matches.
+  if (path.basename(path.dirname(screenDir)) !== 'screens') return { duplicates: [] };
   const duplicates: { scenario: string; flow: string }[] = [];
   // screenDir = <root>/qa/screens/<name>; flows live at <root>/qa/flows/*/features/*.feature
   const flowsRoot = path.resolve(screenDir, '..', '..', 'flows');

package/src/orchestrator/templates/ai-src/skills/sungen-delivery/SKILL.md

@@ -85,7 +85,13 @@ The `.xlsx` leads with an **`Overview`** roll-up sheet, then splits the test cas
 - **`Auto`** — automatable test cases (`Auto` + `Not compiled`).
 - **`Manual`** — `@manual` test cases (always present, header-only when there are none).
 
-Multi-locale (no `SUNGEN_ENV`): `Overview` + one **`<LOCALE> Auto`** sheet per locale + a single shared **`Manual`** sheet (manual TCs are locale-invariant). The **CSV stays one file with every row** — the `Testcase type` column distinguishes Auto vs Manual. The Overview lists every detail sheet, so each locale's counts appear on its own row.
+Multi-locale: `Overview` + one **`<LOCALE> Auto`** sheet per locale + a single shared **`Manual`** sheet (manual TCs are locale-invariant). The **CSV stays one file with every row** — the `Testcase type` column distinguishes Auto vs Manual. The Overview lists every detail sheet, so each locale's counts appear on its own row.
+
+**Which result files become locale sheets — locales are DECLARED, never guessed.** A result-file suffix (`<name>-test-result.<X>.json`) is a locale ONLY when `X` is listed in `qa/capabilities.yaml` `locales:` (written by `/sungen:locale`), or — when delivering with `--env <E>` / `SUNGEN_ENV=<E>` — when `X = <E>-<locale>`. Every delivery mixes results of ONE environment:
+- `sungen delivery login` → base results + bare declared locales (`ja`); `dev`/`stg` suffixes are IGNORED with a hint (`→ sungen delivery login --env dev`)
+- `sungen delivery login --env dev` → `dev` results as base + `dev-ja` sheets; everything else ignored
+- `--env ja` (SUNGEN_ENV=<locale> convention) → that locale's run IS the base, labeled JA
+The base sheet label comes from `base_locale:` (default **EN**). Undeclared env suffixes NEVER fabricate locale sheets — a project without `locales:` always gets one clean `Auto` sheet. Mobile per-OS suffixes (`android`, `ios.ja`, …) are exempt and keep the per-OS files; their Test Data column merges the after-OS tail overlay (`ios.ja` → `<name>.ja.yaml`), matching what the runtime merged.
 
 ---
 

package/src/orchestrator/templates/ai-src/skills/sungen-error-mapping/SKILL.md

@@ -94,6 +94,7 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | `SG-W007` | Browser-alert handler step written AFTER an action — listener registers too late, the dialog auto-dismisses silently | Use the compound form `click [X] button and accept [OK] alert` (preferred), or move the alert step before the trigger |
 | `SG-W008` | `@manual` scenario incomplete in either direction: (a) HAS Gherkin steps but NO `Then` — a dangling `When` is invalid Gherkin, comments can NOT substitute; (b) documentation-style (NO steps) but its comments lack numbered action lines and/or a labeled oracle line — prose paragraphs / rationale-only comments export EMPTY Steps + Expected cells | Two valid shapes only: complete the Gherkin with a `Then`, or write the FULL procedure in the `# Tester verifies:` block as NUMBERED lines — action steps first (`1. <action>`), then labeled `Observable:`/`Oracle:`/`Expected:` lines (the number is what fills Steps, the label is what fills Expected results) |
 | `SG-W009` | test-data references `${QA_<NAME>}` (a SECRET env ref) but the name is declared in neither `.env.qa` nor `.env.qa.example` — the test throws "environment variable not set" the moment the key is used. (Only the `${QA_*}` shape is checked; any other `${...}` is literal data and never flagged.) | Add `QA_<NAME>=<value>` to `.env.qa` (gitignored) and list the NAME in `.env.qa.example` (the committed checklist). See `qa/TEST-DATA-GUIDE.md` |
+| `SG-W010` | A row step's `[Ref]` looks POSITIONAL (`First…`/`Last…`/`Top…`/`nth`) but has no selectors.yaml entry — the label is display-only, so the step checks existence ANYWHERE in the table; an ordering/sort-stability rule would pass even when the row moved | Declare the row in selectors.yaml (a `type: locator` value RELATIVE to the table, e.g. `first contact row:` → `value: 'tbody tr:first-child'`) — the step then asserts `toContainText` on that exact row. This is a selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
 
 ### Runtime error → `Test data "<key>" references ${QA_*} but the environment variable is not set`
 

package/src/orchestrator/templates/ai-src/skills/sungen-gherkin-syntax/SKILL.md

@@ -127,6 +127,14 @@ User see [Table] table match data:
 
 Row scope: `see [Ref] row in [Table] table with {{v}}` enters scope. Subsequent `see [Col] column with {{v}}` checks cell in that row. Use `table match data:` for multi-row verification.
 
+**[Ref] of a row step is a display label UNLESS declared in selectors.yaml.** Without an entry the step checks the value exists in ANY row — a name like `[First Contact Row]` does NOT position the row, and an ordering rule would pass even when the row moved (SG-W010 warns on positional-looking undeclared labels). To assert a POSITION, declare the row (a `type: locator` value RELATIVE to the table):
+```yaml
+first contact row:
+  type: locator
+  value: 'tbody tr:first-child'
+```
+→ compiles to `expect(table.locator('tbody tr:first-child')).toContainText(v)` — the exact row must hold the value — and still enters row scope for `[Col] column` checks.
+
 ### Database verification (optional Data Driver)
 
 Read-only DB-state checks. **Prefer named queries** — SQL lives in `qa/screens/<screen>/database/queries.yaml` (reviewed once, parameterized). Invoke with the `@query:<name>` annotation; it binds the result rows to `{{name}}`, then assert with `expect`:

package/src/orchestrator/templates/ai-src/skills/sungen-locale/SKILL.md

@@ -34,6 +34,14 @@ Take a screen/flow whose `selectors/*.yaml` and `.feature` files were authored a
 1. `selectors/<feature>.yaml` — hardcoded `name`/`value` replaced with `{{var}}`
 2. `test-data/<feature>.yaml` — base locale, complete with all new keys
 3. `test-data/<feature>.<locale>.yaml` — overlay with only the keys that change
+4. **`qa/capabilities.yaml` — DECLARE the locale** (required since 3.2.15): append the code to `locales:` and set `base_locale:` (language of the base test-data; tool default is `en`). Delivery/dashboard treat ONLY declared codes as locales — undeclared result-file suffixes are assumed to be ENVIRONMENTS (dev/staging) and excluded from locale sheets:
+   ```yaml
+   platform: web
+   enabled: [web]
+   base_locale: en      # or vi/ja — whatever the base test-data is written in
+   locales: [ja]        # append every bootstrapped locale here
+   ```
+   Env × locale combos use the compound `SUNGEN_ENV=<env>-<locale>` (e.g. `staging-ja`, overlay `<feature>.staging-ja.yaml`) — the locale segment LAST; delivery recognizes it when the tail matches a declared locale.
 4. (Optional) `selectors/<feature>.yaml` Pages block updated when locale uses URL prefix or query param
 
 After this skill finishes, `sungen run-test <name> --env <locale>` Just Works.

package/src/orchestrator/templates/specs-test-data.ts

@@ -62,16 +62,25 @@ export class TestDataLoader {
 
   /**
    * Resolve a key to its RAW, uncoerced value (array/object/number kept as-is) — for binding
-   * DB query parameters, where type-strict stores (MySQL numeric columns, MongoDB) require the
-   * native type. get() stringifies for Gherkin text; raw() must not. Throws on missing, mirroring
-   * get()'s guard.
+   * DB query / API request params, where type-strict sinks (MySQL numeric columns, MongoDB,
+   * a JSON request body) require the native type. get() stringifies for Gherkin text; raw()
+   * must not. A string value still has its embedded `{{ref}}` cross-references resolved (same
+   * as get()), so an override like `token={{login.body.token}}` or `id={{prefix}}-001` still
+   * interpolates — only the final scalar/array/object type is preserved uncoerced. Arrays and
+   * objects are returned as-is; refs embedded inside their elements are not interpolated (unlike
+   * get()'s JSON-text pass), since raw() callers bind structured values directly, not text.
+   * Throws on missing, mirroring get()'s guard.
    */
   raw(key: string): any {
     const value = this.resolve(key);
     if (value === undefined || value === null) {
       throw new Error(`Test data key not found: ${key}`);
     }
-    if (typeof value === 'string') assertNoUnresolvedEnvRef(key, value);
+    if (typeof value === 'string') {
+      const result = this.interpolate(value);
+      assertNoUnresolvedEnvRef(key, result);
+      return result;
+    }
     return value;
   }