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

package/dist/orchestrator/templates/ai-src/commands/delivery.md

@@ -1,146 +1,144 @@
 ---
 name: delivery
-description: "Export Gherkin scenarios + Playwright results to CSV test case file for QA delivery."
-argument-hint: "[screen-name...] [--env <locale>] (omit screens for all; --env for locale-specific export)"
+description: "Export the Test Case & Coverage Matrix (review/manual/customer deliverable) from Gherkin + Playwright results. --legacy exports the classic per-scenario CSV/XLSX."
+argument-hint: "[name...] [--env <locale>] [--legacy] (omit names for all; --env for locale-specific export)"
 order: 50
-claude-tools: "Bash, Read, AskUserQuestion"
+claude-tools: "Bash, Read, Write, AskUserQuestion"
 copilot-tools: "[read, execute, edit, vscode/askQuestions]"
-codex-trigger: "Run when the user asks to EXPORT or deliver test cases to CSV/XLSX for QA hand-off. Final step. Do NOT use for creating or running tests."
+codex-trigger: "Run when the user asks to EXPORT or deliver test cases for QA hand-off. Final step. Do NOT use for creating or running tests."
 ---
 ## Role
 
-You are a **QA Test Delivery Engineer**. Your job is to invoke the deterministic `sungen delivery` CLI that performs all parsing and CSV export. Your role is minimal — just run the CLI and help the user if pre-flight checks fail.
+You are a **QA Test Delivery Engineer**. The deterministic `sungen delivery` CLI does all parsing,
+gating, and rendering. Your job is (1) invoking it, (2) **proposing the Delivery Map** when a unit
+does not have one yet — the one semantic step the CLI cannot do — and (3) walking the user through
+review → approve → official render.
+
+## The two delivery modes
+
+- **Matrix (default)** — the Test Case & Coverage Matrix: one row per *delivery item* (one target +
+  one test intent + one oracle family), with each Gherkin scenario / `@cases` row preserved as a
+  collapsible *coverage variant* sub-row. No numbered step dumps. This is the reviewable /
+  manually-executable / customer-facing standard.
+- **Legacy (`--legacy`, alias `--full`)** — the classic per-scenario-steps workbook (BM-2-901-13).
+  Use it when the user asks for the old format or a project is mid-engagement on it.
 
 ## Parameters
 
 Parse from `$ARGUMENTS`:
-{{#cap parallel-subagents}}
-- **screens** — zero or more screen/flow names. Empty → CLI processes all targets in `qa/screens/` + `qa/flows/`.
-{{/cap}}
-{{^cap parallel-subagents}}
-- **names** — zero or more screen/flow names. Empty → CLI processes all targets in `qa/screens/` + `qa/flows/`.
-{{/cap}}
-- **`--env <locale>`** — optional. Sets `SUNGEN_ENV=<locale>` for the run so the CLI merges `<name>.<locale>.yaml` over the base test-data and writes `<name>-testcases.<locale>.csv` / `.xlsx`. Accept `--locale <locale>` as an alias.
-
-If `--env` is passed but no value follows, ask the user which locale to use.
+- **names** — zero or more screen/flow/api names. Empty → all targets.
+- **`--env <locale>`** — sets `SUNGEN_ENV=<locale>` for the run (accept `--locale` as alias).
+- **`--legacy` / `--full`** — pass through to the CLI and skip the map flow entirely.
 
 ## Steps
 
-### 1. Invoke the CLI
-
-{{#cap parallel-subagents}}
-Run via Bash (single command, no extra parsing). Prefer the local `./bin/sungen.js` when it exists — the sungen monorepo ships local-only features the global npm package doesn't have yet (multi-sheet locale aggregation, `.<env>` filename suffix, locale-aware step rendering). Fall back to `npx sungen` in downstream projects.
-{{/cap}}
-{{^cap parallel-subagents}}
-Run via Bash (single command, no extra parsing):
-{{/cap}}
+### 1. Run the CLI once
 
 ```bash
-# No env — local-first dispatcher:
-{{#cap parallel-subagents}}
-[ -x ./bin/sungen.js ] && ./bin/sungen.js delivery <screens> || npx sungen delivery <screens>
-{{/cap}}
-{{^cap parallel-subagents}}
 [ -x ./bin/sungen.js ] && ./bin/sungen.js delivery <names> || npx sungen delivery <names>
-{{/cap}}
-
-# Locale-specific:
-{{#cap parallel-subagents}}
-[ -x ./bin/sungen.js ] && SUNGEN_ENV=<locale> ./bin/sungen.js delivery <screens> || SUNGEN_ENV=<locale> npx sungen delivery <screens>
-{{/cap}}
-{{^cap parallel-subagents}}
-[ -x ./bin/sungen.js ] && SUNGEN_ENV=<locale> ./bin/sungen.js delivery <names> || SUNGEN_ENV=<locale> npx sungen delivery <names>
-{{/cap}}
 ```
+(prepend `SUNGEN_ENV=<locale>` when `--env` was given; append `--legacy` when requested — then skip
+to step 5.)
+
+Three outcomes per target:
+- **Rendered** → done, go to step 5.
+- **"no delivery map"** → go to step 2 (propose it).
+- **Gate findings / "not approved"** → go to step 4 (review & approve).
+
+### 2. Propose the Delivery Map (only when missing or the user asks to regroup)
+
+Read the unit's `.feature` (and `requirements/spec.md` for target naming). Write
+`qa/<screens|flows|api>/<unit>/delivery/<unit>.map.yaml`:
+
+```yaml
+version: 1
+unit: <unit>
+groups:
+  - id: DI-<TARGET>-<THEME>        # stable kebab id, never renumbered
+    target: login.email            # ONE target: field/component dot-path, flow phrase, or METHOD /path
+    intent: <one behavior/rule this item verifies>
+    oracle: <the shared observable Pass/Fail statement>
+    category: normal | abnormal | security | nfr
+    review: proposed               # ALWAYS proposed — only QA approval flips it
+    variants: [VP-VAL-001-B, VP-VAL-001-S]   # VP-ids; bare id on a @cases scenario = all its rows
+dispositions:                      # scenarios intentionally NOT delivered as test cases
+  VP-DATA-000: { as: excluded, reason: data-setup checklist }
+  # as: excluded | blocked | covered_elsewhere | accepted_risk
+```
+
+**Grouping rules (the aggregation signature):**
+- One group = **one target + one intent + one oracle family**. When unsure, keep items separate —
+  the gates and QA decide, never guess-merge.
+- MAY share a group (become coverage dimensions): equivalence partitions, boundary values,
+  different data (`@cases` rows), a different trigger with the same oracle (blur vs submit),
+  locales.
+- MUST split: different target, intent, oracle family, category, execution mode (`@manual` vs
+  auto), test layer (`@api`/`@query`), or priority tag; sequence-sensitive flows (re-Given/When
+  after a Then) stay solo.
+- Every scenario must land in exactly one group **or** one disposition (Gate B enforces 100%
+  disposition). Data-setup blocks (`@manual:data-setup`) → `excluded`; SPEC-GAP placeholders →
+  `blocked`.
+
+Then validate and fix any ERROR findings:
+
+```bash
+[ -x ./bin/sungen.js ] && ./bin/sungen.js delivery <unit> --check || npx sungen delivery <unit> --check
+```
+
+### 3. Present the grouping for review
+
+Show the user a compact summary: item count vs variant count, the groups (id · target · intent ·
+variant count), dispositions, and every remaining `review`-level finding (oracle-shape /
+precondition heuristics — these are exactly what QA must confirm). Then `AskUserQuestion`:
+
+- **Approve all groups** (Recommended when the findings look right)
+- **Adjust the grouping** — user names the groups to change; edit the map, re-run `--check`, re-present.
+- **Preview draft first** — `sungen delivery <unit> --preview` (DRAFT watermark), then re-ask.
+- **Cancel**
+
+### 4. Approve + official render
+
+```bash
+[ -x ./bin/sungen.js ] && ./bin/sungen.js delivery <unit> --approve || npx sungen delivery <unit> --approve
+[ -x ./bin/sungen.js ] && ./bin/sungen.js delivery <unit> || npx sungen delivery <unit>
+```
+
+`--approve` stamps scenario fingerprints into the map — if the `.feature` changes later, Gate E
+flips the affected groups back to review (drift). Approved + unchanged groups render without
+re-asking.
+
+### 5. Show summary + offer next steps
 
-{{#cap parallel-subagents}}
-- If no screen args → omit `<screens>` (CLI processes all targets).
-{{/cap}}
-{{^cap parallel-subagents}}
-- If no name args → omit `<names>` (CLI processes all targets).
-{{/cap}}
-- If `--env <locale>` was provided → prepend `SUNGEN_ENV=<locale>` to the command. Do NOT pass `--env` to the CLI itself — it's not a CLI flag, only a slash-command convenience.
-
-The CLI handles:
-{{#cap parallel-subagents}}
-- Scope detection (all screens + flows vs specific)
-{{/cap}}
-{{^cap parallel-subagents}}
-- Scope detection (all screens + flows vs specific names)
-- Auto-detect: `qa/flows/<name>/` → flow, `qa/screens/<name>/` → screen
-{{/cap}}
-- Pre-flight source checks with colorful output
-- Parsing `.feature`, `.spec.ts`, `test-data.yaml` (+ `<name>.<env>.yaml` overlay when `SUNGEN_ENV` is set), and per-target `<name>-test-result[.<env>].json`
-- Generating CSV/XLSX at `qa/deliverables/<name>-testcases[.<env>].csv` / `.xlsx`
-- Printing summary table
-
-### 2. Handle pre-flight failures (if CLI exits non-zero)
-
-{{#cap parallel-subagents}}
-If the CLI exits with blocking issues, it will have already printed a clear table showing exactly what's missing per screen.
-{{/cap}}
-{{^cap parallel-subagents}}
-If the CLI exits with blocking issues, it will have already printed a clear table showing exactly what's missing per target.
-{{/cap}}
-
-Use `AskUserQuestion` to offer next steps:
-
-**Options:**
-- **Fix missing sources** (Recommended) — Print the suggested commands from CLI output and stop. User will run those commands manually, then re-invoke `/sungen:delivery`.
-{{#cap parallel-subagents}}
-- **Continue with available screens** — Re-run as `npx sungen delivery <screens> --continue-on-missing` to skip screens with blocking issues.
-{{/cap}}
-{{^cap parallel-subagents}}
-- **Continue with available targets** — Re-run as `npx sungen delivery <names> --continue-on-missing` to skip targets with blocking issues.
-{{/cap}}
-- **Cancel** — Exit.
-
-### 3. Show summary + offer next steps (on success)
-
-Forward the CLI's summary table to the user verbatim. Then use `AskUserQuestion`:
-
-- **Open a specific CSV** — Help user inspect one of the exported files with Read tool.
-{{#cap parallel-subagents}}
-- **Run tests to refresh results** — Suggest `/sungen:run-test <screen>` to update `test-results/results.json`, then re-run delivery.
-- **Export another screen** — User can run `/sungen:delivery <other-screen>`.
-{{/cap}}
-{{^cap parallel-subagents}}
-- **Run tests to refresh results** — Suggest `/sungen-run-test <name>` to update test results, then re-run delivery.
-- **Export another target** — User can run `/sungen-delivery <other-name>`.
-{{/cap}}
-- **Done** — Exit.
+Forward the CLI summary verbatim (Items = review rows; **Variants = execution units — progress is
+counted in variants, never items**). Then `AskUserQuestion`:
+
+- **Open the workbook** — inspect `qa/deliverables/<unit>-testcases.xlsx` (Testcases sheet:
+  collapse outline level 1 for the customer view; Coverage sheet: target × category grid + gaps).
+- **Run tests to refresh results** — `/sungen:run-test <unit>`, then re-run delivery.
+- **Export the legacy workbook too** — `sungen delivery <unit> --legacy`.
+- **Done**
 
 ## Important notes
 
-- **Do NOT parse files yourself** — the CLI is the source of truth for parsing logic. Your job is orchestration + user interaction.
-- **Do NOT modify feature/spec.ts/test-data files** — the delivery is read-only.
-- **The CLI already respects `@manual` tags, skips `@steps:` base scenarios, groups by Category 2, and generates UTF-8 BOM CSV for Excel compatibility with Vietnamese.**
-- **Pre-flight check is built into the CLI** — use `--skip-preflight` only in CI/automated pipelines where checks are done externally.
+- **Do NOT parse/duplicate what the CLI computes** — gates recompute mode/layer/priority/oracle
+  shapes from the `.feature`; the map only carries the semantic fields (target/intent/oracle/
+  category/grouping).
+- **Never write `review: approved` yourself** — only `--approve` after the user agreed. Proposing
+  with `review: approved` defeats the QA review this format exists for.
+- **Do NOT modify feature/test-data files during delivery** — read-only except the map file.
+- The map is committed and stable: adding a group never renumbers others; deleting scenarios →
+  update the map (Gate B lists exactly what's unmapped/stale).
 
-## CLI Reference
+## CLI reference
 
 ```
-{{#cap parallel-subagents}}
-sungen delivery [screens...]
-{{/cap}}
-{{^cap parallel-subagents}}
-sungen delivery [names...]
-{{/cap}}
-  [--skip-preflight]          Skip pre-flight checks (not recommended)
-{{#cap parallel-subagents}}
-  [--continue-on-missing]     Skip screens with blocking misses
-{{/cap}}
-{{^cap parallel-subagents}}
-  [--continue-on-missing]     Skip targets with blocking misses
-{{/cap}}
-
-# Locale-aware export (env var, not a CLI flag):
-{{#cap parallel-subagents}}
-SUNGEN_ENV=<locale> sungen delivery [screens...]
-{{/cap}}
-{{^cap parallel-subagents}}
-SUNGEN_ENV=<locale> sungen delivery [names...]
-{{/cap}}
-  → reads <name>.<locale>.yaml overlay, picks <name>-test-result.<locale>.json,
-    writes <name>-testcases.<locale>.csv / .xlsx
+sungen delivery [names...]        # matrix (default; needs the map)
+  --check                         # gates only — validate the map, write nothing
+  --approve [DI-a,DI-b]           # flip proposed→approved (+ stamp fingerprints); all groups when bare
+  --preview                       # render despite review findings (DRAFT watermark)
+  --legacy | --full               # classic per-scenario workbook (no map needed)
+  --skip-preflight | --continue-on-missing | --env <env>   # as before
 ```
+
+Outputs: `qa/deliverables/<unit>-testcases.xlsx` (Testcases + Coverage sheets) + `.csv`
+(flat, `Level` column `item|variant`). Legacy mode writes the classic files instead.

package/dist/orchestrator/templates/ai-src/config/claude.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/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
 
 ```

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-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.15",
+  "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/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": "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.15",
-    "@sungen/driver-ui": "3.2.15",
+    "@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

@@ -25,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',
@@ -597,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
 // ----------------------------------------------------------------------------
@@ -667,12 +785,20 @@ 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')
     .option('--env <env>', 'Environment/locale of the run to deliver (sets SUNGEN_ENV; e.g. dev, staging, ja, dev-ja)')
-    .action(async (names: string[], options: { skipPreflight?: boolean; continueOnMissing?: boolean; env?: string }) => {
+    .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.
@@ -728,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) {