@sun-asterisk/sungen 3.2.20 → 3.2.21-beta.2

package/src/harness/script-check.ts

@@ -43,7 +43,10 @@ export function extractTestBlocks(specSrc: string): { title: string; body: strin
   const lines = specSrc.split('\n');
   const blocks: { title: string; body: string[] }[] = [];
   for (let i = 0; i < lines.length; i++) {
-    const m = lines[i].match(/\btest(?:\.(?:only|skip|fixme))?\(\s*(['"`])([^'"`]+)\1/);
+    // Same escape-aware title match as extractTestTitles — with `[^'"`]+` a
+    // quote-bearing title extracted truncated (or not at all), missed the
+    // automatedTitles lookup, and silently dropped out of the BYPASS scan.
+    const m = lines[i].match(/\btest(?:\.(?:only|skip|fixme))?\(\s*(['"`])((?:\\.|(?!\1).)+)\1/);
     if (!m) continue;
     let depth = 0, started = false;
     const body: string[] = [];
@@ -52,7 +55,7 @@ export function extractTestBlocks(specSrc: string): { title: string; body: strin
       body.push(lines[j]);
       if (started && depth <= 0) break;
     }
-    blocks.push({ title: m[2].trim(), body });
+    blocks.push({ title: unescapeJsLiteral(m[2]).trim(), body });
   }
   return blocks;
 }
@@ -104,13 +107,24 @@ function extractTestTitles(specSrc: string): string[] {
   // Count real test cases only. Web/Playwright specs use test(...) (+ .only/.skip/.fixme);
   // mobile/Appium specs use mocha it(...) (#429 — matching only test() reported EVERY mobile
   // scenario as MISSING). Exclude describe / hooks (not test cases).
+  // The content match is escape-aware and excludes ONLY the actual delimiter (same
+  // pattern as spec-parser.ts): the old `[^'"`]+` class truncated a title at its
+  // escaped same-quote (`lottery\'s` → EXTRA `lottery\` + the real title MISSING)
+  // and dropped a title containing an other-quote (`the "x" case`) entirely — so
+  // in-sync specs of quote-bearing scenarios failed the CI gate (field report 3.2.19).
   const titles: string[] = [];
-  const re = /\b(?:test|it)(?:\.(?:only|skip|fixme))?\(\s*(['"`])([^'"`]+)\1/g;
+  const re = /\b(?:test|it)(?:\.(?:only|skip|fixme))?\(\s*(['"`])((?:\\.|(?!\1).)+)\1/g;
   let m: RegExpExecArray | null;
-  while ((m = re.exec(specSrc))) titles.push(m[2].trim());
+  while ((m = re.exec(specSrc))) titles.push(unescapeJsLiteral(m[2]).trim());
   return titles;
 }
 
+/** Undo the compiler's escapeQuotes escaping (\' \\ \n \r \t) so extracted titles
+ *  compare against the raw scenario names from the .feature. */
+function unescapeJsLiteral(s: string): string {
+  return s.replace(/\\(.)/g, (_m, c: string) => (c === 'n' ? '\n' : c === 'r' ? '\r' : c === 't' ? '\t' : c));
+}
+
 function normalize(src: string): string {
   return src
     .split('\n')

package/src/harness/sensors.ts

@@ -33,10 +33,22 @@ const BUCKET_ORDER: Array<[string, string[]]> = [
 ];
 const BUCKETS: Record<string, string[]> = Object.fromEntries(BUCKET_ORDER);
 
+// Flow journey-phase categories (FL-HP-001, FL-ER-002 …). Matched on exact SEGMENTS,
+// never by containment — 'SHOP'.includes('HP') is true, which is exactly the kind of
+// false hit substring matching would produce for two-letter phase tokens. (#569)
+const PHASE_BUCKETS: Record<string, string> = {
+  HP: 'business-core',          // happy path = the business goal itself
+  ER: 'validation-security',    // error recovery (validation must not trap the journey)
+  EH: 'validation-security',    // guards & leakage (direct access, back, refresh)
+};
+
 /** Classify a VP category into a balance bucket by keyword containment + precedence (H1). */
 export function bucketForCategory(category: string | undefined): string {
   const cat = (category || '').toUpperCase();
   if (!cat) return 'other';
+  for (const seg of cat.split('-')) {
+    if (PHASE_BUCKETS[seg]) return PHASE_BUCKETS[seg];
+  }
   for (const [bucket, kws] of BUCKET_ORDER) {
     if (kws.some((k) => cat.includes(k))) return bucket;
   }
@@ -351,7 +363,7 @@ export function flowRegressionDepth(scenarios: ScenarioInfo[]): FlowDepthResult
   // 1. Count/quantity proof — a row count or item quantity, not just presence of a row.
   const countProof = any(/\b(quantity|qty|two (?:rows|lines|cart)|row count|count column|number of items|one[_ ]row|two[_ ]rows|qty[_ ])/i);
   // 2. Teardown — removes the item and verifies the empty/zero state (the inverse operation).
-  const teardown = any(/\b(remove|delete|clear)\b/i) && any(/\b(empty|no items|zero|removed|0 items)\b/i);
+  const teardown = any(/\b(remove|delete|clear)(?:s|d|ed|ing)?\b/i) && any(/\b(empty|emptied|no items|zero|removed|cleared|0 items)\b/i);
   // 3. Multi-source — the cart is fed from >1 source (the main list AND a recommended/related rail).
   const multiSource = any(/\b(recommended|related|you may also|suggest)\b/i) && addsToCart;
 

package/src/harness/spec-coverage.ts

@@ -66,21 +66,43 @@ export function parseSpecClauses(specPath: string): { frs: FrClause[]; valRows:
   if (!fs.existsSync(specPath)) return { frs: [], valRows: [] };
   const lines = readTextFile(specPath).split('\n');
 
+  // Requirement ids follow the PROJECT's scheme, not ours (#572): `**FR-1**:` is one
+  // convention among many — a real spec declared ~30 MUST clauses as `` `REQ-SRCH-001`: ``
+  // and the FR-locked pattern returned zero, so the MUST-coverage gate never ran and the
+  // specFR axis was excluded "for lack of evidence" that was sitting right there. Same
+  // silent-failure class as the CRLF parsers, same id-scheme-tolerance lesson as delivery.
+  //
+  // A declaration is: line-leading (optionally bulleted / bold / backticked) `<ID>:` where
+  // the id ends in a number. Table rows are EXCLUDED — traceability tables cite requirement
+  // ids without declaring them — and so are prefixes that are never requirements
+  // (test cases, viewpoints, known-defect records, data-factory checks, flows, delivery items).
+  const NON_REQUIREMENT_PREFIX = /^(TC|VP|KD|CHK|FL|DI)-/i;
   const frs: FrClause[] = [];
+  const seen = new Set<string>();
   for (const line of lines) {
-    const m = line.match(/\*\*FR-(\d+)\*\*\s*:\s*(.+)$/);
-    if (m) frs.push({ id: `FR-${m[1]}`, text: m[2].replace(/\*\*/g, '').trim(), modality: modalityOf(m[2]) });
+    if (/^\s*\|/.test(line)) continue;   // table row = citation, not declaration
+    const m = line.match(/^\s*(?:[-*+]\s+)?[*_`]*([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d+[a-zA-Z]?)[*_`]*\s*:\s*(.+)$/);
+    if (!m || NON_REQUIREMENT_PREFIX.test(m[1])) continue;
+    const id = m[1].toUpperCase();
+    if (seen.has(id)) continue;          // first declaration wins
+    seen.add(id);
+    frs.push({ id, text: m[2].replace(/\*\*/g, '').trim(), modality: modalityOf(m[2]) });
   }
 
   // Validation Rules table: a row carries a Constraint, a Trigger cell, and (often) a code.
+  // A "Trigger" column alone is NOT enough to claim the table (#578): a screen-STATES table
+  // ("State ID | Trigger | URL/heading oracle | …") uses Trigger for the user action that
+  // enters the state, and reading it as validation rows invented three gate-relevant
+  // TRIGGER-UNCOVERED gaps on a real spec. The table must also name a Constraint/Rule/
+  // Validation column — the thing a validation row is ABOUT.
   const valRows: ValRow[] = [];
   let cTrigger = -1, cConstraint = -1, cCode = -1, inTable = false;
   for (const raw of lines) {
     const line = raw.trim();
-    if (line.startsWith('|') && /\btrigger\b/i.test(line) && cTrigger < 0) {
+    if (line.startsWith('|') && /\btrigger\b/i.test(line) && /\b(constraint|rule|validation)\b/i.test(line) && cTrigger < 0) {
       const cells = line.split('|').map((c) => c.trim());
       cTrigger = cells.findIndex((c) => /^trigger$/i.test(c));
-      cConstraint = cells.findIndex((c) => /constraint/i.test(c));
+      cConstraint = cells.findIndex((c) => /constraint|rule|validation/i.test(c));
       cCode = cells.findIndex((c) => /code/i.test(c));
       inTable = cTrigger >= 0;
       continue;

package/src/orchestrator/templates/ai-src/commands/add-flow.md

@@ -86,15 +86,57 @@ qa/flows/${input:flow}/
     └── ui/                        # Screenshots, mockups
 ```
 
-### 1a. Identify the screens in the flow
+### 1a. Define the flow's BOUNDARY, then its screens
 
-Ask the user: "Which screens does this flow visit, in order? (e.g., login → dashboard → award-form → confirmation)"
+> QA teams often call this level **System Test** — same thing: one fully-integrated business
+> journey verified against the spec. Use whichever name the team knows; the boundary rules
+> below are the ISTQB system-test design rules.
+
+
+A flow is the **smallest complete business action chain**: one clear trigger ending in ONE
+observable, valuable outcome. Before asking for screens, walk this checklist with the user —
+if 1, 3 or 8 fails, propose SPLITTING into separate flows:
+
+1. Exactly **one business goal**? (cart correctness + category filtering = two flows)
+2. A clear **trigger** and precondition?
+3. **One observable final outcome**? (a final assertion you can write in one sentence)
+4. Is that outcome **valuable to the actor**? (an order placed, a password reset — not "a page rendered")
+5. Is **every step necessary** for that outcome?
+6. Are all steps at the **same business abstraction**?
+7. Are optional/error branches **phases of this goal** (ER/EH), not new goals?
+8. Does **no segment** form an independently valuable flow on its own?
+9. Can you write **a single clear final assertion**?
+10. Can you name it "**Verb + outcome**"? (`place-order`, `reset-password` — not `cart-and-filter`)
+
+Then ask: "Which screens does this flow visit, in order? (e.g., login → dashboard → award-form → confirmation)"
 
 Record the screen list — you will need it for:
 - Filling `spec.md` (Step 3)
 - Suggesting `[Screen:Element]` namespace prefixes
 - Capturing visuals per screen (Step 2)
 
+### 1b. Author the Flow Contract (`requirements/flow-contract.yaml`)
+
+Write the answers down as the flow's contract — `sungen audit` scores the flow **against it**
+(the `flowCoverage` axis: HP/ER/EH journey phases; `FLOW-OUTCOME-UNPROVEN` when no automated
+scenario asserts data on the outcome screen; `FLOW-SCOPE-CREEP` when scenarios never touch it):
+
+```yaml
+goal: "Place an order for a product added from home"   # Verb + outcome
+actor: user
+trigger: "Add a product to the cart from the home featured list"
+precondition: "A registered account; an empty cart"
+outcome:
+  screen: checkout            # the [Screen:...] namespace carrying the final proof
+  assertion: "The confirmation shows the order number and the paid total"
+value: "The customer has paid; the shop has a new order"
+phases: [HP, ER, EH]          # journey phases (default); add UI only if the flow owns UI states
+stateful: cart                # the mutated collection, if any — enables regression-depth dims
+```
+
+**A filled contract is an INPUT to generation — never an output.** Like `test-viewpoint.md`,
+generation must not rewrite it to match what was generated; disagree → propose the diff and ask.
+
 ### 2. Capture visual source
 
 **Mobile path** (`platform: mobile`):
@@ -187,7 +229,8 @@ If user picks `/sungen:create-test`, **you MUST use the Skill tool** to invoke i
 - Test data namespaced by phase: `login.email`, `submission.nominee`
 - `@flow` tag required at feature level
 - `Background:` should only contain the starting navigation — the URL path (web) or the `--reach` nav recipe (mobile)
-- Each scenario = one phase of the journey
+- Each scenario = one phase of the journey; ids are `FL-<PHASE>-NNN` (`HP`/`ER`/`EH`, optional `UI`)
+- One flow = ONE business goal with ONE observable outcome (`requirements/flow-contract.yaml`) — a segment with its own value is its own flow
 {{#cap parallel-subagents}}
 - Mobile flows are tagged `@platform:mobile` and run via `/sungen:run-test <flow>` (WebdriverIO, not Playwright)
 {{/cap}}

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

@@ -6,6 +6,16 @@ order: 20
 claude-tools: "Read, Grep, Bash, Glob, Write, AskUserQuestion, Skill, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot"
 copilot-tools: "[vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']"
 codex-trigger: "Run when the user asks to CREATE, generate, write, or author test cases / a .feature file for a screen or flow. Step 2 (after add-screen/add-flow, before run-test). Do NOT use for executing, running, or compiling existing tests."
+---
+## ⛔ HARD RULE — the run's LAST action is the next-step hand-back
+
+A create-test run is NOT finished when the files are written or the audit prints. The final
+action of EVERY run — success, partial, or aborted — is the next-step hand-back
+({{#cap parallel-subagents}}an `AskUserQuestion` offering the next actions{{/cap}}{{^cap parallel-subagents}}a numbered list of next-action choices{{/cap}};
+see "Finish — always hand the next step back" at the end of this file). Ending with a prose
+summary and no choices is a broken run: the operator is left guessing. This holds no matter
+how long the generation/repair loop ran.
+
 ---
 {{#cap parallel-subagents}}
 ## ⛔ HARD RULE — No Figma MCP when PAT data exists

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

@@ -603,24 +603,59 @@ error:
 
 ## Flow Test Generation
 
+> **Terminology**: many QA teams call this level **System Test** (ISTQB: verify the fully
+> integrated system against its specified requirements, designed around business
+> processes/use cases). In sungen a *flow* is that system-test suite run through the real UI;
+> its automation then serves as the regression suite on later runs. The names are
+> interchangeable in conversation; the artifacts stay `qa/flows/<name>/`.
+
+**Representative, not exhaustive (ISTQB system-test design rule).** A flow case takes ONE
+representative input per branch — one valid value for the main flow, one error value that
+triggers the exception branch and proves the journey recovers. The full equivalence/boundary
+matrix belongs to the OWNING SCREEN (as `@cases` there), never re-run inside the flow: if the
+screen already proved "the field rejects negatives", the flow only proves "the journey survives
+one rejected input". `sungen audit` reports `FLOW-EXHAUSTIVE-INPUTS` when ≥3 same-shape flow
+scenarios differ only in data. **Mocked dependencies**: a flow scenario using `@mock` is
+delivered as *Pass (Mocked)* — verified handling logic, not the real dependency; the delivery's
+External Dependency Tracking table lists it until re-verified real.
+
+
 > **Auto-detect**: if path is `qa/flows/<name>/` → use this section. Skip Steps 1–4 above.
 
+**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`).
+
 | Aspect | Screen | Flow |
 |---|---|---|
-| Section focus | UI patterns per section | Journey phases across screens |
+| Section focus | UI patterns per section | Journey phases toward ONE declared outcome |
 | Selector format | `[Element]` | `[Screen:Element]` (namespaced) |
 | Test data keys | `{{variable}}` | `{{phase.variable}}` |
 | Feature tag | `@auto` / `@smoke` etc. | `@flow` (required) |
-| Viewpoints | VP-UI/VAL/LOGIC/SEC per section | VP-LOGIC (transitions), VP-SEC (auth persistence), VP-VAL (cross-screen data) |
+| Scenario ids | `VP-<CATEGORY>-NNN` | `FL-<PHASE>-NNN` — phases: `HP` (happy path), `ER` (error recovery), `EH` (guards), `UI` (journey UI states, optional) |
 
-**Scenarios to generate:**
+**Scenarios to generate — every phase demanded by the contract, automated:**
 
-| Category | What to test |
-|---|---|
-| Happy path | Complete flow end-to-end with valid data |
-| Auth persistence | Auth state maintained across screen transitions |
-| Error recovery | Invalid input mid-flow → fix → continue |
-| Cross-screen data | Data entered on screen A visible on screen B |
+| Phase | What to test | Scoring |
+|---|---|---|
+| `FL-HP` happy path | The complete journey ending in the contract's `outcome.assertion` — an AUTOMATED **data** assertion on `outcome.screen` (an order number, a summed total — not just "page visible"). This scenario is WHY the flow exists: it is the regression proof after a lib/framework upgrade. | uncovered → `flowCoverage` drops + `FLOW-OUTCOME-UNPROVEN` |
+| `FL-ER` error recovery | Invalid input mid-flow → error shown → fix → the journey still completes. Validation must not trap the journey. | uncovered → `flowCoverage` drops |
+| `FL-EH` guards | Direct URL access without the precondition · browser back · refresh · expired context — each ends in a safe observable state. | uncovered → `flowCoverage` drops |
+| 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`) |
+
+**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).
+Auth persistence across transitions is part of `EH` unless the project declares it its own phase.
+
+**Manual in flows**: always `@manual:Mx` with the reason code — bare `@manual` is flagged
+(`MANUAL-CODE-MISSING`) because the capability planner cannot route it. Typical flow deferrals:
+inbox/mail oracle → `M5`, network-request count → `M3`, context expiry control → `M7`. A
+cross-screen scenario inside the flow's own goal is NOT manual — automate it here.
 
 ```gherkin
 @flow @auth:user
@@ -630,19 +665,20 @@ Feature: Award Submission Flow
     Given User is on [Login] page
 
   @high
-  Scenario: User logs in successfully
+  Scenario: FL-HP-001 A signed-in user's nomination is submitted and confirmed
     When User fill [Login:Email] field with {{login.email}}
     And User fill [Login:Password] field with {{login.password}}
     And User click [Login:Submit] button
     Then User see [Dashboard] page
-
-  @high
-  Scenario: User submits nomination
     When User click [Dashboard:Awards] link
-    Then User see [Awards] page
-    When User fill [Awards:Nominee] field with {{submission.nominee}}
+    And User fill [Awards:Nominee] field with {{submission.nominee}}
     And User click [Awards:Submit] button
-    Then User see {{success_message}} message
+    Then User see [Awards:Success Message] text with {{success_message}}
+
+  @high
+  Scenario: FL-EH-001 Direct access to the award form without login redirects to login
+    When User go to [Awards] page
+    Then User see [Login] page
 ```
 
 ```yaml

package/src/orchestrator/templates/qa-context.md

@@ -45,8 +45,21 @@ Example:
 
 ## Testing Strategy
 
+Machine-readable intent — `sungen audit` reads these keys (Intent Profile). Values here are
+live even when the surrounding text changes; an invalid value silently falls back to the default.
+
+focus: functional
+<!-- focus: functional | e-commerce | security | smoke — drives the audit's depth threshold -->
+
+risk_tier: normal
+<!-- risk_tier: high | normal | low -->
+
+To silence driver suggestions in audit findings, add a line: capability_suggestions with value off.
+
 **Focus areas** — what to cover thoroughly:
-<!-- List from: functional, security, ui, accessibility, performance -->
+<!-- Prose for humans; the parseable value is the `focus:` key above.
+     Response-time budgets are NOT a focus value — declare them in qa/perf.yaml
+     (percentile + scenario_ms budgets; reported by `sungen delivery`). -->
 <!-- Example: functional, security -->
 
 **Mandatory coverage:**