@sun-asterisk/sungen 3.2.13 → 3.2.15

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/flow-manager.ts

@@ -7,6 +7,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { readCapabilities } from '../harness/capability';
+import { testDataHeader, ensureTestDataGuideFiles } from './test-data-guide';
 
 export interface FlowOptions {
   name: string;
@@ -114,11 +115,11 @@ export class FlowManager {
     fs.writeFileSync(selectorPath, selectorLines.join('\n'), 'utf-8');
 
     fs.writeFileSync(testDataPath, [
-      `# ${options.name} Flow Test Data`,
-      `# Namespace by phase: login.email, submission.nominee`,
-      `# Reference in features using {{variable}} syntax`,
+      testDataHeader(`${options.name} Flow`).trimEnd(),
+      `# Namespace keys by phase: login.email, submission.nominee`,
       ``,
     ].join('\n'), 'utf-8');
+    ensureTestDataGuideFiles(process.cwd());
 
     const specPath = path.join(requirementsDir, 'spec.md');
     fs.writeFileSync(specPath, this.generateSpecTemplate(options, flowName, isMobile), 'utf-8');

package/src/orchestrator/screen-manager.ts

@@ -7,6 +7,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { chromium } from '@playwright/test';
 import { readCapabilities } from '../harness/capability';
+import { testDataHeader, ensureTestDataGuideFiles } from './test-data-guide';
 
 export interface ScreenOptions {
   name: string;
@@ -144,15 +145,11 @@ export class ScreenManager {
       fs.writeFileSync(selectorPath, selectorLines.join('\n'), 'utf-8');
     }
 
-    // Generate empty test-data YAML
+    // Generate empty test-data YAML (header = the 3-kinds authoring guide)
     if (!fs.existsSync(testDataPath)) {
-      fs.writeFileSync(testDataPath, [
-        `# ${options.name} Screen Test Data`,
-        `# Fill via AI or manually`,
-        `# Reference in features using {{variable}} syntax`,
-        ``,
-      ].join('\n'), 'utf-8');
+      fs.writeFileSync(testDataPath, testDataHeader(`${options.name} Screen`), 'utf-8');
     }
+    ensureTestDataGuideFiles(process.cwd());
 
     // Generate requirements spec.md (only on first screen creation)
     const specPath = path.join(requirementsDir, 'spec.md');

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

@@ -65,7 +65,7 @@ The CLI reads the **per-target result file first** (co-located with `.spec.ts`),
 | Category 3 | Feature name (first line of `.feature`) |
 | Category 4 | Screen name |
 | Pre-condition | Auth tag → "Logged in as X" / "Not authenticated" + Given steps (natural language) |
-| Test Data | `{{vars}}` from scenario resolved via test-data.yaml → `key: value; key2: value2` |
+| Test Data | `{{vars}}` from scenario resolved via test-data.yaml → `key: value; key2: value2`. SECRET refs are printed **verbatim** as `${QA_*}` — the exporter never resolves them, so credentials never enter CSV/XLSX/dashboard |
 | Steps | `.spec.ts` code comments for interactions (numbered) |
 | Expected results | `.spec.ts` `expect(...)` comments (numbered) |
 | Priority | Tag: `@high`/`@normal`/`@low` (default: Normal) |
@@ -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

@@ -93,6 +93,12 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | `SG-W006` | `qa/app.<env>.yaml` found — unsupported by design | Describe the app once in `qa/app.yaml`; env differences belong in test-data overlays |
 | `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`
+
+The scenario uses a SECRET test-data key whose `QA_*` variable is missing in this environment. Fix: copy `.env.qa.example` → `.env.qa` and fill the value (or export it in the shell/CI). Never "fix" it by writing the real secret into test-data.yaml.
 
 ### Assertion errors → apply the Source-of-truth gate above FIRST
 

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/ai-src/skills/sungen-tc-generation/SKILL.md

@@ -29,6 +29,11 @@ user-invocable: false
 - Hardcode exact error messages in test-data.yaml — never leave `{{error}}` vague
   → Assertions are string-equal; vague placeholders produce false-positive passes.
 
+- **Data classification — decide per value which of 3 kinds it is** (the scaffolded test-data header + `qa/TEST-DATA-GUIDE.md` explain this to QA; PRESERVE that header when rewriting the file):
+  1. **INVENTED** (backend need not accept it): validation inputs, boundaries, XSS payloads, expected messages → hardcode in the yaml.
+  2. **ENV-BOUND** (must exist in the test environment; harmless if leaked): seeded ids, registered emails, valid tokens → keep in yaml with a `# ENV-BOUND: <what to seed>` marker; per-environment values go in `<unit>.<env>.yaml`.
+  3. **SECRET** (real login / harmful if leaked): NEVER write the real value — reference `${QA_<NAME>}` (uppercase, `QA_` prefix mandatory; only that shape resolves from `.env.qa` at runtime, any other `${...}` stays literal). Whenever you emit a new `${QA_*}` ref, ALSO append the name to `.env.qa.example`. Note: "password" is not automatically SECRET — a made-up password probing validation is INVENTED; only a real account's password is SECRET (and `@auth:role` via `sungen makeauth` usually removes the need entirely).
+
 - `@parallel` required when mixing `@auth:X` + `@no-auth` in the same feature
   → Playwright shares browser context per worker; auth state leaks across scenarios without isolation.
 
@@ -321,7 +326,9 @@ Security:         [S1 – admin only]
    - **Shape A — documentation-style** (NO Gherkin steps at all): the whole procedure lives in comments — numbered **action steps first**, then labeled `Observable:`/`Oracle:` lines. Use whenever the expected is unconfirmed (SPEC-GAP) or any part of the procedure is outside the DSL (password manager, DevTools, browser zoom/viewport, multi-tab, DB seeding). Do NOT keep a stray Gherkin fragment (`Given … page` + one fill) — a `When` without `Then` is invalid Gherkin, and a partial fragment can INVERT the chronology (e.g. "save a credential first" rendering AFTER "open the page").
    - **Shape B — complete Gherkin**: `Given/When/Then`, all steps present. Use when the expected IS known and only execution is manual.
    Gate (`SG-W008`, both directions): a `@manual` with Gherkin steps but no `Then` fires — comments (even labeled `Oracle:` lines) can NOT substitute for the missing `Then`. A `@manual` with NO steps ALSO fires when its comments lack ≥1 numbered action line + ≥1 labeled `Observable:`/`Oracle:`/`Expected:` line — prose paragraphs and rationale-only comments export EMPTY Steps/Expected cells.
-   In shape A the observable/oracle lines MUST carry their **label** (`Observable:` / `Oracle:` / `Expected:`) — the delivery parser extracts Expected results **by label**; unlabeled prose all lands in the Steps column and the Expected cell exports EMPTY. And the numbered action steps MUST precede them — without the actions the tester has an oracle but no procedure. Use this comment shape:
+   In shape A the observable/oracle lines MUST carry their **label** (`Observable:` / `Oracle:` / `Expected:`) — the delivery parser extracts Expected results **by label**; unlabeled prose all lands in the Steps column and the Expected cell exports EMPTY. And the numbered action steps MUST precede them — without the actions the tester has an oracle but no procedure.
+   **Oracle layer must match the unit** — a screen-unit manual defaults to a **UI oracle**: phrase the expected as what the tester SEES (on-screen message, list/table state after reload). If the business effect IS UI-observable, do NOT cite API responses or DB state as the oracle — "server rejects the request" is verified by *the error message on screen + no new row after reload*, not by reading the API response. Only when the effect has NO UI observation (mail content, stored hash, request count, response-body leak) may the oracle use another layer — then: (a) put the **layer label inside the line**: `Oracle: UI — …` / `Oracle: API — …` / `Oracle: DB — …` so QA knows the tooling needed from the deliverable alone; (b) tag `@manual:M2` so the capability planner recommends the api/db driver; (c) prefer the automation-ready `@requires:api`/`@query` form when the steps are expressible. A deep engineering check may ride along as `(optional deep check: …)` appended to the UI oracle — it must never REPLACE a UI-observable oracle.
+   Use this comment shape:
    ```gherkin
    @high @manual
    Scenario: VP-… <claim>
@@ -330,7 +337,7 @@ Security:         [S1 – admin only]
      #   1. <setup>            e.g. seed a registered email; throttle the network
      #   2. <action>           e.g. click [Submit] with the request in flight
      #   3. Observable: <what> e.g. Observable: only ONE POST is dispatched
-     #   4. Oracle: <tool>     e.g. Oracle: DevTools Network panel / mail-catcher / NVDA
+     #   4. Oracle: <layer — tool>  e.g. Oracle: API — DevTools Network panel · Oracle: UI — visual inspection · Oracle: DB — read the row via DB client
    ```
 
 #### Tier 1 guard — minimum before writing scenarios

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

@@ -188,6 +188,7 @@ Build a mapping table: for each applicable group, does the feature have a matchi
 | Check | Pts |
 |---|---|
 | `@manual` has a valid **technical** reason (not "don't know how to automate" — document as `# TODO: automate when...` comment instead) | 3 |
+| **Manual oracle speaks the unit's layer** — in a screen unit the oracle is UI-observable (on-screen message, list state after reload), NOT "API response/DB state" when the effect is visible in the UI; a genuinely non-UI oracle carries its layer label (`Oracle: API — …` / `Oracle: DB — …`) + `@manual:M2` | 2 |
 | Stable selectors — per `sungen-selector-keys`: keys use spaces, standard types, `locator` only as last resort | 3 |
 | Each step names a concrete element by name/label/role (enough to implement without asking) | 2 |
 | Idempotent + no fixed waits (`wait for [T] dialog` instead of `wait N seconds`) | 2 |

package/src/orchestrator/templates/specs-api.ts

@@ -24,7 +24,9 @@ interface ApiDataSource {
 }
 
 function loadEnvQa(): void {
-  for (const name of ['.env.qa', `.env.qa.${process.env.SUNGEN_ENV || ''}`]) {
+  // Precedence (first set wins, real env highest): shell/CI env > .env.qa.<SUNGEN_ENV>
+  // > .env.qa — the env-specific file OVERLAYS the base, mirroring test-data overlays.
+  for (const name of [`.env.qa.${process.env.SUNGEN_ENV || ''}`, '.env.qa']) {
     const p = path.join(process.cwd(), name);
     if (!name.endsWith('.') && fs.existsSync(p)) {
       for (const line of fs.readFileSync(p, 'utf8').split('\n')) {

package/src/orchestrator/templates/specs-db.ts

@@ -110,7 +110,9 @@ async function openSshTunnel(ssh: SshConfig, dstHost: string, dstPort: number):
 }
 
 function loadEnvQa(): void {
-  for (const name of ['.env.qa', `.env.qa.${process.env.SUNGEN_ENV || ''}`]) {
+  // Precedence (first set wins, real env highest): shell/CI env > .env.qa.<SUNGEN_ENV>
+  // > .env.qa — the env-specific file OVERLAYS the base, mirroring test-data overlays.
+  for (const name of [`.env.qa.${process.env.SUNGEN_ENV || ''}`, '.env.qa']) {
     const p = path.join(process.cwd(), name);
     if (!name.endsWith('.') && fs.existsSync(p)) {
       for (const line of fs.readFileSync(p, 'utf8').split('\n')) {

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

@@ -39,6 +39,8 @@ export class TestDataLoader {
     }
 
     data = resolveDynamicVars(data);
+    loadEnvQa();
+    data = resolveEnvRefs(data);
 
     return new TestDataLoader(data);
   }
@@ -51,21 +53,34 @@ export class TestDataLoader {
     // A projected array (e.g. `{{q.rows[*].name}}`) serializes as a JSON list so the full
     // ordered set is preserved for the assert-compare — String([...]) would flatten it to a
     // lossy comma-join that can't be distinguished from a scalar containing commas.
-    if (Array.isArray(value)) return this.interpolate(JSON.stringify(value));
-    return this.interpolate(String(value));
+    const result = Array.isArray(value)
+      ? this.interpolate(JSON.stringify(value))
+      : this.interpolate(String(value));
+    assertNoUnresolvedEnvRef(key, result);
+    return result;
   }
 
   /**
    * 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') {
+      const result = this.interpolate(value);
+      assertNoUnresolvedEnvRef(key, result);
+      return result;
+    }
     return value;
   }
 
@@ -206,6 +221,63 @@ function deepMerge(base: Record<string, any>, override: Record<string, any>): Re
   return result;
 }
 
+/**
+ * SECRET test data: only `${QA_*}` (uppercase, QA_ prefix) is an env reference — resolved
+ * from .env.qa / process.env so real credentials never live in the committed yaml. The
+ * prefix doubles as the resolution ALLOWLIST: any other `${...}` text is ordinary literal
+ * data (XSS payloads, template strings, passwords containing `${`) — never touched, and a
+ * yaml can never exfiltrate arbitrary environment variables like ${AWS_SECRET_ACCESS_KEY}.
+ */
+const QA_ENV_REF = /\$\{(QA_[A-Z0-9_]+)\}/g;
+
+/**
+ * Load .env.qa files into process.env. Precedence (first set wins, real env highest):
+ * shell/CI env > .env.qa.<SUNGEN_ENV> > .env.qa — the env-specific file OVERLAYS the base,
+ * mirroring how <feature>.<env>.yaml overlays <feature>.yaml.
+ */
+function loadEnvQa(): void {
+  const env = process.env.SUNGEN_ENV;
+  for (const name of [env ? `.env.qa.${env}` : '', '.env.qa']) {
+    if (!name) continue;
+    const p = path.join(process.cwd(), name);
+    if (!fs.existsSync(p)) continue;
+    for (const line of fs.readFileSync(p, 'utf-8').split('\n')) {
+      const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
+      if (m && process.env[m[1]] === undefined) process.env[m[1]] = m[2].replace(/^["']|["']$/g, '');
+    }
+  }
+}
+
+/** Substitute `${QA_*}` refs in every string value. Unset vars stay literal — the guard in
+ *  get()/raw() throws with the var name the moment such a key is actually used. */
+function resolveEnvRefs(data: Record<string, any>): Record<string, any> {
+  function resolveValue(value: any): any {
+    if (typeof value === 'string') {
+      return value.replace(QA_ENV_REF, (match, name) =>
+        process.env[name] !== undefined ? process.env[name]! : match);
+    }
+    if (Array.isArray(value)) return value.map(resolveValue);
+    if (value && typeof value === 'object') {
+      const resolved: Record<string, any> = {};
+      for (const [k, v] of Object.entries(value)) resolved[k] = resolveValue(v);
+      return resolved;
+    }
+    return value;
+  }
+  return resolveValue(data);
+}
+
+/** Fail fast — and only for the test that actually uses the key — when a `${QA_*}` secret
+ *  was referenced but never provided. */
+function assertNoUnresolvedEnvRef(key: string, value: string): void {
+  const m = value.match(/\$\{(QA_[A-Z0-9_]+)\}/);
+  if (m) {
+    throw new Error(
+      `Test data "${key}" references \${${m[1]}} but the environment variable is not set — ` +
+      `add ${m[1]}=... to .env.qa (gitignored; see .env.qa.example), or export it in the shell/CI.`);
+  }
+}
+
 function resolveDynamicVars(data: Record<string, any>): Record<string, any> {
   const ts = String(Date.now());
   const uid = crypto.randomUUID();

package/src/orchestrator/test-data-guide.ts

@@ -0,0 +1,158 @@
+/**
+ * Test-data authoring guide — the QA-facing explanation of the three data classes
+ * (INVENTED / ENV-BOUND / SECRET `${QA_*}`) and the secret-handling convention.
+ *
+ * Two layers, both generated here so they can never drift:
+ *  - a compact header embedded at the top of every scaffolded test-data yaml
+ *    (create-test's skill instructs the AI to preserve it when rewriting the file);
+ *  - the full guide at qa/TEST-DATA-GUIDE.md + the .env.qa.example starter, created
+ *    once per project by add-screen/add-flow.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+/** Compact per-file header — examples first, one line per class. */
+export function testDataHeader(unitName: string): string {
+  return [
+    `# ${unitName} Test Data — reference in features using {{variable}} syntax.`,
+    `# ─── HOW TO FILL VALUES (full guide: qa/TEST-DATA-GUIDE.md) ────────────────`,
+    `# 3 kinds of values:`,
+    `# 1) INVENTED — only exists to probe the screen; make it up from the spec`,
+    `#      wrong_email: "abc@"                    ← write the value right here`,
+    `# 2) ENV-BOUND — must EXIST in the test environment (seeded id/email),`,
+    `#    but leaking it is harmless`,
+    `#      active_user_id: "d4f8-001"             # ENV-BOUND: seeded on staging`,
+    `# 3) SECRET — a real login / harmful if leaked (real password, API key)`,
+    `#      admin_password: \${QA_ADMIN_PASSWORD}   ← never write the real value;`,
+    `#      put it in .env.qa (gitignored), variable name MUST start with QA_`,
+    `# ───────────────────────────────────────────────────────────────────────────`,
+    ``,
+  ].join('\n');
+}
+
+const GUIDE_MD = `# Test Data Guide
+
+Every \`{{variable}}\` in a \`.feature\` file maps to a key in that unit's
+\`test-data/*.yaml\`. When you create or edit a value, decide which of the
+**three kinds** it is — each kind is handled differently.
+
+## 1) INVENTED — made-up values that only probe the screen
+
+**What it is:** the value exists only to trigger a reaction (an error message, a
+boundary, a rendering) — the backend does not need to accept it as real data.
+
+**Examples:** a wrong-format email \`"abc@"\`; a 6-char password to trigger the
+"minimum 7 characters" error; a 256-char string to test a 255 limit; an XSS
+payload \`<script>alert(1)</script>\`; the exact expected error message from the spec.
+
+**What to do:** write the value directly in the yaml. Nothing else.
+
+**Self-check:** *"If I swapped this for another value of the same kind, would the
+test still mean the same thing?"* → yes = INVENTED.
+
+## 2) ENV-BOUND — real records of the test environment (not secret)
+
+**What it is:** the value must EXIST in the environment for the test to work — a
+seeded record id, a registered email, a valid invite token — but leaking it
+causes no harm.
+
+**Examples:**
+\`\`\`yaml
+active_user_id: "d4f8-001"              # ENV-BOUND: seeded user on staging
+existing_email: "tester01@example.com"  # ENV-BOUND: pre-registered account
+\`\`\`
+
+**What to do:** keep it in the yaml and mark the line with \`# ENV-BOUND: ...\` so
+the next person knows it must be re-seeded/replaced per environment. When the
+value differs per environment, override it in \`<unit>.<env>.yaml\`
+(e.g. \`login.staging.yaml\`) and run with \`SUNGEN_ENV=staging\`.
+
+**Self-check:** *"If someone deleted this record from the DB, would the test
+fail?"* → yes = ENV-BOUND.
+
+## 3) SECRET — real credentials; harmful if leaked
+
+**What it is:** values that grant real access or cause harm when exposed — a
+real account password, an API key, a system token.
+
+\`\`\`yaml
+# ❌ WRONG — the real password lives in git; anyone who clones the repo reads it:
+admin_password: "Sun@2026"
+
+# ✅ RIGHT — the yaml holds only the variable name; the real value stays in
+#    .env.qa, which is gitignored:
+admin_password: \${QA_ADMIN_PASSWORD}
+\`\`\`
+
+and in \`.env.qa\` (NOT committed — copy \`.env.qa.example\` and fill it):
+
+\`\`\`bash
+QA_ADMIN_PASSWORD=Sun@2026
+\`\`\`
+
+**Rules that matter:**
+- The variable name MUST start with \`QA_\` and be UPPERCASE — only \`\${QA_...}\`
+  is replaced at runtime. Any other \`\${...}\` text is treated as ordinary
+  characters (so XSS payloads / template strings containing \`\${\` are safe).
+- Whenever you add a new \`\${QA_*}\` reference, also add the NAME to
+  \`.env.qa.example\` — that file is the committed checklist of variables each
+  environment must provide.
+- Delivery reports (CSV/Excel) and the dashboard always print \`\${QA_ADMIN_PASSWORD}\`
+  literally — secrets never enter deliverables.
+- Per environment: \`.env.qa.<env>\` overlays \`.env.qa\` (run with \`SUNGEN_ENV=<env>\`);
+  a variable exported in the shell/CI beats both files.
+- If a referenced \`QA_*\` variable is missing at run time, the test that uses it
+  fails immediately with the variable name — check \`.env.qa\`.
+
+**Self-check:** *"Could sharing this file outside the team cause harm?"* → yes = SECRET.
+
+## Easy to confuse
+
+- **"password" is not automatically SECRET.** \`password_below_min: "Aa1bcd"\` used
+  to trigger a validation error is INVENTED — make it up. Only a password that
+  actually logs in to a real account is SECRET.
+- **Testing screens behind login usually needs NO password at all** — run
+  \`sungen makeauth\` once: it opens a browser, you log in by hand, and the saved
+  session (storageState) is reused by \`@auth:<role>\` scenarios.
+
+## Quick reference
+
+| Kind | Recognize by | Where the value lives |
+|---|---|---|
+| INVENTED | backend need not accept it | the yaml, as-is |
+| ENV-BOUND | must exist in the environment; harmless if leaked | the yaml + \`# ENV-BOUND:\` marker (+ \`<unit>.<env>.yaml\` overlay) |
+| SECRET | real access / harmful if leaked | \`\${QA_*}\` in the yaml → real value in \`.env.qa\` (gitignored), name listed in \`.env.qa.example\` |
+`;
+
+const ENV_QA_EXAMPLE = `# Secret test data referenced as \${QA_*} in qa/**/test-data/*.yaml.
+# Copy this file to .env.qa (gitignored) and fill the real values per environment.
+# Per-environment overrides: .env.qa.<env> + run with SUNGEN_ENV=<env>.
+#
+# QA_ADMIN_PASSWORD=
+`;
+
+/**
+ * Idempotently create qa/TEST-DATA-GUIDE.md and .env.qa.example, and make sure
+ * .gitignore covers .env.qa (incl. .env.qa.<env> overlays, but NOT .env.qa.example).
+ */
+export function ensureTestDataGuideFiles(cwd: string): void {
+  const guidePath = path.join(cwd, 'qa', 'TEST-DATA-GUIDE.md');
+  if (fs.existsSync(path.join(cwd, 'qa')) && !fs.existsSync(guidePath)) {
+    fs.writeFileSync(guidePath, GUIDE_MD, 'utf-8');
+  }
+  const examplePath = path.join(cwd, '.env.qa.example');
+  if (!fs.existsSync(examplePath)) {
+    fs.writeFileSync(examplePath, ENV_QA_EXAMPLE, 'utf-8');
+  }
+  const gitignorePath = path.join(cwd, '.gitignore');
+  if (fs.existsSync(gitignorePath)) {
+    const lines = fs.readFileSync(gitignorePath, 'utf-8').split('\n').map((l) => l.trim());
+    // `.env.qa` alone does not cover `.env.qa.staging` — ignore the whole family
+    // except the committed example (negation must come after the glob).
+    if (!lines.includes('.env.qa') && !lines.includes('.env.qa*') && !lines.includes('.env*')) {
+      fs.appendFileSync(gitignorePath, `\n# sungen secret test data (see .env.qa.example)\n.env.qa*\n!.env.qa.example\n`);
+    }
+  } else {
+    fs.writeFileSync(gitignorePath, `# sungen secret test data (see .env.qa.example)\n.env.qa*\n!.env.qa.example\n`, 'utf-8');
+  }
+}