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

package/src/exporters/matrix/wording.ts

@@ -0,0 +1,157 @@
+/**
+ * Wording normalization — deterministic rendering step AFTER semantic
+ * normalization (review feedback §10): turn sungen DSL steps into controlled
+ * manual-test English without changing the target, condition, trigger,
+ * precondition, oracle, or trace.
+ *
+ * - Actions render in the imperative:      "User fill [Email] field with X"
+ *                                        →  "Enter X in the Email field."
+ * - Expected results render as observable assertions (never tester actions):
+ *   "User see [Jobs] page" → "The Jobs page is displayed."
+ * - Manual `# Tester verifies:` labels (Setup:/Action:/Observable:/Oracle:)
+ *   become structured fields instead of prose: Setup → precondition,
+ *   Action → action, Observable → expected, Oracle → verification method.
+ */
+
+// `[Email] field` → `Email field` (the visible label + its element type).
+function deRef(text: string): string {
+  return text.replace(/\[([^\]]+)\]/g, '$1');
+}
+
+function sentence(text: string): string {
+  let s = text.trim().replace(/\s+/g, ' ');
+  if (!s) return s;
+  s = s.charAt(0).toUpperCase() + s.slice(1);
+  if (!/[.!?…]$/.test(s)) s += '.';
+  return s;
+}
+
+/**
+ * Render one action step in the imperative. Pattern table covers the common
+ * sungen step verbs; anything unmatched falls back to actor-stripped text —
+ * still readable, never a raw `User fill`.
+ */
+export function renderAction(raw: string): string {
+  let s = raw.trim().replace(/^(User|The user)\s+/i, '');
+
+  const rules: Array<[RegExp, (m: RegExpMatchArray) => string]> = [
+    // fill [X] field with V
+    [/^fills? \[([^\]]+)\][a-z ]* with (.+)$/i, (m) => `Enter ${m[2]} in the ${m[1]} field`],
+    // clear [X] field
+    [/^clears? \[([^\]]+)\](.*)$/i, (m) => `Clear the ${m[1]}${m[2] || ' field'}`],
+    // click [X] <type>
+    [/^clicks? \[([^\]]+)\]\s*(\w+)?$/i, (m) => `Click the ${m[1]}${m[2] ? ` ${m[2]}` : ''}`],
+    // press <Key> at/in [X] field
+    [/^press(?:es)? (.+?) (?:at|in|inside) \[([^\]]+)\](?: field)?$/i, (m) => `Press ${m[1]} in the ${m[2]} field`],
+    [/^press(?:es)? (.+)$/i, (m) => `Press ${m[1]}`],
+    // select V in/from [X] dropdown
+    [/^selects? (.+?) (?:in|from) \[([^\]]+)\]\s*(\w+)?$/i, (m) => `Select ${m[1]} in the ${m[2]}${m[3] ? ` ${m[3]}` : ''}`],
+    // check/uncheck [X] checkbox
+    [/^(un)?checks? \[([^\]]+)\]\s*(\w+)?$/i, (m) => `${m[1] ? 'Uncheck' : 'Check'} the ${m[2]}${m[3] ? ` ${m[3]}` : ''}`],
+    // hover [X]
+    [/^hovers? (?:over )?\[([^\]]+)\]\s*(\w+)?$/i, (m) => `Hover over the ${m[1]}${m[2] ? ` ${m[2]}` : ''}`],
+    // upload V to [X]
+    [/^uploads? (.+?) (?:to|into) \[([^\]]+)\]\s*(\w+)?$/i, (m) => `Upload ${m[1]} to the ${m[2]}${m[3] ? ` ${m[3]}` : ''}`],
+    // is on [X] page (as an action = navigate)
+    [/^is on \[([^\]]+)\] page(.*)$/i, (m) => `Open the ${m[1]} page${m[2] ?? ''}`],
+    // wait for [X] <type> (is )?visible
+    [/^waits? for \[([^\]]+)\]\s*(\w+)?(?: is)?(?: visible)?$/i, (m) => `Wait until the ${m[1]}${m[2] ? ` ${m[2]}` : ''} is visible`],
+    // scroll to [X]
+    [/^scrolls? (?:to|into) \[([^\]]+)\]\s*(\w+)?$/i, (m) => `Scroll to the ${m[1]}${m[2] ? ` ${m[2]}` : ''}`],
+  ];
+
+  for (const [re, out] of rules) {
+    const m = s.match(re);
+    if (m) return sentence(deRef(out(m)));
+  }
+  return sentence(deRef(s));
+}
+
+/**
+ * Render one expected step as an observable assertion (no tester action, no
+ * `should`, no DSL `User see`).
+ */
+export function renderExpected(raw: string): string {
+  let s = raw.trim().replace(/^(User|The user)\s+/i, '');
+
+  const rules: Array<[RegExp, (m: RegExpMatchArray) => string]> = [
+    // see [X] page
+    [/^sees? \[([^\]]+)\] page$/i, (m) => `The ${m[1]} page is displayed`],
+    // see [X] <type> with V
+    [/^sees? \[([^\]]+)\]\s*(\w+)? with (.+)$/i, (m) => `The ${m[1]}${m[2] ? ` ${m[2]}` : ''} shows ${m[3]}`],
+    // see [X] <type> contains V
+    [/^sees? \[([^\]]+)\]\s*(\w+)? contains (.+)$/i, (m) => `The ${m[1]}${m[2] ? ` ${m[2]}` : ''} contains ${m[3]}`],
+    // see [X] <type> has text V
+    [/^sees? \[([^\]]+)\]\s*(\w+)? has text (.+)$/i, (m) => `The ${m[1]}${m[2] ? ` ${m[2]}` : ''} shows ${m[3]}`],
+    // see [X] <type> is hidden / is disabled / is enabled / …
+    [/^sees? \[([^\]]+)\]\s*(\w+)? is (.+)$/i, (m) => `The ${m[1]}${m[2] ? ` ${m[2]}` : ''} is ${m[3]}`],
+    // not see [X] <type>
+    [/^(?:do(?:es)? )?not sees? \[([^\]]+)\]\s*(\w+)?$/i, (m) => `The ${m[1]}${m[2] ? ` ${m[2]}` : ''} is not displayed`],
+    // see [X] <type>
+    [/^sees? \[([^\]]+)\]\s*(\w+)?$/i, (m) => `The ${m[1]}${m[2] ? ` ${m[2]}` : ''} is visible`],
+  ];
+
+  for (const [re, out] of rules) {
+    const m = s.match(re);
+    if (m) return sentence(deRef(out(m)));
+  }
+  return sentence(deRef(s));
+}
+
+/** Precondition wording: a state, not an action ("The user is signed out."). */
+export function renderPrecondition(raw: string): string {
+  const s = raw.trim().replace(/^(User|The user)\s+/i, '');
+  const m = s.match(/^is on \[([^\]]+)\] page(.*)$/i);
+  if (m) return sentence(`The user is on the ${m[1]} page${m[2] ?? ''}`);
+  return sentence(deRef(`The user ${s.charAt(0).toLowerCase()}${s.slice(1)}`));
+}
+
+// ---------------------------------------------------------------------------
+// Manual `# Tester verifies:` comment classification (structured, label-free)
+// ---------------------------------------------------------------------------
+
+export interface ManualProcedure {
+  /** Setup/Precondition/Arrange lines — the state to establish first. */
+  preconditions: string[];
+  /** Action/unlabelled lines — the imperative procedure. */
+  actions: string[];
+  /** Observable/Expect/Result/Assert lines — the observable outcome. */
+  expected: string[];
+  /** Oracle/Verify lines — HOW to check (tools, panes, queries). */
+  verification: string[];
+}
+
+/**
+ * Split a manual scenario's numbered comment lines into the four structured
+ * fields. Labels are consumed (structured), never left inside the prose —
+ * review feedback §10.2(3). Continuation lines append to the previous item;
+ * pre-amble (rationale/header/dividers) is skipped.
+ */
+export function classifyManualComments(comments: string[]): ManualProcedure {
+  const out: ManualProcedure = { preconditions: [], actions: [], expected: [], verification: [] };
+  let last: { list: string[]; idx: number } | null = null;
+
+  const bucketOf = (label: string): keyof ManualProcedure => {
+    if (/setup|precondition|arrange|given/i.test(label)) return 'preconditions';
+    if (/oracle|verify|verification|how to check/i.test(label)) return 'verification';
+    if (/observ|expect|result|then|assert/i.test(label)) return 'expected';
+    return 'actions';
+  };
+
+  for (const raw of comments) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (/^[-=*_]{2,}/.test(line)) { last = null; continue; }
+    const m = line.match(/^\d+[.)]\s*(?:([A-Za-z][A-Za-z /]*?):\s*)?(.+)$/);
+    if (m) {
+      const label = (m[1] || '').trim();
+      const text = m[2].trim();
+      const list = out[bucketOf(label)];
+      list.push(text);
+      last = { list, idx: list.length - 1 };
+    } else if (last) {
+      last.list[last.idx] += ' ' + line;
+    }
+  }
+  return out;
+}

package/src/exporters/scenario-merger.ts

@@ -162,7 +162,7 @@ function findMatchingSpecTest(scenario: ScenarioMetadata, tests: SpecTest[]): Sp
   if (exact) return exact;
 
   // Fallback: match by VP-ID prefix (ignore trailing text differences)
-  const vpMatch = scenario.name.match(/^(VP-[A-Z][A-Z0-9]*-\d+[a-zA-Z]?)/);
+  const vpMatch = scenario.name.match(/^(VP-[A-Z][A-Z0-9]*-\d+(?:[a-zA-Z]|-[A-Z0-9]+)?)/);
   if (vpMatch) {
     const vpId = vpMatch[1];
     const byVp = tests.find((t) => t.vpId === vpId);

package/src/exporters/spec-parser.ts

@@ -165,7 +165,7 @@ function classifyBlock(block: CodeBlock): 'precondition' | 'step' | 'expectation
  * Try to extract VP ID (e.g., VP-UI-001) from the start of a scenario title.
  */
 function extractVpId(title: string): string | undefined {
-  const match = title.match(/^(VP-[A-Z][A-Z0-9]*-\d+[a-zA-Z]?)\b/);
+  const match = title.match(/^(VP-[A-Z][A-Z0-9]*-\d+(?:[a-zA-Z]|-[A-Z0-9]+)?)\b/);
   return match ? match[1] : undefined;
 }
 

package/src/exporters/xlsx-report-builder.ts

@@ -143,6 +143,7 @@ export function renderReportHeaderBand(
   ws: ExcelJS.Worksheet,
   titleLabel: string,
   sungenVersion?: string,
+  formNo: string = 'BM-2-901-13',
 ): void {
   const issueDate = (() => {
     const d = new Date();
@@ -187,9 +188,9 @@ export function renderReportHeaderBand(
   d1.alignment = { horizontal: 'center', vertical: 'middle', wrapText: true };
   d1.border = allBordersBlack;
 
-  // G1 — No: BM-2-901-13
+  // G1 — No: <form number> (the company ISO form id; configurable via the delivery map)
   const g1 = ws.getCell('G1');
-  g1.value = 'No: BM-2-901-13';
+  g1.value = `No: ${formNo}`;
   g1.font = { size: 12, name: TIMES };
   g1.alignment = { vertical: 'middle' };
   g1.border = { top: thinBlack, left: thinBlack, right: thinBlack };

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/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,170 @@
 ---
 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. **Different risk classes never merge** — XSS and SQL injection are
+  separate items even though both are "injection on the same field" (different risk, action,
+  and oracle family); a component's visibility rule and its action/revalidation rule are two
+  intents, not one.
+- 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`.
+
+**Wording rules for `intent`/`oracle` (customer-facing — Gate W lints these):**
+- Plain product language, present simple, ~10–20 words, one behavior:
+  "A user can sign in with valid credentials and is redirected to the Jobs page."
+- Oracle = the observable outcome as a definite assertion ("The Jobs page is displayed and the
+  Logout link is visible.") — no `should`, no tester actions.
+- NEVER: `{{tokens}}`, `[Selector]` references, DSL phrasing (`User fill/click/see`), generator
+  labels (`Setup:`/`Observable:`/`Oracle:`), or vague verbs (`handles`, `surfaces`) when a precise
+  behavior exists. Use the visible UI label (the Login button, the Email field).
+- **Preserve the source meaning exactly** — never strengthen, weaken, or reinterpret an oracle
+  (a security assertion especially: if the source says "the password appears ONLY in the HTTPS
+  POST body", do not write "no plaintext password on the network").
+
+**Requirement coverage (`requirements:` section, optional):** `sungen delivery` scans
+`requirements/spec.md` for FR-/TR-/NFR- ids; ids traced by `@spec:` tags are `covered`, the rest
+are `gap` (Gate R warning). Record the reviewed status for genuine non-gaps:
+
+```yaml
+requirements:
+  TR-007: { status: planned, note: Performance needs Lighthouse-style tooling }
+  TR-004: { status: partially_covered, note: client-side covered by VP-SEC-003; hashing needs DB verify }
+  # status: covered | partially_covered | covered_elsewhere | planned | gap | not_applicable
+```
+
+Then validate and fix any ERROR findings:
+
+```bash
+[ -x ./bin/sungen.js ] && ./bin/sungen.js delivery <unit> --check || npx sungen delivery <unit> --check
 ```
 
-{{#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.
+### 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
+
+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.