@sun-asterisk/sungen 3.2.14 → 3.2.16

package/src/cli/commands/delivery.ts

@@ -13,6 +13,7 @@ import { parseSpecFile } from '../../exporters/spec-parser';
 import { loadTestData } from '../../exporters/test-data-resolver';
 import { loadSelectorKeyMap } from '../../exporters/selector-key-resolver';
 import { loadPlaywrightReport, resolveResultsPath as resolveResultsPathShared } from '../../exporters/playwright-report-parser';
+import { discoverLocaleVariants } from '../../exporters/locale-variants';
 import { mergeFeatureAndSpec } from '../../exporters/scenario-merger';
 import {
   buildTestCaseRows,
@@ -167,70 +168,11 @@ function resolveResultsPath(cwd: string, target: DeliveryTarget): string | null
   return resolveResultsPathShared(cwd, generatedDir(cwd, target), target.featureBaseName);
 }
 
-/**
- * A single locale variant of a delivery target.
- *
- * `locale === ''` denotes the base locale (file `<name>-test-result.json`,
- * test-data without overlay). Non-empty values come from
- * `<name>-test-result.<locale>.json` files found in the generated directory.
- *
- * `displayCode` is what we show in sheet names — `BASE_LOCALE.toUpperCase()`
- * for base, the locale code uppercased otherwise (e.g. `EN`, `JA`, `EN-US`).
- */
-interface LocaleVariant {
-  locale: string;          // '' for base, 'en' / 'ja' / 'staging-ja' for variants
-  displayCode: string;     // 'VI' / 'EN' / 'JA' — used in sheet name
-  resultsPath: string | null;
-}
-
-/**
- * Base locale assumed when no `SUNGEN_ENV` and no explicit override.
- * Configurable later via `qa/.sungen-config.yaml` or similar — currently
- * hardcoded since every existing sungen project uses Vietnamese as the
- * source-of-truth `test-data/<feature>.yaml`.
- */
-const DEFAULT_BASE_LOCALE = 'vi';
-
-/**
- * Discover every locale variant available for a feature by scanning the
- * generated directory for `<featureBaseName>-test-result*.json` files.
- *
- * Result always includes the base (locale = '') as the first entry — even if
- * `<name>-test-result.json` doesn't exist, callers still need somewhere to
- * fall back to (Pending status). Variants follow alphabetically by locale
- * code, so the sheet order is deterministic across runs.
- */
-function discoverLocaleVariants(cwd: string, target: DeliveryTarget): LocaleVariant[] {
-  const genDir = generatedDir(cwd, target);
-  const prefix = `${target.featureBaseName}-test-result`;
-  const variants: LocaleVariant[] = [];
-
-  // Base variant: per-target result file if present, else fall back to the global
-  // test-results/results.json (what playwright.config writes by default) via resolveResultsPath.
-  variants.push({
-    locale: '',
-    displayCode: DEFAULT_BASE_LOCALE.toUpperCase(),
-    resultsPath: resolveResultsPath(cwd, target),
-  });
-
-  if (fs.existsSync(genDir)) {
-    const localeFiles = fs.readdirSync(genDir)
-      .filter((f) => f.startsWith(`${prefix}.`) && f.endsWith('.json') && f !== `${prefix}.json`)
-      .sort();
-    for (const f of localeFiles) {
-      // Strip prefix + '.' on the left, '.json' on the right → locale code.
-      const locale = f.slice(prefix.length + 1, -'.json'.length);
-      if (!locale) continue;
-      variants.push({
-        locale,
-        displayCode: locale.toUpperCase(),
-        resultsPath: path.join(genDir, f),
-      });
-    }
-  }
-
-  return variants;
-}
+// Locale/env variant discovery is SHARED with the dashboard snapshot builder —
+// see exporters/locale-variants.ts for the classification rules (declared
+// locales via qa/capabilities.yaml, env pairing, mobile OS exemption). The two
+// surfaces previously hand-mirrored this logic and drifted into the
+// fake-locale bug (any env-suffixed result file became a "locale" sheet).
 
 function resolveTestDataPathForTarget(cwd: string, target: DeliveryTarget): string {
   return path.join(qaDir(cwd, target), 'test-data', `${target.featureBaseName}.yaml`);
@@ -522,7 +464,17 @@ async function exportTarget(
       return buildSummary(label, rows, path.relative(cwd, csvPath));
     }
 
-    const variants = discoverLocaleVariants(cwd, target);
+    const { variants, ignored } = discoverLocaleVariants(
+      cwd, generatedDir(cwd, target), target.featureBaseName,
+      () => resolveResultsPath(cwd, target),
+    );
+    if (ignored.length > 0) {
+      const env = process.env.SUNGEN_ENV;
+      log(`  ${COLOR.gray}Ignored result file(s) from other environments: ${ignored.join(', ')}${COLOR.reset}`);
+      for (const suffix of ignored) {
+        log(`  ${COLOR.cyan}→ sungen delivery ${target.screen} --env ${suffix}${COLOR.reset}${env ? '' : ` ${COLOR.gray}(this run uses the base results only)${COLOR.reset}`}`);
+      }
+    }
 
     // Mobile: emit ONE deliverable per OS (csv + xlsx), each from its own
     // `<feature>-test-result.<os>.json`. Android/iOS are SEPARATE platform runs,
@@ -542,7 +494,11 @@ async function exportTarget(
             featureName: feature.featureName,
             featurePath: resolvePlatformAppId(featurePath, variant.locale), // OS-precise app id
             merged,
-            testData: loadTestData(testDataFile, variant.locale || null),
+            // Overlay = the after-OS tail (what SUNGEN_ENV was during that run):
+            // `android.ja` merged <name>.ja.yaml at runtime — the old code passed the
+            // full `android.ja` suffix, looked up a nonexistent overlay, and silently
+            // showed base-language values in the Test Data column.
+            testData: loadTestData(testDataFile, variant.overlay ?? null),
             results: variant.resultsPath ? loadPlaywrightReport(variant.resultsPath) : null,
             env,
             selectorKeyMap,
@@ -579,9 +535,11 @@ async function exportTarget(
     const multiLocale = variants.length > 1;
 
     for (const variant of variants) {
-      // For the base variant the overlay merge is skipped (`locale: null`);
-      // for locale variants the matching `<feature>.<locale>.yaml` is merged.
-      const variantTestData = loadTestData(testDataFile, variant.locale || null);
+      // Overlay parity with the RUNTIME: merge exactly what TestDataLoader merged
+      // during that run (the run's SUNGEN_ENV) — the base variant under --env dev
+      // merges <feature>.dev.yaml, a ja variant merges <feature>.ja.yaml, plain
+      // base merges nothing.
+      const variantTestData = loadTestData(testDataFile, variant.overlay ?? null);
       const variantResults = variant.resultsPath ? loadPlaywrightReport(variant.resultsPath) : null;
       const variantRows = buildTestCaseRows({
         screen: label,
@@ -713,8 +671,12 @@ export function registerDeliveryCommand(program: Command): void {
     .argument('[names...]', 'Specific screen or flow names. Omit to process all.')
     .option('--skip-preflight', 'Skip pre-flight checks (not recommended)')
     .option('--continue-on-missing', 'Skip targets with blocking misses instead of aborting')
-    .action(async (names: string[], options: { skipPreflight?: boolean; continueOnMissing?: boolean }) => {
+    .option('--env <env>', 'Environment/locale of the run to deliver (sets SUNGEN_ENV; e.g. dev, staging, ja, dev-ja)')
+    .action(async (names: string[], options: { skipPreflight?: boolean; continueOnMissing?: boolean; env?: string }) => {
       try {
+        // Same effect as running with SUNGEN_ENV=<env> — result-file resolution,
+        // locale pairing, and test-data overlays all key off this one string.
+        if (options.env) process.env.SUNGEN_ENV = options.env;
         const cwd = process.cwd();
 
         // 1. Scope detection — each positional name expands into one target

package/src/dashboard/snapshot-builder.ts

@@ -25,6 +25,7 @@ import { buildScreenSnapshot } from '../exporters/json-exporter';
 import { loadApiCatalog } from '../exporters/api-catalog-loader';
 import { buildApiDetailRows } from '../exporters/xlsx-exporter';
 import { resolvePlatformAppId } from '../exporters/mobile-app-id';
+import { discoverLocaleVariants, LocaleVariant } from '../exporters/locale-variants';
 import { getPackageVersion } from '../exporters/package-info';
 import { ApiCatalogEntry, EnvironmentInfo } from '../exporters/types';
 import {
@@ -38,11 +39,10 @@ import {
   SNAPSHOT_VERSION,
 } from './types';
 
-/**
- * Locale code displayed when a screen has no overlay variants — the base
- * test-data file alone. Matches the delivery CLI's `DEFAULT_BASE_LOCALE`.
- */
-const DEFAULT_BASE_LOCALE = 'vi';
+// Locale/env variant discovery is SHARED with the delivery CLI — see
+// exporters/locale-variants.ts (declared locales, env pairing, mobile OS
+// exemption). Previously a hand-mirrored copy that drifted into the
+// fake-locale bug.
 
 export interface DashboardTarget {
   name: string;
@@ -217,13 +217,16 @@ function buildOneFeature(
   // Discover locale variants by scanning <feature>-test-result*.json files.
   // Always includes base ('') as the first entry, even if its results file
   // is missing — UI still needs to render the feature.
-  const variants = discoverLocaleVariants(cwd, genBase, featureBaseName);
+  const { variants } = discoverLocaleVariants(
+    cwd, genBase, featureBaseName,
+    () => resolveResultsPath(cwd, genBase, featureBaseName),
+  );
 
   // Build one per-variant ScreenSnapshot (test-data overlay + results + OS-precise
   // env column). Reused by both the web/i18n (locale-axis) and mobile (platform-axis) paths.
-  const buildVariant = (variant: FeatureLocaleVariant) => {
+  const buildVariant = (variant: LocaleVariant) => {
     const testData = fs.existsSync(testDataFile)
-      ? loadTestData(testDataFile, variant.locale || null)
+      ? loadTestData(testDataFile, variant.overlay ?? null)
       : {};
     const results = variant.resultsPath ? loadPlaywrightReport(variant.resultsPath) : null;
     return buildScreenSnapshot({
@@ -341,59 +344,6 @@ function buildOneFeature(
   }];
 }
 
-/**
- * A single locale variant of a feature.
- * `locale === ''` denotes the base (file `<name>-test-result.json`,
- * test-data without overlay merge). Variants come from
- * `<name>-test-result.<locale>.json` filenames.
- */
-interface FeatureLocaleVariant {
-  locale: string;
-  displayCode: string;
-  resultsPath: string | null;
-}
-
-/**
- * Scan the generated directory for `<basename>-test-result*.json` files
- * and infer locale codes. The base entry is always returned first; locale
- * variants follow alphabetically so sheet/tab order stays deterministic.
- *
- * Mirrors `discoverLocaleVariants` in `src/cli/commands/delivery.ts` so the
- * dashboard and the CSV/XLSX delivery agree on what locales exist for a
- * given feature.
- */
-function discoverLocaleVariants(cwd: string, genDir: string, featureBaseName: string): FeatureLocaleVariant[] {
-  const prefix = `${featureBaseName}-test-result`;
-  const variants: FeatureLocaleVariant[] = [];
-
-  // Base variant resolves through the SHARED candidate chain (per-feature file
-  // first, then the global test-results/results.json playwright writes by
-  // default) — the same resolution delivery.ts uses. Without the fallback the
-  // dashboard showed every scenario Pending on projects that only have the
-  // global results file, while delivery correctly reported Passed.
-  variants.push({
-    locale: '',
-    displayCode: DEFAULT_BASE_LOCALE.toUpperCase(),
-    resultsPath: resolveResultsPath(cwd, genDir, featureBaseName),
-  });
-
-  if (fs.existsSync(genDir)) {
-    const localeFiles = fs.readdirSync(genDir)
-      .filter((f) => f.startsWith(`${prefix}.`) && f.endsWith('.json') && f !== `${prefix}.json`)
-      .sort();
-    for (const f of localeFiles) {
-      const locale = f.slice(prefix.length + 1, -'.json'.length);
-      if (!locale) continue;
-      variants.push({
-        locale,
-        displayCode: locale.toUpperCase(),
-        resultsPath: path.join(genDir, f),
-      });
-    }
-  }
-
-  return variants;
-}
 
 /**
  * Combine per-feature summaries into a single screen-level rollup.

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/audit.ts

@@ -17,7 +17,7 @@ import {
 } from './sensors';
 import { loadFlowScenarios } from './flow-check';
 import { manualReasonMismatches, MANUAL_REASONS, buildPlan } from './capability-plan';
-import { readCapabilities } from './capability';
+import { readCapabilities, verificationScopeFindings } from './capability';
 import { readIntent, projectRootFromScreenDir, IntentProfile } from './intent';
 import { getProvenance, Provenance } from './provenance';
 import { specCoverage, SpecCoverageResult, parseSpecClauses } from './spec-coverage';
@@ -129,7 +129,8 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   discoverAndRegisterCapabilities();
   // The active platform (web | mobile | …) activates its own capability for scoring + sensor routing.
   // `web` has no capability of its own → scoringCap stays the default `ui` (byte-identical).
-  const platform = readCapabilities(projectRootFromScreenDir(screenDir)).platform;
+  const capProfile = readCapabilities(projectRootFromScreenDir(screenDir));
+  const platform = capProfile.platform;
   const defaultCap = capabilityRegistry.defaultCapabilityId();
   const scoringCapId = scoringCapabilityFor(catalogScreenName, defaultCap, platform);
   const scoringCap = scoringCapId ? capabilityRegistry.get(scoringCapId) : undefined;
@@ -223,6 +224,10 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   for (const c of flowCredits) {
     findings.push(`COVERED-VIA-FLOW: critical theme "${c.theme}" is not covered on this screen but is deeply covered by flow "${c.flow}" — cross-screen depth correctly owned by the flow, so it is credited (not a screen gap). Verify with \`sungen flow-check\`.`);
   }
+  // Verification-scope (advisory): API/DB verification the project's recorded test type never asked for.
+  for (const v of verificationScopeFindings(featureText, fs.existsSync(viewpointPath) ? fs.readFileSync(viewpointPath, 'utf-8') : '', capProfile)) {
+    findings.push(`VERIFICATION-OUT-OF-SCOPE (${v.layer}): this unit ${v.message}`);
+  }
   for (const g of gate.gaps) {
     if (g.status === 'shallow') {
       findings.push(`GATE: critical theme "${g.theme}" is covered only by SHALLOW scenarios (no data assertion) → deepen with \`... with {{value}}\` / \`table ... with {{value}}\` (count @manual cross-screen too).`);