@sun-asterisk/sungen 3.2.12 → 3.2.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.12",
+  "version": "3.2.14",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -12,7 +12,7 @@
     "copy-templates": "mkdir -p dist/generators/test-generator/adapters/playwright/templates/steps && mkdir -p dist/generators/test-generator/templates && mkdir -p dist/orchestrator/templates && mkdir -p dist/dashboard/templates && cp -r src/generators/test-generator/adapters/playwright/templates/*.hbs dist/generators/test-generator/adapters/playwright/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/playwright/templates/steps dist/generators/test-generator/adapters/playwright/templates/ && mkdir -p dist/generators/test-generator/adapters/appium/templates/steps && cp -r src/generators/test-generator/adapters/appium/templates/*.hbs dist/generators/test-generator/adapters/appium/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/appium/templates/steps dist/generators/test-generator/adapters/appium/templates/ && cp src/generators/test-generator/templates/*.hbs dist/generators/test-generator/templates/ 2>/dev/null || true && cp -r src/orchestrator/templates/* dist/orchestrator/templates/ && cp src/dashboard/templates/index.html dist/dashboard/templates/index.html && mkdir -p dist/harness/catalog && cp src/harness/catalog/*.yaml dist/harness/catalog/",
     "build:dashboard": "cd ../../dashboard && npm install --silent && npm run build && cd - && cp ../../dashboard/dist/index.html src/dashboard/templates/index.html",
     "dev": "tsx src/cli/index.ts",
-    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts && tsx tests/exporter/run.ts && tsx tests/exporter/feature-parser-category.run.ts && tsx tests/exporter/api-detail-sheet.run.ts && tsx tests/exporter/overview-sheet.run.ts && tsx tests/exporter/delivery-divider-tcid.run.ts && tsx tests/exporter/note-expected-actual.run.ts && tsx tests/exporter/test-data-vars.run.ts && tsx tests/exporter/mobile-app-id.run.ts && tsx tests/exporter/api-testcase-cells.run.ts && tsx tests/exporter/delivery-cases-result.run.ts && tsx tests/exporter/precondition-auth-role.run.ts && tsx tests/exporter/report-builder-parity.run.ts && tsx tests/exporter/delivery-preflight-testdata.run.ts && tsx tests/exporter/delivery-preflight-selectors.run.ts && tsx tests/exporter/delivery-prerun-overview.run.ts && tsx tests/exporter/manual-testcase-testdata.run.ts && tsx tests/dashboard/api-flows-discovery.run.ts && tsx tests/dashboard/status-results-fallback.run.ts && tsx tests/codegen/verb-ref-masking.run.ts && tsx tests/codegen/table-aria-hidden-locators.run.ts && tsx tests/codegen/steps-base-not-compiled.run.ts && tsx tests/codegen/manual-oracle-gate.run.ts && tsx tests/api-runtime/base-path-url-join.run.ts && tsx tests/api-runtime/file-upload-multipart.run.ts && tsx tests/api-runtime/schema-assertion.run.ts && tsx tests/runtime/test-data-cross-ref.run.ts && tsx tests/runtime/test-data-array-projection.run.ts &&tsx tests/capabilities/run.ts && tsx tests/openapi/run.ts && tsx tests/api-field-coverage/run.ts && tsx tests/packaging/run.ts && tsx tests/generate-hint/run.ts && tsx tests/template-assertion/run.ts && tsx tests/journey/run.ts && tsx tests/harness/serial-cascade.run.ts && tsx tests/ai-skills/cross-assistant-orphan.run.ts && tsx tests/init/codex-mcp-config.run.ts && tsx src/orchestrator/ai-skills/golden-skills.test.ts && tsx tests/db-runtime/sql-placeholder-rewrite.run.ts && tsx tests/db-runtime/fallback-flow-codified.run.ts && tsx tests/db-runtime/cosmos-engine.run.ts && tsx tests/db-runtime/mongodb-engine.run.ts && tsx tests/db-runtime/dynamodb-engine.run.ts && tsx tests/db-runtime/mysql-integration.opt-in.run.ts && tsx tests/db-runtime/mongodb-integration.opt-in.run.ts && tsx tests/db-runtime/dynamodb-integration.opt-in.run.ts",
+    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts && tsx tests/exporter/run.ts && tsx tests/exporter/feature-parser-category.run.ts && tsx tests/exporter/api-detail-sheet.run.ts && tsx tests/exporter/overview-sheet.run.ts && tsx tests/exporter/delivery-divider-tcid.run.ts && tsx tests/exporter/note-expected-actual.run.ts && tsx tests/exporter/test-data-vars.run.ts && tsx tests/exporter/mobile-app-id.run.ts && tsx tests/exporter/api-testcase-cells.run.ts && tsx tests/exporter/delivery-cases-result.run.ts && tsx tests/exporter/precondition-auth-role.run.ts && tsx tests/exporter/report-builder-parity.run.ts && tsx tests/exporter/delivery-preflight-testdata.run.ts && tsx tests/exporter/delivery-preflight-selectors.run.ts && tsx tests/exporter/delivery-prerun-overview.run.ts && tsx tests/exporter/manual-testcase-testdata.run.ts && tsx tests/dashboard/api-flows-discovery.run.ts && tsx tests/dashboard/status-results-fallback.run.ts && tsx tests/codegen/verb-ref-masking.run.ts && tsx tests/codegen/table-aria-hidden-locators.run.ts && tsx tests/codegen/steps-base-not-compiled.run.ts && tsx tests/codegen/manual-oracle-gate.run.ts && tsx tests/codegen/locator-value-qualified-assertions.run.ts && tsx tests/api-runtime/base-path-url-join.run.ts && tsx tests/api-runtime/file-upload-multipart.run.ts && tsx tests/api-runtime/schema-assertion.run.ts && tsx tests/runtime/test-data-cross-ref.run.ts && tsx tests/runtime/test-data-array-projection.run.ts && tsx tests/runtime/env-secret-interpolation.run.ts && tsx tests/capabilities/run.ts && tsx tests/openapi/run.ts && tsx tests/api-field-coverage/run.ts && tsx tests/packaging/run.ts && tsx tests/generate-hint/run.ts && tsx tests/template-assertion/run.ts && tsx tests/journey/run.ts && tsx tests/harness/serial-cascade.run.ts && tsx tests/ai-skills/cross-assistant-orphan.run.ts && tsx tests/init/codex-mcp-config.run.ts && tsx src/orchestrator/ai-skills/golden-skills.test.ts && tsx tests/db-runtime/sql-placeholder-rewrite.run.ts && tsx tests/db-runtime/fallback-flow-codified.run.ts && tsx tests/db-runtime/cosmos-engine.run.ts && tsx tests/db-runtime/mongodb-engine.run.ts && tsx tests/db-runtime/dynamodb-engine.run.ts && tsx tests/db-runtime/mysql-integration.opt-in.run.ts && tsx tests/db-runtime/mongodb-integration.opt-in.run.ts && tsx tests/db-runtime/dynamodb-integration.opt-in.run.ts",
     "test:update": "tsx tests/golden/run.ts --update && tsx tests/audit/run.ts --update && tsx tests/ingest/run.ts --update",
     "prepublishOnly": "npm run build:dashboard && npm run build"
   },
@@ -39,8 +39,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.2.12",
-    "@sungen/driver-ui": "3.2.12",
+    "@sungen/driver-data-factory": "3.2.14",
+    "@sungen/driver-ui": "3.2.14",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

package/src/generators/test-generator/adapters/playwright/templates/steps/actions/hover-element-with-text.hbs

@@ -0,0 +1 @@
+await {{> locator-base}}.filter({ hasText: {{> has-text-value dataValue=dataValue exact=exact legacyTail=(and (eq strategy "text") (eq value ""))}} }){{> locator-nth}}.hover();

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/state-with-filter-assertion.hbs

@@ -0,0 +1,11 @@
+{{#if selectedProbe}}
+{ const el = {{> locator-base}}.filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{> locator-nth}};
+if ((await el.getAttribute('aria-selected')) !== null) {
+await expect(el).toHaveAttribute('aria-selected', 'true');
+} else {
+await expect(el).toBeChecked();
+}
+}
+{{else}}
+await expect({{> locator-base}}.filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{> locator-nth}}).{{{stateAssertion}}};
+{{/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/visible-filtered-assertion.hbs

@@ -0,0 +1 @@
+await expect({{> locator-base}}.filter({ hasText: {{> has-text-value dataValue=dataValue exact=exact legacyTail=(and (eq strategy "text") (eq value ""))}} }){{> locator-nth}}).toBeVisible();

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

@@ -937,6 +937,40 @@ export class CodeGenerator {
   /**
    * Generate tests for all features in a directory
    */
+  /**
+   * SG-W009 — every `${QA_*}` secret reference in the unit's test-data yaml must be
+   * DECLARED: as a real value in .env.qa (or an overlay .env.qa.<env>), or at least as
+   * a name in the committed .env.qa.example. An undeclared ref means the test throws
+   * "environment variable not set" the moment the key is used — surface it at compile
+   * time instead. Only the `${QA_*}` shape is checked: any other `${...}` text is
+   * ordinary literal data by design (never resolved, never warned about).
+   */
+  private reportedEnvRefs = new Set<string>();
+  private checkEnvSecretRefs(featureFile: string): void {
+    const testDataDir = path.join(path.dirname(featureFile), '..', 'test-data');
+    if (!fs.existsSync(testDataDir)) return;
+    const referenced = new Set<string>();
+    for (const f of fs.readdirSync(testDataDir).filter((x) => x.endsWith('.yaml') || x.endsWith('.yml'))) {
+      const text = fs.readFileSync(path.join(testDataDir, f), 'utf-8');
+      for (const m of text.matchAll(/\$\{(QA_[A-Z0-9_]+)\}/g)) referenced.add(m[1]);
+    }
+    if (!referenced.size) return;
+    const declared = new Set<string>();
+    for (const f of fs.readdirSync(process.cwd()).filter((x) => x === '.env.qa' || x.startsWith('.env.qa.'))) {
+      for (const line of fs.readFileSync(path.join(process.cwd(), f), 'utf-8').split('\n')) {
+        const m = line.match(/^\s*#?\s*(QA_[A-Z0-9_]+)\s*=/);
+        if (m) declared.add(m[1]);
+      }
+    }
+    for (const name of referenced) {
+      if (declared.has(name) || this.reportedEnvRefs.has(name)) continue;
+      this.reportedEnvRefs.add(name);
+      this.diagnostics.add('SG-W009',
+        `test-data references \${${name}} but ${name} is declared in neither .env.qa nor .env.qa.example — the test will throw "environment variable not set" when the key is used. Add ${name}=<value> to .env.qa (gitignored), and list the name in .env.qa.example`,
+        { feature: path.basename(featureFile, '.feature'), step: name });
+    }
+  }
+
   async generateAllTests(
     featuresDir: string,
     outputDir: string,
@@ -956,6 +990,7 @@ export class CodeGenerator {
       try {
         const feature = parser.parseFeatureFile(featureFile);
         features.push(feature);
+        this.checkEnvSecretRefs(featureFile);
       } catch (error) {
         console.error(`✗ Failed to parse ${featureFile}:`, error);
         parseErrors.push({ file: featureFile, error });

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

@@ -15,12 +15,14 @@
  *             Then (invalid Gherkin; comments cannot substitute), or a documentation-style
  *             manual (no steps) whose comments lack the extractable procedure — ≥1 numbered
  *             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
  *
  * 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';
+export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009';
 
 export interface Diagnostic {
   code: DiagnosticCode;

package/src/generators/test-generator/utils/runtime-data-transformer.ts

@@ -5,11 +5,17 @@ const MARKER_PATTERN = /__SUNGEN_TD_([A-Za-z0-9_]+)__/;
  * Three passes: comments, string literals, then regex literals.
  */
 export function transformToRuntimeData(code: string, accessor: string = 'testData'): string {
-  // Pass 0: Comments — replace markers in // comments with decoded key name
-  // Prevents Pass 2 from misinterpreting // comment markers as regex delimiters
+  // Pass 0: Comments — replace markers in // comments with decoded key name.
+  // Prevents Pass 2 from misinterpreting // comment markers as regex delimiters.
+  // ANCHORED to line start (^\s*//) so a `//` INSIDE a string literal on a code line
+  // — e.g. a URL `https://careerforum.aki-inc.jp/` in a selector name — is NOT mistaken
+  // for a comment. Before this anchor, such a URL preceding a marker on the same line
+  // made Pass 0 strip the marker to its bare key, so Pass 1 never wrapped it in
+  // testData.get() (silent: `toHaveAttribute('href', 'official_site_url')`). Generated
+  // comments are always full-line, so anchoring loses nothing.
   code = code.replace(
-    /\/\/(.*)__SUNGEN_TD_([A-Za-z0-9_]+)__(.*)/g,
-    (_, before, enc, after) => `//${before}${decodeKey(enc)}${after}`
+    /^(\s*)\/\/(.*)__SUNGEN_TD_([A-Za-z0-9_]+)__(.*)$/gm,
+    (_, indent, before, enc, after) => `${indent}//${before}${decodeKey(enc)}${after}`
   );
 
   // Pass 1: String literal context — handles both whole-string and embedded markers

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) |

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

@@ -76,6 +76,7 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | Error | Diagnosis | Fix |
 |---|---|---|
 | strict mode violation | Multiple elements match | Add `nth: 0`, `exact: true`, or more specific `name` |
+| strict mode violation on `see`/`hover [X] item\|option\|cell with {{v}}` (dynamic list) | Older builds didn't filter the locator by the value | Since 3.2.13 `see`/`hover ... with {{v}}` on list-member roles filters by `hasText` like `click` (existence/hover the matching item) — keep the step data-driven, don't add per-item selectors. Update sungen if still unfiltered |
 | Timeout / not found | Element doesn't exist or name wrong | Re-snapshot → copy exact accessible name. Check iframe/dialog scope |
 | Element is not an input | Wrong element type targeted | Change `type` or `value` to match actual element |
 | not a select | Custom dropdown, not native `<select>` | Set the widget variant: `variant: radix-select`/`antd-select` (built-in recipes), a custom recipe name from `qa/app.yaml`, or project-wide `widgets.select` in `qa/app.yaml` |
@@ -92,6 +93,11 @@ 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` |
+
+### 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-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,8 +53,11 @@ 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;
   }
 
   /**
@@ -66,6 +71,7 @@ export class TestDataLoader {
     if (value === undefined || value === null) {
       throw new Error(`Test data key not found: ${key}`);
     }
+    if (typeof value === 'string') assertNoUnresolvedEnvRef(key, value);
     return value;
   }
 
@@ -206,6 +212,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');
+  }
+}