@sun-asterisk/sungen 3.2.32 → 3.2.33

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

@@ -227,7 +227,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 +297,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
@@ -594,12 +603,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

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 {

package/src/harness/catalog/universal-viewpoints.yaml

@@ -24,7 +24,7 @@ page_types:
     detect_keywords: [cart, product, checkout, catalog, brand, category, "add to cart"]
     must_cover:
       - theme: list-data
-        keywords: [list, displayed, card, "product card", grid]
+        keywords: ["product list", displayed, card, "product card", grid]
         depth:
           requires: data-assertion
           cross_screen: false
@@ -38,7 +38,7 @@ page_types:
           keywords: ["product detail", "detail page", "same product name", "matching name", "consistency", "same price"]
           template: "User remember [Product Name] text as {{v}} … User see [Detail Product Name] header with {{v}}"
       - theme: cart-correctness
-        keywords: ["cart contains", quantity, "price", subtotal, "in cart", "cart content", "cart product"]
+        keywords: ["cart contains", "cart quantity", "cart price", subtotal, "in cart", "cart content", "cart product"]
         depth:
           requires: data-assertion
           cross_screen: true
@@ -77,7 +77,7 @@ page_types:
           keywords: ["required", "must be", "error message", "validation message"]
           template: "User see [Field Error] message with {{error_text}}"
       - theme: format-boundary
-        keywords: [format, invalid, boundary, length, range]
+        keywords: [format, invalid, boundary, "max length", "min length", range]
         depth:
           requires: data-assertion
           cross_screen: false
@@ -125,10 +125,10 @@ page_types:
   # suite, which is a scoring decision for an owner, not a drive-by. `viewpoint-ledger` already
   # covers the dangerous half by refusing `tap [Back]` as an answer to an OS-back viewpoint item.
   mobile-list:
-    detect_keywords: [feed, "pull to refresh", "infinite scroll", "load more", "list item", "list row"]
+    detect_keywords: ["feed item", "pull to refresh", "infinite scroll", "load more", "list item", "list row"]
     must_cover:
       - theme: list-data
-        keywords: [list, feed, row, "list item", displayed]
+        keywords: ["feed item", row, "list item", displayed]
         depth:
           requires: data-assertion
           cross_screen: false

package/src/harness/config-file.ts

@@ -0,0 +1,66 @@
+/**
+ * Reading a config file has THREE outcomes, not two: absent, parsed, and present-but-unreadable.
+ *
+ * Collapsing the third into the first is the defect class #782 catalogues. The shape recurs because
+ * it looks harmless: an `fs.existsSync` guard already answers absence, so the `catch` below it only
+ * ever fires for CORRUPTION — and returning the absent value there is the one case that must not be
+ * silent. A file that is absent was never written; a file that is broken WAS written, by someone who
+ * believes it is in effect.
+ *
+ * `run-manifest.ts:hashTopLevel` already draws the distinction for its own reader (`__unparseable__`
+ * rather than `{}`); this is that idea as a seam every config reader can share, so the next one does
+ * not have to rediscover it.
+ *
+ * Nothing here throws: the caller owns the consequence, because only the caller knows it. What the
+ * type removes is the option of not deciding.
+ */
+import * as fs from 'fs';
+import { parse as parseYaml } from 'yaml';
+
+export type ConfigRead<T> =
+  | { state: 'absent' }
+  | { state: 'ok'; value: T }
+  | { state: 'unreadable'; error: string };
+
+const message = (e: unknown): string => (e instanceof Error ? e.message.split('\n')[0] : String(e));
+
+/** Read + parse a YAML config. An empty or comment-only file parses to null — that is `ok`, not broken. */
+export function readYamlConfig<T>(file: string): ConfigRead<T> {
+  if (!fs.existsSync(file)) return { state: 'absent' };
+  try {
+    return { state: 'ok', value: (parseYaml(fs.readFileSync(file, 'utf-8')) ?? null) as T };
+  } catch (e) {
+    return { state: 'unreadable', error: message(e) };
+  }
+}
+
+/** Read + parse a JSON config. Unlike YAML, an empty file is NOT valid JSON and reads as unreadable. */
+export function readJsonConfig<T>(file: string): ConfigRead<T> {
+  if (!fs.existsSync(file)) return { state: 'absent' };
+  try {
+    return { state: 'ok', value: JSON.parse(fs.readFileSync(file, 'utf-8')) as T };
+  } catch (e) {
+    return { state: 'unreadable', error: message(e) };
+  }
+}
+
+/**
+ * One line to stderr naming the file, the parse error, and WHAT THE RUN WILL DO INSTEAD — the last
+ * part is the whole point: "capabilities.yaml is broken" leaves the reader guessing; "…so this run
+ * treats the project as web" tells them why their mobile suite just compiled wrong.
+ *
+ * At most once per file per process. `readCapabilities` alone has fifteen call sites, and a warning
+ * repeated fifteen times reads as noise — which is its own way of being ignored.
+ */
+const warned = new Set<string>();
+
+export function warnUnreadableConfig(file: string, error: string, consequence: string): void {
+  if (warned.has(file)) return;
+  warned.add(file);
+  console.error(`⚠️  ${file}: unreadable (${error}) — ${consequence}`);
+}
+
+/** Test seam: the dedup set is process-global, so a suite exercising several cases must clear it. */
+export function resetUnreadableConfigWarnings(): void {
+  warned.clear();
+}

package/src/harness/depth-lint.ts

@@ -15,6 +15,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { loadUnitScenarios, parseViewpointOverview, ScenarioInfo, ViewpointEntry } from './parse';
 import { loadCatalog, viewpointGate, assertionDepth, dataThemesFor, CatalogTheme } from './sensors';
+import { keywordHit } from './keyword-match';
 
 export type DepthAction = 'deepen' | 'defer';
 
@@ -45,7 +46,7 @@ export interface DepthLintReport {
 function matchTheme(s: ScenarioInfo, dataThemes: CatalogTheme[]): CatalogTheme | undefined {
   return dataThemes.find((t) => {
     const kws = t.depth?.keywords?.length ? t.depth.keywords : t.keywords;
-    return kws.some((k) => s.haystack.includes(k.toLowerCase()));
+    return kws.some((k) => keywordHit(s.haystack, k));
   });
 }