@sun-asterisk/sungen 3.2.24 → 3.2.26

package/src/generators/test-generator/utils/runtime-data-transformer.ts

@@ -1,3 +1,5 @@
+import { scanSegments, type Segment } from './js-literal-scanner';
+
 /**
  * Wire format of a runtime test-data marker: `__SUNGEN_TD$<key>$__`.
  *
@@ -14,12 +16,12 @@
  * swallowed one `_` of the `___` run and decoding produced `get('code_')` plus
  * a detached `ACCESS_TOKEN`. `$` is also identifier-safe — the whole marker
  * still parses as ONE bare JS token, so it survives the bare-identifier
- * (numeric) positions Pass 3 handles.
+ * (numeric) positions the code context handles.
  *
- * Single source of truth: every pass and every whole-literal probe below is
- * built from these constants. Invariant: every marker producer goes through
- * DataResolver.encodeMarker and every consumer through this module — a
- * drifting hand-copied char class is what let the suffix bug hide.
+ * Single source of truth: every context below is built from these constants.
+ * Invariant: every marker producer goes through DataResolver.encodeMarker and
+ * every consumer through this module — a drifting hand-copied char class is what
+ * let the suffix bug hide.
  */
 const MARKER_KEY = '[A-Za-z0-9_-]+';
 // Templates that embed a value into a regex literal run it through the escapeRegex
@@ -27,100 +29,148 @@ const MARKER_KEY = '[A-Za-z0-9_-]+';
 // arrive here spelled `__SUNGEN_TD\$key\$__`. `\\\\?` accepts that optional backslash
 // before each delimiter; the replacement consumes it, so no escape leaks to output.
 const DELIM = '\\\\?\\$';
-/** Marker with no capture group — for "contains a marker" positions inside bigger regexes. */
+/** Marker with no capture group — for "contains a marker" probes. */
 const MARKER = `__SUNGEN_TD${DELIM}${MARKER_KEY}${DELIM}__`;
 /** Marker capturing the encoded key. */
 const MARKER_CAP = `__SUNGEN_TD${DELIM}(${MARKER_KEY})${DELIM}__`;
 
 const MARKER_PATTERN = new RegExp(MARKER);
-// Pass 0: full-line // comments carrying a marker (anchored — see pass comment).
-const RE_COMMENT_LINE = new RegExp(`^(\\s*)\\/\\/(.*)${MARKER_CAP}(.*)$`, 'gm');
-// Pass 1: a quoted string literal containing at least one marker. Covers ', " and
-// backtick containers; `\\.` lets an ESCAPED quote (`'it\'s {{x}}'`) sit inside the
-// body instead of terminating the literal early. The single-char branch excludes `\`
-// so every backslash is consumed by exactly ONE branch — an ambiguous `(?!\1).`
-// alternative enumerates 2^n segmentations when a marker-less escape-heavy literal
-// (escapeQuotes output: multi-line Flutter content-desc) fails to match, hanging
-// the generate run. `\n` exclusion just makes the dot's no-newline behavior explicit.
-const RE_STRING_LITERAL = new RegExp('([\'"`])((?:\\\\.|(?!\\1)[^\\\\\\n])*?' + MARKER + '(?:\\\\.|(?!\\1)[^\\\\\\n])*)\\1', 'g');
-// Pass 2: a single-line regex literal containing at least one marker.
-const RE_REGEX_LITERAL = new RegExp(`\\/((?:[^/\\\\\\n]|\\\\.)*?${MARKER}(?:[^/\\\\\\n]|\\\\.)*)\\/([gimsuy]*)`, 'g');
-// Whole-literal probe: the body is EXACTLY one marker (bare accessor call, no template).
+/** Whole-literal probe: the body is EXACTLY one marker (bare accessor call, no template). */
 const RE_WHOLE_MARKER = new RegExp(`^${MARKER_CAP}$`);
-// Every marker occurrence, capturing the key (Pass 3 + interpolation).
+/** Every marker occurrence, capturing the key. */
 const RE_MARKER_G = new RegExp(MARKER_CAP, 'g');
 
 /**
  * Replace __SUNGEN_TD$…$__ markers with testData.get() calls in generated code.
- * Four passes: comments, string literals, regex literals, then bare identifiers.
+ *
+ * The code is scanned ONCE into literal/regex/comment/code segments and each
+ * segment is rewritten for the context it is actually in. This replaced four
+ * independent global-regex passes whose ordering was the defect: the string pass
+ * ran first and, finding no marker inside a genuine literal, re-matched from that
+ * literal's CLOSING quote — pairing it with the OPENING quote of the next literal
+ * and rewriting the regex literal between them into a broken backtick template
+ * (`getByText('Tìm thấy`)` … `state: `visible' })`, a .spec.ts that would not
+ * parse at all). See js-literal-scanner.ts for the full field report.
  */
 export function transformToRuntimeData(code: string, accessor: string = 'testData'): string {
-  // Pass 0: Comments — replace markers in // comments with decoded key name.
-  // Prevents Pass 2 from misinterpreting // comment markers as regex delimiters.
-  // ANCHORED to line start (^\s*//) so a `//` INSIDE a string literal on a code line
-  // — e.g. a URL `https://careerforum.aki-inc.jp/` in a selector name — is NOT mistaken
-  // for a comment. Before this anchor, such a URL preceding a marker on the same line
-  // made Pass 0 strip the marker to its bare key, so Pass 1 never wrapped it in
-  // testData.get() (silent: `toHaveAttribute('href', 'official_site_url')`). Generated
-  // comments are always full-line, so anchoring loses nothing.
-  code = code.replace(
-    RE_COMMENT_LINE,
-    (_, indent, before, enc, after) => `${indent}//${before}${decodeKey(enc)}${after}`
-  );
-
-  // Pass 1: String literal context — a literal may carry SEVERAL markers
-  // ('/{{code}}/car-search?{{prefill}}' compiles to two markers in ONE literal).
-  // Match the whole quoted literal that contains at least one marker, then
-  // interpolate EVERY marker inside it. The old shape (one marker + lazy
-  // prefix/suffix) swallowed trailing markers into its suffix verbatim; they
-  // escaped the quote context (the literal had become a backtick template) and
-  // Pass 3's numeric catch-all emitted them as literal
-  // `Number(testData.get(...))` TEXT inside the template — a compiling spec
-  // navigating to a garbage URL.
-  // 'marker'          → testData.get('key')
-  // 'a__m1__b__m2__c' → `a${testData.get('k1')}b${testData.get('k2')}c`
-  code = code.replace(
-    RE_STRING_LITERAL,
-    (_, _quote, body) => {
-      const whole = RE_WHOLE_MARKER.exec(body);
-      if (whole) return `${accessor}.get('${decodeKey(whole[1])}')`;
-      return `\`${interpolateMarkers(body, accessor)}\``;
-    }
-  );
+  if (!MARKER_PATTERN.test(code)) return code;
+  return scanSegments(code).map((seg) => transformSegment(seg, accessor)).join('');
+}
 
-  // Pass 2: Regex literal context — /…$marker$…/ → new RegExp(`…`). Same
-  // several-markers-per-literal rule as Pass 1 (/{{min}}-{{max}} items/).
-  // Only matches within a single line (no newlines in the body).
-  code = code.replace(
-    RE_REGEX_LITERAL,
-    (_, body, flags) => {
-      const flagStr = flags ? `, '${flags}'` : '';
-      const whole = RE_WHOLE_MARKER.exec(body);
-      if (whole) return `new RegExp(${accessor}.get('${decodeKey(whole[1])}')${flagStr})`;
-      return `new RegExp(\`${interpolateMarkers(body, accessor)}\`${flagStr})`;
-    }
-  );
+export function hasRuntimeDataMarkers(code: string): boolean {
+  return MARKER_PATTERN.test(code);
+}
 
-  // Pass 3: Bare-identifier context — any marker left after the string/regex passes
-  // sits as a bare token in a numeric position (e.g. `toHaveCount(__marker__)` from the
-  // table/list count templates). testData.get() returns a string, so coerce with Number().
-  code = code.replace(
-    RE_MARKER_G,
-    (_, enc) => `Number(${accessor}.get('${decodeKey(enc)}'))`
-  );
+function transformSegment(seg: Segment, accessor: string): string {
+  if (!MARKER_PATTERN.test(seg.text)) return seg.text;
+  switch (seg.kind) {
+    // Decode to the plain key: a marker in a comment documents the ref, it is not code.
+    case 'comment':
+      return seg.text.replace(RE_MARKER_G, (_, enc) => decodeKey(enc));
+    case 'string':
+      return transformStringLiteral(seg.text, accessor);
+    case 'regex':
+      return transformRegexLiteral(seg.text, accessor);
+    // Bare-token position (e.g. `toHaveCount(__marker__)` from the table/list count
+    // templates). testData.get() returns a string, so coerce with Number().
+    case 'code':
+      return seg.text.replace(RE_MARKER_G, (_, enc) => `Number(${accessor}.get('${decodeKey(enc)}'))`);
+  }
+}
 
-  return code;
+/**
+ * 'marker'          → testData.get('key')
+ * 'a__m1__b__m2__c' → `a${testData.get('k1')}b${testData.get('k2')}c`
+ *
+ * A literal may carry SEVERAL markers ('/{{code}}/car-search?{{prefill}}' compiles
+ * to two markers in ONE literal), so every marker inside it is interpolated.
+ */
+function transformStringLiteral(text: string, accessor: string): string {
+  const quote = text[0];
+  const body = text.slice(1, -1);
+  const whole = RE_WHOLE_MARKER.exec(body);
+  if (whole) return `${accessor}.get('${decodeKey(whole[1])}')`;
+  return `\`${interpolateMarkers(escapeForTemplate(body, quote === '`'), accessor)}\``;
 }
 
-export function hasRuntimeDataMarkers(code: string): boolean {
-  return MARKER_PATTERN.test(code);
+/**
+ * /…$marker$…/flags → new RegExp(`…`, 'flags'). Same several-markers rule as above.
+ *
+ * Two regex-only twists on top of the string path:
+ * - The runtime VALUE is literal text (test-data holds data, not patterns), so every
+ *   accessor is wrapped in the runtime escapeRegExp helper — a value containing
+ *   `( [ $ . * +` must not throw a SyntaxError or silently widen the match. The helper
+ *   lives in the synced specs/regex-escape.ts; the generator imports it when the
+ *   transformed body references it. Templates that intend PATTERN semantics (attribute
+ *   `pattern:`) emit a string container instead of a regex literal, so they skip this.
+ * - Marker-less SEGMENTS get their backslashes doubled for the template context: regex
+ *   source text like a hand-written `\s*` (or escapeRegex output `\)`) means one thing
+ *   in a /…/ literal but loses its backslash when the template cooks one escape level —
+ *   the constructed RegExp would read `s*` / a bare `)`. Segments are escaped AFTER the
+ *   markers are cut out, so an escapeRegex-spelled marker delimiter (`\$`) is never
+ *   double-escaped into something the marker regex can no longer see.
+ */
+function transformRegexLiteral(text: string, accessor: string): string {
+  // Flags never contain `/`, so the last slash always closes the pattern.
+  const close = text.lastIndexOf('/');
+  const body = text.slice(1, close);
+  const flags = text.slice(close + 1);
+  const flagStr = flags ? `, '${flags}'` : '';
+  const whole = RE_WHOLE_MARKER.exec(body);
+  if (whole) return `new RegExp(escapeRegExp(${accessor}.get('${decodeKey(whole[1])}'))${flagStr})`;
+  return `new RegExp(\`${interpolateMarkersInRegexBody(body, accessor)}\`${flagStr})`;
 }
 
 function decodeKey(encoded: string): string {
   return encoded.replace(/_D_/g, '.');
 }
 
-/** Replace every marker in a literal's body with a `${accessor.get('key')}` interpolation. */
+/** Replace every marker in a body with a `${accessor.get('key')}` interpolation. */
 function interpolateMarkers(body: string, accessor: string): string {
   return body.replace(RE_MARKER_G, (_, enc) => `\${${accessor}.get('${decodeKey(enc)}')}`);
 }
+
+/**
+ * Regex-body variant: markers are cut out FIRST, each accessor is wrapped in the
+ * runtime escapeRegExp helper, and only the marker-less segments between them are
+ * re-escaped for the template context (backslashes doubled, backtick/`${` neutralized).
+ */
+function interpolateMarkersInRegexBody(body: string, accessor: string): string {
+  let out = '';
+  let last = 0;
+  for (const m of body.matchAll(RE_MARKER_G)) {
+    out += escapeRegexSegmentForTemplate(body.slice(last, m.index!)) +
+      `\${escapeRegExp(${accessor}.get('${decodeKey(m[1])}'))}`;
+    last = m.index! + m[0].length;
+  }
+  return out + escapeRegexSegmentForTemplate(body.slice(last));
+}
+
+/**
+ * Regex pattern text moving into a template literal: the template layer cooks one
+ * level of escapes BEFORE RegExp ever sees the string, so `\)` arrives as a bare `)`
+ * (SyntaxError: unmatched paren) and `\.` as a match-anything dot. Double the
+ * backslashes and neutralize the template's own metacharacters so the constructed
+ * RegExp source equals the original pattern text.
+ */
+const escapeRegexSegmentForTemplate = (segment: string): string =>
+  segment.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+
+/**
+ * Both rewrites move a body into a backtick template, where a raw backtick or `${`
+ * would be read as syntax rather than text — a `'…'` selector value or a regex
+ * pattern is allowed to contain either (escapeQuotes/escapeRegex escape neither).
+ * Escape before interpolating so the `${…}` this module inserts is the only live one.
+ * An already-backtick container needs no pass: its body was valid template text.
+ *
+ * PRECONDITION: the body must already have its backslashes DOUBLED — which every caller
+ * satisfies, because every dynamic value reaches a literal through escapeQuotes or
+ * escapeRegex (template-engine.ts) and both double `\` before anything else. An unpaired
+ * backslash immediately before a backtick would make the pass below emit `\\\``, i.e. an
+ * escaped backslash followed by a LIVE backtick, ending the template early. If you
+ * hand-write a backslash into a .hbs template, keep it paired.
+ */
+function escapeForTemplate(body: string, alreadyTemplate: boolean): string {
+  if (alreadyTemplate) return body;
+  return body.replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+}

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

@@ -229,6 +229,24 @@ export class SelectorResolver {
    * - Legacy format: "login:email_field" or "login.email_field" (with screen prefix)
    */
   resolveSelector(selectorRef: string, featureName?: string, elementType?: string, nth?: number): ResolvedSelector {
+    // A [Reference] is a selectors.yaml KEY, looked up verbatim (generateKey only lowercases and
+    // normalizes whitespace) — it is never interpolated. Embedding a {{var}} in it is therefore
+    // unsupported, and silence was the harmful part: with no matching entry the ref fell through
+    // to auto-infer and produced getByRole(..., { name: '{{var}}' }) — an accessible name that can
+    // never match — so the run failed far from the cause. Fail here instead, naming the two
+    // supported ways to target dynamic text. Browser-storage keys legitimately embed vars but are
+    // not selectors and never reach this method (see driver-ui storage-patterns).
+    const templateVarInRef = /\{\{\s*([^}]+?)\s*\}\}/.exec(selectorRef);
+    if (templateVarInRef) {
+      throw new Error(
+        `Selector reference "[${selectorRef}]" embeds a template variable ({{${templateVarInRef[1]}}}). ` +
+        `A [Reference] is a selectors.yaml key and is matched verbatim, not interpolated. ` +
+        `To target text that varies (locale, @cases column), keep the reference static and put the ` +
+        `variable in the entry instead — e.g. "confirm answer": { type: role, value: button, name: "{{${templateVarInRef[1]}}}" } ` +
+        `used as [Confirm Answer] button. To pick an element by its text inside a container, use ` +
+        `\`with {{${templateVarInRef[1]}}}\` (e.g. User click [Answer List] item with {{${templateVarInRef[1]}}}).`
+      );
+    }
     const contextName = featureName || this.featureName;
 
     // Check if it's legacy format (contains : or has dot with screen prefix)
@@ -590,7 +608,9 @@ export class SelectorResolver {
       });
     }
 
-    // If type is 'locator', use locator field (or value as fallback) as the CSS locator directly
+    // If type is 'locator', use locator field (or value as fallback) as the CSS locator directly.
+    // `exact` travels along: a locator LIST filtered by a test-data value (hasText) matches by
+    // substring by default, and `exact: true` in the YAML opts into the anchored full-text match.
     if (type === 'locator') {
       const locatorValue = locator && locator.trim() ? locator : value;
       return withExtras({
@@ -598,6 +618,7 @@ export class SelectorResolver {
         value: locatorValue,
         locator: locatorValue,
         nth,
+        exact,
       });
     }
 

package/src/generators/test-generator/utils/spec-syntax-check.ts

@@ -0,0 +1,22 @@
+import { parse } from '@babel/parser';
+
+/**
+ * Compiler self-check for emitted spec files.
+ *
+ * Every template and post-processor in the generator assembles TEXT, so a delimiter
+ * bug in any one of them produces a file Playwright cannot parse AT ALL: one
+ * SyntaxError, zero scenarios run, and nothing points at the compiler. That is how the
+ * runtime-data quote-pairing defect reached a user (3.2.23) — `sungen generate` printed
+ * success and the breakage only surfaced a step later, at `npx playwright test`.
+ *
+ * Parsing what we are about to write costs one parse per spec file and makes the
+ * compiler name its own bad output at the moment it makes it (SG-E022).
+ */
+export function findSyntaxError(code: string): string | null {
+  try {
+    parse(code, { sourceType: 'module', plugins: ['typescript'] });
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}

package/src/harness/annotation-overrides.ts

@@ -3,13 +3,18 @@
  *
  * Parses `name(a={{x}},b="lit",c=3)` overrides into a map of JS expressions, e.g.
  * `{ a: "testData.raw('x')", b: "\"lit\"", c: "3" }`. Used by the DB and API capability drivers'
- * precondition codegen; lives in core so both drivers can share it. Gherkin tags carry no whitespace,
- * so values are single tokens — flows thread a prior response via a whole-value ref, e.g.
+ * precondition codegen; lives in core so both drivers can share it. Gherkin tags carry no
+ * whitespace, but a QUOTED value can still embed `{{ref}}` next to static text
+ * (`user_email="pre-{{id}}-x"`) — those interpolate through literalExpr; shipping the braces
+ * verbatim would bind `{{...}}` text as a SQL parameter or POST it in a live request body.
+ * Flows thread a prior response via a whole-value ref, e.g.
  * `@api:get_profile(token={{login.body.token}})`, with the auth scheme declared in the catalog header.
- * A `{{ref}}` override binds into a typed sink (DB query param, JSON request body), so it resolves
- * via `testData.raw()` (native type, still interpolates embedded refs) rather than `get()`
+ * A bare `{{ref}}` override binds into a typed sink (DB query param, JSON request body), so it
+ * resolves via `testData.raw()` (native type, still interpolates embedded refs) rather than `get()`
  * (Gherkin-text stringify) — a numeric override otherwise reaches the DB/API as a JSON string.
  */
+import { literalExpr } from '../generators/test-generator/patterns/expect-patterns';
+
 export function parseQueryOverrides(raw?: string): Record<string, string> {
   const out: Record<string, string> = {};
   if (!raw) return out;
@@ -22,7 +27,7 @@ export function parseQueryOverrides(raw?: string): Record<string, string> {
     const v = val.match(/^\{\{\s*([^}]+?)\s*\}\}$/);
     const q = val.match(/^["'](.*)["']$/);
     if (v) out[key] = `testData.raw(${JSON.stringify(v[1])})`;
-    else if (q) out[key] = JSON.stringify(q[1]);
+    else if (q) out[key] = literalExpr(q[1]);
     else if (/^-?\d+(?:\.\d+)?$/.test(val)) out[key] = val;
     else out[key] = JSON.stringify(val);
   }

package/src/harness/audit.ts

@@ -27,6 +27,8 @@ import { specCoverage, SpecCoverageResult, parseSpecClauses, restatedRequirement
 import { downstreamScope, manualOracle, readText, DownstreamResult, ManualOracleResult,
   negativeSideEffect, sourceBacked, crossArtifactOwnership, isolationRisk, serialCascadeRisk } from './quality-gates';
 import { viewpointLedger, parseViewpointItems, browserGestureSubstitutions, viewpointIntegrity, LedgerResult } from './viewpoint-ledger';
+import { specBranches, unenumeratedBranches, sameOracleClusters, permissionPairGaps, awaitingSeedData, unconsideredRisks, MULTI_SCREEN_RISKS } from './spec-branches';
+const MULTI_SCREEN_RISK_COUNT = MULTI_SCREEN_RISKS.length;
 import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 import { contextRouter } from '../capabilities/context-router';
@@ -65,6 +67,12 @@ export interface AuditReport {
   score: {
     overall: number;            // 0..10, business-weighted over the APPLICABLE axes
     notApplicable?: string[];   // axes with no evidence — excluded, not scored as 1.0
+    /**
+     * Why each excluded axis is excluded. "No evidence" and "evidence WITHHELD pending review"
+     * are different states with different remedies, and reporting both as "no evidence" told the
+     * author of a 93%-covered ledger to go write the viewpoint they had just written (#657).
+     */
+    naReasons?: Record<string, string>;
     cappedAt?: number;          // set when a weak critical axis holds the score down
     coverage: number;           // 0..1
     businessDepth: number;      // 0..1
@@ -76,7 +84,7 @@ export interface AuditReport {
      * `specFR` and `atomicLedger` entirely — so a flow's real coverage axis was never printed
      * while `balance`, which carried no weight, was.
      */
-    axes: Array<{ key: string; value: number; weight: number; applicable: boolean; critical: boolean; byDesign?: boolean }>;
+    axes: Array<{ key: string; value: number; weight: number; applicable: boolean; critical: boolean; byDesign?: boolean; withheld?: boolean }>;
     formula: string;
   };
   gateStatus: 'PASS' | 'FAIL';
@@ -196,7 +204,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const isUiFlowUnit = /^flows\//.test(catalogScreenName);
   const flowQ: FlowQualityResult = isUiFlowUnit
     ? flowQuality(screenDir, scenarios)
-    : { hasContract: false, errors: [], outcomeProven: false, outcomeManualOnly: false, offGoal: [], offGoalRatio: 0, offGoalCategories: [], phases: [], phaseRatio: 1, handoffs: { total: 0, asserted: 0, ratio: 1 }, sit: [] };
+    : { hasContract: false, errors: [], outcomeProven: false, outcomeManualOnly: false, offGoal: [], offGoalRatio: 0, offGoalCategories: [], phases: [], phaseRatio: 1, danglingPhaseRefs: [], handoffs: { total: 0, asserted: 0, ratio: 1 }, sit: [] };
   const gateCatalog = (flowQ.hasContract && !declaredPageType(viewpointText, catalog))
     ? { ...catalog, page_types: {} } as Catalog
     : catalog;
@@ -230,7 +238,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // #1 taxonomy-match: when the project defines a viewpoint taxonomy, scenarios must use it.
   const taxonomyMismatch = viewpoints.length > 0 && trace.withVpCode > 0 && trace.mappedRatio < 0.6;
   // #2 downstream-scope + #4 manual-oracle
-  const downstream = downstreamScope(readText(specPath), scenarios);
+  const downstream = downstreamScope(readText(specPath), scenarios, featureText);
   const manualOracleResult = manualOracle(featureText);
   const autoManual = automatableManual(scenarios); // TQ-2 — @manual that is really automatable
   const ledger = viewpointLedger(viewpointPath, scenarios, featureText);
@@ -331,7 +339,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // this KIND of unit". Only the first is a reason to cap the score: a contract flow can never
   // supply balance evidence, so capping for it held every flow at 8.9 forever and printed
   // "weakest: flowCoverage 100% — fix it to lift the number", which is not fixable advice (#595).
-  const axisDefs: Array<{ key: string; value: number; weight: number; applicable: boolean; critical: boolean; byDesign?: boolean }> = [
+  const axisDefs: Array<{ key: string; value: number; weight: number; applicable: boolean; critical: boolean; byDesign?: boolean; withheld?: boolean }> = [
     flowScored
       // A declared flow claimed only by @manual scenarios is ACCOUNTED FOR but nothing runs, so
       // it cannot count the same as an automated one — `covered` was collapsing three very
@@ -340,10 +348,10 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
       ? { key: 'flowCoverage', value: inventory ? Math.min((inventory.ratio + inventory.automatedRatio) / 2, flowQ.phaseRatio) : flowQ.phaseRatio, weight: 0.22, applicable: true, critical: true }
       : { key: 'coverage', value: coverage, weight: 0.22, applicable: !!gate.pageType && gate.themesTotal > 0, critical: true },
     { key: 'specFR', value: specRatio, weight: 0.15, applicable: spec.hasSpec && spec.frTotal > 0, critical: true },
-    { key: 'atomicLedger', value: ledger.ratio, weight: 0.13, applicable: ledger.hasViewpoint && ledger.total > 0 && !viewpointMoved, critical: true },
+    { key: 'atomicLedger', value: ledger.ratio, weight: 0.13, applicable: ledger.hasViewpoint && ledger.total > 0 && !viewpointMoved, critical: true, withheld: viewpointMoved && ledger.hasViewpoint && ledger.total > 0 },
     { key: 'businessDepth', value: businessDepth, weight: 0.20, applicable: true, critical: true },
     { key: 'claimProof', value: claim.ratio, weight: 0.15, applicable: claim.withClaims > 0, critical: true },
-    { key: 'traceability', value: traceScore, weight: 0.09, applicable: viewpoints.length > 0 && !viewpointMoved, critical: false },
+    { key: 'traceability', value: traceScore, weight: 0.09, applicable: viewpoints.length > 0 && !viewpointMoved, critical: false, withheld: viewpointMoved && viewpoints.length > 0 },
     // A use-case decomposition is EF-heavy by construction (1 basic flow, N alternates, N
     // exceptions) — that is the shape of a well-decomposed use case, not neglected business
     // core. `flowCoverage` already measures whether the journey's phases are covered, so
@@ -394,10 +402,24 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const overall = seniorBandedOverall(rawOverall, { flowStateful: flowDepth.stateful, flowRatio: flowDepth.ratio, oracleWeak: oracle.weak.length, isolationRisk: isoRisk });
 
   const findings: string[] = [];
+  // A baseline that could not be compared was re-recorded rather than reported as an edit.
+  // Migrating in silence would be the same sin one level down, so it is stated.
+  if (viewpointBaseline.reparsed) {
+    findings.push(`VIEWPOINT-BASELINE-REPARSED: the recorded baseline for this unit was written by an earlier version whose viewpoint parser had a different granularity, so its ids cannot be compared with today's. \`test-viewpoint.md\` itself is unchanged — the file is now fingerprinted by its own bytes, which no parser upgrade can move, and the baseline has been re-recorded against it. \`atomicLedger\` and \`traceability\` count normally. If you DID edit the viewpoint since ${viewpointBaseline.recordedAt?.slice(0, 10) ?? 'it was accepted'}, review that diff yourself — this one migration could not tell an edit from the parser change.`);
+  }
   if (capped) {
     const why = weakestCritical && weakestCritical.value < 0.7
       ? `"${weakestCritical.key}" is ${(weakestCritical.value * 100).toFixed(0)}% — a weak axis is a hole, not something the other axes can average away`
-      : `this unit supplies no evidence for [${missingEvidence.join(', ')}], and a top mark has to rest on complete evidence`;
+      : (() => {
+        const held = axisDefs.filter((a) => a.withheld).map((a) => a.key);
+        const absent = missingEvidence.filter((k) => !held.includes(k.replace(/ .*$/, '')));
+        const parts = [];
+        if (absent.length) parts.push(`supplies no evidence for [${absent.join(', ')}]`);
+        // An axis WAS measured and is being held — saying "no evidence" here sends the author
+        // to write a declaration that already exists, when the actual next move is to review a diff.
+        if (held.length) parts.push(`has [${held.join(', ')}] measured but WITHHELD until the changed viewpoint baseline is reviewed and accepted`);
+        return `this unit ${parts.join(', and ')}, and a top mark has to rest on complete evidence`;
+      })();
     findings.push(`SCORE-CAPPED: overall held at ${cap.toFixed(1)} because ${why}.`);
   }
   if (viewpointBaseline.status === 'changed') {
@@ -460,7 +482,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
       }
     }
     // #595 — a viewpoint item naming a browser-level gesture, answered with an in-app control.
-    for (const g of browserGestureSubstitutions(viewpointPath, scenarios).slice(0, 4)) {
+    for (const g of browserGestureSubstitutions(viewpointPath, scenarios, platform).slice(0, 4)) {
       findings.push(`VIEWPOINT-GESTURE-SUBSTITUTED: the viewpoint asks for "${g.gesture}" ("${g.item.slice(0, 80)}…") but the suite exercises an in-app control instead. They are different mechanisms — an app button runs the screen's own re-hydrate logic, browser history does not, and a defect that only shows on history navigation lives in exactly that gap. The step vocabulary has no reload/back step (#593), so defer it with \`@manual\` naming the gesture rather than substituting silently.`);
     }
     // #595 — a flow whose requirement list is a hand restatement of the screen specs it
@@ -622,6 +644,9 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   if (taxonomyMismatch) {
     findings.push(`VP-TAXONOMY-MISMATCH: only ${(trace.mappedRatio * 100).toFixed(0)}% of scenarios use the viewpoint IDs declared in test-viewpoint.md — scenarios invented a generic VP-<CAT> scheme. Re-tag to the project's viewpoint IDs so the coverage matrix is accurate.`);
   }
+  for (const a of downstream.absent.slice(0, 5)) {
+    findings.push(`NAV-TARGET-ABSENT: the spec declares "${a.route}" as a navigation target and NO scenario mentions it — not even a page assertion. Testing the render conditions of the region that links there does not test the link: a click-through case is what proves the destination. Add one, or record why this flow does not own it.`);
+  }
   for (const d of downstream.underCovered) {
     findings.push(`DOWNSTREAM-SCOPE-MISSING: "${d.route}" is a navigation target but is covered only by a page-nav assertion — cover its content/guards, or scaffold it (\`sungen add --screen ${d.slug}\`).`);
   }
@@ -643,7 +668,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   if (intent.capabilitySuggestions) {
     // The catalog unit id (`flows/<f>`, `api/<a>`) carries the unit KIND, which gates which
     // drivers can serve it at all.
-    const plan = buildPlan(screenDir, screenName, catalogScreenName);
+    const plan = buildPlan(screenDir, screenName, catalogScreenName, platform);
     if (plan.recommendations.length) {
       const recs = plan.recommendations.map((r) => `\`sungen capability add ${r.driver}\` (automates ${r.count})`).join(' · ');
       findings.push(`CAPABILITY-SUGGESTION: ${plan.capabilityManual} @manual scenario(s) are capability-manual (a driver could automate them) — ${recs}. Recommend-only: nothing is installed automatically; the ${plan.judgmentManual} judgment-manual (M6/M8/M9) correctly stay manual.`);
@@ -651,8 +676,8 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     // Named, not dropped: without this the scenarios read as "nothing could help", and the
     // operator's only clue was an install that dead-ends (#597).
     if (plan.unavailable.length) {
-      const un = plan.unavailable.map((r) => `${r.driver} (would automate ${r.count})`).join(' · ');
-      findings.push(`CAPABILITY-UNAVAILABLE: ${un} — ${plan.unavailable.length === 1 ? 'that driver does' : 'those drivers do'} not support a ${plan.unavailable[0].unitKind} unit, so ${plan.unavailable.length === 1 ? 'it' : 'they'} cannot automate these scenarios here. Do NOT install: the scenarios stay @manual until the driver gains ${plan.unavailable[0].unitKind} support. Automating the same behaviour on the owning SCREEN unit is the available route today.`);
+      const un = plan.unavailable.map((r) => `${r.driver} (would automate ${r.count}) — ${r.why}`).join(' · ');
+      findings.push(`CAPABILITY-UNAVAILABLE: ${un}. Do NOT install: the scenarios stay @manual until the driver gains that support, and installing it buys an install, a dead end and a manual rollback. ${plan.unavailable.some((r) => /no .* support/.test(r.why)) ? 'On this platform, verify the same behaviour through `@api`/`@query` against the real dependency instead.' : 'Automating the same behaviour on the owning SCREEN unit is the available route today.'}`);
     }
   }
   // TQ-11b — automation-ready (pending capability): @requires:<cap> scenarios whose cap isn't enabled.
@@ -670,6 +695,46 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   if (depth.deferredBusinessCritical > 0 && depth.deferredBusinessCritical >= depth.businessCriticalTotal) {
     findings.push(`DEPTH-DEFERRED: businessDepth ${businessDepth.toFixed(2)} is computed over only ${depth.businessCriticalTotal} on-screen scenario(s); ${depth.deferredBusinessCritical} business-critical scenario(s) are deferred to @manual (excluded from the ratio). Automate them in a flow and verify with \`sungen flow-check\` — this ratio is NOT "all business depth covered".`);
   }
+  // #630 — the branches the spec ENUMERATES must each have a scenario. Narrative guidance for
+  // this already existed and was missed three times in three flows, so the check is an enforced
+  // enumeration rather than another sentence.
+  {
+    const branches = specBranches(readText(specPath) ?? '');
+    for (const b of unenumeratedBranches(branches, featureText).slice(0, 6)) {
+      findings.push(`SPEC-BRANCH-UNCOVERED: the spec enumerates "${b.label}" (${b.source}) and no scenario cites it. A mutually-exclusive branch is only covered when its OWN arm is verified — covering a sibling arm proves nothing about this one. Write it, or record the exclusion in the feature so the omission is a decision.`);
+    }
+    for (const c of sameOracleClusters(scenarios).slice(0, 4)) {
+      findings.push(`BRANCH-OVERCLAIMED: ${c.scenarios.length} scenarios assert an identical oracle (${c.scenarios.slice(0, 3).join(' | ')}${c.scenarios.length > 3 ? ' …' : ''}) — "${c.oracle}". They verify one branch several times while the coverage sheet counts them as ${c.scenarios.length}. Give each the assertion that distinguishes ITS branch, or merge them.`);
+    }
+  }
+  // #651 F1-7 — the fixed risk catalog, reconciled. SPEC-BRANCH-UNCOVERED enforces the branches a
+  // spec DECLARES; this is the half a spec is often silent about, which a reviewer catches and a
+  // generator does not. Consideration counts from anywhere the author reasons — a declared flow's
+  // branch point or reason, a scenario, the viewpoint — so "thought about, does not apply" is a
+  // one-line answer rather than a scenario nobody needs.
+  if (flowQ.hasContract) {
+    const unconsidered = unconsideredRisks(flowQ.contract!, scenarios, viewpointText);
+    if (unconsidered.length > 0) {
+      const list = unconsidered.map((r) => `${r.label} (${r.why})`).join(' · ');
+      findings.push(`RISK-FAMILY-UNCONSIDERED: ${unconsidered.length} of ${MULTI_SCREEN_RISK_COUNT} multi-screen risk families are not mentioned anywhere in this flow's contract, viewpoint or scenarios — ${list}. Each is a question, not a demand: if it does not apply here, record that in the \`flows:\` inventory as \`out-of-scope\` with the reason and it stops being asked. A flow is "enough" when every family has an answer, and a silent family is the one nobody weighed.`);
+    }
+  }
+  // #630 — a deny-side security case with no allow-side counterpart cannot tell a working guard
+  // from a feature that is broken for everyone.
+  for (const g of permissionPairGaps(scenarios).slice(0, 4)) {
+    findings.push(`PERMISSION-PAIR-MISSING: "${g.scenario}" proves the content is hidden when permission is denied, but no scenario proves it is SHOWN when permission is granted. If the code hid it unconditionally this would still pass — the pair is the test, the way min-1/min/max/max+1 is the test for a boundary. Add the allow-side case${g.subject.length ? ` for [${g.subject.join(', ')}]` : ''}.`);
+  }
+  // #630 — a scenario blocked on unseeded data is a DATA task, not unfinished test design.
+  {
+    const tdDir = path.join(screenDir, 'test-data');
+    let tdText = '';
+    try {
+      for (const f of fs.readdirSync(tdDir).filter((x) => x.endsWith('.yaml'))) tdText += `${readText(path.join(tdDir, f)) ?? ''}\n`;
+    } catch { /* no test-data yet */ }
+    for (const a of awaitingSeedData(tdText, scenarios).slice(0, 4)) {
+      findings.push(`AWAITING-SEED-DATA: \`${a.key}\` is still a placeholder and ${a.scenarios.length} scenario(s) reference it (${a.scenarios.slice(0, 2).join(' | ')}${a.scenarios.length > 2 ? ' …' : ''}). These are Pending for a DATA reason, not an unresolved design — seed the value (or move it to \`<unit>.<env>.yaml\`) and they become runnable as written.`);
+    }
+  }
   // #622 — a claim that names a count, proved by fewer assertions than it names. The count sits
   // in the viewpoint CLAIM, so both the title-level and the claim-level shape are checked.
   for (const g of ledger.partial.slice(0, 5)) {
@@ -791,7 +856,12 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
       // flow) that carried no weight at all.
       axes: axisDefs.map((a) => ({ ...a, weight: a.applicable ? a.weight / weightSum : 0 })),
       formula: `overall = (${scored.map((a) => `${(a.weight / weightSum).toFixed(2)}*${a.key}`).join(' + ')}) * 10`
-        + (missingEvidence.length ? ` — n/a (no evidence): ${missingEvidence.join(', ')}` : '')
+        + (() => {
+          const held = new Set(axisDefs.filter((a) => a.withheld).map((a) => a.key));
+          const absent = missingEvidence.filter((k) => !held.has(k.replace(/ .*$/, '')));
+          return (absent.length ? ` — n/a (no evidence): ${absent.join(', ')}` : '')
+            + (held.size ? ` — measured but held: ${[...held].join(', ')}` : '');
+        })()
         + (notApplicableByDesign.length ? ` — n/a for this unit kind: ${notApplicableByDesign.join(', ')}` : ''),
     },
     gateStatus,

package/src/harness/capability-plan.ts

@@ -8,7 +8,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { loadDriverCatalog, unitKindOf, driverServesUnit } from './capability';
+import { loadDriverCatalog, driverMeta, unitKindOf, driverServesUnit, driverServesPlatform } from './capability';
 import { readTextFile } from './read-text';
 import { featureFilesFor } from './unit-paths';
 
@@ -197,11 +197,11 @@ export interface CapabilityPlan {
    * dropped: the scenarios stay manual for a reason the operator needs to know, and a silent
    * omission would read as "nothing could help here" (#597).
    */
-  unavailable: { driver: string; reason: string; count: number; unitKind: string }[];
+  unavailable: { driver: string; reason: string; count: number; unitKind: string; why: string }[];
   keep: { code: string; count: number }[];
 }
 
-export function buildPlan(screenDir: string, screenName: string, unitId = screenName): CapabilityPlan {
+export function buildPlan(screenDir: string, screenName: string, unitId = screenName, platform?: string): CapabilityPlan {
   const scenarios = featureFilesFor(screenDir, screenName).flatMap(parseScenarios);
   const catalog = loadDriverCatalog();
   // Recommending a driver that cannot serve this unit KIND costs an install, a dead end and a
@@ -241,14 +241,19 @@ export function buildPlan(screenDir: string, screenName: string, unitId = screen
     }
   }
 
-  const servable = [...recByDriver.entries()].filter(([d]) => driverServesUnit(d, unitKind));
+  // Two axes, same guarantee: a driver must be able to serve this unit KIND and this PLATFORM.
+  const serves = (d: string): boolean => driverServesUnit(d, unitKind) && driverServesPlatform(d, platform);
+  const servable = [...recByDriver.entries()].filter(([d]) => serves(d));
   const unavailable = [...recByDriver.entries()]
-    .filter(([d]) => !driverServesUnit(d, unitKind))
+    .filter(([d]) => !serves(d))
     .map(([driver, v]) => ({
       driver,
       reason: v.reason,
       count: v.scenarios.length,
       unitKind,
+      why: !driverServesUnit(driver, unitKind)
+        ? `does not support a ${unitKind} unit`
+        : `has no ${platform} support (its step patterns are ${(driverMeta(driver)?.platforms ?? []).join('/')}-only)`,
     }))
     .sort((a, b) => b.count - a.count);
   const recommendations = servable

package/src/harness/capability.ts

@@ -81,6 +81,15 @@ export interface DriverMeta {
    * driver on a flow: install, dead end, manual rollback (#597).
    */
   units?: Array<'screen' | 'flow' | 'api'>;
+  /**
+   * Platforms this driver can serve. Absent = all.
+   *
+   * The same guarantee as `units`, on the other axis. Step patterns already gate themselves
+   * (`platforms: ['web']` → SG-W020 at compile time), but the PLANNER did not know, so a mobile
+   * project was still told to install a web-only driver — install, dead end, manual rollback,
+   * exactly as in #597 (#626).
+   */
+  platforms?: string[];
 }
 
 /** The unit kind of a catalog unit id: `flows/<f>` → flow, `api/<a>` → api, else screen. */
@@ -97,6 +106,13 @@ export function driverServesUnit(driverId: string, kind: 'screen' | 'flow' | 'ap
   return !units || units.includes(kind);
 }
 
+/** Can this driver serve that platform? No declared platform on either side → assume yes. */
+export function driverServesPlatform(driverId: string, platform?: string): boolean {
+  const platforms = driverMeta(driverId)?.platforms;
+  if (!platforms || !platform) return true;
+  return platforms.includes(platform.toLowerCase());
+}
+
 export function capabilitiesPath(cwd: string): string {
   return path.join(cwd, 'qa', 'capabilities.yaml');
 }

package/src/harness/catalog/drivers.yaml

@@ -66,6 +66,11 @@ drivers:
     # (mockCatalogPath is hardcoded to that shape), so it cannot serve a flow. Recommending
     # it for one sent an operator through an install, a dead end and a manual rollback (#597).
     units: [screen]
+    # `platforms:` is the same guarantee on the other axis. Absent → every platform.
+    # `mock.install` is Playwright route interception (page.route) and its step patterns already
+    # declare `platforms: ['web']`, so on mobile they compile to SG-W020. The PLANNER did not know
+    # that, so a mobile project was still told to install it — the #597 dead end, one axis over.
+    platforms: [web]
   mail-file:
     kind: capability
     package: "@sungen/driver-mail-file"