@sun-asterisk/sungen 3.2.17 → 3.2.18

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

@@ -1,146 +1,229 @@
 ---
 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...] [--format csv] [--env <locale>] [--legacy] (omit names for all)"
 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 → **a sweep of every unit**.
+  Strictness follows the scope: a **named** unit that is not ready aborts the run (the user asked
+  for that unit); a **sweep** exports every ready unit and skips the rest with an accounted
+  "Not exported" list, succeeding as long as something was written. So `/sungen:delivery` with no
+  argument is safe in a work-in-progress project — scaffolded units (added but `create-test` not
+  run) no longer block the units that are ready.
+- **`--format <xlsx|csv|both>`** — output format. **Default `xlsx` — one artifact only.** Pass
+  `--format csv` when the user wants the flat CSV (pipelines/diffing), `--format both` for both.
+- **`--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 `--format <fmt>` when the user asked
+for a non-default format; 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).
+
+On a sweep, read the **"Not exported"** list at the end: units marked *not authored yet* need
+`/sungen:create-test` first, the others each printed their own reason above (missing map, gate
+errors, or awaiting approval). Handle them one unit at a time — do not re-run the sweep expecting
+a different result.
+
+### 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>
+    dimensions: violated rule — required ×3 · format ×10 · full-width ×2   # see below
+    category: normal | abnormal | security | nfr   # see the rule below
+    review: proposed               # ALWAYS proposed — only QA approval flips it
+    variants: [VP-VAL-001-B, VP-VAL-001-S]   # the scenario ids of THIS project (VP-…, SEC-123, MS-HP-001 —
+                                             # whatever the titles use); a 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) — group COMPACTLY.** The matrix exists to be
+substantially shorter than the scenario list, so a reviewer can see missing viewpoints at a
+glance. Merge whenever the cases share ALL of: target · test intent/business rule ·
+precondition/condition · trigger or procedure shape · **the way the expected result is
+determined** (its oracle *family*, not its exact message).
+
+- **Oracle family = the determination method, parameterized.** All validation branches of ONE
+  field belong to ONE item — required, format, length, character-class are *expected branches*
+  (parameters) of "the field shows the validation message defined for the violated rule", shown
+  per variant, never separate items.
+- MAY vary inside one item (coverage dimensions, visible on the sub-rows): data values, boundary
+  points, **account states** (a seeded/locked/deleted account next to a wrong-password case),
+  provider/browser/locale, `@cases` rows, a different trigger with the same oracle (blur vs
+  submit), **execution mode** (auto + manual mix — the parent shows `Auto n · Manual m`), and
+  **priority** (the item takes the highest; per-variant priorities stay visible).
+- MUST split: different target, different intent/business rule, different way of determining the
+  expected result (a field-error family ≠ a session-established family), different test layer
+  (`@api`/`@query`), materially different precondition, or a different procedure shape —
+  sequence-sensitive flows (re-Given/When after a Then) stay solo. **Different risk classes never
+  merge**: XSS and SQL injection are separate items (different risk and determination), even on
+  the same field.
+- **Look for these families before settling on a grouping** — they are where under-merging happens:
+  | Family | Merge into one item |
+  |---|---|
+  | Static render | every "element X is visible/has its content on load" scenario of the screen — title, instructions, progress step, buttons present, header/footer |
+  | Field validation branches | all rules of ONE field (required · format · length · character class · full-width) |
+  | Account/entity states | wrong-credentials · locked · deleted · unverified for the same rejection oracle |
+  | Provider / surface sets | the 3 OAuth providers, header+footer, the a11y surfaces of one behaviour |
+  | Lifetime / mode pairs | checked vs unchecked, mobile vs desktop, when the oracle is one rule with two branches |
+  On a 36-scenario screen, four separate one-variant "renders on load" items should have been one.
+- When unsure, keep items separate — the gates and QA decide, never guess-merge.
+- 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`.
+
+**`dimensions:` — the compact coverage digest (required for items with >3 variants).**
+This one short line is what the collapsed parent row shows instead of listing every variant, so a
+reviewer sees *which dimensions* the item covers without expanding it. Name the dimension, then the
+branches with counts:
+- `violated rule — required ×3 · format ×10 · full-width ×2`
+- `account state — wrong password · unregistered · locked · soft-deleted`
+- `submission method — Login button · Enter in Password · Enter in Email`
+
+Keep it ≤120 chars (Gate W warns). **YAML caveat:** a bare `: ` inside the value breaks the parse —
+use ` — ` as the label separator (as above) or quote the whole string.
+
+**`category` is not free choice for two classes (Gate K checks it):** a group whose variants are
+`VP-SEC-*` MUST be `category: security`, and `VP-NFR-*` MUST be `nfr` — otherwise the Coverage
+sheet's security/nfr column renders empty and the grid reports a gap the unit does not have while
+hiding the work it does have. `normal` vs `abnormal` stays your judgement.
+
+**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
+```
+
+**Never write `status: covered` for a requirement no variant traces to** (Gate R flags it). A note
+saying "proven by DI-SEC-CSRF" is prose — nothing detects it when that scenario later changes. If a
+scenario in THIS feature proves the requirement, **add `@spec:<id>` to that scenario** so the trace
+is real, then drop the override (it derives as `covered` on its own). Use `covered_elsewhere` only
+when another suite proves it, and name that suite; `not_applicable` when the spec itself excludes
+the requirement.
+
+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.
+- **Also export CSV** — `sungen delivery <unit> --format csv` (flat `item`/`variant` rows for pipelines).
+- **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) → XLSX only
+  --format <xlsx|csv|both>        # output format; default xlsx (one artifact)
+  --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) by default;
+`--format csv` writes `<unit>-testcases.csv` instead (flat, `Level` column `item|variant`),
+`--format both` writes both. 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,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/src/orchestrator/templates/ai-src/skills/sungen-gherkin-syntax/SKILL.md

@@ -295,6 +295,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/src/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.
@@ -318,6 +340,7 @@ Security:         [S1 – admin only]
 `sungen audit` enforces these. Generate compliant output up front:
 
 1. **Taxonomy-match** (`VP-TAXONOMY-MISMATCH`, gate-FAIL) — when `test-viewpoint.md` declares its own viewpoint IDs (e.g. `VP0`, `VP1`, … `VP12`, `MS-HP-001`, `MS-EH-001`), **reuse those IDs verbatim as the scenario codes**. Do NOT invent a generic `VP-UI / VP-LOGIC / VP-VAL` scheme — that breaks the coverage matrix. Only fall back to `VP-<CATEGORY>-<NNN>` when the viewpoint file declares no IDs.
+   - **Match the scenarios to the file — never the file to the scenarios.** A filled `test-viewpoint.md` is an input; do not rewrite its declarations to fit what you generated. That is not compliance, it is moving the yardstick: `traceability` + `atomicLedger` then read 100% by construction and a dropped viewpoint stops being missing from anything. Disagree with the taxonomy → propose the diff and ask. `sungen audit` reports `VIEWPOINT-BASELINE-CHANGED` and excludes both axes until a human accepts the change (`sungen audit --screen <name> --accept-viewpoint`).
 2. **Spec-coverage triggers** (`TRIGGER-UNCOVERED`, gate-FAIL) — the Validation-Rules table lists a **trigger** per constraint (e.g. `blur, submit`). Generate one scenario **per (constraint × trigger)** — a `format` rule validating *on blur AND on submit* needs BOTH a blur scenario (`press Tab`) and a submit scenario (`click [Submit]` / `press Enter`). Never collapse the trigger × input matrix to one representative case.
 3. **Claim-Proof** (`CLAIM-UNPROVEN`) — a title claiming `all`/`only`/`every`/`single`/`correct`/`same`/`changes`/`hidden`/`cleared`/`restored`/`independent`/`sanitized`/`announces` MUST have the matching assertion (`see all …`, count, `remember`+compare, `is hidden`, return-and-assert-empty, etc.). If the title promises it, the steps must prove it.
    - **Negative / absence claims** (`does not` / `no` / `never` / `prevents` / `không` / `chưa` — any language; `no-side-effect/no-duplicate`, `negative-claim/absence`): the `Then` must **differ** between the claim holding and not holding. A terminal `see [X] page` that looks identical whether or not the bad thing happened proves nothing. For a side-effect that should NOT repeat (re-submit on back, re-charge, duplicate order, resend OTP), assert the **count is unchanged** (`User see [Records] table with {{one}}` / `row with {{count}}`); if it's not UI-observable, mark `@manual` with a request-count oracle (shape below). This is general — it covers any side-effect, not a fixed verb list.