@sun-asterisk/sungen 3.2.14 → 3.2.16-beta.1

package/dist/orchestrator/templates/ai-src/config/copilot.md

@@ -30,7 +30,7 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `/sungen-create-data-test <name>` | Generate standardized test-data (valid/boundary/invalid + CHK trace) from the Data Factory catalog; no name = all units (asks to confirm) |
 | `/sungen-review <name>` | Score syntax, coverage, viewpoint quality (auto-detects screen or flow) |
 | `/sungen-run-test <name>` | Generate `selectors.yaml`, compile, run, auto-fix (auto-detects screen or flow) |
-| `/sungen-delivery [name...]` | Export test cases → CSV for QA delivery (all screens if no arg) |
+| `/sungen-delivery [name...]` | Export the Test Case & Coverage Matrix (review/manual/customer deliverable; `--legacy` = classic CSV; all screens if no arg) |
 | `/sungen-locale <name> <locale>` | Bootstrap i18n for a screen — audit selectors, detect locale switch, generate overlay (run before `/sungen-run-test --env <locale>`) |
 
 **Screen path:** add-screen → create-test → review → run-test → delivery.

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

@@ -1,21 +1,51 @@
 ---
 name: sungen-delivery
-description: 'Export Gherkin scenarios + Playwright results → CSV test case deliverable. Auto-loaded by delivery command.'
+description: 'Export the Test Case & Coverage Matrix (or the legacy per-scenario CSV) from Gherkin + Playwright results. Auto-loaded by delivery command.'
 user-invocable: false
 ---
 
 ## Purpose
 
-Export test cases from Sungen screens and flows to a standardized CSV file (format BM-2-901-13) for QA delivery.
+Export test cases from Sungen units to the QA deliverable. Two modes:
 
-**This skill delegates all heavy work to the `sungen delivery` CLI.** The CLI is the single source of truth for parsing logic — do NOT re-parse files in AI. Your role is only to:
+- **Matrix (default)** — the **Test Case & Coverage Matrix**: one row per *delivery item* (one
+  target + one test intent + one oracle family); scenarios / `@cases` rows stay as collapsible
+  *coverage variant* sub-rows. Built for review, manual execution, customer hand-off, and
+  reporting — no numbered step dumps.
+- **Legacy (`--legacy`/`--full`)** — the classic per-scenario BM-2-901-13 workbook (documented
+  in the second half of this skill; unchanged).
 
-1. Invoke the CLI
-2. Show its output verbatim
-3. Help the user react to pre-flight failures
+**This skill delegates all heavy work to the `sungen delivery` CLI.** The CLI is the single source
+of truth for parsing + gating. The AI's only semantic contribution is **proposing the Delivery
+Map** (grouping) — everything else is: invoke the CLI, show output verbatim, help on failures.
 
 ---
 
+## Matrix mode — the Delivery Map
+
+`qa/<screens|flows|api>/<unit>/delivery/<unit>.map.yaml` — committed, AI-proposed
+(`review: proposed`), gate-validated, QA-approved (`sungen delivery --approve` stamps scenario
+fingerprints). Schema + grouping rules live in the delivery command instructions; the normative
+spec is `docs/spec/delivery-coverage-matrix-spec.md`.
+
+**Gates** (CLI `--check`): A source (VP-ids unique, oracle present, Background setup-only) ·
+B mapping (every scenario in exactly one group XOR one disposition) · C aggregation (mode/layer/
+priority recomputed and equal within a group — heuristic oracle-shape/precondition mismatches are
+review-level, silenced once approved and unchanged) · D executability (precondition · condition+
+data · trigger · oracle all renderable; every `{{var}}` resolves) · E drift (fingerprint mismatch
+→ back to review) · G review state (proposed groups block the official render; `--preview` renders
+a DRAFT watermark).
+
+**Workbook**: `Testcases` sheet (parent rows + outline-level-1 variant sub-rows — collapse for the
+customer view, expand to execute; result roll-up failed→blocked→not_run→partial→passed, counts like
+`7/8 Passed · 1 Failed`) + `Coverage` sheet (target × category grid with explicit `—` gaps,
+dispositions, generation manifest). CSV is flat with a `Level` column (`item`/`variant`).
+`delivery_item_count` ≠ progress — variants are the execution metric.
+
+---
+
+## Legacy mode (--legacy / --full)
+
 ## Architecture
 
 ```
@@ -85,7 +115,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/dist/orchestrator/templates/ai-src/skills/sungen-error-mapping/SKILL.md

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

package/dist/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/dist/orchestrator/templates/ai-src/skills/sungen-harness-audit/SKILL.md

@@ -66,7 +66,7 @@ Use these when repairing GATE/DEPTH findings for the hard viewpoints (cart/detai
 2. **Stop when** `gateStatus == PASS` AND `findings` empty — or budget exhausted.
 3. **Never fake a pass.** A shallow `see [Cart] page` does not satisfy `cart-correctness`. If a gap is genuinely cross-screen or needs capabilities the DSL lacks (e.g. capture an element value to compare elsewhere), **report it as a residual gap / flow item** instead of forcing a green gate.
 4. **EP/data families are OK.** A `duplicates` cluster with `sameDataLikely=false` is an intentional equivalence-partition family (e.g. many invalid-email cases) — keep it; only collapse `sameDataLikely=true` exact duplicates.
-5. **Advisory findings — surface, don't gate.** `MANUAL-REASON-MISMATCH` → fix the scenario's `@manual:Mx` code (so the planner recommends the right driver) during repair. `CAPABILITY-SUGGESTION` → **present it to the user as a next-step option** (e.g. "N @manual could be automated — `sungen capability add api db`?"), **recommend-only — never auto-install**. Neither fails the gate.
+5. **Advisory findings — surface, don't gate.** `MANUAL-REASON-MISMATCH` → fix the scenario's `@manual:Mx` code (so the planner recommends the right driver) during repair. `CAPABILITY-SUGGESTION` → **present it to the user as a next-step option** (e.g. "N @manual could be automated — `sungen capability add api db`?"), **recommend-only — never auto-install**. `VERIFICATION-OUT-OF-SCOPE (api|db)` → the unit uses `@api`/`@query`/`@requires:api|db` verification the project's recorded **test type** never opted into (E2E/UI-only per `capabilities.yaml`, and the viewpoint doesn't ask for it). During repair: **rewrite the oracle to be UI-observable** (or downgrade the deep check to an `(optional deep check: …)` note); only keep the API/DB verification if the project genuinely tests that layer — then record it (`verification: [ui, api]` / `sungen capability add`). Keep API/DB-in-E2E to the ≤20% band. Neither of these fails the gate.
 
 ## Discovery / fallback tree (when input is limited)
 

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

@@ -328,6 +328,7 @@ Security:         [S1 – admin only]
    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.
    **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.
+   **Respect the project's VERIFICATION SCOPE (the recorded test type).** Read `qa/capabilities.yaml` — the effective scope is `verification:` if set, else derived from `enabled` (`ui` always; `api`/`db` only if that driver is on). If the project is **E2E/UI-only** (no `api`/`db`) **and the test-viewpoint does not ask for API/DB verification**, do **NOT** author `@api`/`@query`/`@requires:api|db` verification — keep the oracle **UI-observable**, or leave the deep check as an `(optional deep check: …)` note. Author API/DB verification only when the scope (or an explicit viewpoint) calls for it, and even then keep the API/DB-in-E2E combination to a **≤20% band** of scenarios (the effects with no UI observation) — never the default. `sungen audit` reports `VERIFICATION-OUT-OF-SCOPE` when a unit uses API/DB verify the project never opted into.
    Use this comment shape:
    ```gherkin
    @high @manual

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.14",
+  "version": "3.2.16-beta.1",
   "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/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": "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/delivery-matrix.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/delivery-locale-env-discovery.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/codegen/table-match-data-column-mapping.run.ts && tsx tests/codegen/param-binding-native-type.run.ts && tsx tests/codegen/table-row-scope-redeclaration.run.ts && tsx tests/codegen/table-row-label-resolution.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.14",
-    "@sungen/driver-ui": "3.2.14",
+    "@sungen/driver-data-factory": "3.2.16-beta.1",
+    "@sungen/driver-ui": "3.2.16-beta.1",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

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,
@@ -24,6 +25,16 @@ import { renderXlsxMultiSheet, writeXlsx, buildApiDetailRows, addApiDetailSheet
 import { loadApiCatalog } from '../../exporters/api-catalog-loader';
 import { resolvePlatformAppId } from '../../exporters/mobile-app-id';
 import { EnvironmentInfo, PreflightCheck, ScreenSummary, TestCaseRow, ApiCatalogEntry } from '../../exporters/types';
+import { mapFilePath } from '../../exporters/matrix/map-loader';
+import {
+  MatrixTargetPaths,
+  loadMatrixModel,
+  approveMatrix,
+  writeMatrixDeliverables,
+  hasErrors,
+  hasReview,
+} from '../../exporters/matrix/export';
+import { MatrixFinding } from '../../exporters/matrix/types';
 
 const COLOR = {
   reset: '\x1b[0m',
@@ -167,70 +178,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 +474,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 +504,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 +545,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,
@@ -639,6 +607,114 @@ async function exportTarget(
   }
 }
 
+// ----------------------------------------------------------------------------
+// Matrix export (Delivery v2 — the default; --legacy keeps the classic workbook)
+// ----------------------------------------------------------------------------
+
+function matrixPathsFor(cwd: string, target: DeliveryTarget): MatrixTargetPaths {
+  const base = qaDir(cwd, target);
+  const genBase = generatedDir(cwd, target);
+  return {
+    cwd,
+    unit: target.featureBaseName,
+    label: target.isFlow ? `flow/${target.featureBaseName}` : target.featureBaseName,
+    featureFile: path.join(base, 'features', `${target.featureBaseName}.feature`),
+    testDataFile: resolveTestDataPathForTarget(cwd, target),
+    specFile: path.join(genBase, `${target.featureBaseName}.spec.ts`),
+    resultsPath: resolveResultsPath(cwd, target),
+    mapFile: mapFilePath(base, target.featureBaseName),
+  };
+}
+
+function printFindings(findings: MatrixFinding[]): void {
+  const icon = { error: `${COLOR.red}✗`, review: `${COLOR.yellow}⚠`, warning: `${COLOR.gray}·` } as const;
+  for (const f of findings) {
+    log(`  ${icon[f.severity]} [Gate ${f.gate}]${COLOR.reset} ${f.ref ? `${f.ref}: ` : ''}${f.message}`);
+  }
+}
+
+interface MatrixRunSummary {
+  label: string;
+  items: number;
+  variants: number;
+  passed: number;
+  failed: number;
+  file: string;
+}
+
+/**
+ * Matrix-mode export of one target. Returns null when blocked (missing map,
+ * gate errors, or unapproved groups without --preview) — the caller aggregates
+ * a non-zero exit.
+ */
+async function exportMatrixTarget(
+  cwd: string,
+  target: DeliveryTarget,
+  opts: { check?: boolean; preview?: boolean },
+): Promise<MatrixRunSummary | null> {
+  const paths = matrixPathsFor(cwd, target);
+  const { model, mapMissing, mapErrors } = loadMatrixModel(paths);
+
+  if (mapMissing) {
+    log(`${COLOR.yellow}${paths.label}: no delivery map${COLOR.reset} (${path.relative(cwd, paths.mapFile)})`);
+    log(`  The matrix needs the reviewed grouping (target / intent / oracle per delivery item).`);
+    log(`  ${COLOR.cyan}→ run /sungen:delivery ${target.screen} so the map is proposed for your review${COLOR.reset}`);
+    log(`  ${COLOR.cyan}→ or export the classic per-scenario workbook: sungen delivery ${target.screen} --legacy${COLOR.reset}`);
+    return null;
+  }
+  if (mapErrors.length > 0 || !model) {
+    log(`${COLOR.red}${paths.label}: delivery map is invalid${COLOR.reset}`);
+    for (const e of mapErrors) log(`  - ${e}`);
+    return null;
+  }
+
+  log(`${COLOR.bold}${paths.label}${COLOR.reset} — ${model.manifest.itemCount} delivery item(s), ${model.manifest.variantCount} coverage variant(s), state: ${model.manifest.approvalState}`);
+  printFindings(model.findings);
+
+  if (opts.check) {
+    // Gates-only run: the summary IS the output; exit code reflects errors.
+    return hasErrors(model.findings)
+      ? null
+      : { label: paths.label, items: model.manifest.itemCount, variants: model.manifest.variantCount, passed: 0, failed: 0, file: '(check only)' };
+  }
+  if (hasErrors(model.findings)) {
+    log(`  ${COLOR.red}blocked:${COLOR.reset} fix the Gate errors above, then re-run.`);
+    return null;
+  }
+  if (hasReview(model.findings) && !opts.preview) {
+    log(`  ${COLOR.yellow}not approved for official delivery.${COLOR.reset}`);
+    log(`  ${COLOR.cyan}→ approve the reviewed grouping: sungen delivery ${target.screen} --approve${COLOR.reset}`);
+    log(`  ${COLOR.cyan}→ or render a watermarked draft:  sungen delivery ${target.screen} --preview${COLOR.reset}`);
+    return null;
+  }
+
+  const { csvPath, xlsxPath } = await writeMatrixDeliverables(paths, model);
+  const passed = model.items.reduce((a, i) => a + i.resultCounts.passed, 0);
+  const failed = model.items.reduce((a, i) => a + i.resultCounts.failed, 0);
+  log(`  ${COLOR.green}→ ${path.relative(cwd, xlsxPath)}${COLOR.reset} ${COLOR.gray}(+ ${path.relative(cwd, csvPath)})${COLOR.reset}`);
+  return {
+    label: paths.label,
+    items: model.manifest.itemCount,
+    variants: model.manifest.variantCount,
+    passed,
+    failed,
+    file: path.relative(cwd, xlsxPath),
+  };
+}
+
+function printMatrixSummaryTable(summaries: MatrixRunSummary[]): void {
+  log(`\n${COLOR.bold}Delivery matrix export complete${COLOR.reset}\n`);
+  const colWidth = Math.max(20, ...summaries.map((s) => s.label.length)) + 1;
+  log(`  ${'Feature'.padEnd(colWidth)}Items  Variants  Passed  Failed  File`);
+  log('  ' + '-'.repeat(colWidth + 50));
+  for (const s of summaries) {
+    log(
+      `  ${s.label.padEnd(colWidth)}${String(s.items).padStart(5)}  ${String(s.variants).padStart(8)}  ${String(s.passed).padStart(6)}  ${String(s.failed).padStart(6)}  ${s.file}`
+    );
+  }
+  log(`\n${COLOR.gray}Items = review rows (one target + intent + oracle family). Variants = execution units — use variant counts for progress.${COLOR.reset}\n`);
+}
+
 // ----------------------------------------------------------------------------
 // Reporter
 // ----------------------------------------------------------------------------
@@ -709,12 +785,24 @@ function printSummaryTable(summaries: ScreenSummary[]): void {
 export function registerDeliveryCommand(program: Command): void {
   program
     .command('delivery')
-    .description('Export Gherkin + Playwright results → CSV test case deliverable')
+    .description('Export the Test Case & Coverage Matrix (Gherkin + results). --legacy keeps the classic per-scenario workbook.')
     .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)')
+    .option('--legacy', 'Classic per-scenario-steps workbook (BM-2-901-13 layout)')
+    .option('--full', 'Alias of --legacy')
+    .option('--check', 'Matrix gates only — validate the delivery map, write nothing')
+    .option('--approve [ids]', 'Approve proposed groups (all, or a comma-separated id list) + stamp fingerprints')
+    .option('--preview', 'Render the matrix despite review-required findings (DRAFT watermark)')
+    .action(async (names: string[], options: {
+      skipPreflight?: boolean; continueOnMissing?: boolean; env?: string;
+      legacy?: boolean; full?: boolean; check?: boolean; approve?: boolean | string; preview?: boolean;
+    }) => {
       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
@@ -766,6 +854,46 @@ export function registerDeliveryCommand(program: Command): void {
         }
 
         // 3. Export
+        const legacy = options.legacy || options.full;
+        if (!legacy) {
+          // Matrix mode (the default). --approve is its own sub-action.
+          if (options.approve !== undefined) {
+            const ids = typeof options.approve === 'string'
+              ? options.approve.split(',').map((s) => s.trim()).filter(Boolean)
+              : undefined;
+            let blocked = false;
+            for (const target of toExport) {
+              const paths = matrixPathsFor(cwd, target);
+              try {
+                const { findings, approved } = approveMatrix(paths, ids);
+                if (approved.length === 0) {
+                  log(`${COLOR.red}${paths.label}: approval blocked by Gate errors${COLOR.reset}`);
+                  printFindings(findings);
+                  blocked = true;
+                } else {
+                  log(`${COLOR.green}${paths.label}: approved ${approved.length} group(s)${COLOR.reset} — fingerprints stamped in ${path.relative(cwd, paths.mapFile)}`);
+                }
+              } catch (e) {
+                log(`${COLOR.red}${paths.label}:${COLOR.reset} ${e instanceof Error ? e.message : e}`);
+                blocked = true;
+              }
+            }
+            if (blocked) process.exit(1);
+            return;
+          }
+
+          const matrixSummaries: MatrixRunSummary[] = [];
+          let failedTargets = 0;
+          for (const target of toExport) {
+            const s = await exportMatrixTarget(cwd, target, { check: options.check, preview: options.preview });
+            if (s) matrixSummaries.push(s);
+            else failedTargets++;
+          }
+          if (matrixSummaries.length > 0 && !options.check) printMatrixSummaryTable(matrixSummaries);
+          if (failedTargets > 0) process.exit(1);
+          return;
+        }
+
         const env = getEnvironment(cwd);
         const summaries: ScreenSummary[] = [];
         for (const target of toExport) {