@sun-asterisk/sungen 3.2.16-beta.3 → 3.2.16-beta.5

package/src/exporters/matrix/types.ts

@@ -29,6 +29,10 @@ export interface MapGroup {
   oracle: string;
   category: MapCategory;
   review: ReviewState;
+  /** Optional short digest of the coverage dimensions this item varies over
+   *  (e.g. "required ×3 · format ×9 · full-width ×2"). Rendered on the parent row
+   *  instead of concatenating every variant's title — the compact review view. */
+  dimensions?: string;
   /** Variant refs: `VP-ID` (all @cases rows when the scenario has a dataset) or `VP-ID#label`. */
   variants: string[];
 }
@@ -57,7 +61,9 @@ export interface DeliveryMap {
   /** Requirement-id → reviewed status override (partially_covered / not_applicable / …).
    *  Without an override a requirement is `covered` when a variant traces to it, else `gap`. */
   requirements: Record<string, RequirementOverride>;
-  /** VP-id → scenario fingerprint stamped at approval time (drift detector input). */
+  /** VP-id → scenario fingerprint stamped at approval time (drift detector input).
+   *  The reserved key `__map__` holds the fingerprint of the map's own semantic
+   *  content (groups + dispositions) so edited wording re-opens review (GAP-09). */
   fingerprints: Record<string, string>;
 }
 
@@ -116,7 +122,11 @@ export interface CoverageVariant {
   result?: PlaywrightResult;
 }
 
-export type ItemResult = 'passed' | 'failed' | 'blocked' | 'partial' | 'not_run';
+export type ItemResult = 'passed' | 'failed' | 'blocked' | 'partial' | 'not_run' | 'na';
+
+/** The exact word rendered in a variant's Result cell — the single vocabulary the
+ *  parent's roll-up formula counts (COUNTIF is exact-match). */
+export type VariantState = 'Passed' | 'Failed' | 'Blocked' | 'Pending' | 'N/A';
 
 /** One summarized row in the matrix — a group of variants sharing the signature. */
 export interface DeliveryItem {
@@ -124,6 +134,8 @@ export interface DeliveryItem {
   target: string;
   intent: string;
   oracle: string;
+  /** Short coverage-dimension digest from the map (compact parent view). */
+  dimensions?: string;
   category: MapCategory;
   review: ReviewState;
   /** Highest priority among the variants (per-variant priorities stay on the sub-rows). */
@@ -134,13 +146,19 @@ export interface DeliveryItem {
   layers: MatrixLayer[];
   /** Union of variant traces (exact per-variant traces stay on the variants). */
   traces: string[];
+  /** Preconditions shared by EVERY variant (the intersection) — written once here. */
   precondition: string[];
-  /** Common trigger when all variants share one shape, else '(per variant)'. */
+  /** Leading trigger steps shared by every variant — written once here; each
+   *  variant renders only its remaining steps (`triggerDeltas`). */
   trigger: string[];
   variants: CoverageVariant[];
+  /** variant ref → its precondition lines that are not on the parent. */
+  preconditionDeltas: Record<string, string[]>;
+  /** variant ref → its trigger steps after the shared prefix. */
+  triggerDeltas: Record<string, string[]>;
   /** Derived roll-up — never entered independently (Gate F). */
   result: ItemResult;
-  resultCounts: { passed: number; failed: number; blocked: number; notRun: number };
+  resultCounts: { passed: number; failed: number; blocked: number; notRun: number; na: number };
 }
 
 export interface MatrixDisposition {

package/src/exporters/matrix/wording.ts

@@ -19,10 +19,13 @@ function deRef(text: string): string {
 }
 
 function sentence(text: string): string {
-  let s = text.trim().replace(/\s+/g, ' ');
+  // Trim the ENDS only — internal whitespace may be the test data itself
+  // (a padded email, a spaces-only value); collapsing it would silently
+  // change what the tester types (review GAP-04).
+  let s = text.trim();
   if (!s) return s;
   s = s.charAt(0).toUpperCase() + s.slice(1);
-  if (!/[.!?…]$/.test(s)) s += '.';
+  if (!/[.!?…"]$/.test(s)) s += '.';
   return s;
 }
 
@@ -42,7 +45,7 @@ export function renderAction(raw: string): string {
     // 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)? (.+?) (?:at|in|on|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]}` : ''}`],
@@ -103,9 +106,23 @@ 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] ?? ''}`);
+  // "wait for [X] <type> (is) visible" is a STATE once established, not an action.
+  const w = s.match(/^waits? for \[([^\]]+)\]\s*(\w+)?(?: is)?(?: visible)?$/i);
+  if (w) return sentence(`The ${w[1]}${w[2] ? ` ${w[2]}` : ''} is visible`);
+  const auth = s.match(/^is (signed|logged) (in|out)(.*)$/i);
+  if (auth) return sentence(`The user is ${auth[1]} ${auth[2]}${auth[3] ?? ''}`);
   return sentence(deRef(`The user ${s.charAt(0).toLowerCase()}${s.slice(1)}`));
 }
 
+/**
+ * A manual `Setup:` line is an INSTRUCTION the tester performs to establish the
+ * state — imperative reads correctly ("Seed the locked account."), while
+ * "The user seed …" is broken grammar (review GAP-08).
+ */
+export function renderSetupInstruction(raw: string): string {
+  return renderAction(raw);
+}
+
 // ---------------------------------------------------------------------------
 // Manual `# Tester verifies:` comment classification (structured, label-free)
 // ---------------------------------------------------------------------------

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

@@ -1,7 +1,7 @@
 ---
 name: delivery
 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)"
+argument-hint: "[name...] [--format csv] [--env <locale>] [--legacy] (omit names for all)"
 order: 50
 claude-tools: "Bash, Read, Write, AskUserQuestion"
 copilot-tools: "[read, execute, edit, vscode/askQuestions]"
@@ -27,6 +27,8 @@ review → approve → official render.
 
 Parse from `$ARGUMENTS`:
 - **names** — zero or more screen/flow/api names. Empty → all targets.
+- **`--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.
 
@@ -37,8 +39,8 @@ Parse from `$ARGUMENTS`:
 ```bash
 [ -x ./bin/sungen.js ] && ./bin/sungen.js delivery <names> || npx sungen delivery <names>
 ```
-(prepend `SUNGEN_ENV=<locale>` when `--env` was given; append `--legacy` when requested — then skip
-to step 5.)
+(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.
@@ -58,6 +60,7 @@ groups:
     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
     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
@@ -92,6 +95,17 @@ determined** (its oracle *family*, not its exact message).
   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.
+
 **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."
@@ -151,6 +165,7 @@ 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**
 
@@ -168,7 +183,8 @@ counted in variants, never items**). Then `AskUserQuestion`:
 ## CLI reference
 
 ```
-sungen delivery [names...]        # matrix (default; needs the map)
+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)
@@ -176,5 +192,6 @@ sungen delivery [names...]        # matrix (default; needs the map)
   --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.
+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/skills/sungen-delivery/SKILL.md

@@ -36,7 +36,8 @@ oracle-shape/precondition mismatches are review-level, silenced once approved an
 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
+(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) · 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).
@@ -51,17 +52,39 @@ Precondition, `Action:` → Action, `Observable:` → Expected Result, `Oracle:`
 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.
+
 **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.
+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.
 
+**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`),