@sun-asterisk/sungen 3.2.26 → 3.2.28

package/src/cli/commands/next.ts

@@ -40,8 +40,8 @@ function render(s: UnitState): void {
   if (s.audit) L(`  audit: ${s.audit.overall}/10 [${s.audit.gateStatus}] · ${s.audit.findings.length} finding(s)`);
   L('');
   for (const st of s.steps) {
-    const mark = st.kind === 'blocked' ? '⛔' : st.kind === 'optional' ? '○' : '→';
-    L(`  ${mark} ${st.command}`);
+    const mark = st.kind === 'blocked' ? '⛔' : st.kind === 'optional' ? '○' : st.kind === 'decide' ? '⚖' : '→';
+    L(`  ${mark} ${st.command}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}`);
     L(`     ${st.because}`);
   }
   L('');

package/src/generators/test-generator/adapters/appium/templates/steps/assertions/page-assertion.hbs

@@ -1 +1,7 @@
+{{#if anchor~}}
+{{!-- A native app has no URL; the page's declared `anchor:` (a screen marker) IS the page oracle
+      here — the same rendered-content proof the web side adds after its URL check (#662). --}}
+await __assertVisible({{#with anchor}}{{> appium-selector-expr}}{{/with}});
+{{~else~}}
 // page/URL assertion is not applicable on mobile (no URL) — [{{value}}]
+{{~/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/page-assertion.hbs

@@ -1 +1,2 @@
-{{> url-assertion}}
+{{> url-assertion}}{{#if anchor}}
+await expect({{#with anchor}}{{> locator}}{{/with}}).toBeVisible();{{/if}}

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

@@ -11,5 +11,9 @@
       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}} }));
+      a plain string literal so the runtime-data marker pass can rewrite it to testData.get(…).
+
+      `expectPage`, not a bare `toHaveURL`: a polling URL assertion passes on the first transient
+      match, before a route guard has bounced the user away (#662). The helper arrives, lets the
+      page settle, holds, and re-asserts — read specs/url-assert.ts. --}}
+await expectPage(page, { pathname: /^{{pathRegex}}\/?$/{{#if query}}, dataRef: '{{escapeQuotes dataRef}}', declared: '{{escapeQuotes query}}'{{/if}} });

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

@@ -346,7 +346,7 @@ export class CodeGenerator {
     // 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(', ');
+    const urlAssertImports = ['urlMatches', 'joinPath', 'expectPage'].filter((n) => testCode.includes(`${n}(`)).join(', ');
     if (urlAssertImports) this.syncGeneratedHelper(outputDir, 'url-assert.ts', 'specs-url-assert.ts');
 
     // Same body-first rule for the runtime regex-escape helper: only a spec whose

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

@@ -490,7 +490,7 @@ export class StepMapper {
    */
   private checkPageAssertionFallback(step: ParsedStep, mapped: MappedStep): void {
     if (!this.diagnostics || !step.selectorRef || step.elementType !== 'page') return;
-    if (!(mapped.code || '').includes('urlMatches(')) return;
+    if (!/\b(?:urlMatches|expectPage)\(/.test(mapped.code || '')) return;   // both URL-assertion shapes (#662)
     let resolvedAsPage = false;
     try {
       const resolved = this.selectorResolver.resolveSelector(
@@ -518,7 +518,7 @@ export class StepMapper {
    */
   private checkDeclaredUrlHasNoQuery(step: ParsedStep, mapped: MappedStep): void {
     if (!this.diagnostics || !step.dataRef || step.elementType !== 'page') return;
-    if (!(mapped.code || '').includes('urlMatches(')) return;
+    if (!/\b(?:urlMatches|expectPage)\(/.test(mapped.code || '')) return;   // both URL-assertion shapes (#662)
     // 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);

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

@@ -1,4 +1,5 @@
 import * as fs from 'fs';
+import { normalizeRefLabel } from '../../../utils/ref-key';
 import * as path from 'path';
 import yaml from 'yaml';
 import { readYaml, readYamlIfExists } from '../../../utils/yaml-io';
@@ -22,6 +23,12 @@ interface SelectorEntry {
   scope?: string;         // Parent landmark aria-label to scope within (e.g., 'desktop navigation')
   match?: 'exact' | 'partial';  // For getByText matching (default: partial)
 
+  // === Page anchor (#662) ===
+  // For a `type: page` entry: the element that proves the page has RENDERED — a heading, a
+  // landmark, a title. `see [X] page` asserts the URL and then this element, so a route guard
+  // that bounces the user after the URL has already matched turns the step red instead of green.
+  anchor?: SelectorEntry;
+
   // === Mobile per-platform variant (issue #392) ===
   // `android:`/`ios:` sub-selectors for one logical element whose locator differs per OS (composite
   // content-desc, partial/dynamic text, native predicate). Each is a full SelectorEntry.
@@ -126,6 +133,7 @@ export interface ResolvedSelector {
   attribute?: string;   // Attribute to check
   pattern?: string;     // Regex for attribute value
   expanded?: { class?: string; attribute?: string; state?: 'none' };  // Expand/collapse state signal
+  anchor?: ResolvedSelector;  // page entries only — the rendered-content proof behind `see [X] page` (#662)
 }
 
 /**
@@ -189,7 +197,7 @@ export class SelectorResolver {
    * "書類一覧"        → "書類一覧"
    */
   static generateKey(label: string): string {
-    return label.normalize('NFC').toLowerCase().trim().replace(/\s+/g, ' ');
+    return normalizeRefLabel(label);   // the one definition — the harness reads the same rule (#660)
   }
 
   /**
@@ -579,6 +587,9 @@ export class SelectorResolver {
     if (entry.attribute) v2Fields.attribute = entry.attribute;
     if (entry.pattern) v2Fields.pattern = entry.pattern;
     if (entry.expanded) v2Fields.expanded = entry.expanded;
+    // The anchor is a selector in its own right; it must not inherit the PAGE's label as its
+    // accessible name, so it resolves against its own name (or nothing).
+    if (entry.anchor) v2Fields.anchor = this.resolveFromEntry(entry.anchor, entry.anchor.name ?? '');
 
     // Helper to attach v2 fields and inputMethod
     const withExtras = (resolved: ResolvedSelector): ResolvedSelector => {

package/src/harness/audit.ts

@@ -427,7 +427,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
       viewpointBaseline.removed?.length ? `removed [${viewpointBaseline.removed.join(', ')}]` : '',
       viewpointBaseline.added?.length ? `added [${viewpointBaseline.added.join(', ')}]` : '',
     ].filter(Boolean).join(', ');
-    findings.push(`VIEWPOINT-BASELINE-CHANGED: test-viewpoint.md no longer declares what it did when this unit was last accepted — ${moved || 'the declared ids were reordered or replaced'}. atomicLedger + traceability measure the suite AGAINST this file, so they are excluded from the score until the change is confirmed: a generator that rewrites the declaration scores both 100% by construction, and a viewpoint dropped from the file stops being missing from anything. Review the diff (a removed id means that coverage is now unclaimed), then run \`sungen audit --screen ${screenName} --accept-viewpoint\`.`);
+    findings.push(`VIEWPOINT-BASELINE-CHANGED: test-viewpoint.md no longer declares what it did when this unit was last accepted — ${moved || 'the declared ids were reordered or replaced'}. atomicLedger + traceability measure the suite AGAINST this file, so they are excluded from the score until the change is confirmed: a generator that rewrites the declaration scores both 100% by construction, and a viewpoint dropped from the file stops being missing from anything. Review the diff (a removed id means that coverage is now unclaimed), then run \`sungen audit --screen ${screenName} --accept-viewpoint\` — a QA decision: an agent presents it and does not run it, because a yardstick accepted by the process it measures reads 100% by construction.`);
   }
   // On a contract flow the page type is INTENTIONALLY not applied — the contract is the checklist.
   if (gate.pageTypeSource === 'undetermined' && !flowScored) {
@@ -445,7 +445,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
         : `FLOW-OUTCOME-UNPROVEN: no scenario asserts data on the outcome screen \`${flowQ.contract!.outcome.screen}\` — the flow never proves its own goal ("${flowQ.contract!.goal}"). Add the happy-path scenario that ends in the declared final assertion.`);
     }
     if (flowQ.offGoalRatio > 0.35) {
-      findings.push(`FLOW-SCOPE-CREEP: ${flowQ.offGoal.length}/${scenarios.length} scenarios never touch the outcome screen \`${flowQ.contract!.outcome.screen}\` and are not guards/error-recovery (categories: ${flowQ.offGoalCategories.join(', ')}) — evidence of a SECOND business goal in this flow. Split them into their own flow (one flow = one goal, one observable outcome).`);
+      findings.push(`FLOW-SCOPE-CREEP: ${flowQ.offGoal.length}/${scenarios.length} scenarios never touch the outcome screen \`${flowQ.contract!.outcome.screen}\` and are not guards/error-recovery (categories: ${flowQ.offGoalCategories.join(', ')}) — evidence of a SECOND business goal in this flow. Split them into their own flow (one flow = one goal, one observable outcome) — or, when the spec KEEPS a variant deliberately light (an entry variant that only proves it reaches the action bar), declare that flow in \`flows:\` with its own \`outcome:\` and it is judged against that, not against the use case's. Never widen a scenario to satisfy this finding: that trades a reviewer's "over-testing" for the gate's approval, and the gate is the one that is wrong.`);
     }
     for (const ph of flowQ.phases.filter((p) => !p.covered || !p.automated)) {
       findings.push(`FLOW-PHASE-${ph.phase}-MISSING: journey phase ${ph.phase} (${ph.phase === 'HP' ? 'happy path proving the outcome' : ph.phase === 'ER' ? 'error recovery — validation must not trap the journey' : 'guards — direct access / back / refresh'}) is ${ph.covered ? 'covered only by @manual' : 'not covered'} → it does not count toward flowCoverage until automated.`);
@@ -591,7 +591,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     findings.push(`FLOW-DEPTH: this stateful flow (${what}) exercises ${dims - flowDepth.missing.length}/${dims} applicable regression dimensions — missing [${flowDepth.missing.join(', ')}] → ${flowDepth.missing.map((m) => how[m]).join('; ')}. (businessDepth is capped until covered.)`);
   }
   for (const w of oracle.weak) {
-    findings.push(`ORACLE-WEAK: "${w.name}" — ${w.hint}`);
+    findings.push(`${w.code ?? 'ORACLE-WEAK'}: "${w.name}" — ${w.hint}`);
   }
   for (const u of claim.unproven) {
     const tag = u.severity === 'fail' ? 'CLAIM-UNPROVEN' : 'CLAIM-WEAK';
@@ -606,7 +606,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     findings.push(`BALANCE: ${balance.note} Stop expanding secondary viewpoints until business-core gaps are filled.`);
   }
   if (adoptedPostHoc) {
-    findings.push(`VIEWPOINT-ADOPTED-POST-HOC: this is the first audit of \`requirements/test-viewpoint.md\` and the suite ALREADY has ${scenarios.length} scenarios, so the yardstick is being introduced against tests that already exist. A declaration written after the suite can only measure what its author already thought of — and if it was derived FROM the suite, \`atomicLedger\` and \`traceability\` read 100% by construction while anything dropped along the way stops being missing from anything. Both axes are held as unverified until you review the claims (add what you care about, delete what you do not) and confirm: \`sungen audit --screen ${screenName} --accept-viewpoint\`.`);
+    findings.push(`VIEWPOINT-ADOPTED-POST-HOC: this is the first audit of \`requirements/test-viewpoint.md\` and the suite ALREADY has ${scenarios.length} scenarios, so the yardstick is being introduced against tests that already exist. A declaration written after the suite can only measure what its author already thought of — and if it was derived FROM the suite, \`atomicLedger\` and \`traceability\` read 100% by construction while anything dropped along the way stops being missing from anything. Both axes are held as unverified until you review the claims (add what you care about, delete what you do not) and confirm: \`sungen audit --screen ${screenName} --accept-viewpoint\` — a QA decision: an agent presents it and does not run it.`);
   }
   if (!hasYardstick) {
     const lost = [

package/src/harness/flow-contract.ts

@@ -22,6 +22,7 @@
  *                       declared collection (order, application, submission …)
  */
 import * as fs from 'fs';
+import { refNamespaces, screenKey } from '../utils/ref-key';
 import * as path from 'path';
 import { parse as parseYaml } from 'yaml';
 import { ScenarioInfo } from './parse';
@@ -179,7 +180,7 @@ export function loadFlowContract(unitDir: string): { contract: FlowContract | nu
       actor: raw.actor !== undefined ? String(raw.actor) : undefined,
       trigger: raw.trigger !== undefined ? String(raw.trigger) : undefined,
       precondition: raw.precondition !== undefined ? String(raw.precondition) : undefined,
-      outcome: { screen: String(outcome!.screen).toLowerCase(), assertion: outcome!.assertion !== undefined ? String(outcome!.assertion) : undefined },
+      outcome: { screen: screenKey(String(outcome!.screen)), assertion: outcome!.assertion !== undefined ? String(outcome!.assertion) : undefined },
       value: raw.value !== undefined ? String(raw.value) : undefined,
       successGuarantee: raw.successGuarantee !== undefined ? String(raw.successGuarantee) : (raw.success_guarantee !== undefined ? String(raw.success_guarantee) : undefined),
       minimalGuarantee: raw.minimalGuarantee !== undefined ? String(raw.minimalGuarantee) : (raw.minimal_guarantee !== undefined ? String(raw.minimal_guarantee) : undefined),
@@ -210,7 +211,7 @@ export function loadFlowContract(unitDir: string): { contract: FlowContract | nu
             .map((e) => ({
               name: String(e.name),
               owner: e.owner !== undefined ? String(e.owner) : undefined,
-              screens: Array.isArray(e.screens) ? (e.screens as unknown[]).map((x) => String(x).toLowerCase()) : [],
+              screens: Array.isArray(e.screens) ? (e.screens as unknown[]).map((x) => screenKey(String(x))) : [],
             }))
         : undefined,
       golden: raw.golden === true,
@@ -223,13 +224,12 @@ export function loadFlowContract(unitDir: string): { contract: FlowContract | nu
 
 /** `[screen:element]` namespaces referenced by a scenario's steps, in step order. */
 function namespacesInOrder(s: ScenarioInfo): string[] {
-  const out: string[] = [];
-  for (const m of s.stepsText.matchAll(/\[([a-z0-9_.-]+):/g)) out.push(m[1]);
-  return out;
+  // Through the shared vocabulary — a private regex here once dropped every multi-word screen (#660).
+  return refNamespaces(s.stepsText);
 }
 
 function touchesOutcome(s: ScenarioInfo, outcomeScreen: string): boolean {
-  return namespacesInOrder(s).includes(outcomeScreen);
+  return namespacesInOrder(s).includes(screenKey(outcomeScreen));
 }
 
 /**
@@ -244,7 +244,8 @@ function reachesOutcome(s: ScenarioInfo, outcomeScreen: string): boolean {
   // anywhere in the scenario would suppress every positive assertion in it.
   const steps = (s.steps ?? []).map((st) => st.text.toLowerCase());
   if (steps.length === 0) return touchesOutcome(s, outcomeScreen);
-  return steps.some((t) => t.includes(`[${outcomeScreen}`)
+  const key = screenKey(outcomeScreen);
+  return steps.some((t) => refNamespaces(t, { bare: true }).includes(key)
     && !/\b(is hidden|is not visible|does not exist|is absent|no longer)\b/.test(t));
 }
 
@@ -366,15 +367,39 @@ export function flowInventory(contract: FlowContract, scenarios: ScenarioInfo[])
  * Both inflate the flow count while adding no branch coverage, which is exactly what makes a
  * suite look complete to the harness and thin to a reviewer.
  */
+/** An interaction, whichever keyword the author put in front of it — `Then User click` exists. */
+const INTERACTION_VERB = /\buser\s+(?:click|clicks|tap|taps|fill|fills|type|types|select|selects|press|presses|check|checks|uncheck|unchecks|upload|uploads|submit|submits|enter|enters|choose|chooses|toggle|toggles|drag|drags|swipe|swipes|scroll|scrolls|hover|hovers|clear|clears)\b/i;
+
 export function misfiledPhases(
   contract: FlowContract, scenarios: ScenarioInfo[], basicPhase: string,
 ): Array<{ scenario: string; id: string; why: string }> {
   const out: Array<{ scenario: string; id: string; why: string }> = [];
   const outcome = contract.outcome.screen;
+  // A branch point is a STRUCTURAL fact before it is a vocabulary one. The check used to demand a
+  // branch WORD (back / cancel / retry…), so a precondition guard — `Given` already authenticated,
+  // or no originating session → `Then` redirected — had no way to satisfy it: such a scenario has
+  // no interaction step at all, by construction, and its branch is in the `Given`, not in a verb.
+  // Reported under AF and EF alike on a real project (#660). Two structural signals now count:
+  // no `When` at all (a guard by construction), or a `Given` the basic flow never establishes
+  // (a precondition branch). Vocabulary remains as the fallback for scenarios without step data.
+  const basicGivens = new Set(scenarios
+    .filter((sc) => phaseToken(flowIdOf(sc, contract.phases) ?? '') === phaseToken(basicPhase))
+    .flatMap((sc) => (sc.steps ?? []).filter((st) => st.bucket === 'given').map((st) => st.text.toLowerCase().trim())));
+  const branchesStructurally = (sc: ScenarioInfo): boolean => {
+    const steps = sc.steps ?? [];
+    if (steps.length === 0) return false;
+    // No interaction AND the journey does not complete: a guard by construction (the redirect or
+    // the blocked screen IS the branch). No interaction but the outcome IS reached is a different
+    // animal — a postcondition on the basic path — and stays subject to the checks below.
+    const interacts = steps.some((st) => st.bucket === 'when' || INTERACTION_VERB.test(st.text));
+    if (!interacts && !reachesOutcome(sc, outcome)) return true;
+    return steps.some((st) => st.bucket === 'given' && !basicGivens.has(st.text.toLowerCase().trim()));
+  };
   for (const s of scenarios) {
     const id = flowIdOf(s, contract.phases);
     if (!id || phaseToken(id) === phaseToken(basicPhase)) continue;
     const ph = phaseToken(id);
+    if (branchesStructurally(s)) continue;
     if (ph === 'EF' && reachesOutcome(s, outcome)) {
       // An error-then-recover flow legitimately ends at the outcome — it is the recovery that
       // is being proven, and a guard flow is blocked rather than "failed". Only a scenario with
@@ -415,8 +440,16 @@ export function flowQuality(unitDir: string, scenarios: ScenarioInfo[]): FlowQua
   // guard/error phase is evidence of a SECOND business goal in this flow.
   const declaredPhases = contract.phases;
   const basic = declaredPhases.filter((p) => p !== 'UI')[0];
+  // A flow the inventory declares WITH ITS OWN outcome is measured against that outcome, never
+  // against the use case's. A spec that keeps an entry variant deliberately light ("prove the
+  // entry reaches the action bar; do not repeat the full assertion") could only satisfy the old
+  // check by widening the scenario — which the human reviewer then called over-testing. The gate
+  // and the reviewer were optimising different things; the declaration is where they agree (#660).
+  const ownOutcome = new Set((contract.flows ?? []).filter((f) => f.outcome).map((f) => f.id));
   const offGoalScenarios = scenarios.filter((s) => {
     if (touchesOutcome(s, outcomeScreen)) return false;
+    const fid = flowIdOf(s, declaredPhases);
+    if (fid && ownOutcome.has(fid)) return false;
     const ph = phaseOf(s, declaredPhases, contract.phaseDetails);
     // Any NON-basic declared phase (guards, error recovery, alternate branches) legitimately
     // stops before the outcome — that is what a branch IS. Only an unclassified scenario that
@@ -470,7 +503,7 @@ export function flowQuality(unitDir: string, scenarios: ScenarioInfo[]): FlowQua
     const steps = s.steps ?? [];
     let current: string | null = null;
     for (let i = 0; i < steps.length; i++) {
-      const ns = (steps[i].text.match(/\[([A-Za-z0-9_.-]+):/) || [])[1]?.toLowerCase() ?? null;
+      const ns = refNamespaces(steps[i].text)[0] ?? null;
       if (!ns) continue;
       if (current !== null && ns !== current) {
         total++;

package/src/harness/next-step.ts

@@ -25,8 +25,14 @@ export interface NextStep {
   command: string;
   /** Why it is next — stated so an agent can weigh it, not just obey it. */
   because: string;
-  /** `blocked` steps are not runnable yet; they name what to resolve first. */
-  kind: 'do' | 'blocked' | 'optional';
+  /**
+   * `blocked` steps are not runnable yet; they name what to resolve first. `decide` steps are a
+   * HUMAN'S to run: an agent presents them and stops. Accepting the viewpoint baseline is the
+   * case — offered as a plain `do`, an agent that had just rewritten `test-viewpoint.md` from the
+   * spec ran it, and `atomicLedger`/`traceability` read 100% against a checklist it wrote itself
+   * in the same session (#660).
+   */
+  kind: 'do' | 'blocked' | 'optional' | 'decide';
 }
 
 export interface UnitState {
@@ -160,6 +166,7 @@ export function readUnitState(
 const REPAIRABLE = [
   'FLOW-CONTRACT-MISSING', 'FLOW-INVENTORY-MISSING', 'FLOW-UNCOVERED', 'FLOW-UNDECLARED',
   'FLOW-PHASE-MISFILED', 'FLOW-GUARANTEE-MISSING', 'FLOW-OUTCOME-UNPROVEN', 'CONTINUITY-ONE-SIDED',
+  'ORACLE-URL-ONLY',
   'SPEC-RESTATED-UNVERIFIED', 'VIEWPOINT-GESTURE-SUBSTITUTED', 'SPEC-UNCOVERED', 'TRIGGER-UNCOVERED',
   'VIEWPOINT-ITEM-MISSING', 'MANUAL-CODE-MISSING', 'MANUAL-AUTOMATABLE', 'DEPTH-DEFERRED',
 ];
@@ -228,9 +235,9 @@ export function deriveSteps(s: UnitState): NextStep[] {
   }
   if (s.audit.viewpointBaselineStatus === 'changed') {
     out.push({
-      kind: 'do',
+      kind: 'decide',
       command: `sungen audit --screen ${s.unit} --accept-viewpoint`,
-      because: 'test-viewpoint.md changed since the accepted baseline, so the ledger and traceability axes are not evidence until you confirm the new declaration',
+      because: 'test-viewpoint.md changed since the accepted baseline, so the ledger and traceability axes are not evidence until a QA confirms the new declaration. A decision, not a step: an agent presents it and does not run it — accepting the yardstick you just wrote makes both axes read 100% by construction',
     });
   }
   const repair = s.audit.findings

package/src/harness/sensors.ts

@@ -386,7 +386,7 @@ export function flowRegressionDepth(scenarios: ScenarioInfo[]): FlowDepthResult
 // ---------- Sensor: Oracle strength (H4) ----------
 
 export interface OracleStrengthResult {
-  weak: { name: string; hint: string }[];   // scenarios proving facet membership by a name-substring
+  weak: { name: string; hint: string; code?: string }[];   // facet-by-name-substring, or URL-only (code ORACLE-URL-ONLY)
   facetClaims: number;                       // scenarios that touch a category/brand facet (denominator)
   ratio: number;                             // 1 - weak/facetClaims (1 when none) — caps businessDepth
 }
@@ -395,11 +395,34 @@ export interface OracleStrengthResult {
 // a category/brand term does NOT prove the item BELONGS to that facet (a "Dress" item need not contain
 // "Dress" in its name). The strong oracle is the results-page title/header, a detail-page facet field,
 // an API/DB query, or an explicit @manual:M2 deferral.
+/** A `Then` that only asserts where the browser IS: `see [X] page`, `is on [X] page`, `should see route`. */
+const URL_ONLY_THEN = /\]\s*page\b|\bis on \[|\bshould (?:see route|remain on)\b/i;
+/** The scenarios where a transient URL lies most expensively: permission, auth, guards, redirects. */
+const GUARD_LIKE = /\b(?:auth\w*|role|permission|access|guard|redirect\w*|forbidden|403|unauthori[sz]\w*|logged[- ]?(?:in|out)|session)\b|権限|quyền|đăng nhập/i;
+
 const WEAK_FACET_ORACLE = /\bsee all\b\s*\[[^\]]*\b(name|title|label)\b[^\]]*\][^{[]*\bcontains?\b[^{]*\{\{[^}]*\b(categ|brand|facet|filter|term)/i;
 const FACET_REF = /\{\{[^}]*\b(categ|brand|facet|filter)\b[^}]*\}\}|\b(category|brand)\b/i;
 
 export function oracleStrength(scenarios: ScenarioInfo[]): OracleStrengthResult {
-  const weak: { name: string; hint: string }[] = [];
+  const weak: { name: string; hint: string; code?: string }[] = [];
+  // A scenario whose EVERY `Then` is a URL assertion has a URL-only oracle. `toHaveURL` passes on
+  // the first transient match, and a client-side router pushes the destination before the guard or
+  // the API has answered — so "role X can open screen Y" stayed green while the server returned 403
+  // and the app bounced to its error page (#662). The runtime now settles and re-asserts, which
+  // catches the bounce; this names the scenarios that still prove nothing about the page having
+  // RENDERED, and the one-line-per-screen fix.
+  for (const s of scenarios) {
+    if (s.manual) continue;
+    const thens = (s.steps ?? []).filter((st) => st.bucket === 'then');
+    if (thens.length === 0) continue;
+    if (!thens.every((st) => URL_ONLY_THEN.test(st.text))) continue;
+    const guardLike = GUARD_LIKE.test(s.haystack);
+    weak.push({
+      name: s.name.slice(0, 80),
+      code: 'ORACLE-URL-ONLY',
+      hint: `every \`Then\` is a URL assertion${guardLike ? ' on a permission / guard scenario' : ''} — it proves the router pushed a path, not that the page rendered for this user${guardLike ? ', and this is exactly the scenario a late 403 redirect turns falsely green' : ''}. Give the page selector an \`anchor:\` (a heading/landmark only the rendered page has) — one line per screen, and every \`see [X] page\` on it becomes a content oracle — or add a content assertion after it.`,
+    });
+  }
   for (const s of scenarios) {
     if (s.manual) continue; // a @manual facet check is a deliberate deferral, not a weak automated oracle
     if (WEAK_FACET_ORACLE.test(s.stepsText)) {
@@ -659,7 +682,15 @@ const CLAIM_RULES: ClaimRule[] = [
     // category behind "browser back does not re-submit", "does not re-charge the card",
     // "double-click does not create two orders" — not a per-feature keyword.
     claim: 'no-side-effect/no-duplicate',
-    title: /(?=.*\b(submit|sen[dt]|resend|resubmit|re-?fire|re-?issue|re-?post|repost|create|charge|order|payment|\bpay\b|email|request|\botp\b|insert|register|book|duplicate|double[- ]?submit|again|twice)\b)(?=.*(\bno\b|\bnot\b|n['’]t\b|\bnever\b|\bwithout\b|\bcannot\b|prevent|block|avoid|reject|disabl|\bdeny\b|denies|\bkhông\b|\bchưa\b))/i,
+    // The negation must attach to an EFFECT — something created, sent, stored, charged, fired
+    // twice — not to the INPUT being refused. "duplicate address is rejected" is an observable
+    // rejection, proven by the error assertion in front of the user; "no duplicate record is
+    // created" is an absence nothing on the page can show. The rule used to fire on any action
+    // word beside any negation word, so ordinary rejection titles were told to go find a DB count,
+    // and renaming around the trigger words became the workflow (#660). Two shapes now qualify:
+    // (a) a negation followed by an effect token, (b) a repeat token (twice / again / double- or
+    // re-submit / second …) beside a negation, "only once" or a disabled control.
+    title: /(?:\b(?:no|not|n['’]t|never|without|cannot|không|chưa)\b[^.;]{0,40}?\b(?:creat(?:e|es|ed|ion)|record(?:s|ed)?|rows?|entr(?:y|ies)|sen[dt]|resen[dt]|charg(?:e|es|ed)|order(?:s|ed)?|payment|paid|insert(?:s|ed)?|submit(?:s|ted)?|submission|stor(?:e|es|ed)|sav(?:e|es|ed)|persist(?:s|ed)?|fir(?:e|es|ed)|issu(?:e|es|ed)|post(?:s|ed)?|email(?:s|ed)?|request(?:s|ed)?|\botp\b|twice|again|second|double|duplicate[sd]?|re-?submit(?:s|ted)?|tạo|gửi|lưu)\b)|(?=.*\b(?:double[- ]?(?:submit|click|tap|activation)|re-?submi(?:t|ts|tted|ssion)|twice|again|second (?:submit|submission|request|click|tap|order|charge|email|record))\b)(?=.*\b(?:no|not|n['’]t|never|without|cannot|prevent(?:s|ed)?|block(?:s|ed)?|avoid(?:s|ed)?|only once|exactly one|single|idempotent|disabled|không|chưa)\b)/i,
     // `is disabled` counts: when the spec's own mechanism against a repeat is "the control
     // is disabled immediately" (FR-014-style), asserting the disabled state IS the contrast —
     // the second activation cannot occur. Without it the canonical double-submit proof shape

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

@@ -96,7 +96,7 @@ dropped along the way stops being missing from anything. `sungen audit` now repo
 `VIEWPOINT-ADOPTED-POST-HOC` on the first sighting of a viewpoint alongside an existing suite and
 holds `atomicLedger` + `traceability` as unverified until a human accepts it — so the honest move
 is to write the claims from `spec.md` and the contract, mark plainly that they are a draft for QA
-review, and let the QA revise before `--accept-viewpoint`.
+review, and let the QA revise before `--accept-viewpoint`. **You never run `--accept-viewpoint` yourself** — `sungen next` lists it as a `⚖ decide` step for exactly this reason: an agent accepting the yardstick it wrote in the same session makes `atomicLedger` and `traceability` read 100% against its own checklist, and the Exception Flow it forgot stops being missing from anything. Present the acceptance to the QA (`AskUserQuestion`) with what the file declares, and stop.
 
 **When you give a claim an id, a scenario must carry that id.** The id is the contract: a claim
 whose id no scenario carries is reported MISSING, and word overlap will not rescue it. Several

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

@@ -121,10 +121,28 @@ two content-filtered queries can hit different rows if the table re-renders in b
 > assert the page you expect (`Then User see [Other] page`); to say "this went away", assert a marker
 > element (`Then User see [Some Element] is hidden`).
 
+**Pattern 8 is a URL oracle, and a URL is not a rendered page.** `see [T] page` proves the router
+pushed a path — it does NOT prove the page rendered for this user. A client-side router pushes the
+destination BEFORE the route guard or the permission API has answered, so a user with no permission
+is "on" `/items/detail` for a few hundred milliseconds before being bounced to the 403 page. Since
+3.2.28 the step compiles to `expectPage(page, {…})` — arrive, let the page settle, HOLD the URL, and
+re-assert — so a late redirect fails and names where the user ended up. But the page having
+rendered is still unproven: **for permission / auth-guard / "role X can open screen Y" scenarios,
+give the page selector an `anchor:`** (a heading or landmark only the rendered page has) — every
+`see [T] page` on that screen then asserts the anchor too — or follow the page step with a content
+assertion. A scenario whose every `Then` is a page assertion is reported as `ORACLE-URL-ONLY`.
+
+```yaml
+detail:
+  type: 'page'
+  value: '/items/detail'
+  anchor: { type: 'role', value: 'heading', name: 'Item Detail' }   # the rendered-content proof
+```
+
 **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:
+`is on [T] page` (Then-side) compile to ONE web-first check — `expectPage(page, {…})`, built on
+`toHaveURL(urlMatches({…}))` and retrying like any other assertion — comparing the **exact** pathname
+(anchored, trailing slash normalised) plus the query:
 
 | step | asserts |
 |---|---|

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

@@ -34,6 +34,7 @@ user-invocable: false
 | **DEPTH** | business-critical scenarios assert only visibility/navigation | Replace `Then User see [X] page/section` with **observable data assertions**: `Then User see [X] with {{value}}`, `Then User see [T] table match data:`. Capture real expected values into `test-data.yaml`. |
 | **BALANCE** | secondary viewpoints (UI/validation/security) outweigh business-core | **Stop expanding** secondary viewpoints; generate the missing business-core scenarios first. Do not add more subscription/UI variants while core is thin. |
 | **TRACE** | scenarios use ad-hoc `VP-<CAT>-NNN` codes not linked to the viewpoint-overview | Make each scenario map to a viewpoint-overview id (align category codes, or add a mapping comment). |
+| **ORACLE-URL-ONLY** | every `Then` in the scenario is a page/URL assertion — it proves a path was pushed, not that the page rendered; on a permission/guard scenario a late 403 redirect turns it falsely green | Add `anchor:` to the page selector (one line per screen; every `see [X] page` on it becomes a content oracle) or a content assertion after the page step. Never delete the page step to silence it. |
 | **UNIVERSAL** | a universal theme (error/empty-state, accessibility) is absent | Low priority — add if in scope; otherwise note as out-of-scope with reason. |
 
 ## P5 steps for deep cross-screen / list coverage
@@ -68,6 +69,23 @@ Use these when repairing GATE/DEPTH findings for the hard viewpoints (cart/detai
 4. **EP/data families are OK.** A `duplicates` cluster with `sameDataLikely=false` is an intentional equivalence-partition family (e.g. many invalid-email cases) — keep it; only collapse `sameDataLikely=true` exact duplicates.
 5. **Advisory findings — surface, don't gate.** `MANUAL-REASON-MISMATCH` → fix the scenario's `@manual:Mx` code (so the planner recommends the right driver) during repair. `CAPABILITY-SUGGESTION` → **present it to the user as a next-step option** (e.g. "N @manual could be automated — `sungen capability add api db`?"), **recommend-only — never auto-install**. `VERIFICATION-OUT-OF-SCOPE (api|db)` → the unit uses `@api`/`@query`/`@requires:api|db` verification the project's recorded **test type** never opted into (E2E/UI-only per `capabilities.yaml`, and the viewpoint doesn't ask for it). During repair: **rewrite the oracle to be UI-observable** (or downgrade the deep check to an `(optional deep check: …)` note); only keep the API/DB verification if the project genuinely tests that layer — then record it (`verification: [ui, api]` / `sungen capability add`). Keep API/DB-in-E2E to the ≤20% band. Neither of these fails the gate.
 
+6. **A gate that contradicts the spec's intent is a question, not a repair.** When the only way to
+   satisfy a finding is to change what the spec deliberately asked for — widening an entry variant the
+   spec keeps light so `FLOW-SCOPE-CREEP` stops firing, renaming a title around a trigger word so a
+   claim rule stops firing, adding an assertion the spec never demands — **stop and put the conflict
+   to the user** (`AskUserQuestion`: the finding, the spec passage it collides with, the two ways out).
+   A score reached by editing toward the gate is not a measurement of the suite; it is a measurement
+   of how well the gate was gamed, and the human reviewer will read it as over-testing or a false
+   claim. Where the harness provides a declaration route — `flows:` with a per-flow `outcome:`, a
+   `status: deferred` with a reason, `@manual` naming the gesture — that route is the fix, never the
+   scenario.
+7. **`--accept-viewpoint` is a QA decision. Never run it.** `atomicLedger` and `traceability` are
+   evidence only while `test-viewpoint.md` is independent of what was generated. `sungen next` lists
+   the acceptance as a `⚖ decide` step: present it (the diff of declared ids, what was added, what was
+   dropped) and let the QA run the command. An agent that accepts the yardstick it just wrote makes
+   both axes read 100% by construction — and the spec's Exception Flow it forgot stops being missing
+   from anything.
+
 ## Discovery / fallback tree (when input is limited)
 
 ```

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

@@ -63,6 +63,10 @@ login:
 awards:
   type: 'page'
   value: '/awards'
+  anchor:                      # optional — the element that proves the page RENDERED (#662).
+    type: 'role'               # `see [Awards] page` asserts the URL, then this; without it the step is
+    value: 'heading'           # a URL-only oracle a late 403 redirect can satisfy. One line per screen.
+    name: 'Awards'
 
 "awards:submit":
   type: 'role'

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

@@ -340,6 +340,9 @@ Security:         [S1 – admin only]
 `sungen audit` enforces these. Generate compliant output up front:
 
 1. **Taxonomy-match** (`VP-TAXONOMY-MISMATCH`, gate-FAIL) — when `test-viewpoint.md` declares its own viewpoint IDs (e.g. `VP0`, `VP1`, … `VP12`, `MS-HP-001`, `MS-EH-001`), **reuse those IDs verbatim as the scenario codes**. Do NOT invent a generic `VP-UI / VP-LOGIC / VP-VAL` scheme — that breaks the coverage matrix. Only fall back to `VP-<CATEGORY>-<NNN>` when the viewpoint file declares no IDs.
+   - **`--accept-viewpoint` is the QA's command, not yours.** `sungen next` shows it as a `⚖ decide`
+     step. Present the declared-id diff and stop; a yardstick accepted by the process it measures
+     reads 100% by construction.
    - **Match the scenarios to the file — never the file to the scenarios.** A filled `test-viewpoint.md` is an input; do not rewrite its declarations to fit what you generated. That is not compliance, it is moving the yardstick: `traceability` + `atomicLedger` then read 100% by construction and a dropped viewpoint stops being missing from anything. Disagree with the taxonomy → propose the diff and ask. `sungen audit` reports `VIEWPOINT-BASELINE-CHANGED` and excludes both axes until a human accepts the change (`sungen audit --screen <name> --accept-viewpoint`).
 2. **Spec-coverage triggers** (`TRIGGER-UNCOVERED`, gate-FAIL) — the Validation-Rules table lists a **trigger** per constraint (e.g. `blur, submit`). Generate one scenario **per (constraint × trigger)** — a `format` rule validating *on blur AND on submit* needs BOTH a blur scenario (`press Tab`) and a submit scenario (`click [Submit]` / `press Enter`). Never collapse the trigger × input matrix to one representative case.
 3. **Claim-Proof** (`CLAIM-UNPROVEN`) — a title claiming `all`/`only`/`every`/`single`/`correct`/`same`/`changes`/`hidden`/`cleared`/`restored`/`independent`/`sanitized`/`announces` MUST have the matching assertion (`see all …`, count, `remember`+compare, `is hidden`, return-and-assert-empty, etc.). If the title promises it, the steps must prove it.
@@ -372,7 +375,7 @@ Security:         [S1 – admin only]
 | Validation rule | 1 exact-message TC per rule | `@high` |
 | Business rule | 1 behavioral TC per rule | `@high` |
 | **Secondary behavior / tiebreaker** | **1 TC per tiebreaker or fallback rule in `Secondary behaviors`** | **`@high`** |
-| Auth / OAuth / permissions | 1 VP-SEC TC | `@high` |
+| Auth / OAuth / permissions | 1 VP-SEC TC — **with a rendered-content oracle**: `see [X] page` alone is a URL check a late 403 redirect passes; give the page selector an `anchor:` or add a content assertion (`ORACLE-URL-ONLY`) | `@high` |
 | Free-text input | 1 XSS TC **and** 1 SQL injection TC (separate) | `@high` |
 | **Free-text LIKE / partial-match field** | **1 field-level SQL TC + 1 API-level SQL `@manual` TC** | **`@high`** |
 | Lifecycle states | 1 key state transition TC | `@high` |
@@ -821,6 +824,13 @@ is a gap to REPORT, not to quietly absorb.
 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.
+**The exception is declared, not widened:** when the spec KEEPS a variant deliberately light — an
+entry variant that only proves the alternative entry reaches the action bar, without repeating the
+full assertion the basic flow already carries — declare that flow in `flows:` with its own
+`outcome:` and the audit judges it against that outcome. Never widen the scenario to satisfy the
+gate; a reviewer reads the result as over-testing, and the finding was the thing that was wrong.
+When a gate and the spec's stated intent collide and no declaration route exists, stop and put the
+conflict to the user — do not edit toward the score.
 
 **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:
@@ -847,7 +857,7 @@ Feature: Award Submission Flow
 
   @high
   Scenario: FL-EH-001 Direct access to the award form without login redirects to login
-    When User go to [Awards] page
+    Given User is on [Awards] page
     Then User see [Login] page
 ```
 

package/src/orchestrator/templates/ai-src/skills/sungen-viewpoint/group-d-display.md

@@ -147,6 +147,7 @@ See `SKILL.md` for the 4 Viewpoints, Shared Checks, and Security Tag Rules.
 
 - A menu item for a restricted page is shown but the user has no permission → click → a 403 page; or the item is hidden from the menu (verify the DOM has no link and the API returns no data)
 - Direct URL access to a restricted page while not logged in → redirect to Login, the URL is preserved so post-login redirects correctly
+- **The oracle for "role X can open screen Y" is rendered content, not the URL.** A client-side router shows the destination URL before the permission check answers; assert a heading/landmark of the screen (or give its page selector an `anchor:`) so a late 403 bounce fails the case
 
 ---
 

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

@@ -18,6 +18,8 @@
  * URL, and needs no regex escaping of runtime values, which is what forced the split.
  */
 
+import { expect, type Page } from '@playwright/test';
+
 export interface UrlExpectation {
   /**
    * Anchored pathname pattern, compiled by the generator from the page selector's `value`
@@ -132,3 +134,55 @@ export function urlMatches({ pathname, declared, dataRef }: UrlExpectation): (u:
     return queryOk && hashOk;
   };
 }
+
+/**
+ * `toHaveURL` is a polling assertion: it passes on the FIRST sample that matches. A client-side
+ * router pushes the destination URL before the route guard or the API has answered, so a user
+ * with no permission is "on" `/items/detail` for a few hundred milliseconds — long enough for
+ * the assertion to sample it, pass, and end the test green — and is then bounced to `/forbidden`
+ * with no assertion left to see it. A real project shipped a permission matrix on that oracle;
+ * the 403s were found by hand (#662).
+ *
+ * `expectPage` is the page oracle `see [X] page` compiles to now. Arriving is not enough: the URL
+ * has to be STILL matching once the page has settled.
+ *   1. arrive   — the same predicate `toHaveURL` always used;
+ *   2. settle   — wait for network to go quiet (bounded: an app that polls forever must not hang
+ *                 the test, so a timeout here is not a failure);
+ *   3. hold     — sample the URL over a settle window; the moment it stops matching, fail and
+ *                 NAME where it went, because that destination is the finding;
+ *   4. re-assert — the arrival predicate, once more, on the settled page.
+ *
+ * `SUNGEN_URL_SETTLE_MS` (default 1000) is the hold window; `SUNGEN_URL_NETWORKIDLE_MS` (default
+ * 3000) bounds step 2. Both are runtime knobs, so a slow environment is a config change, not a
+ * regenerate.
+ */
+export async function expectPage(
+  page: { url(): string; waitForLoadState(state: 'networkidle', opts?: { timeout?: number }): Promise<void> },
+  expectation: UrlExpectation,
+  opts: { settleMs?: number; networkIdleMs?: number; assertUrl?: (matches: (u: URL) => boolean) => Promise<void> } = {},
+): Promise<void> {
+  const settleMs = opts.settleMs ?? Number(process.env.SUNGEN_URL_SETTLE_MS ?? 1000);
+  const networkIdleMs = opts.networkIdleMs ?? Number(process.env.SUNGEN_URL_NETWORKIDLE_MS ?? 3000);
+  const matches = urlMatches(expectation);
+  const assertUrl = opts.assertUrl ?? (async (m: (u: URL) => boolean) => { await expect(page as unknown as Page).toHaveURL(m); });
+
+  await assertUrl(matches);
+  const arrivedAt = page.url();
+
+  await page.waitForLoadState('networkidle', { timeout: networkIdleMs }).catch(() => undefined);
+
+  const started = Date.now();
+  while (Date.now() - started < settleMs) {
+    const now = page.url();
+    if (!matches(new URL(now))) {
+      throw new Error(
+        `page assertion: reached ${arrivedAt} and then left for ${now} after ${Date.now() - started}ms — `
+        + 'a route guard, an error boundary or a redirect moved the user away after the URL had already '
+        + 'matched. The page the test asserted is not the page the user ended on.',
+      );
+    }
+    await new Promise((r) => setTimeout(r, 50));
+  }
+
+  await assertUrl(matches);
+}