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

package/src/harness/annotation-overrides.ts

@@ -2,10 +2,13 @@
  * Shared annotation-override grammar for precondition annotations (`@query`/`@api`).
  *
  * Parses `name(a={{x}},b="lit",c=3)` overrides into a map of JS expressions, e.g.
- * `{ a: "testData.get('x')", b: "\"lit\"", c: "3" }`. Used by the DB and API capability drivers'
+ * `{ a: "testData.raw('x')", b: "\"lit\"", c: "3" }`. Used by the DB and API capability drivers'
  * precondition codegen; lives in core so both drivers can share it. Gherkin tags carry no whitespace,
  * so values are single tokens — flows thread a prior response via a whole-value ref, e.g.
  * `@api:get_profile(token={{login.body.token}})`, with the auth scheme declared in the catalog header.
+ * A `{{ref}}` override binds into a typed sink (DB query param, JSON request body), so it resolves
+ * via `testData.raw()` (native type, still interpolates embedded refs) rather than `get()`
+ * (Gherkin-text stringify) — a numeric override otherwise reaches the DB/API as a JSON string.
  */
 export function parseQueryOverrides(raw?: string): Record<string, string> {
   const out: Record<string, string> = {};
@@ -18,7 +21,7 @@ export function parseQueryOverrides(raw?: string): Record<string, string> {
     if (!key) continue;
     const v = val.match(/^\{\{\s*([^}]+?)\s*\}\}$/);
     const q = val.match(/^["'](.*)["']$/);
-    if (v) out[key] = `testData.get(${JSON.stringify(v[1])})`;
+    if (v) out[key] = `testData.raw(${JSON.stringify(v[1])})`;
     else if (q) out[key] = JSON.stringify(q[1]);
     else if (/^-?\d+(?:\.\d+)?$/.test(val)) out[key] = val;
     else out[key] = JSON.stringify(val);

package/src/harness/audit.ts

@@ -17,7 +17,7 @@ import {
 } from './sensors';
 import { loadFlowScenarios } from './flow-check';
 import { manualReasonMismatches, MANUAL_REASONS, buildPlan } from './capability-plan';
-import { readCapabilities } from './capability';
+import { readCapabilities, verificationScopeFindings } from './capability';
 import { readIntent, projectRootFromScreenDir, IntentProfile } from './intent';
 import { getProvenance, Provenance } from './provenance';
 import { specCoverage, SpecCoverageResult, parseSpecClauses } from './spec-coverage';
@@ -129,7 +129,8 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   discoverAndRegisterCapabilities();
   // The active platform (web | mobile | …) activates its own capability for scoring + sensor routing.
   // `web` has no capability of its own → scoringCap stays the default `ui` (byte-identical).
-  const platform = readCapabilities(projectRootFromScreenDir(screenDir)).platform;
+  const capProfile = readCapabilities(projectRootFromScreenDir(screenDir));
+  const platform = capProfile.platform;
   const defaultCap = capabilityRegistry.defaultCapabilityId();
   const scoringCapId = scoringCapabilityFor(catalogScreenName, defaultCap, platform);
   const scoringCap = scoringCapId ? capabilityRegistry.get(scoringCapId) : undefined;
@@ -223,6 +224,10 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   for (const c of flowCredits) {
     findings.push(`COVERED-VIA-FLOW: critical theme "${c.theme}" is not covered on this screen but is deeply covered by flow "${c.flow}" — cross-screen depth correctly owned by the flow, so it is credited (not a screen gap). Verify with \`sungen flow-check\`.`);
   }
+  // Verification-scope (advisory): API/DB verification the project's recorded test type never asked for.
+  for (const v of verificationScopeFindings(featureText, fs.existsSync(viewpointPath) ? fs.readFileSync(viewpointPath, 'utf-8') : '', capProfile)) {
+    findings.push(`VERIFICATION-OUT-OF-SCOPE (${v.layer}): this unit ${v.message}`);
+  }
   for (const g of gate.gaps) {
     if (g.status === 'shallow') {
       findings.push(`GATE: critical theme "${g.theme}" is covered only by SHALLOW scenarios (no data assertion) → deepen with \`... with {{value}}\` / \`table ... with {{value}}\` (count @manual cross-screen too).`);

package/src/harness/capability.ts

@@ -15,9 +15,55 @@ import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 export interface CapabilityProfile {
   platform?: string;       // web | mobile | …  (the runtime adapter)
   enabled: string[];       // driver ids enabled for this project
+  /**
+   * Which VERIFICATION layers this project's test scope uses — the recorded "test type"
+   * (`ui` = E2E-only; add `api` / `db` when the project also verifies via API/DB). Explicit here wins;
+   * when absent it is DERIVED from `enabled` (ui always; api if the api driver is on; db if db is on).
+   * Generation and the audit use it so an E2E-only project does not get @api/@query verification it
+   * never asked for.
+   */
+  verification?: string[];
   source: 'capabilities.yaml' | 'absent';
 }
 
+export type VerifyLayer = 'ui' | 'api' | 'db';
+
+/**
+ * Effective verification scope = the recorded "test type". Explicit `verification` wins; otherwise
+ * derived from the enabled drivers. `ui` is always in scope (every project observes the UI/E2E result).
+ */
+export function verificationScope(profile: CapabilityProfile): Set<VerifyLayer> {
+  if (profile.verification?.length) {
+    const s = new Set<VerifyLayer>(['ui']);
+    for (const v of profile.verification) if (v === 'api' || v === 'db' || v === 'ui') s.add(v);
+    return s;
+  }
+  const s = new Set<VerifyLayer>(['ui']);
+  if (profile.enabled.includes('api')) s.add('api');
+  if (profile.enabled.includes('db')) s.add('db');
+  return s;
+}
+
+export interface VerifyScopeFinding { layer: 'api' | 'db'; message: string; }
+
+/**
+ * Flag API/DB verification that is OUT OF the project's recorded scope: a unit whose scenarios use
+ * `@api`/`@requires:api` (or `@query`/`@requires:db`) while the project is not API/DB-testing AND the
+ * viewpoint never asked for that layer. Deterministic; advisory only (a nudge, never a hard gate).
+ */
+export function verificationScopeFindings(featureText: string, viewpointText: string, profile: CapabilityProfile): VerifyScopeFinding[] {
+  const scope = verificationScope(profile);
+  const vp = (viewpointText || '').toLowerCase();
+  const out: VerifyScopeFinding[] = [];
+  if (/@api\b|@requires:\s*api\b/.test(featureText) && !scope.has('api') && !/\bapi\b/.test(vp)) {
+    out.push({ layer: 'api', message: 'uses @api / @requires:api verification, but this project is not API-testing (capabilities `enabled` has no `api`) and the viewpoint does not request API verification. Keep the oracle UI-observable, OR record API in scope (capabilities `verification: [ui, api]` or `sungen capability add api`). Reserve API/DB verify for the ≤20% of effects with no UI observation.' });
+  }
+  if (/@query\b|@requires:\s*db\b/.test(featureText) && !scope.has('db') && !/\b(database|db)\b/.test(vp)) {
+    out.push({ layer: 'db', message: 'uses @query / @requires:db verification, but this project is not DB-testing (capabilities `enabled` has no `db`) and the viewpoint does not request DB verification. Keep the oracle UI-observable, OR record DB in scope (capabilities `verification: [ui, db]` or `sungen capability add db`). Reserve API/DB verify for the ≤20% of effects with no UI observation.' });
+  }
+  return out;
+}
+
 export interface DriverMeta {
   id: string;
   kind: 'platform' | 'capability';
@@ -41,6 +87,7 @@ export function readCapabilities(cwd: string): CapabilityProfile {
     return {
       platform: typeof y.platform === 'string' ? y.platform : undefined,
       enabled: Array.isArray(y.enabled) ? y.enabled.map(String) : [],
+      verification: Array.isArray(y.verification) ? y.verification.map(String) : undefined,
       source: 'capabilities.yaml',
     };
   } catch {
@@ -48,14 +95,17 @@ export function readCapabilities(cwd: string): CapabilityProfile {
   }
 }
 
-export function writeCapabilities(cwd: string, profile: { platform?: string; enabled: string[] }): string {
+export function writeCapabilities(cwd: string, profile: { platform?: string; enabled: string[]; verification?: string[] }): string {
   const p = capabilitiesPath(cwd);
   fs.mkdirSync(path.dirname(p), { recursive: true });
   const body =
     '# Sungen capability profile — which runtime/drivers this project uses.\n' +
     '# platform: the runtime adapter (web → Playwright, mobile → Appium). No default.\n' +
-    '# enabled: drivers turned on (added via `sungen capability add <driver>`).\n\n' +
-    stringifyYaml({ platform: profile.platform, enabled: profile.enabled });
+    '# enabled: drivers turned on (added via `sungen capability add <driver>`).\n' +
+    '# verification: the TEST TYPE — which layers this project verifies (`ui` = E2E only; add `api`/`db`\n' +
+    '#   only if the project actually verifies via API/Database). Absent → derived from `enabled`.\n' +
+    '#   This keeps an E2E-only project from getting @api/@query verification it never asked for.\n\n' +
+    stringifyYaml({ platform: profile.platform, enabled: profile.enabled, ...(profile.verification ? { verification: profile.verification } : {}) });
   fs.writeFileSync(p, body, 'utf-8');
   return p;
 }

package/src/harness/quality-gates.ts

@@ -174,6 +174,10 @@ export interface OwnershipResult { duplicates: { scenario: string; flow: string
 
 /** Scenarios whose step-skeleton also appears in a sibling flow feature → duplicate ownership. */
 export function crossArtifactOwnership(screenDir: string, scenarios: ScenarioInfo[]): OwnershipResult {
+  // A behavior's ownership is judged from the screen side; flow/api units are the owners, so the
+  // gate does not apply to them. Without this guard, auditing qa/flows/<x>, qa/api/<x>, or
+  // qa/api/flows/<x> resolves flowsRoot to the unit's own parent and every scenario self-matches.
+  if (path.basename(path.dirname(screenDir)) !== 'screens') return { duplicates: [] };
   const duplicates: { scenario: string; flow: string }[] = [];
   // screenDir = <root>/qa/screens/<name>; flows live at <root>/qa/flows/*/features/*.feature
   const flowsRoot = path.resolve(screenDir, '..', '..', 'flows');

package/src/orchestrator/templates/ai-src/commands/create-test.md

@@ -22,7 +22,7 @@ If `spec_figma.md` exists OR the user provides a Figma URL for the PAT flow:
 
 ## Platform detection (do this FIRST)
 
-Read `qa/capabilities.yaml` and check the `platform` field.
+Read `qa/capabilities.yaml` and check the `platform` field — **and the verification scope** (`verification:` if set, else derived from `enabled`: `ui` always; `api`/`db` only if that driver is on). This is the project's recorded **test type**: an **E2E/UI-only** project (no `api`/`db`) must NOT get `@api`/`@query`/`@requires:api|db` verification unless the test-viewpoint explicitly asks for it — keep oracles UI-observable, and cap any in-scope API/DB-in-E2E verification at the **≤20% band** (see `sungen-tc-generation` → "Respect the project's verification scope"). `sungen audit` flags `VERIFICATION-OUT-OF-SCOPE`.
 
 - If `platform: mobile` → the visual-capture step (Step 3, "Auto-detect visual source") uses the **`sungen-capture-mobile`** skill (Appium MCP live capture) **instead of** the web `sungen-capture` (figma/live). Scenarios use mobile gesture vocabulary from `sungen-mobile-gestures` (tap, swipe, long-press — not click/hover) and `accessibility-id`-first selectors; mobile-specific steps (permission dialogs, clipboard, geolocation) are valid Gherkin, not errors. The `Background:` is a **navigation recipe** (see `add-screen --reach`), not a URL path. Everything else — viewpoints, `sungen-tc-generation`, the harness/audit loop — is platform-agnostic and unchanged.
 - If `platform: web` or field absent → follow the **web path** (all steps below, unchanged) — Figma/live capture via `sungen-capture` as documented in Step 3.

package/src/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/src/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/src/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/src/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/src/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/src/orchestrator/templates/ai-src/skills/sungen-gherkin-syntax/SKILL.md

@@ -127,6 +127,14 @@ User see [Table] table match data:
 
 Row scope: `see [Ref] row in [Table] table with {{v}}` enters scope. Subsequent `see [Col] column with {{v}}` checks cell in that row. Use `table match data:` for multi-row verification.
 
+**[Ref] of a row step is a display label UNLESS declared in selectors.yaml.** Without an entry the step checks the value exists in ANY row — a name like `[First Contact Row]` does NOT position the row, and an ordering rule would pass even when the row moved (SG-W010 warns on positional-looking undeclared labels). To assert a POSITION, declare the row (a `type: locator` value RELATIVE to the table):
+```yaml
+first contact row:
+  type: locator
+  value: 'tbody tr:first-child'
+```
+→ compiles to `expect(table.locator('tbody tr:first-child')).toContainText(v)` — the exact row must hold the value — and still enters row scope for `[Col] column` checks.
+
 ### Database verification (optional Data Driver)
 
 Read-only DB-state checks. **Prefer named queries** — SQL lives in `qa/screens/<screen>/database/queries.yaml` (reviewed once, parameterized). Invoke with the `@query:<name>` annotation; it binds the result rows to `{{name}}`, then assert with `expect`:

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

@@ -34,6 +34,14 @@ Take a screen/flow whose `selectors/*.yaml` and `.feature` files were authored a
 1. `selectors/<feature>.yaml` — hardcoded `name`/`value` replaced with `{{var}}`
 2. `test-data/<feature>.yaml` — base locale, complete with all new keys
 3. `test-data/<feature>.<locale>.yaml` — overlay with only the keys that change
+4. **`qa/capabilities.yaml` — DECLARE the locale** (required since 3.2.15): append the code to `locales:` and set `base_locale:` (language of the base test-data; tool default is `en`). Delivery/dashboard treat ONLY declared codes as locales — undeclared result-file suffixes are assumed to be ENVIRONMENTS (dev/staging) and excluded from locale sheets:
+   ```yaml
+   platform: web
+   enabled: [web]
+   base_locale: en      # or vi/ja — whatever the base test-data is written in
+   locales: [ja]        # append every bootstrapped locale here
+   ```
+   Env × locale combos use the compound `SUNGEN_ENV=<env>-<locale>` (e.g. `staging-ja`, overlay `<feature>.staging-ja.yaml`) — the locale segment LAST; delivery recognizes it when the tail matches a declared locale.
 4. (Optional) `selectors/<feature>.yaml` Pages block updated when locale uses URL prefix or query param
 
 After this skill finishes, `sungen run-test <name> --env <locale>` Just Works.

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

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