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

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

@@ -1,21 +1,117 @@
 ---
 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 (test layer
+recomputed and equal within a group — **execution mode and priority are coverage dimensions, not
+splits**: mixed items show `Auto n · Manual m` and take the highest variant priority; 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; **no template token may survive
+into a rendered cell** — test-data cross-references are resolved for display) · E drift
+(scenario fingerprint mismatch → back to review; the map's OWN reviewed
+wording/grouping is fingerprinted as `__map__` too, so post-approval edits re-open review) · G review state (proposed groups block the official
+render; `--preview` renders a DRAFT watermark) · K category class (a `VP-SEC-*` variant outside
+`category: security`, or `VP-NFR-*` outside `nfr` → warning: the Coverage grid's column would render
+empty and report a false gap) · R requirement coverage (spec FR/TR/NFR ids with no trace and no
+`requirements:` status → warning; **and a `status: covered` override that no variant traces to** →
+warning: tag the proving scenario `@spec:<id>` instead of asserting it in prose) · W wording lint (map intent/oracle containing
+tokens, `[Selector]` refs, DSL phrasing, or generator labels → warning).
+
+**Wording normalization (deterministic, after semantic normalization):** DSL steps render as
+controlled manual-test English without changing meaning — actions in the imperative (`User fill
+[Email] field with X` → `Enter X in the Email field.`), expected results as observable assertions
+(`User see [Jobs] page` → `The Jobs page is displayed.`), preconditions as states (`The user is
+signed out.`). Manual `# Tester verifies:` labels become structured fields: `Setup:` →
+Precondition, `Action:` → Action, `Observable:` → Expected Result, `Oracle:` → a separate
+`Verification method:` line. Sequence-sensitive flows keep event order: actions numbered with
+mid-flow assertions inline as `Verify: …`; only the final Then block is the Expected Result.
+Empty test values render as `(empty)`.
+
+**Output format**: **XLSX only by default** (one artifact). `--format csv` writes the flat CSV
+instead; `--format both` writes both.
+
+**Scope decides strictness**: a **named** unit that is not ready aborts with exit 1 (pass
+`--continue-on-missing` to tolerate it); a **no-argument sweep** exports every ready unit, lists
+every unit it did not export with the reason, and exits 0 as long as it wrote something — a
+scaffolded unit never blocks the ready ones.
+
+**Workbook**: `Testcases` sheet — parent rows + outline-level-1 variant sub-rows for **every**
+item (single-variant included: the sub-row carries the source VP-id, resolved data, and the
+result/evidence entry). Sub-rows are **delta-only**: knowledge common to the whole item
+(precondition, trigger) is written ONCE on the parent; a child repeats only what distinguishes it
+(condition/data, precondition delta, trigger when it differs) plus its own precise oracle and
+execution fields. The parent never carries placeholder text — when triggers differ the cell is
+simply empty and the sub-rows carry them.
+
+Parent preconditions are the **intersection** of the variants' and the parent's Action holds the
+**shared leading steps**; each variant renders only its remaining steps, numbered to continue the
+parent's list — so a shared prefix is written once, not repeated on every child. The parent's
+Coverage cell is the map's short `dimensions:` digest (or the variant refs when none is declared),
+never a concatenation of variant titles.
+
+Variant Result cells hold exactly one of `Passed`/`Failed`/`Blocked`/`Pending`/`N/A` (dropdown) —
+that vocabulary is the contract: the parent Result and the summary band are **live Excel formulas**
+counting those words, so a parent label is always a composed `n/m Passed …` string (`All N/A` when
+every variant is N/A) and never a bare state word. **`N/A` leaves the denominator.** Evidence and
+Defect ID are separate columns; ID + Target frozen; ISO dates; landscape print with repeated
+header rows.
+
+`Coverage` sheet — requirement coverage table (every FR/TR/NFR id with an explicit status),
+target × category grid with explicit `—` gaps, dispositions, manifest. CSV mirrors the same model
+flat with a `Level` column (`item`/`variant`) + a requirement-coverage appendix.
+`delivery_item_count` ≠ progress — variants are the execution metric.
+
+**Id schemes**: the `VP-<CAT>-<NNN>` convention is a suggestion, not a requirement — a project's own
+scheme (`SEC-123`, `PER-345`, `MS-HP-001`) is addressed the same way, and the category segment
+(`SEC`, `PER`) still drives Gate K. Requirement ids come from the spec's own bolded declarations
+(`- **REQ-12**: …`), so a project that does not use FR/TR/NFR still gets its coverage table.
+
+**Runtime-captured values**: a scenario may produce its own values — `User remember [X] text as
+{{v}}` (compared later) or a capability binding (`@query:`/`@api:`/`@dataFactory:`). These never
+exist in test-data, so Gate D does not ask for them: the capture step renders as an instruction
+(`Note the X text for later (as "v")`) and later references read `the captured v`.
+
+**Data fidelity**: invisible test data is made visible, never normalized — `''` → `(empty)`,
+whitespace-only → `(5 spaces)`, padded → `" value "` quoted verbatim. A trim/collapse here would
+silently break the whitespace tests it describes.
+
+**Authoring guidance the matrix rewards** (create-test side): payload/provider matrices (SQLi
+payload lists, OAuth provider sets) belong in `@cases` datasets so each case is an atomic,
+independently-reportable variant; keep dataset `case:` labels short and stable (`CHK-EMAIL-I1`),
+with descriptions in other columns — the label is part of the variant's identity.
+
+---
+
+## Legacy mode (--legacy / --full)
+
 ## Architecture
 
 ```

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

@@ -288,6 +288,7 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 
 | Tag | Effect |
 |---|---|
+| `@spec:<id>` | **Traceability**: this scenario proves requirement `<id>` from `requirements/spec.md` (`@spec:FR-003`). Repeatable — a scenario may prove several. Read by `sungen audit` (requirement coverage) and by delivery (the Coverage sheet's requirement table). Without it the link is only inferred from wording and cannot survive an edit. |
 | `@manual` | Skip in generation |
 | `@auth:role` | Use auth storage state for role |
 | `@no-auth` | Disable inherited auth |

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

@@ -4,6 +4,28 @@ description: 'Use when create-test needs to translate spec.md/Figma/UI into .fea
 user-invocable: false
 ---
 
+
+## Traceability — tag the requirement each scenario proves
+
+Every requirement id in `requirements/spec.md` (`FR-`/`TR-`/`NFR-`) must be reachable from a
+scenario, and the link must be **written down, not inferred**:
+
+```gherkin
+@high @spec:FR-003
+Scenario: VP-VAL-002 An email in an invalid format shows the format error
+```
+
+- Put `@spec:<id>` on the scenario that actually proves the requirement; repeat the tag when one
+  scenario proves several (`@spec:FR-003 @spec:FR-004`).
+- One requirement may be proved by several scenarios — tag each of them.
+- A requirement you deliberately do not cover here (performance budget, i18n suite, server-side
+  concern) needs no tag; record it later in the delivery map's `requirements:` section with a
+  status and reason.
+- Why it matters: `sungen audit` also counts a requirement as covered when its keywords merely
+  resemble a scenario title, and reports `SPEC-TRACE-IMPLICIT` for those. Delivery's requirement
+  table follows **only** the explicit tag — an untagged requirement reads as an uncovered gap in
+  the customer-facing coverage sheet even when a scenario does prove it.
+
 ## ⚠️ Gotchas — read before generating
 
 - **Field-level test-data follows the Data Factory standard — don't hand-invent values.** When the unit has input fields, the field values (valid / boundary / invalid + error codes) come from the **`sungen-data-factory`** catalog via a field-map + `sungen data gen` (create-test step 5.3), not free-form guessing. Weave the standardized boundary/invalid sets into `@cases` with `CHK-*` trace. This skill still owns scenario structure, viewpoints, and non-field oracles.
@@ -328,6 +350,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.10",
   "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/delivery-scope-strictness.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/harness/spec-trace-crlf.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.10",
+    "@sungen/driver-ui": "3.2.16-beta.10",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

package/src/cli/commands/delivery.ts

@@ -25,6 +25,17 @@ 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,
+  MatrixFormat,
+  hasErrors,
+  hasReview,
+} from '../../exporters/matrix/export';
+import { MatrixFinding } from '../../exporters/matrix/types';
 
 const COLOR = {
   reset: '\x1b[0m',
@@ -597,6 +608,129 @@ 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`),
+    specMdFile: path.join(base, 'requirements', 'spec.md'),
+    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; format?: MatrixFormat },
+): 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, opts.format ?? 'xlsx');
+  const passed = model.items.reduce((a, i) => a + i.resultCounts.passed, 0);
+  const failed = model.items.reduce((a, i) => a + i.resultCounts.failed, 0);
+  const written = [xlsxPath, csvPath].filter((p): p is string => !!p).map((p) => path.relative(cwd, p));
+  for (const rel of written) log(`  ${COLOR.green}→ ${rel}${COLOR.reset}`);
+  return {
+    label: paths.label,
+    items: model.manifest.itemCount,
+    variants: model.manifest.variantCount,
+    passed,
+    failed,
+    file: written.join(' + '),
+  };
+}
+
+/**
+ * One place that accounts for every target the run did NOT write, so a sweep is
+ * never silently partial: scaffolds skipped by preflight and units whose gates /
+ * missing map stopped the export.
+ */
+function printSkipSummary(skipped: string[], notExported: string[]): void {
+  if (skipped.length === 0 && notExported.length === 0) return;
+  log(`${COLOR.gray}Not exported (${skipped.length + notExported.length}):${COLOR.reset}`);
+  for (const s of skipped) log(`  ${COLOR.gray}· ${s}${COLOR.reset}`);
+  for (const n of notExported) log(`  ${COLOR.gray}· ${n} (see the message above)${COLOR.reset}`);
+  log('');
+}
+
+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(s)`);
+  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,23 +801,41 @@ 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)')
+    .option('--format <format>', 'Matrix output format: xlsx (default) | csv | both', 'xlsx')
+    .action(async (names: string[], options: {
+      skipPreflight?: boolean; continueOnMissing?: boolean; env?: string;
+      legacy?: boolean; full?: boolean; check?: boolean; approve?: boolean | string; preview?: boolean;
+      format?: string;
+    }) => {
       try {
         // Same effect as running with SUNGEN_ENV=<env> — result-file resolution,
         // locale pairing, and test-data overlays all key off this one string.
         if (options.env) process.env.SUNGEN_ENV = options.env;
         const cwd = process.cwd();
 
+        // Matrix output format — one artifact by default (xlsx); csv/both on request.
+        const format = (options.format ?? 'xlsx').toLowerCase();
+        if (!['xlsx', 'csv', 'both'].includes(format)) {
+          console.error(`${COLOR.red}Invalid --format "${options.format}"${COLOR.reset} — use xlsx | csv | both`);
+          process.exit(1);
+        }
+
         // 1. Scope detection — each positional name expands into one target
         //    per `.feature` file inside that screen/flow. Passing a specific
         //    feature basename (e.g. `home-modal`) narrows to that one file.
         let targets: DeliveryTarget[];
-        if (names && names.length > 0) {
+        const explicitScope = !!(names && names.length > 0);
+        if (explicitScope) {
           targets = names.flatMap((n) => resolveTargetsFromArg(cwd, n));
         } else {
           targets = listAllTargets(cwd);
@@ -696,8 +848,13 @@ export function registerDeliveryCommand(program: Command): void {
         const labels = targets.map((t) => t.isFlow ? `flow/${t.featureBaseName}` : t.featureBaseName);
         log(`${COLOR.bold}sungen delivery${COLOR.reset} — exporting ${targets.length} feature(s): ${labels.join(', ')}\n`);
 
-        // 2. Pre-flight
+        // 2. Pre-flight — strictness follows the SCOPE. Naming a unit means "I want
+        //    this one" (fail loudly); a no-argument sweep means "export everything
+        //    that is ready", so scaffolded units (added but not yet authored) are
+        //    skipped with a note instead of aborting the whole run — otherwise one
+        //    untouched scaffold in a work-in-progress project produces zero files.
         let toExport: DeliveryTarget[];
+        const skipped: string[] = [];
         if (options.skipPreflight) {
           toExport = targets;
         } else {
@@ -706,28 +863,79 @@ export function registerDeliveryCommand(program: Command): void {
 
           const blockers = checks.filter(hasBlockingMissing);
           if (blockers.length > 0) {
-            if (options.continueOnMissing) {
-              const passedScreens = new Set(
-                checks.filter((c) => !hasBlockingMissing(c)).map((c) => c.screen)
-              );
-              toExport = targets.filter((t) => {
-                const label = t.isFlow ? `flow/${t.featureBaseName}` : t.featureBaseName;
-                return passedScreens.has(label);
-              });
-              log(`${COLOR.yellow}Continuing with ${toExport.length} ready target(s).${COLOR.reset}\n`);
-            } else {
+            if (explicitScope && !options.continueOnMissing) {
               console.error(
-                `${COLOR.red}Aborted:${COLOR.reset} ${blockers.length} target(s) have blocking issues.\n` +
+                `${COLOR.red}Aborted:${COLOR.reset} ${blockers.length} named target(s) have blocking issues.\n` +
                 `Run the suggested commands above, or use ${COLOR.cyan}--continue-on-missing${COLOR.reset} to skip them.`
               );
               process.exit(1);
             }
+            const readyLabels = new Set(
+              checks.filter((c) => !hasBlockingMissing(c)).map((c) => c.screen)
+            );
+            toExport = targets.filter((t) => {
+              const label = t.isFlow ? `flow/${t.featureBaseName}` : t.featureBaseName;
+              return readyLabels.has(label);
+            });
+            for (const b of blockers) skipped.push(`${b.screen} (not authored yet — run /sungen:create-test)`);
+            log(`${COLOR.yellow}Skipping ${blockers.length} target(s) that have no test cases yet; continuing with ${toExport.length}.${COLOR.reset}\n`);
           } else {
             toExport = targets;
           }
         }
 
         // 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[] = [];
+          const notExported: string[] = [];
+          for (const target of toExport) {
+            const s = await exportMatrixTarget(cwd, target, {
+              check: options.check, preview: options.preview, format: format as MatrixFormat,
+            });
+            if (s) matrixSummaries.push(s);
+            else notExported.push(target.isFlow ? `flow/${target.featureBaseName}` : target.featureBaseName);
+          }
+          if (matrixSummaries.length > 0 && !options.check) printMatrixSummaryTable(matrixSummaries);
+          printSkipSummary(skipped, notExported);
+          // A named target that produced nothing is a failure. A sweep is a failure
+          // only when it produced nothing at all — units still waiting for a map or
+          // an approval are the normal state of a live project. Preflight skips are
+          // not counted here: reaching this point in an explicit scope means
+          // --continue-on-missing was passed, which IS the opt-in to tolerate them.
+          const failed = explicitScope
+            ? notExported.length > 0
+            : matrixSummaries.length === 0;
+          if (failed) process.exit(1);
+          return;
+        }
+
         const env = getEnvironment(cwd);
         const summaries: ScreenSummary[] = [];
         for (const target of toExport) {
@@ -737,6 +945,10 @@ export function registerDeliveryCommand(program: Command): void {
 
         // 4. Summary
         printSummaryTable(summaries);
+        printSkipSummary(skipped, []);
+        // Same rule as the matrix path: every attempted target in an explicit scope
+        // must have produced a file; a sweep only fails when nothing was written.
+        if (explicitScope ? summaries.length < toExport.length : summaries.length === 0) process.exit(1);
       } catch (err) {
         console.error(`${COLOR.red}Fatal:${COLOR.reset} ${err instanceof Error ? err.message : err}`);
         process.exit(1);