@sun-asterisk/sungen 3.2.23 → 3.2.24-beta.2

package/src/harness/viewpoint-ledger.ts

@@ -23,6 +23,19 @@ export interface LedgerResult {
 }
 
 const ID_RE = /\b([A-Z]{1,5}\d{0,2}(?:[.\-][A-Za-z0-9]+)*-?\d{0,3})\b/; // VP0.Title, VP7-002, MS-HP-001, TV-01
+
+/**
+ * Lines that DECLARE something about the checklist rather than being a checklist item —
+ * atomizing them manufactures gaps that can never be closed (QA field report: 4 of 6
+ * "missing items" were a `qa/bug-reports` placeholder plus three Priority-Viewpoints
+ * rows whose third cell is the PROSE REASON for a priority, not a claim to test).
+ */
+// "None on file yet …", "N/A", "TBD", "Do not invent …" — an explicit statement that there
+// is nothing here. A gap report built from these tells the author to test the absence.
+const PLACEHOLDER_ITEM = /^(none\b|n\/a\b|tbd\b|no known\b|nothing\b|do not invent\b|-+$)/i;
+/** A priority-DECLARATION row: `| VP-LOGIC | High | <reason prose> |`. The category id and its
+ *  priority are consumed by the traceability + balance axes; the reason is rationale. */
+const PRIORITY_ROW = /^(?:VP|FL)[A-Z0-9._-]*\s+—\s+(?:critical|high|medium|normal|low|deferred)\b/i;
 const GENERIC = new Set(['display', 'shown', 'value', 'field', 'input', 'page', 'screen', 'button', 'link', 'text', 'check', 'verify', 'should', 'with', 'when', 'then', 'user', 'this', 'that', 'each', 'item', 'items']);
 
 /** Extract atomic checklist items from a viewpoint file (format-tolerant). */
@@ -42,11 +55,13 @@ export function parseViewpointItems(viewpointPath: string): { id?: string; text:
     else if (line.startsWith('|')) {                       // table data row
       if (/^\|[\s|:-]+\|?$/.test(line)) continue;           // separator
       const cells = line.split('|').map((c) => c.trim()).filter(Boolean);
-      if (/^(vp|id|viewpoint|priority|reason|no\.?|category|item|trigger|#|pattern|applicable|notes|field|constraint|code|description|status)$/i.test(cells[0] || '')) continue; // header
+      if (/^(vp|id|viewpoint|priority|reason|no\.?|category|item|trigger|#|pattern|applicable|notes|field|constraint|code|description|status|step|flow|ref|level|question|screen|actor|branches from|own steps|component|thành phần|trường|bước)$/i.test(cells[0] || '')) continue; // header
       text = cells.join(' — ');
     } else continue;
     text = text.replace(/[*`]/g, '').trim();
     if (!text) continue;
+    if (PLACEHOLDER_ITEM.test(text)) continue;   // "None on file yet" is not a claim
+    if (PRIORITY_ROW.test(text)) continue;       // priority declaration, not a checklist item
     const idM = text.match(ID_RE);
     const id = idM && /\d/.test(idM[1]) ? idM[1] : undefined; // require a digit so prose words aren't IDs
     const words = (text.toLowerCase().match(/[a-z][a-z-]{3,}/g) || []).filter((w) => !GENERIC.has(w));
@@ -79,3 +94,45 @@ export function viewpointLedger(viewpointPath: string, scenarios: ScenarioInfo[]
 
   return { hasViewpoint: true, total: items.length, covered, ratio: items.length ? covered / items.length : 1, missing };
 }
+
+/**
+ * A viewpoint item that names a BROWSER-LEVEL gesture, met by an in-app control instead.
+ *
+ * "Browser back button from Basic Info Confirmation to Basic Info — values must be restored"
+ * was answered with `User click [Confirmation:Back] button`. Those are different mechanisms: an
+ * app button runs the screen's own re-hydrate logic, browser history does not, and a defect
+ * that only appears on history navigation lives exactly in the gap. The ledger counted the item
+ * covered because the words matched, so the substitution was invisible (#595).
+ *
+ * The language has no reload/back step at all (#593), so the honest outcome is a `@manual`
+ * deferral naming the gesture — not a silent swap.
+ */
+const BROWSER_GESTURES: Array<{ gesture: string; re: RegExp; appSubstitute: RegExp }> = [
+  { gesture: 'browser back', re: /\bbrowser(?:'s)?[ -]?(?:back|history)\b|\bhistory[ -]back\b/i,
+    appSubstitute: /\bclick \[[^\]]*back[^\]]*\]/i },
+  { gesture: 'browser reload/refresh', re: /\b(?:page |browser )?(?:reload|refresh)(?:ing|ed|es)?\b/i,
+    appSubstitute: /\bis on \[[^\]]+\] page\b/i },
+  { gesture: 'closing and reopening the tab', re: /\bclos(?:e|ing) (?:and reopen\w*\s*)?the tab\b|\breopen\w* the tab\b/i,
+    appSubstitute: /\bis on \[[^\]]+\] page\b/i },
+];
+
+export function browserGestureSubstitutions(
+  viewpointPath: string, scenarios: ScenarioInfo[],
+): Array<{ gesture: string; item: string }> {
+  const out: Array<{ gesture: string; item: string }> = [];
+  // Judged PER SCENARIO, not over the whole file: a @manual scenario elsewhere that merely
+  // mentions the gesture in passing (explaining a tooling limit) silenced the check for an
+  // item that an automated scenario had quietly substituted.
+  const deferred = scenarios.filter((s) => s.manual).map((s) => s.haystack);
+  const automated = scenarios.filter((s) => !s.manual).map((s) => s.haystack);
+  for (const item of parseViewpointItems(viewpointPath)) {
+    for (const g of BROWSER_GESTURES) {
+      if (!g.re.test(item.text)) continue;
+      // A @manual scenario whose own subject IS the gesture is the honest answer.
+      if (deferred.some((h) => g.re.test(h))) break;
+      if (automated.some((h) => g.appSubstitute.test(h))) out.push({ gesture: g.gesture, item: item.text });
+      break;
+    }
+  }
+  return out;
+}

package/src/orchestrator/templates/ai-src/commands/create-test.md

@@ -30,6 +30,34 @@ If `spec_figma.md` exists OR the user provides a Figma URL for the PAT flow:
 **Input**: Screen or flow name (e.g., `/sungen-create-test admin-users`).
 {{/cap}}
 
+## ⛔ HARD RULE — in flow mode, AUTHOR the flow contract before generating
+
+If `requirements/flow-contract.yaml` is missing, **write it first** — never cite a contract you
+did not create, and never generate scenarios without one. Without it the flow is scored as a
+generic screen (page-type themes that do not fit a journey), and the audit reports
+`FLOW-CONTRACT-MISSING`.
+
+It needs the use-case declaration ONCE — actor · trigger · goal · precondition · `outcome` —
+plus **both** postconditions: `successGuarantee` (true when the goal is reached) and
+`minimalGuarantee` (what must still hold when the journey FAILS). Exception flows assert against
+the second one; with no `minimalGuarantee` they can only prove "an error appeared"
+(`FLOW-GUARANTEE-MISSING`). Then declare `phases:` — `[BF, AF, EF]` for a use-case decomposition
+(the first phase is the Basic Flow). Then enumerate the use case's flows with the step × risk
+matrix in the `sungen-tc-generation` skill and **write them into the contract's `flows:`
+inventory**, each with a `status:` (`covered` / `deferred` / `pending-clarification` /
+`out-of-scope`) and a `reason:` for anything but `covered`. Without the inventory, coverage can
+only be measured per phase — and a phase counts as covered as soon as ONE scenario carries it, so
+a fifteen-flow use case scores 100% on three scenarios (`FLOW-INVENTORY-MISSING`, and the top mark
+is withheld).
+
+A risk the specs do NOT settle is `pending-clarification` with the question written down — never a
+scenario asserting invented behaviour, and never a silent omission. If the flow's requirements are
+restated from screen specs the project does not hold, say so: the audit reports
+`SPEC-RESTATED-UNVERIFIED` because `specFR 100%` over a hand-copied list certifies the copy, not
+the source.
+
+---
+
 ## Platform detection (do this FIRST)
 
 Read `qa/capabilities.yaml` and check the `platform` field — **and the verification scope** (`verification:` if set, else derived from `enabled`: `ui` always; `api`/`db` only if that driver is on). This is the project's recorded **test type**: an **E2E/UI-only** project (no `api`/`db`) must NOT get `@api`/`@query`/`@requires:api|db` verification unless the test-viewpoint explicitly asks for it — keep oracles UI-observable, and cap any in-scope API/DB-in-E2E verification at the **≤20% band** (see `sungen-tc-generation` → "Respect the project's verification scope"). `sungen audit` flags `VERIFICATION-OUT-OF-SCOPE`.

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

@@ -636,10 +636,21 @@ those namespaces are the **System INTEGRATION** group — keep their oracles abo
 
 **Read `requirements/flow-contract.yaml` FIRST — it is the flow's boundary and the yardstick
 `sungen audit` scores the flow against** (`flowCoverage` axis = journey phases HP/ER/EH automated;
-`FLOW-OUTCOME-UNPROVEN`; `FLOW-SCOPE-CREEP`). No contract yet → author it with the user via the
-boundary checklist in `add-flow` (one business goal · clear trigger · ONE observable outcome
-valuable to the actor · name = "Verb + outcome"), THEN generate. **A filled contract is an INPUT —
-never rewrite it to match your output** (same rule as `test-viewpoint.md`).
+`FLOW-OUTCOME-UNPROVEN`; `FLOW-SCOPE-CREEP`). **A filled contract is an INPUT — never rewrite it
+to match your output** (same rule as `test-viewpoint.md`).
+
+> **HARD RULE — the contract must be AUTHORED, never merely cited.** If
+> `requirements/flow-contract.yaml` is absent, WRITE it (with the user, via the boundary checklist
+> in `add-flow`: one business goal · clear trigger · ONE observable outcome valuable to the actor ·
+> name = "Verb + outcome") **before** generating scenarios. Citing a contract you did not create
+> leaves the flow scored as a generic screen — `flowCoverage` never applies, `coverage` falls back
+> to page-type themes that do not fit a journey, and the audit reports `FLOW-CONTRACT-MISSING`.
+> A contract also needs **both** guarantees, not just the happy one:
+>
+> - `successGuarantee` — everything true once the goal IS reached (what the Basic Flow proves).
+> - `minimalGuarantee` — what must still hold when the journey **FAILS** (no duplicate record, no
+>   mail on a rejected submit, no half-written state). Without it an Exception Flow has nothing to
+>   assert against beyond "an error appeared", and `FLOW-GUARANTEE-MISSING` is reported.
 
 | Aspect | Screen | Flow |
 |---|---|---|
@@ -647,7 +658,7 @@ never rewrite it to match your output** (same rule as `test-viewpoint.md`).
 | Selector format | `[Element]` | `[Screen:Element]` (namespaced) |
 | Test data keys | `{{variable}}` | `{{phase.variable}}` |
 | Feature tag | `@auto` / `@smoke` etc. | `@flow` (required) |
-| Scenario ids | `VP-<CATEGORY>-NNN` | `FL-<PHASE>-NNN` — phases: `HP` (happy path), `ER` (error recovery), `EH` (guards), `UI` (journey UI states, optional) |
+| Scenario ids | `VP-<CATEGORY>-NNN` | `FL-<PHASE>-NNN` — use-case phases `BF`/`AF0n`/`EF0n` (see below), or the flat `HP` (happy path) / `ER` (error recovery) / `EH` (guards) / `UI` for a short single-outcome flow |
 
 **Scenarios to generate — every phase demanded by the contract, automated:**
 
@@ -659,6 +670,88 @@ never rewrite it to match your output** (same rule as `test-viewpoint.md`).
 | Cross-screen handoff | After every screen transition, assert the CARRIED state on the new screen (the added product's name in the cart, the email echoed on the sent screen). | blind tails cap `businessDepth` (`FLOW-HANDOFF-SHALLOW`) |
 | Stateful regression (when `stateful:` declared) | Count/quantity proof · teardown (remove → empty) · multi-source add. | missing dims cap `businessDepth` (`FLOW-DEPTH`) |
 
+### Use-case decomposition — how a flow becomes 15 scenarios instead of 3
+
+`HP`/`ER`/`EH` are phase *buckets*; they do not tell you how many flows a use case HAS. The
+use-case framework does, and it is the default decomposition for a multi-screen journey:
+
+**1 Use Case = 1 Basic Flow + N Alternate Flows + N Exception Flows.**
+
+| Phase | Meaning | Test |
+|---|---|---|
+| `BF` Basic Flow | **Exactly one.** The path where nothing goes wrong, end to end. | Reaches `outcome.assertion` and satisfies `successGuarantee`. |
+| `AF` Alternate Flow | A **designed-for branch** — the user does something else legitimate. NOT an error. | Its own outcome: either re-enters the BF at a named step, or ends elsewhere on purpose. |
+| `EF` Exception Flow | **Blocked.** The goal is not reached. | Asserts `minimalGuarantee` — what must STILL be true now that this failed. |
+
+`AF` is the bucket most generators skip entirely, and it is where the interesting bugs live
+(going back and finding the form re-hydrated, two tabs, an escape hatch out of the journey).
+Use `FL-BF-NNN` / `FL-AF0n-NNN` / `FL-EF0n-NNN` ids — `sungen audit` buckets them (BF→business
+core, AF→behaviour, EF→validation/security) and traces them to the viewpoint's `FL-BF`/`FL-AF`/
+`FL-EF` priority rows. Declare `phases: [BF, AF, EF]` in the contract; the FIRST phase is the
+Basic Flow and is the one that must reach `outcome`.
+
+**Declare the flow INVENTORY, not just the phases.** `phases: [BF, AF, EF]` says which
+vocabulary the suite uses; it cannot say how many flows the use case has — a phase counts as
+covered the moment ONE scenario carries it, so a fifteen-flow use case with three scenarios
+reported full phase coverage while a reviewer counting flows read it as a third done. List every
+flow in the contract, and give each one a status:
+
+```yaml
+flows:
+  - id: BF
+    outcome: "The successGuarantee — verified, recorded, signed in"
+    status: covered
+  - id: AF02
+    branchFrom: "BF step 4, before submitting"
+    outcome: "Re-enters BF at step 4 with the buffer restored"
+    status: covered
+  - id: EF08
+    branchFrom: "BF step 1, the control tapped twice"
+    outcome: "One request, one record"
+    status: pending-clarification      # the spec is silent — ASK, never assume a guard
+    reason: "The guard lives in ST_AUTH_001's spec, which this project does not hold."
+```
+
+Four statuses, and **silence is not one of them**: `covered` · `deferred` · `pending-clarification`
+(the behaviour is not agreed yet, so no scenario can be right) · `out-of-scope` (another suite owns
+it). Anything but `covered` needs a `reason:` — a deferral nobody can audit is the same as a
+missing flow. `sungen audit` then measures `flowCoverage` per DECLARED FLOW and reports
+`FLOW-UNCOVERED` (declared, nobody wrote it), `FLOW-UNDECLARED` (a scenario claiming a flow id the
+inventory never declares), `FLOW-STATUS-UNREASONED` and `FLOW-INVENTORY-MISSING`.
+
+**One flow, one id — a viewpoint is not a flow.** Several scenarios may prove one flow: give them
+the same flow id and different sequence numbers (`VP-VAL-EF01-001`, `VP-VAL-EF01-002`), never a
+fresh flow id per assertion. Two shapes the audit reports as `FLOW-PHASE-MISFILED`: an `EF` that
+reaches the outcome with nothing failing (that is a success-path postcondition, so it belongs to
+the BF), and an `AF` with no branch point (it walks the basic path asserting extra content — also
+the BF's). Both inflate the flow count while adding no branch coverage.
+
+**Declare once, then declare only the differences.** Actor · Trigger · Goal · Precondition ·
+`successGuarantee` · `minimalGuarantee` are use-case-level: they live in `flow-contract.yaml`
+and are never repeated per flow. Each flow in `test-viewpoint.md` then states only three things:
+**where it branches from · its own steps · its own outcome.** Repeating the precondition in
+fifteen rows is noise; the branch point is the information.
+
+**Enumerate flows with the step × risk matrix.** Walk every BF step and ask each column. A hit
+with a basis in the spec becomes a flow; a hit with no basis becomes an **open question** — never
+an invented behaviour:
+
+| Risk family | The question at this step |
+|---|---|
+| Double submit | Is the control tapped twice guarded? One request, one record? (Spec silent → open question, not an assumed guard.) |
+| Client-side buffer | Is state held client-side between this step and the next? Then test **both** directions — it survives a legitimate back, and it is **LOST** on reload. A suite proving only the surviving side has tested half the mechanism (`CONTINUITY-ONE-SIDED`). |
+| Concurrency | Two tabs / two devices at this step — whose state wins? |
+| Server error | This step's submit fails server-side: what is kept, what is retryable, is anything half-written? |
+| Abandonment / TTL | The user stops here. Does the partial state lapse, expire, or linger forever? |
+| Direct access | This step's URL opened cold, without the preceding state → refused, and the screen never renders. |
+| Auth transition | Where exactly does the session begin? Before that point the actor is unauthenticated — prove it. |
+| Escape hatch | Is there a documented way OUT of the journey here (back to top, cancel)? That is an `AF`, and its outcome is "goal deliberately not reached". |
+
+**Do NOT re-derive field validation.** Per-field equivalence and boundary values belong to the
+OWNING SCREEN's suite. A flow takes representative inputs (see the system-test rule above). State
+that exclusion in the viewpoint's Design Decisions — and if the screen suite does not exist, that
+is a gap to REPORT, not to quietly absorb.
+
 **Boundary discipline while generating:** every scenario must serve the contract's goal. A scenario
 that never touches `outcome.screen` and is not a guard (`EH`) or error-recovery (`ER`) belongs in a
 DIFFERENT flow — propose the split instead of writing it here (`FLOW-SCOPE-CREEP` will flag it).

package/src/orchestrator/templates/ai-src/skills/sungen-viewpoint/group-e-identity.md

@@ -107,7 +107,7 @@ See `SKILL.md` for the 4 Viewpoints, Shared Checks, and Security Tag Rules.
 
 **[VP-VAL] Edge cases**
 
-- [@normal] Register with a sub-address email (user+tag@gmail.com) → treated as a unique email, creation succeeds
+- [@normal] Register with a sub-address email (user+tag@sun-asterisk.com) → treated as a unique email, creation succeeds
 - [@low] Browser autofill fills the fields → the form receives the correct values, no conflict with a custom input component
 
 ---

package/src/orchestrator/test-data-guide.ts

@@ -50,6 +50,14 @@ payload \`<script>alert(1)</script>\`; the exact expected error message from the
 **Self-check:** *"If I swapped this for another value of the same kind, would the
 test still mean the same thing?"* → yes = INVENTED.
 
+**Email domains — never a live mailbox provider.** An invented address still gets
+mail sent to it: a registration or password-reset test submits it and the system
+dispatches for real. \`@gmail.com\`, \`@yahoo.com\`, \`@outlook.com\` and friends all
+resolve, so that mail reaches whoever owns the address — a stranger, or someone's
+personal account. Use the project domain \`@sun-asterisk.com\`, or \`@example.com\`
+(RFC 2606 — reserved, guaranteed never to deliver). Make each run unique with
+\`{{$timestamp}}\` in the local part: \`"signup+{{\$timestamp}}@sun-asterisk.com"\`.
+
 ## 2) ENV-BOUND — real records of the test environment (not secret)
 
 **What it is:** the value must EXIST in the environment for the test to work — a