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

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

@@ -29,19 +29,85 @@ fingerprints). Schema + grouping rules live in the delivery command instructions
 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`).
+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)

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

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

package/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.