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

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/orchestrator/templates/ai-src/commands/delivery.md

@@ -66,19 +66,55 @@ dispositions:                      # scenarios intentionally NOT delivered as te
   # 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.
+**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.
+- 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`.
 
+**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

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

@@ -29,19 +29,44 @@ 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
+(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)