@sun-asterisk/sungen 3.2.19 → 3.2.20

package/src/exporters/test-data-resolver.ts

@@ -141,10 +141,43 @@ function truncate(s: string, max: number): string {
  * test-data map (or resolving to empty) is left as the literal `{{var}}` — never blanked.
  */
 export function substituteTestDataVars(text: string, testData: Record<string, string>): string {
-  return text.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (m, key: string) => {
+  const out = text.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (m, key: string) => {
     const v = testData[key];
     return v === undefined || v === null || v === '' ? m : String(v);
   });
+  // A substituted value may itself carry a dynamic token ("Award-{{$timestamp}}").
+  // String.replace never re-scans its own replacement, so name them afterwards.
+  return renderDynamicTokens(out);
+}
+
+/**
+ * Give the documented dynamic vars (`{{$timestamp}}`, `{{$uuid}}`,
+ * `{{$random:min:max}}`, `{{$date}}`, `{{$datetime}}`) a form a tester can act on.
+ *
+ * These are resolved by TestDataLoader at execution time, never from
+ * test-data.yaml — so at export time they have no static value, exactly like a
+ * value the run captures (`remember … as {{v}}` → `the captured v`). Left raw,
+ * the token ships into the deliverable and the matrix's Gate D rejects the
+ * whole export. Named, the tester reads what to type: any value of that shape,
+ * uniqueness being the whole point.
+ *
+ * An UNKNOWN `{{$foo}}` stays literal on purpose — the runtime resolver also
+ * leaves it raw, so it is an authoring typo and must keep failing Gate D.
+ */
+export function renderDynamicTokens(text: string): string {
+  return text.replace(/\{\{\s*\$(\w+)(?::([^}]*))?\s*\}\}/g, (m, name: string, args?: string) => {
+    switch (name) {
+      case 'timestamp': return '<unique timestamp>';
+      case 'uuid': return '<unique id>';
+      case 'random': {
+        const [min, max] = (args || '1:9999').split(':');
+        return `<random ${min}-${max}>`;
+      }
+      case 'date': return "<today's date>";
+      case 'datetime': return '<current date-time>';
+      default: return m;
+    }
+  });
 }
 
 /**

package/src/generators/test-generator/adapters/adapter-interface.ts

@@ -67,7 +67,7 @@ export interface TestGeneratorAdapter {
   // Template rendering methods
   renderTestFile(data: TestFileData): string;
   renderScenario(data: ScenarioData): string;
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean }): string;
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean; urlAssertImports?: string }): string;
   renderBeforeEach(data: { steps: Array<{ comment?: string; code: string }> }): string;
   renderBeforeAll(data: { steps: Array<{ comment?: string; code: string }> }): string;
   renderAfterEach(data: { steps: Array<{ comment?: string; code: string }> }): string;

package/src/generators/test-generator/adapters/appium/appium-adapter.ts

@@ -31,7 +31,7 @@ export class AppiumAdapter implements TestGeneratorAdapter {
     return this.templateEngine.renderScenario(data);
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean }): string {
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean; urlAssertImports?: string }): string {
     return this.templateEngine.renderImports(options);
   }
 

package/src/generators/test-generator/adapters/playwright/playwright-adapter.ts

@@ -26,7 +26,7 @@ export class PlaywrightAdapter implements TestGeneratorAdapter {
     return this.templateEngine.renderScenario(data);
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean }): string {
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean; urlAssertImports?: string }): string {
     return this.templateEngine.renderImports(options);
   }
 

package/src/generators/test-generator/adapters/playwright/templates/imports.hbs

@@ -12,6 +12,9 @@ import { api } from '{{basePath}}/api';
 {{#if needsMock}}
 import { mock } from '{{basePath}}/mock';
 {{/if}}
+{{#if urlAssertImports}}
+import { {{urlAssertImports}} } from '{{basePath}}/url-assert';
+{{/if}}
 
 // This file is auto-generated from Gherkin feature files
 // DO NOT EDIT MANUALLY - changes will be overwritten

package/src/generators/test-generator/adapters/playwright/templates/steps/navigation/navigation.hbs

@@ -1,2 +1,6 @@
+{{#if query}}
+await page.goto(joinPath('{{#if baseURL}}{{baseURL}}{{/if}}', '{{path}}', '{{escapeQuotes query}}'), { waitUntil: 'load' });
+{{else}}
 await page.goto('{{#if baseURL}}{{baseURL}}{{/if}}{{path}}', { waitUntil: 'load' });
+{{/if}}
 await page.waitForLoadState('domcontentloaded');

package/src/generators/test-generator/adapters/playwright/templates/steps/partials/url-assertion.hbs

@@ -2,9 +2,14 @@
       Both used to carry their own copy and drifted apart: `see [X] page` wildcarded a dynamic
       `:id` segment but silently dropped `with {{v}}`, while `is on [X] page` asserted the query
       but escaped `:id` literally into a regex that can never match. One partial, one behaviour.
-      `pathRegex` is pre-escaped by pathToRegexSource (`:id` → `[^/]+`); the query is asserted
-      separately because its value is runtime data full of regex-special characters. --}}
-await expect(page).toHaveURL(/{{pathRegex}}/);
-{{#if query}}
-expect(page.url()).toContain('{{escapeQuotes query}}');
-{{/if}}
+
+      The predicate itself lives in specs/url-assert.ts (template: specs-url-assert.ts) — read it
+      for the semantics. It is a runtime helper rather than an inline lambda so that correcting
+      what "the URL matches" MEANS is a runtime patch, not a regenerate-the-world breaking change
+      for every suite in the field.
+
+      Only `pathRegex` is the generator's business: it alone knows the page selector's value and
+      its `:id` wildcards, and it is pre-escaped by pathToRegexSource. `\/?$` normalises a
+      trailing slash so `/vi/search/` does not read as a different page. The declared value stays
+      a plain string literal so the runtime-data marker pass can rewrite it to testData.get(…). --}}
+await expect(page).toHaveURL(urlMatches({ pathname: /^{{pathRegex}}\/?$/{{#if query}}, dataRef: '{{escapeQuotes dataRef}}', declared: '{{escapeQuotes query}}'{{/if}} }));

package/src/generators/test-generator/code-generator.ts

@@ -316,11 +316,19 @@ export class CodeGenerator {
       for (const h of capabilityRegistry.get(id)?.runtimeHelpers ?? []) this.syncGeneratedHelper(outputDir, h.file, h.template);
     }
 
-    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath, needsCleanupImport, needsDb, needsApi, needsMock });
-
     // Generate test code (async now to support AI mapping)
     const testCode = await this.generateTestCode(feature);
 
+    // `url-assert` is imported from what the body actually emitted, not from an active capability:
+    // page assertions belong to the DEFAULT ui capability, so a capability flag would import the
+    // helper into every UI spec — including the many that touch no URL at all. Hence the body is
+    // rendered BEFORE the imports. Importing exactly the names used keeps the import honest; the
+    // helper file itself is synced only when something needs it (an api-only unit carries none).
+    const urlAssertImports = ['urlMatches', 'joinPath'].filter((n) => testCode.includes(`${n}(`)).join(', ');
+    if (urlAssertImports) this.syncGeneratedHelper(outputDir, 'url-assert.ts', 'specs-url-assert.ts');
+
+    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath, needsCleanupImport, needsDb, needsApi, needsMock, urlAssertImports });
+
     // Combine and collapse any runs of 3+ newlines down to 2 (one blank line max)
     const raw = `${imports}\n\n${testCode}`;
     let code = raw.replace(/\n{3,}/g, '\n\n');

package/src/generators/test-generator/diagnostics.ts

@@ -26,12 +26,21 @@
  *   SG-W012 — a mock-install step AFTER a navigation step in the same block: page.route()
  *             registered after goto() misses every request fired during page load — move
  *             the install before the navigation (or into Background)
+ *   SG-W013 — a page assertion whose path came from a FALLBACK, not from a `type: page` selector
+ *             entry: the `[Ref]` did not resolve (or resolved to a non-page entry), so the step
+ *             asserts the feature's own path (or `/<ref>/`) instead of the page it names. The
+ *             assertion is anchored, so this is now a test that cannot pass rather than one that
+ *             always passed — either way it is not asserting what it reads as
+ *   SG-W014 — `[X] page with {{v}}` where the value carries no query and no fragment: there is
+ *             nothing for the query half to assert, so the step checks the PATH only. Not an
+ *             error (the value may legitimately vary per environment), but the step asserts
+ *             strictly less than it appears to
  *
  * Diagnostics never block generation by themselves; `sungen generate --strict`
  * turns any collected diagnostic into a non-zero exit.
  */
 
-export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012';
+export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012' | 'SG-W013' | 'SG-W014';
 
 export interface Diagnostic {
   code: DiagnosticCode;

package/src/generators/test-generator/step-mapper.ts

@@ -333,6 +333,8 @@ export class StepMapper {
         console.log(`  ✓ Pattern matched: ${step.text.substring(0, 50)}...`);
       }
       this.checkDataRefConsumed(step, mappedStep);
+      this.checkPageAssertionFallback(step, mappedStep);
+      this.checkDeclaredUrlHasNoQuery(step, mappedStep);
       return mappedStep;
     }
 
@@ -400,6 +402,58 @@ export class StepMapper {
     return expr || undefined;
   }
 
+  /**
+   * SG-W013 — a page assertion whose path came from a fallback rather than from a `type: page`
+   * selector entry. Both resolvers degrade quietly when `[Ref]` does not resolve: `see [X] page`
+   * falls back to the feature's own path, `is on [X] page` to `/<ref>/`. Before the assertion was
+   * anchored that produced a test which always PASSED; anchored, it produces one that can never
+   * pass. Neither is the assertion the author wrote, and nothing said so.
+   *
+   * Detected here rather than in the resolver on purpose: `MappedStep` carries only
+   * `{code, comment, imports}`, and the resolvers live in the driver packages while the collector
+   * lives in core. Re-asking the SAME resolver the step-mapper already owns costs three lines and
+   * duplicates no logic — the alternative is widening the adapter contract for every driver.
+   */
+  private checkPageAssertionFallback(step: ParsedStep, mapped: MappedStep): void {
+    if (!this.diagnostics || !step.selectorRef || step.elementType !== 'page') return;
+    if (!(mapped.code || '').includes('urlMatches(')) return;
+    let resolvedAsPage = false;
+    try {
+      const resolved = this.selectorResolver.resolveSelector(
+        step.selectorRef, this.featureName, step.elementType, step.nth
+      );
+      resolvedAsPage = resolved.selectorType === 'page' && !!resolved.value;
+    } catch {
+      resolvedAsPage = false;
+    }
+    if (resolvedAsPage) return;
+    this.diagnostics.add('SG-W013',
+      `page assertion for "[${step.selectorRef}]" has no "type: page" selector entry, so it asserts a FALLBACK path — the anchored assertion cannot match the real URL. Declare the page, e.g. "${step.selectorRef.toLowerCase()}:\\n  type: page\\n  value: '/your/path'"`,
+      { feature: this.featureName, step: step.text });
+  }
+
+  /**
+   * SG-W014 — `[X] page with {{v}}` where the value carries neither a query nor a fragment, so the
+   * query half of the assertion has nothing to check and the step asserts the PATH only.
+   *
+   * Deliberately a warning, not an error, and deliberately judged on the BASE test-data value: an
+   * env overlay can supply a query the base file lacks, so failing generation here would block a
+   * suite over data that is fine at run time. But it must not be silent either — asserting less
+   * than the step reads as is exactly the false-positive class this assertion exists to remove.
+   * Distinct from SG-W002: there the value is DROPPED, here it is used and found to hold no query.
+   */
+  private checkDeclaredUrlHasNoQuery(step: ParsedStep, mapped: MappedStep): void {
+    if (!this.diagnostics || !step.dataRef || step.elementType !== 'page') return;
+    if (!(mapped.code || '').includes('urlMatches(')) return;
+    // The base value, never resolveData(): in runtime mode that returns the marker, which carries
+    // no query by construction — the diagnostic would then fire on every single step.
+    const value = this.dataResolver.peekBaseValue(step.dataRef, this.featureName);
+    if (value == null || /[?#]/.test(value)) return;
+    this.diagnostics.add('SG-W014',
+      `{{${step.dataRef}}} = "${value}" carries no query and no fragment, so this page assertion checks the PATH only. Pass a value like "?q=…" (or drop the "with" and let the step assert a bare page).`,
+      { feature: this.featureName, step: step.text });
+  }
+
   /**
    * SG-W002 — a step carried a parsed {{dataRef}} but the matched pattern's generated
    * code never uses it (neither the runtime marker, the ${ref} fallback, nor the

package/src/generators/test-generator/template-engine.ts

@@ -277,8 +277,8 @@ export class TemplateEngine {
     this.baseContext = { ...this.persistentContext };
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean }): string {
-    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..', isParallel: options?.isParallel, needsCleanupImport: options?.needsCleanupImport, needsDb: options?.needsDb, needsApi: options?.needsApi, needsMock: options?.needsMock });
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean; urlAssertImports?: string }): string {
+    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..', isParallel: options?.isParallel, needsCleanupImport: options?.needsCleanupImport, needsDb: options?.needsDb, needsApi: options?.needsApi, needsMock: options?.needsMock, urlAssertImports: options?.urlAssertImports });
   }
 
   renderTestFile(data: {

package/src/generators/test-generator/utils/data-resolver.ts

@@ -64,6 +64,25 @@ export class DataResolver {
     return this.resolveValue(dataRef, featureName);
   }
 
+  /**
+   * The value as the BASE test-data file spells it, whatever the mode — for compile-time
+   * diagnostics that must judge the value itself, not the `__SUNGEN_TD$…$__` marker that
+   * `resolveData` returns in runtime mode.
+   *
+   * Returns undefined rather than throwing when the ref cannot be read (unknown path, or a
+   * captured var that only exists at runtime): a diagnostic must never break generation. Callers
+   * must treat the result as the base value only — an env overlay can change it at run time, so
+   * anything said about it belongs in a warning, never a gate.
+   */
+  peekBaseValue(dataRef: string, featureName?: string): string | undefined {
+    if (this.capturedVars.has(dataRef)) return undefined;
+    try {
+      return this.resolveValue(dataRef, featureName);
+    } catch {
+      return undefined;
+    }
+  }
+
   private resolveValue(dataRef: string, featureName?: string): string {
     const { fileName, valuePath } = this.parseDataRef(dataRef, featureName);
     const data = this.loadDataFile(fileName);

package/src/harness/script-check.ts

@@ -57,7 +57,15 @@ export function extractTestBlocks(specSrc: string): { title: string; body: strin
   return blocks;
 }
 
-const CODE_LINE = /\b(await|expect|testData|page\.)\b|=\s*[^=]/;
+// A line counts as executable code when it interacts with the page/assertions/data,
+// assigns, OR is a standalone call expression (`mock.setPassthrough(page);`,
+// `driver.enable(...)`). The call branch is what keeps capability helpers from
+// reading as hollow: a sync void call after its step comment matched none of the
+// original alternatives (no await/expect/testData, `page` only as a bare argument,
+// no `=`), so @mock:passthrough scenarios were flagged BYPASS (field report) — on
+// sungen's own mock-route golden fixture, no less. Comment lines are step markers
+// (never inside a scanned region), so `identifier(` cannot false-match non-code.
+const CODE_LINE = /\b(await|expect|testData|page\.)\b|=\s*[^=]|[\w$]\s*\(/;
 
 /**
  * Faithfulness / anti-bypass: a non-@manual test that performs actions but proves

package/src/harness/secret-scan.ts

@@ -27,7 +27,18 @@ function scanText(text: string, file: string): SecretHit[] {
     }
     const m = raw.match(SECRET_KEY);
     if (m) {
-      const val = m[2].trim().replace(/^["']|["']$/g, '');
+      // Take only the FIRST scalar after the key. The old `(.+)$` capture swallowed
+      // the rest of the line, so in an inline-map @cases row
+      //   - { …, password: "${QA_X}", expected_status: 201 }
+      // the "value" included `, expected_status: 201 }` — whose digits + length
+      // pushed EVERY such row over the threshold regardless of the actual value
+      // (field report: ${QA_*} refs and a deliberate wrong_password all warned).
+      const tail = m[2].trim();
+      const quoted = tail.match(/^(["'])((?:\\.|(?!\1).)*)\1/);
+      const val = (quoted ? quoted[2] : tail.split(/[,}\s]/, 1)[0]).trim();
+      // A ${VAR} env ref IS the recommended practice (.env.qa overlays) — never
+      // warn on it, or the gate teaches users the opposite of the convention.
+      if (/^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(val)) return;
       // Long, high-entropy-ish, not an obvious placeholder/test value.
       if (val.length >= 20 && !PLACEHOLDERish.test(raw) && /[A-Za-z]/.test(val) && /[0-9]/.test(val)) {
         hits.push({ file, line, reason: `secret-named key "${m[1]}" with a long literal value` });

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/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;
+  };
+}