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

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

@@ -1,21 +1,74 @@
 ---
 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; **no template token may survive
+into a rendered cell** — test-data cross-references are resolved for display) · E drift
+(fingerprint mismatch → back to review) · G review state (proposed groups block the official
+render; `--preview` renders a DRAFT watermark) · R requirement coverage (spec FR/TR/NFR ids with
+no trace and no `requirements:` status → warning) · 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)`.
+
+**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). Collapse outline for the customer view, expand to execute. Variant Result
+cells have a dropdown (Passed/Failed/Blocked/Pending/N/A) and the parent Result is a **live Excel
+formula** over its children (failed→blocked→pending→partial→passed, e.g. `2/3 Passed · 1 Failed`)
+— a parent can never contradict its variants, even after manual edits. ID + Target columns are
+frozen; dates are ISO (`2026-08-04`). `Coverage` sheet — requirement coverage table (every FR/TR/
+NFR id with an explicit status), target × category grid with explicit `—` gaps, dispositions,
+manifest. CSV is flat with a `Level` column (`item`/`variant`) + a requirement-coverage appendix.
+`delivery_item_count` ≠ progress — variants are the execution metric.
+
+**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-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-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