@sun-asterisk/sungen 3.2.32 → 3.2.34

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

@@ -6,7 +6,7 @@ import { readYaml, readYamlIfExists } from '../../../utils/yaml-io';
 
 import { SelectorType } from '../../../utils/selector-types';
 import { DataResolver } from './data-resolver';
-import { DiagnosticsCollector } from '../diagnostics';
+import { DiagnosticsCollector, type DiagnosticCode } from '../diagnostics';
 import { DEFAULT_CONTENT_NAMED_ROLES } from '../app-profile';
 import { reportUnknownEntryFields } from './selector-entry-fields';
 import { reportUnknownSelectorTypes } from './selector-type-validation';
@@ -33,6 +33,25 @@ interface SelectorEntry {
   // that bounces the user after the URL has already matched turns the step red instead of green.
   anchor?: SelectorEntry;
 
+  // === Page query identity (#748) ===
+  // For a `type: page` entry: `any` means the query string is NOT part of this page's identity.
+  //
+  // A bare `see [X] page` asserts that the URL carries NO query at all (#464 — a filter/search
+  // regression read as green while the query was wrong or gone). That is right for a page whose
+  // identity IS its path, and unsatisfiable for one keyed by a query — `/admins/detail?id=5`,
+  // where the id comes from the row the previous step clicked and is unknowable when the scenario
+  // is written. `with {{v}}` cannot rescue it: that asserts a LITERAL value.
+  //
+  // Declared on the ENTRY rather than added to the step grammar because it is a fact about the
+  // PAGE — every step targeting it needs the same reading — and because `wait for [X] page`
+  // already ignores the query. A step-form escape hatch would serve only the Then side and widen
+  // the very drift the shared url-assertion partial was written to end.
+  //
+  // It does NOT weaken a step that declares its own query: `with {{v}}` still asserts every
+  // declared param. This changes only what SILENCE means — from "there must be no query" to
+  // "the query is not mine to judge".
+  query?: 'any';
+
   // === 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.
@@ -166,12 +185,114 @@ export interface ResolvedSelector {
   checkedClass?: string;
   checkedAttribute?: string;
   anchor?: ResolvedSelector;  // page entries only — the rendered-content proof behind `see [X] page` (#662)
+  query?: 'any';        // page entries only — the query is not part of this page's identity (#748)
 }
 
 /**
  * SelectorResolver - Resolves selector references to direct Playwright locator code
  * Supports natural language references with auto-generated keys
  */
+/**
+ * Read an OWN property of a lookup table, or undefined.
+ *
+ * Every type table here — the alias map, the strategy map, the reverse index, and the parsed
+ * selectors.yaml itself — is a bare object literal, so it inherits Object.prototype and answers for
+ * keys it does not have. `elementType` is whatever word the author wrote after `]`, and the three
+ * readers failed three different ways on an inherited one: normalizeElementType is declared
+ * `: string` and returned a FUNCTION to be interpolated into a selector key; inferFromElementType
+ * CALLED that function with no receiver and crashed the compiler with "Cannot convert undefined or
+ * null to object"; and `ALIAS_SPELLINGS[t] ?? []` sailed past its own `??` guard, because a
+ * function is neither null nor undefined, and died on `.map`.
+ *
+ * No real feature file says `[X] valueOf`. The rule is the point: a lookup table must not answer
+ * for a key it does not have, and one helper is cheaper to keep right than four call sites.
+ */
+function own<T>(table: Record<string, T>, key: string): T | undefined {
+  return Object.prototype.hasOwnProperty.call(table, key) ? table[key] : undefined;
+}
+
+/**
+ * Gherkin element-type spelling → the canonical suffix used in selectors.yaml keys.
+ *
+ * Module-scope so the table has exactly ONE reader-facing definition and the reverse index below
+ * can be DERIVED from it. A second, hand-written reverse table is the failure mode issue #728
+ * recorded: a hand-maintained mirror of something the source already states drifts, quietly, for
+ * months. Declaration order is meaningful — it decides which alias wins when a selectors.yaml
+ * declares two spellings of one canonical type (see ALIAS_SPELLINGS).
+ */
+const ELEMENT_TYPE_ALIASES: Record<string, string> = {
+      // Text-like aliases → "text"
+      'title': 'text',
+      'label': 'text',
+      'caption': 'text',
+      // Heading aliases → "heading" (role-based)
+      'heading': 'heading',
+      'header': 'heading',
+      'message': 'text',
+      // Table-related aliases
+      'column': 'columnheader',
+      // List-related aliases
+      'list-item': 'listitem',
+      // Image aliases
+      'logo': 'img',
+      'image': 'img',
+      'icon': 'img',
+      // Button aliases
+      'btn': 'button',
+      // Field aliases
+      'input': 'field',
+      'textbox': 'field',
+      'textarea': 'field',
+      'editor': 'field',
+      // Search alias → searchbox role
+      'search': 'searchbox',
+      // Toggle alias → switch role
+      'toggle': 'switch',
+      // Alert alias → alertdialog role.
+      // UNREACHABLE in practice, kept for the same reason it is not changed: in sungen's grammar
+      // `alert` means the BROWSER system dialog, so `see [X] alert` matches a dedicated step pattern
+      // and compiles to `page.on('dialog', …)` without ever entering the selector resolver
+      // (verified by compiling the step; target-dictionary.mdx documents it as `page.on('dialog')`).
+      // This entry only answers a step form that reaches the resolver with the type `alert`, and
+      // none does. Removing it would be a behaviour change with no caller to benefit, so it stays.
+      'alert': 'alertdialog',
+      // Modal/drawer alias → dialog role
+      'modal': 'dialog',
+      'drawer': 'dialog',
+      // Dropdown/select alias -> combobox role
+      'dropdown': 'combobox',
+      'select': 'combobox',
+      // Data aliases
+      'item': 'listitem',
+      'card': 'article',
+      'cell': 'cell',
+      'section': 'region',
+      // Feedback aliases
+      'badge': 'text',
+      'tooltip': 'text',
+      'tag': 'text',
+      // Trigger aliases
+      'menuitem': 'menuitem',
+      // System aliases
+      'progressbar': 'progressbar',
+      'spinner': 'status',
+      'breadcrumb': 'navigation',
+};
+
+/**
+ * Canonical type → every alias spelling that normalizes to it, in ELEMENT_TYPE_ALIASES declaration
+ * order. Derived, never authored. Identity entries ('heading': 'heading') are excluded: they are
+ * already covered by the canonical candidate and would only duplicate a lookup.
+ */
+const ALIAS_SPELLINGS: Record<string, string[]> = (() => {
+  const out: Record<string, string[]> = {};
+  for (const [alias, canonical] of Object.entries(ELEMENT_TYPE_ALIASES)) {
+    if (alias === canonical) continue;
+    (out[canonical] ??= []).push(alias);
+  }
+  return out;
+})();
+
 export class SelectorResolver {
   private selectorCache = new Map<string, SelectorFile | LegacySelectorFile>();
   private selectorsDir: string;
@@ -393,69 +514,54 @@ export class SelectorResolver {
       'navigation': () => ({ strategy: 'role', role: 'navigation', name: label, value: 'navigation' }),
     };
 
-    const factory = strategyMap[normalized];
+    const factory = own(strategyMap, normalized);
     return factory ? factory() : null;
   }
 
+  /**
+   * Does the compiler have an OPINION about this element type — is it an alias it normalizes, or a
+   * type auto-infer can serve?
+   *
+   * The distinction decides whether the last-resort sweep may run, and it exists because
+   * `step.elementType` is not always an element type. The parser takes the first word after `]`
+   * (gherkin-parser/index.ts), so `see [Quick Panel] is hidden` arrives here with the "type" `is`
+   * and `drag [Item] to [Drop Zone]` with `to`. Nine such function words appear across the shipped
+   * features. A word the compiler cannot reason about carries no type information at all, so it must
+   * not be treated as a narrowing signal — a step like that has to keep the same open fallback a
+   * bare `[Ref]` gets, or a project whose label needs suffixed keys loses every state-clause step.
+   *
+   * Derived from the two maps rather than listed, so a new alias or strategy is known here the day
+   * it is added. tests/docs/element-type-vocabulary-parity.run.ts pins the maps against the parser's
+   * own list and the published table.
+   */
+  private static isKnownElementType(elementType: string): boolean {
+    if (own(ELEMENT_TYPE_ALIASES, elementType) !== undefined) return true;
+    return SelectorResolver.inferFromElementType(elementType, '') !== null;
+  }
+
+  /**
+   * Every selectors.yaml key that could legitimately hold the entry for `[label] <elementType>`.
+   *
+   * Shared by the lookup and by the not-found message, so the error can never advertise a key the
+   * resolver did not actually try — the two drifting apart is how #752 stayed invisible: the throw
+   * that would have named the missing key was unreachable, and when it did fire it listed two
+   * candidates while the resolver had its own idea of which to check.
+   */
+  private static typedKeyCandidates(key: string, elementType: string, normalizedType: string): string[] {
+    return [...new Set([
+      `${key}--${normalizedType}`,
+      `${key}--${elementType}`,
+      ...(own(ALIAS_SPELLINGS, normalizedType) ?? []).map((alias) => `${key}--${alias}`),
+    ])];
+  }
+
   /**
    * Normalize elementType aliases to canonical YAML suffix
    * Gherkin writers may use: title, label, heading, text → all map to "text"
    * Similarly: btn → button, link → link, input/field → field
    */
   private static normalizeElementType(elementType: string): string {
-    const aliasMap: Record<string, string> = {
-      // Text-like aliases → "text"
-      'title': 'text',
-      'label': 'text',
-      'caption': 'text',
-      // Heading aliases → "heading" (role-based)
-      'heading': 'heading',
-      'header': 'heading',
-      'message': 'text',
-      // Table-related aliases
-      'column': 'columnheader',
-      // List-related aliases
-      'list-item': 'listitem',
-      // Image aliases
-      'logo': 'img',
-      'image': 'img',
-      'icon': 'img',
-      // Button aliases
-      'btn': 'button',
-      // Field aliases
-      'input': 'field',
-      'textbox': 'field',
-      'textarea': 'field',
-      'editor': 'field',
-      // Search alias → searchbox role
-      'search': 'searchbox',
-      // Toggle alias → switch role
-      'toggle': 'switch',
-      // Alert alias → alertdialog role
-      'alert': 'alertdialog',
-      // Modal/drawer alias → dialog role
-      'modal': 'dialog',
-      'drawer': 'dialog',
-      // Dropdown/select alias -> combobox role
-      'dropdown': 'combobox',
-      'select': 'combobox',
-      // Data aliases
-      'item': 'listitem',
-      'card': 'article',
-      'cell': 'cell',
-      'section': 'region',
-      // Feedback aliases
-      'badge': 'text',
-      'tooltip': 'text',
-      'tag': 'text',
-      // Trigger aliases
-      'menuitem': 'menuitem',
-      // System aliases
-      'progressbar': 'progressbar',
-      'spinner': 'status',
-      'breadcrumb': 'navigation',
-    };
-    return aliasMap[elementType] || elementType;
+    return own(ELEMENT_TYPE_ALIASES, elementType) ?? elementType;
   }
 
   /**
@@ -475,33 +581,37 @@ export class SelectorResolver {
     // Try nth-suffixed key first: hay.gui.loi.cam.on--3
     if (nth && nth > 0) {
       const nthKey = `${key}--${nth}`;
-      const nthEntry = selectorFile[nthKey];
+      const nthEntry = own(selectorFile, nthKey);
       if (nthEntry) {
         return this.resolveFromEntry(nthEntry, displayLabel);
       }
     }
 
-    // Try type-suffixed key first: add.campaign--button, add.campaign--text
+    // Try type-suffixed keys: add.campaign--button, add.campaign--text
+    //
+    // EVERY spelling of the step's type is tried, not just the two the step itself could have been
+    // written with (#752). The alias table maps a Gherkin spelling onto a canonical one, but it was
+    // only ever applied to the STEP; the file's keys were compared raw. So `confirm--modal` was
+    // invisible to `[Confirm] dialog` while `confirm--dialog` resolved for `[Confirm] modal` —
+    // the mapping is one-directional and the lookup inherited that. The hole was not specific to
+    // modal/drawer: all 30 non-identity aliases had it.
+    //
+    // Order is deterministic and NOT file order: canonical first (the spelling the compiler thinks
+    // in), then whatever the author literally typed, then the remaining aliases in alias-table
+    // declaration order. A file declaring both `--modal` and `--drawer` therefore resolves the same
+    // way on every machine.
     if (elementType) {
       const normalizedType = SelectorResolver.normalizeElementType(elementType);
-      const typedKey = `${key}--${normalizedType}`;
-      const typedEntry = selectorFile[typedKey];
-      if (typedEntry) {
-        return this.resolveFromEntry(typedEntry, displayLabel);
-      }
-
-      // If normalized differs from original, also try original as-is
-      if (normalizedType !== elementType) {
-        const originalKey = `${key}--${elementType}`;
-        const originalEntry = selectorFile[originalKey];
-        if (originalEntry) {
-          return this.resolveFromEntry(originalEntry, displayLabel);
+      for (const candidate of SelectorResolver.typedKeyCandidates(key, elementType, normalizedType)) {
+        const typedEntry = own(selectorFile, candidate);
+        if (typedEntry) {
+          return this.resolveFromEntry(typedEntry, displayLabel);
         }
       }
     }
 
     // Fallback to base key
-    const entry = selectorFile[key];
+    const entry = own(selectorFile, key);
     if (entry) {
       return this.resolveFromEntry(entry, displayLabel);
     }
@@ -545,20 +655,30 @@ export class SelectorResolver {
       }
     }
 
-    // Last resort: find any suffixed key matching key--*
-    const suffixedKeys = Object.keys(selectorFile).filter(k => k.startsWith(`${key}--`));
-    if (suffixedKeys.length > 0) {
-      return this.resolveFromEntry(selectorFile[suffixedKeys[0]], displayLabel);
-    }
-
-    const tried: string[] = [];
-    if (elementType) {
-      const normalizedType = SelectorResolver.normalizeElementType(elementType);
-      tried.push(`${key}--${normalizedType}`);
-      if (normalizedType !== elementType) {
-        tried.push(`${key}--${elementType}`);
+    // Last resort: any suffixed key matching key--*, for a [Ref] the compiler could not type.
+    //
+    // Two cases reach here and they are the same case: a bare [Ref] with no word after it, and a
+    // [Ref] followed by a word that is not an element type. The parser cannot tell the two apart —
+    // it takes the FIRST word after `]`, so `see [Quick Panel] is hidden` arrives typed `is`. In
+    // both, nothing is known about what kind of element is wanted, so any suffixed key is as good a
+    // guess as the next, and a project whose label needs suffixed keys keeps its state-clause steps.
+    //
+    // A step the compiler CAN type gets no such guess. The candidate scan above already tried every
+    // spelling that normalizes to that type, so whatever is still sitting under `key--` is a
+    // DIFFERENT element, and handing it back is the silent-wrong-answer shape of #752 itself.
+    // Falling through to the throw is better: it names the keys that were tried, and "add an entry"
+    // is an instruction the author can act on.
+    if (!elementType || !SelectorResolver.isKnownElementType(elementType)) {
+      const suffixedKeys = Object.keys(selectorFile).filter(k => k.startsWith(`${key}--`));
+      if (suffixedKeys.length > 0) {
+        return this.resolveFromEntry(selectorFile[suffixedKeys[0]], displayLabel);
       }
     }
+
+    const tried: string[] = elementType
+      ? SelectorResolver.typedKeyCandidates(
+          key, elementType, SelectorResolver.normalizeElementType(elementType))
+      : [];
     const suffix = tried.length > 0 ? ` (also tried ${tried.join(', ')})` : '';
     throw new Error(
       `Selector "${label}" (key: ${key}) not found in ${featureName}.yaml${suffix}. ` +
@@ -751,6 +871,20 @@ export class SelectorResolver {
     return out.class || out.attribute ? out : undefined;
   }
 
+  /**
+   * Report a selectors.yaml problem ONCE per entry+field, not once per step that resolves it.
+   *
+   * An entry is resolved again for every step that names it, so an unguarded `diagnostics.add`
+   * here repeats the same sentence a dozen times for one typo and buries everything else in the
+   * channel. `warnedContentNamed` is the existing de-dupe set; `key` namespaces the callers so two
+   * diagnostics about one entry cannot silence each other.
+   */
+  private warnOnce(key: string, code: DiagnosticCode, message: string): void {
+    if (this.warnedContentNamed.has(key)) return;
+    this.warnedContentNamed.add(key);
+    this.diagnostics?.add(code, message, { feature: this.featureName });
+  }
+
   /**
    * Resolve a selectors.yaml entry that is NOT reachable by key — a `columns.<col>.elements.cell`
    * declaration, which lives nested under a table entry. Public for that one caller; everything
@@ -824,6 +958,28 @@ export class SelectorResolver {
     // 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 ?? '');
+    // Gated on the entry KIND, like the value check below: `query:` means nothing on a non-page
+    // entry, and both the field and its diagnostic are worded purely in page terms. Today's two
+    // consumers re-check `selectorType === 'page'` at the read site (the `anchor:` precedent), so
+    // this is belt-and-braces — but a third consumer that forgets the guard would otherwise inherit
+    // a field that was never meant for it.
+    if (type === 'page' && entry.query !== undefined) {
+      const declared = String(entry.query).trim().toLowerCase();
+      // Exactly one value is legal today. A typo must NOT read as the permissive form: it would
+      // silently turn off the bare-page query assertion (#464) on a page the author meant to keep
+      // strict, which is the class of quiet weakening this whole diagnostic channel exists for.
+      if (declared === 'any') v2Fields.query = 'any';
+      else this.warnOnce(`w037:${originalLabel}:query`, 'SG-W037',
+        `selector "${originalLabel}": query: ${JSON.stringify(String(entry.query))} is not a query rule — the only value is \`any\` ("the query is not part of this page's identity"). The declaration is ignored, so a bare \`see [${originalLabel}] page\` still requires the URL to carry NO query at all.`);
+    }
+    // A page `value` is the PATH only — pathToRegexSource strips a `?`/`#` before building the
+    // pattern. Silently, until now: an author who hit the bare-page query rule (#464) and reached
+    // for the obvious workaround got byte-identical output and no hint why, which is exactly how
+    // #748 was misdiagnosed in the field as a regex-escaping bug.
+    if (type === 'page' && typeof entry.value === 'string' && /[?#]/.test(entry.value)) {
+      this.warnOnce(`w037:${originalLabel}:value`, 'SG-W037',
+        `selector "${originalLabel}": the page value ${JSON.stringify(entry.value)} carries a query/fragment, which is DROPPED — a page value is the path only, and the pattern is matched against \`u.pathname\`, which never holds one. Writing it here changes nothing. To assert the query, declare it on the step (\`see [${originalLabel}] page with {{v}}\`); to say the query is not part of this page's identity, add \`query: any\` to the entry.`);
+    }
 
     // Helper to attach v2 fields and inputMethod
     const withExtras = (resolved: ResolvedSelector): ResolvedSelector => {

package/src/harness/audit.ts

@@ -32,7 +32,8 @@ 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';
-import { readTextFile } from './read-text';
+import { readTextFile, readViewpointText } from './read-text';
+import { uiInventoryCoverage, uiInventoryFindings, UiInventoryResult } from './ui-inventory';
 
 export interface AuditReport {
   screen: string;
@@ -57,6 +58,8 @@ export interface AuditReport {
   flowQuality?: FlowQualityResult;      // #569 — flow contract verification (flows only)
   /** #595 — coverage per DECLARED FLOW; absent when the contract declares no `flows:`. */
   flowInventory?: InventoryResult;
+  /** #811 — design items vs the suite; present only when the unit holds design sources. */
+  uiInventory?: UiInventoryResult;
   calibration: {                // #8 — multi-axis score so a high overall can't hide a weak axis
     axes: Record<string, number>;
     weakest: { axis: string; value: number };
@@ -185,6 +188,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const scoringCap = scoringCapId ? capabilityRegistry.get(scoringCapId) : undefined;
   const catalog = (scoringCap?.viewpoints?.() as Catalog | undefined) || loadCatalog();
   const spec = specCoverage(specPath, scenarios, featureText);
+  const uiInv = uiInventoryCoverage(path.join(screenDir, 'requirements'), featureText);
 
   // P3 — intent profile from qa/context.md drives the depth threshold (focus).
   const intent = readIntent(projectRootFromScreenDir(screenDir));
@@ -196,7 +200,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // Is the declaration this suite is measured against still the one a human accepted?
   const viewpointBaseline = checkViewpointBaseline(
     projectRootFromScreenDir(screenDir), catalogScreenName, viewpointPath);
-  const viewpointText = fs.existsSync(viewpointPath) ? readTextFile(viewpointPath) : '';
+  const viewpointText = readViewpointText(viewpointPath);
   // #569 — a flow WITH a contract is measured against ITS declaration, not a screen's.
   // Keyword page-type detection force-fit flows into screen checklists (a registration
   // flow judged as a `form` screen scored coverage 0%), so for contract-holding flows the
@@ -227,7 +231,12 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     if (flowScenarios.length) {
       for (const c of flowCoveredThemes(gate.gaps, flowScenarios)) {
         const i = gate.gaps.findIndex((g) => g.theme === c.theme);
-        if (i >= 0) { gate.gaps.splice(i, 1); gate.themesCovered++; flowCredits.push(c); }
+        if (i >= 0) {
+          gate.gaps.splice(i, 1); gate.themesCovered++; flowCredits.push(c);
+          // Keep the claim-proof list in step with the count (#776) — a theme credited to a flow
+          // must SAY it came from a flow, or the evidence lines silently under-report the total.
+          gate.coveredBy.push({ theme: c.theme, by: `(flow) ${c.flow}`, keyword: '—' });
+        }
       }
       gate.coverageRatio = gate.themesTotal ? gate.themesCovered / gate.themesTotal : 1;
     }
@@ -292,12 +301,16 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // #569 — handoff integrity: a flow's depth is also whether each cross-screen transition
   // is followed by an assertion on the carried state (same floor discipline as the other caps).
   const HANDOFF_FLOOR = 0.5;
-  const businessDepth = Math.min(
+  // Each FLOOR is a floor on the CAP, not on the result — an out-of-range input ratio walks
+  // straight through it (a -1.5 oracle ratio yielded businessDepth -0.25 and crashed the CLI's
+  // bar renderer, #762). The axis is declared `0..1` above and weighted `critical`, so a negative
+  // value would also drag `score.overall` below zero. Clamp once, here, where the axis is formed.
+  const businessDepth = Math.max(0, Math.min(1, Math.min(
     depth.bcDepthRatio,
     flowDepth.stateful ? FLOW_DEPTH_FLOOR + (1 - FLOW_DEPTH_FLOOR) * flowDepth.ratio : 1,
-    oracle.weak.length ? ORACLE_FLOOR + (1 - ORACLE_FLOOR) * oracle.ratio : 1,
+    oracle.weakFacet ? ORACLE_FLOOR + (1 - ORACLE_FLOOR) * oracle.ratio : 1,
     flowQ.hasContract && flowQ.handoffs.total > 0 ? HANDOFF_FLOOR + (1 - HANDOFF_FLOOR) * flowQ.handoffs.ratio : 1,
-  );
+  )));
   // When the taxonomy drifted (most scenarios unclassified), the balance axis is unreliable — cap it
   // at 0.5 instead of awarding a vacuous 1.0 so a stale taxonomy fails loudly, not silently (H1).
   const balanceScore = balance.unclassifiedRatio > 0.4
@@ -364,7 +377,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     { 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, withheld: viewpointMoved && viewpoints.length > 0 },
+    { key: 'traceability', value: traceScore, weight: 0.09, applicable: viewpoints.length > 0 && scenarios.length > 0 && !viewpointMoved, critical: false, withheld: viewpointMoved && viewpoints.length > 0 && scenarios.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
@@ -576,7 +589,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     findings.push(`COVERED-VIA-FLOW: critical theme "${c.theme}" is not covered on this screen but is deeply covered by flow "${c.flow}" — cross-screen depth correctly owned by the flow, so it is credited (not a screen gap). Verify with \`sungen flow-check\`.`);
   }
   // Verification-scope (advisory): API/DB verification the project's recorded test type never asked for.
-  for (const v of verificationScopeFindings(featureText, fs.existsSync(viewpointPath) ? readTextFile(viewpointPath) : '', capProfile)) {
+  for (const v of verificationScopeFindings(featureText, viewpointText, capProfile)) {
     findings.push(`VERIFICATION-OUT-OF-SCOPE (${v.layer}): this unit ${v.message}`);
   }
   for (const g of gate.gaps) {
@@ -594,12 +607,13 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
       `add data assertions (\`... with {{value}}\`, \`see all ... contain {{v}}\`) or, if cross-screen, defer to a flow with @manual + reason.`,
     );
   }
-  // H5 — state isolation: a @parallel stateful flow that mutates the cart needs per-scenario
-  // isolation, else count/quantity asserts go flaky. Warn (advisory) when no mitigation is present
+  // H5 — state isolation: a stateful flow that mutates the cart needs per-scenario isolation, else
+  // count/quantity asserts go flaky. Warn (advisory) when no mitigation is present
   // (@cleanup:cart / @isolate / a "Given … empty cart" background / fresh context).
+  // #759 — scoped by the ABSENCE of @serial, not the presence of @parallel: parallel is the default.
   if (isoRisk) {
     const what = flowQ.contract?.stateful ?? 'cart';
-    findings.push(`ISOLATION-RISK: this @parallel flow mutates ${what} but has no per-scenario isolation → count/quantity/state asserts can go flaky when scenarios share it. Add \`@cleanup:${what}\` (or \`@isolate\`, a fresh context, or \`{{$timestamp}}\` data) so each scenario starts clean.`);
+    findings.push(`ISOLATION-RISK: this flow mutates ${what} but has no per-scenario isolation → count/quantity/state asserts can go flaky when scenarios share it. Add \`@cleanup:${what}\` (or \`@isolate\`, a fresh context, or \`{{$timestamp}}\` data) so each scenario starts clean.`);
   }
   // #414 — serial-cascade masking: an @serial suite of independent (re-navigating) scenarios hides
   // failures, because Playwright's describe.serial SKIPS everything after the first red. Isolation is
@@ -647,7 +661,8 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
       ...(unsourced.length ? [`${unsourced.length} scenario(s) could not be traced to a source`] : []),
     ];
     findings.push(`VIEWPOINT-MISSING: \`requirements/test-viewpoint.md\` ${ledger.hasViewpoint ? 'declares no viewpoints' : 'does not exist'}, so this unit has no yardstick. Two scored axes are excluded (atomicLedger, traceability) and four sensors cannot run: the atomic ledger, the declaration-integrity checks (reused ids, dangling refs, uniform priority), the browser-gesture check and the two-way continuity check. Nothing here is a pass — it is unmeasured [${lost.join(', ')}]. A flow contract does NOT substitute: the contract declares the use case, the viewpoint declares the CLAIMS the suite is scored against, and only the second is independent of what was generated. Author it (\`sungen add-flow\` scaffolds a template), then \`sungen audit --screen ${screenName} --accept-viewpoint\`.`);
-  } else if (trace.mappedRatio < 0.5) {
+  } else if (scenarios.length > 0 && trace.mappedRatio < 0.5) {
+    // No scenario yet is not a traceability gap — the axis is n/a, like coverage and claimProof (#852).
     findings.push(`TRACE: ${trace.note}`);
   }
   // (UNIVERSAL viewpoint-gap finding now emitted by the `ui` gate sensor — see the gate block below.)
@@ -688,8 +703,10 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   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}\`).`);
   }
+  // #811 — design inventory (advisory): never moves the score or the gate.
+  findings.push(...uiInventoryFindings(uiInv));
   for (const m of manualOracleResult.insufficient.slice(0, 8)) {
-    findings.push(`MANUAL-STEPS-INSUFFICIENT: "${m}" — @manual is incomplete: either Gherkin steps without a Then (invalid Gherkin; comments can't substitute), or a documentation manual whose comments lack numbered action steps + a labeled Observable:/Oracle: line. Write \`# Tester verifies:\` as "1. <action>" … "N. Observable: <what>" / "Oracle: <tool>" — that is what the delivery parser extracts into Steps/Expected.`);
+    findings.push(`MANUAL-STEPS-INSUFFICIENT: "${m}" — @manual is incomplete: either Gherkin steps without a Then (invalid Gherkin; comments can't substitute), a Then that only asserts presence (\`see [X] table\`) while the real oracle sits in a \`# Tester verifies:\` comment (the deliverable's Expected would not say what is checked), or a documentation manual whose comments lack numbered action steps + a labeled Observable:/Oracle: line. Write \`# Tester verifies:\` as "1. <action>" … "N. Observable: <what>" / "Oracle: <tool>" — that is what the delivery parser extracts into Steps/Expected.`);
   }
   // TQ-2 — automatable @manual: deferred (usually cross-screen) but fully DSL-expressible.
   for (const m of autoManual.scenarios.slice(0, 8)) {
@@ -787,7 +804,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // #622 — the priority table is where release selection comes from; a tag that contradicts it
   // means nobody can tell which of the two was the decision.
   {
-    const pm = priorityMismatches(hasYardstick ? (readText(viewpointPath) ?? '') : '', scenarios);
+    const pm = priorityMismatches(hasYardstick ? viewpoints : [], scenarios);
     const byId = new Map<string, { declared: string; tagged: string; n: number }>();
     for (const m of pm) {
       const cur = byId.get(m.id) ?? { declared: m.declared, tagged: m.tagged, n: 0 };
@@ -860,8 +877,11 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   axes.manualOracle = Math.round(manualCompleteness * 100) / 100;
   // Only a real mismatch scores 0. Without a yardstick `trace.mappedRatio` is 0 because there is
   // nothing to map to, and reporting that as the weakest axis sent authors to "raise taxonomy" —
-  // an axis that was never measured.
-  if (hasYardstick) axes.taxonomy = taxonomyMismatch ? 0 : Math.round(trace.mappedRatio * 100) / 100;
+  // an axis that was never measured. The same holds for a yardstick the ledger can read but that
+  // declares no viewpoint ID traceability can read (per-axis tables only, #832): the ledger has
+  // items, so `hasYardstick` is true, yet there is still nothing to map to. Same condition as the
+  // `traceability` score axis (`applicable: viewpoints.length > 0`).
+  if (hasYardstick && viewpoints.length > 0 && scenarios.length > 0) axes.taxonomy = taxonomyMismatch ? 0 : Math.round(trace.mappedRatio * 100) / 100;
   const notApplicable = axisDefs.filter((a) => !a.applicable).map((a) => a.key);
   const weakestEntry = Object.entries(axes).sort((a, b) => a[1] - b[1])[0];
   const weakest = { axis: weakestEntry[0], value: weakestEntry[1] };
@@ -889,6 +909,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     gate, depth, claim, taxonomy, balance, duplicates, trace, spec,
     taxonomyMismatch, reusedScenarioIds: reusedIds, downstream, manualOracle: manualOracleResult, automatableManual: autoManual, flowDepth, oracle, ledger, viewpointBaseline, calibration,
     ...(isUiFlow ? { flowQuality: flowQ, flowInventory: inventory ?? undefined } : {}),
+    ...(uiInv.designSources.length ? { uiInventory: uiInv } : {}),
     score: {
       overall: Math.round(overall * 10) / 10,
       coverage: Math.round(coverage * 100) / 100,

package/src/harness/capability.ts

@@ -11,6 +11,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { readYamlConfig, warnUnreadableConfig } from './config-file';
 
 export interface CapabilityProfile {
   platform?: string;       // web | mobile | …  (the runtime adapter)
@@ -23,7 +24,13 @@ export interface CapabilityProfile {
    * never asked for.
    */
   verification?: string[];
-  source: 'capabilities.yaml' | 'absent';
+  /**
+   * Where the profile came from. `'unreadable'` is NOT `'absent'`: the file exists and says
+   * something, we just cannot read it. Callers that WRITE capabilities.yaml must branch on this —
+   * scaffolding a default over a file whose contents we failed to parse destroys the user's
+   * declaration (see `cli/commands/generate.ts`).
+   */
+  source: 'capabilities.yaml' | 'absent' | 'unreadable';
 }
 
 export type VerifyLayer = 'ui' | 'api' | 'db';
@@ -119,18 +126,22 @@ export function capabilitiesPath(cwd: string): string {
 
 export function readCapabilities(cwd: string): CapabilityProfile {
   const p = capabilitiesPath(cwd);
-  if (!fs.existsSync(p)) return { platform: undefined, enabled: [], source: 'absent' };
-  try {
-    const y = parseYaml(fs.readFileSync(p, 'utf-8')) || {};
-    return {
-      platform: typeof y.platform === 'string' ? y.platform : undefined,
-      enabled: Array.isArray(y.enabled) ? y.enabled.map(String) : [],
-      verification: Array.isArray(y.verification) ? y.verification.map(String) : undefined,
-      source: 'capabilities.yaml',
-    };
-  } catch {
-    return { platform: undefined, enabled: [], source: 'absent' };
+  const read = readYamlConfig<Record<string, unknown> | null>(p);
+  if (read.state === 'absent') return { platform: undefined, enabled: [], source: 'absent' };
+  if (read.state === 'unreadable') {
+    // The profile decides the runtime adapter, the driver set and the verification scope. Reporting
+    // it once here covers all fifteen call sites; what each does about it is still its own choice.
+    warnUnreadableConfig(p, read.error,
+      'this run cannot tell which platform or drivers the project declares, and falls back to none');
+    return { platform: undefined, enabled: [], source: 'unreadable' };
   }
+  const y = (read.value || {}) as Record<string, unknown>;
+  return {
+    platform: typeof y.platform === 'string' ? y.platform : undefined,
+    enabled: Array.isArray(y.enabled) ? y.enabled.map(String) : [],
+    verification: Array.isArray(y.verification) ? y.verification.map(String) : undefined,
+    source: 'capabilities.yaml',
+  };
 }
 
 export function writeCapabilities(cwd: string, profile: { platform?: string; enabled: string[]; verification?: string[] }): string {