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

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

@@ -86,15 +86,52 @@ 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)"
+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 +224,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/skills/sungen-delivery/SKILL.md

@@ -99,6 +99,12 @@ scheme (`SEC-123`, `PER-345`, `MS-HP-001`) is addressed the same way, and the ca
 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`.
 
+**Dynamic vars**: `{{$timestamp}}`, `{{$uuid}}`, `{{$random:min:max}}`, `{{$date}}`, `{{$datetime}}`
+are resolved by TestDataLoader at execution time — including when nested inside a test-data value
+(`seed: "Summary intro {{$timestamp}}"`). They have no static value to print, so the report names
+them instead: `<unique timestamp>`, `<unique id>`, `<random 1-100>`, `<today's date>`,
+`<current date-time>`. An unknown `{{$foo}}` is left raw on purpose — it is a typo and Gate D says so.
+
 **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.

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

@@ -95,6 +95,10 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | `SG-W008` | `@manual` scenario incomplete in either direction: (a) HAS Gherkin steps but NO `Then` — a dangling `When` is invalid Gherkin, comments can NOT substitute; (b) documentation-style (NO steps) but its comments lack numbered action lines and/or a labeled oracle line — prose paragraphs / rationale-only comments export EMPTY Steps + Expected cells | Two valid shapes only: complete the Gherkin with a `Then`, or write the FULL procedure in the `# Tester verifies:` block as NUMBERED lines — action steps first (`1. <action>`), then labeled `Observable:`/`Oracle:`/`Expected:` lines (the number is what fills Steps, the label is what fills Expected results) |
 | `SG-W009` | test-data references `${QA_<NAME>}` (a SECRET env ref) but the name is declared in neither `.env.qa` nor `.env.qa.example` — the test throws "environment variable not set" the moment the key is used. (Only the `${QA_*}` shape is checked; any other `${...}` is literal data and never flagged.) | Add `QA_<NAME>=<value>` to `.env.qa` (gitignored) and list the NAME in `.env.qa.example` (the committed checklist). See `qa/TEST-DATA-GUIDE.md` |
 | `SG-W010` | A row step's `[Ref]` looks POSITIONAL (`First…`/`Last…`/`Top…`/`nth`) but has no selectors.yaml entry — the label is display-only, so the step checks existence ANYWHERE in the table; an ordering/sort-stability rule would pass even when the row moved | Declare the row in selectors.yaml (a `type: locator` value RELATIVE to the table, e.g. `first contact row:` → `value: 'tbody tr:first-child'`) — the step then asserts `toContainText` on that exact row. This is a selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
+| `SG-W011` | A storage assertion written as `expect … in local/session storage` — `expect` steps only read `{{response}}` refs, so this compiles to a silent no-op | Rewrite using the supported grammar: `User see [KEY] in local storage exists/…` |
+| `SG-W012` | A mock-install step written AFTER a navigation step in the same block — `page.route()` registered after `goto()` misses every request fired during page load | Move the mock-install step before the navigation, or into `Background` |
+| `SG-W013` | A page assertion (`see [X] page` / `is on [X] page`) whose `[Ref]` has no `type: page` selector entry (or collides with a non-page entry) — the step falls back to the feature's own path (or `/<ref>/`) instead of `X`'s real URL, so the anchored assertion can never pass | Declare a `type: page` entry for `[Ref]` with its real URL; if the key collides with another type, disambiguate with a `--type` suffix (`sungen-selector-keys` § Collision rule) |
+| `SG-W014` | `[X] page with {{v}}` where `{{v}}`'s base test-data value carries no query and no fragment — the step checks the PATH only, asserting less than it reads as | Informational — pass a value like `?q=…` if you meant to assert a query, or drop `with {{v}}` for a bare page |
 
 ### Runtime error → `Test data "<key>" references ${QA_*} but the environment variable is not set`
 

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

@@ -106,11 +106,39 @@ two content-filtered queries can hit different rows if the table re-renders in b
 # 8. Page: User see [T] page | page with {{url}}   ← `with` also asserts the query string
 ```
 
-**Pattern 8 — assert the query, not just the path.** Bare `see [T] page` only checks the base path,
-so a search/filter test PASSES when the query string is wrong or gone entirely. When the URL carries
-state worth proving, pass it: `Then User see [Search] page with {{search_query}}` compiles to the
-path assertion PLUS `expect(page.url()).toContain(<value>)`. Same for `Then User is on [T] page with
-{{v}}`. A dynamic segment in the selector value (`/users/:id/profile`) wildcards to `[^/]+` on its own.
+**Pattern 8 — the page assertion judges pathname AND query together.** Both `see [T] page` and
+`is on [T] page` (Then-side) compile to ONE web-first predicate — `toHaveURL(urlMatches({…}))`,
+which retries like any other assertion — comparing the **exact** pathname (anchored, trailing slash
+normalised) plus the query:
+
+| step | asserts |
+|---|---|
+| `Then User see [Search] page` | pathname `/vi/search` **and no query at all** — `/vi/search?x=1` FAILS |
+| `… page with {{v}}`, `v` = `?q=abc` | pathname + **every declared param must match**; extra params are tolerated (a UTM/tracking param cannot turn the test red); a repeated param (`?tag=a&tag=b`) matches per value, so param ORDER never matters |
+| `… page with {{v}}`, `v` = `?q=abc#tab` | the fragment is asserted too |
+| `… page with {{v}}`, `v` = `/vi/search?q=abc` | only the query part is used — the page selector already owns the path |
+| `… page with {{v}}`, `v` = `/vi/search` (no query) | **path only**, and the compiler warns (`SG-W014`): the step asserts less than it reads as |
+| `… page with {{v}}`, `v` empty or key missing at run time | **throws, naming the key** — an unusable value is never a silent pass |
+
+So pass `with {{v}}` whenever the URL carries state worth proving, and leave it off when the page
+must be reached clean. A dynamic segment in the selector value (`/users/:id/profile`) wildcards to
+`[^/]+` on its own, still anchored — `/users/42/profile/edit` does not match. Params compare
+decoded on both sides, so a deliberately malformed query still asserts what was written.
+
+Two asymmetries worth knowing rather than discovering:
+
+1. **`Given`/`When` navigate, `Then` asserts** — so they read `{{v}}` differently. `Then` uses only
+   its query/fragment; `Given User is on [T] page with {{v}}` also honours a path the value carries
+   (`/vi/other?q=1` navigates to `/vi/other?q=1`, and a value repeating the page's own path no
+   longer doubles it). Anything that is not a path, query, or fragment is appended **verbatim** —
+   nothing is encoded or normalised, so a test can still drive a deliberately malformed query.
+2. **A repeated param matches as a subset per key**, which is the same rule as "extra params are
+   tolerated": every value you declare must be present, and the URL may carry more.
+
+The predicate itself lives in `specs/url-assert.ts` (auto-generated, `DO NOT EDIT`). If `[T]` has no
+`type: page` selector entry — or its key collides with a non-page entry, so `value` is something like
+`button` rather than a URL — the step falls back to another path and cannot match the real URL. The
+compiler warns (`SG-W013`); declare the page (or rename the colliding key) instead of chasing the red.
 
 ### Collection / all-card (P5)
 

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

@@ -97,7 +97,7 @@ When running Phase 0 for a **flow** (`qa/flows/<name>/`), check existing screen
    - Loading indicator for `wait for [T] table to refresh` → `feedback.loading.indicator` (skip if the app sets `aria-busy`).
    - **Every qa/app.yaml edit MUST carry provenance** in `detection:`: who/when (`detected_by`) and the observed evidence per key (`evidence:`). A profile without evidence is a guess a human cannot review.
 8. **Merge, don't overwrite**: preserve the page selector and any user-authored entries in `selectors.yaml`. Only add missing keys.
-   - **Type-collision check** (see `sungen-selector-keys` § Collision rule): before writing a base key, check whether it already exists with a *different* `type`. If so, give **both** entries a `--type` suffix instead of clobbering or sharing the base key — a base-key entry of the wrong type gets picked up by any step referencing that label. Watch `page` especially: a `[X] page` step reads `value` as a URL, so if `X` already holds a button (`value: 'button'`) the assertion compiles to `toHaveURL(/button/)`. Write `X--page` (URL from the live page / feature `Path:`) alongside `X--button`.
+   - **Type-collision check** (see `sungen-selector-keys` § Collision rule): before writing a base key, check whether it already exists with a *different* `type`. If so, give **both** entries a `--type` suffix instead of clobbering or sharing the base key — a base-key entry of the wrong type gets picked up by any step referencing that label. Watch `page` especially: a `[X] page` step reads `value` as a URL, so if `X` already holds a button (`value: 'button'`) the compiler won't use the button's value as a URL, but it can't invent the real one either — it falls back to the feature's own path and warns `SG-W013`, asserting a page that isn't `X`'s. Write `X--page` (URL from the live page / feature `Path:`) alongside `X--button`.
 9. **Show summary + confirm**: list the keys that will be added, ask the user to approve, then write the file.
 10. **Compile**: **Screen**: `sungen generate --screen <screen>`. **Flow**: `sungen generate --flow <flow>`. Then proceed to Phase 1.
 

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

@@ -97,12 +97,15 @@ its own `--type` suffix. A key match alone does not carry type: the resolver wal
 picked up by any step referencing that label, regardless of the type the step expects.
 
 The `page` type is the sharpest trap. A page step (`Then User see [X] page`) reads the entry's
-`value` as a **URL**. If key `X` already holds a `role`/button entry, the page step resolves that
-button and emits `toHaveURL(/button/)` — a literal button label treated as a URL path.
+`value` as a **URL**. If key `X` already holds a `role`/button entry, the compiler guards the type
+— it does NOT emit `toHaveURL(/button/)` — but it can't invent the real URL either, so it falls
+back to the feature's own path (or `/<ref>/`) and warns `SG-W013`: a test that reads as asserting
+`X`'s page but never can, since the fallback path is anchored and almost certainly wrong.
 
 ```yaml
 # Gherkin: `When User click [読取結果一覧] button`  AND  `Then User see [読取結果一覧] page`
-# WRONG — one base key, page step inherits the button's value ('button') as a URL:
+# WRONG — one base key: the page step can't use the button's value, falls back to the feature path
+# instead, and the compiler warns SG-W013 rather than asserting the real page:
 読取結果一覧:
   type: 'role'
   value: 'button'

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

@@ -605,22 +605,40 @@ error:
 
 > **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 +648,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:**

package/src/orchestrator/templates/specs-url-assert.ts

@@ -0,0 +1,134 @@
+/* eslint-disable */
+/**
+ * Sungen URL assertion helper — auto-generated into specs/url-assert.ts. DO NOT EDIT.
+ *
+ * Every Then-side URL assertion (`see [X] page`, `is on [X] page`) compiles to one call here.
+ *
+ * Why a helper and not an inline predicate. The predicate used to be emitted inline into every
+ * spec, so each correction to what "the URL matches" MEANS was a breaking change for every
+ * generated suite in the field: regenerate everything, re-review every newly-red test. Behind a
+ * helper the same correction ships as a runtime patch. The generator's job shrinks to what it
+ * alone knows — the pathname pattern — and the semantics live in one readable place.
+ *
+ * Why a predicate and not two assertions. The shape before this one was
+ *   await expect(page).toHaveURL(/\/vi\/search/);      // unanchored: passes on /vi/search-x
+ *   expect(page.url()).toContain('<query>');           // synchronous, one-shot: never retries
+ * — two half-checks, neither anchored, and nothing ever compared pathname and query together.
+ * `toHaveURL(predicate)` is web-first (it retries like any other assertion), receives a parsed
+ * URL, and needs no regex escaping of runtime values, which is what forced the split.
+ */
+
+export interface UrlExpectation {
+  /**
+   * Anchored pathname pattern, compiled by the generator from the page selector's `value`
+   * (`:id` segments already wildcarded). Anchored against `u.pathname` ONLY: pathname never
+   * carries the query, so `^…$` is exact there — the same source that was unsafe to anchor
+   * against a full URL.
+   */
+  pathname: RegExp;
+  /**
+   * The `with {{v}}` value, raw from test-data: '?q=1' · '/vi/search?q=1' · '#tab' · ''.
+   * `undefined` means the step declared nothing, which is itself an assertion — see below.
+   */
+  declared?: string;
+  /** The test-data key behind `declared`, so a failure can name what an author must go fix. */
+  dataRef?: string;
+}
+
+/**
+ * Join a page's URL with the `with {{v}}` value for a NAVIGATION step
+ * (`Given User is on [X] page with {{v}}`).
+ *
+ * Why this is not a plain `base + path + value`. It used to be, and an author writing the value as a
+ * whole relative URL — the habit the assertion side already had to accommodate — navigated to
+ * `/vi/search/vi/search?q=1`: the page's own path, twice. The Then side then asserted the real path
+ * correctly, so the scenario could never go green.
+ *
+ * `base` (the configured baseURL, possibly '') and `path` (the page selector's value) arrive
+ * SEPARATELY so a value that carries its own rooted path replaces the page's path without also
+ * discarding a path prefix baked into the baseURL — a deployment under `https://host/tenant-a`
+ * would otherwise navigate to the wrong tenant, and only when a `with {{v}}` was present, which is
+ * exactly the kind of inconsistency nobody would think to look for.
+ *
+ * What it deliberately does NOT do is sanitize. A test may legitimately drive a MALFORMED query to
+ * prove the app rejects it (issue #464), so anything that is not a duplicated path is appended
+ * verbatim: no encoding, no normalising, no reordering.
+ */
+export function joinPath(base: string, path: string, declared?: string | null): string {
+  if (declared === undefined || declared === null || declared === '') return base + path;
+  const value = String(declared);
+  // A query/fragment appends — the overwhelmingly common shape, and the only one #464 needs.
+  if (value.startsWith('?') || value.startsWith('#')) return base + path + value;
+  // An absolute URL replaces everything: the author pasted a full address.
+  if (/^[a-z]+:\/\//i.test(value)) return value;
+  // A rooted path carries its own path, so it replaces the PAGE's path while everything the
+  // baseURL contributed — scheme, host, and any path prefix — is kept.
+  if (value.startsWith('/')) return base + value;
+  // Anything else is raw input the test wants appended as-is.
+  return base + path + value;
+}
+
+/**
+ * `u.pathname` is percent-encoded; a regex built from a selector's literal `value` is not, so a
+ * non-ASCII route (`/読取結果一覧`) could never match. Decoding can throw on a lone `%`, in which
+ * case the raw form is all there is.
+ */
+function decodedPath(pathname: string): string {
+  try {
+    return decodeURIComponent(pathname);
+  } catch {
+    return pathname;
+  }
+}
+
+/**
+ * Build the predicate for `expect(page).toHaveURL(...)`.
+ *
+ * Query semantics are deliberately asymmetric:
+ *   no `with {{v}}`  → the URL must carry NO query. A bare page means a bare page, so
+ *                      `/vi/search` does not pass on `/vi/search?x=1`.
+ *   `with {{v}}`     → every declared param must match; extra params are tolerated, so a
+ *                      tracking/UTM param the test never cared about cannot turn it red.
+ *                      A declared fragment is asserted too; a declared value carrying no query
+ *                      at all constrains the path only (the compiler warns: SG-W014).
+ */
+export function urlMatches({ pathname, declared, dataRef }: UrlExpectation): (u: URL) => boolean {
+  return (u: URL): boolean => {
+    if (!pathname.test(u.pathname) && !pathname.test(decodedPath(u.pathname))) return false;
+
+    // `dataRef`, not `declared`, decides which rule applies. Both "the step declared nothing" and
+    // "the step declared {{v}} but the key resolved to nothing at runtime" arrive here as
+    // undefined, and they mean opposite things: the first is a real assertion (a bare page must be
+    // bare), the second is broken test-data. Only the generator knows which, and it says so by
+    // emitting `dataRef` exactly when the step carried a `with {{v}}`.
+    if (!dataRef) return u.search === '';
+
+    // Silence is the whole bug class this assertion exists to kill, so an unusable declared value
+    // is an ERROR, not a quiet verdict. Returning false would read as "the app is wrong"; these
+    // throws say "your test-data is wrong, and here is the key". An empty value used to parse to
+    // an empty param list, and `[].every()` is vacuously TRUE — it passed on any query at all.
+    if (declared === undefined || declared === null) {
+      throw new Error(`url assertion: test-data key "${dataRef}" is missing — nothing to assert`);
+    }
+    if (String(declared).trim() === '') {
+      throw new Error(`url assertion: test-data key "${dataRef}" is empty — nothing to assert`);
+    }
+
+    // Parsing against the live pathname as base lets ONE expression handle every shape an author
+    // writes: '?q=1' (query only), '/vi/search?q=1' (a whole relative URL — its path is ignored,
+    // the page selector already owns the path), and '#tab' (fragment only). The predecessor
+    // regex-stripped the prefix instead, which silently turned a value with NO query
+    // ('/vi/search') into a bogus param NAME — an assertion that could never be satisfied.
+    const d = new URL(String(declared), 'http://sungen.invalid' + u.pathname);
+
+    // getAll, not get: a multi-select filter (?tag=a&tag=b) is the exact case this assertion is
+    // for, and `get()` returns only the first value — so the correct URL failed. Comparing as a
+    // subset per key keeps this consistent with "extra params are tolerated", and makes param
+    // order meaningless, which is what a URL actually means.
+    const queryOk = [...d.searchParams].every(([k, v]) => u.searchParams.getAll(k).includes(v));
+
+    // Only assert a fragment the author actually declared.
+    const hashOk = !d.hash || d.hash === u.hash;
+    return queryOk && hashOk;
+  };
+}