@sun-asterisk/sungen 3.2.27 → 3.2.29

package/dist/orchestrator/templates/specs-url-assert.js

@@ -21,6 +21,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.joinPath = joinPath;
 exports.urlMatches = urlMatches;
+exports.expectPage = expectPage;
+const test_1 = require("@playwright/test");
 /**
  * Join a page's URL with the `with {{v}}` value for a NAVIGATION step
  * (`Given User is on [X] page with {{v}}`).
@@ -118,4 +120,45 @@ function urlMatches({ pathname, declared, dataRef }) {
         return queryOk && hashOk;
     };
 }
+/**
+ * `toHaveURL` is a polling assertion: it passes on the FIRST sample that matches. A client-side
+ * router pushes the destination URL before the route guard or the API has answered, so a user
+ * with no permission is "on" `/items/detail` for a few hundred milliseconds — long enough for
+ * the assertion to sample it, pass, and end the test green — and is then bounced to `/forbidden`
+ * with no assertion left to see it. A real project shipped a permission matrix on that oracle;
+ * the 403s were found by hand (#662).
+ *
+ * `expectPage` is the page oracle `see [X] page` compiles to now. Arriving is not enough: the URL
+ * has to be STILL matching once the page has settled.
+ *   1. arrive   — the same predicate `toHaveURL` always used;
+ *   2. settle   — wait for network to go quiet (bounded: an app that polls forever must not hang
+ *                 the test, so a timeout here is not a failure);
+ *   3. hold     — sample the URL over a settle window; the moment it stops matching, fail and
+ *                 NAME where it went, because that destination is the finding;
+ *   4. re-assert — the arrival predicate, once more, on the settled page.
+ *
+ * `SUNGEN_URL_SETTLE_MS` (default 1000) is the hold window; `SUNGEN_URL_NETWORKIDLE_MS` (default
+ * 3000) bounds step 2. Both are runtime knobs, so a slow environment is a config change, not a
+ * regenerate.
+ */
+async function expectPage(page, expectation, opts = {}) {
+    const settleMs = opts.settleMs ?? Number(process.env.SUNGEN_URL_SETTLE_MS ?? 1000);
+    const networkIdleMs = opts.networkIdleMs ?? Number(process.env.SUNGEN_URL_NETWORKIDLE_MS ?? 3000);
+    const matches = urlMatches(expectation);
+    const assertUrl = opts.assertUrl ?? (async (m) => { await (0, test_1.expect)(page).toHaveURL(m); });
+    await assertUrl(matches);
+    const arrivedAt = page.url();
+    await page.waitForLoadState('networkidle', { timeout: networkIdleMs }).catch(() => undefined);
+    const started = Date.now();
+    while (Date.now() - started < settleMs) {
+        const now = page.url();
+        if (!matches(new URL(now))) {
+            throw new Error(`page assertion: reached ${arrivedAt} and then left for ${now} after ${Date.now() - started}ms — `
+                + 'a route guard, an error boundary or a redirect moved the user away after the URL had already '
+                + 'matched. The page the test asserted is not the page the user ended on.');
+        }
+        await new Promise((r) => setTimeout(r, 50));
+    }
+    await assertUrl(matches);
+}
 //# sourceMappingURL=specs-url-assert.js.map

package/dist/orchestrator/templates/specs-url-assert.js.map

@@ -1 +1 @@
-{"version":3,"file":"specs-url-assert.js","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-url-assert.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"specs-url-assert.js","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-url-assert.ts"],"names":[],"mappings":";AAAA,oBAAoB;AACpB;;;;;;;;;;;;;;;;;GAiBG;;AAwCH,4BAYC;AA0BD,gCAuCC;AAuBD,gCA6BC;AAvKD,2CAAqD;AAmBrD;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,QAAQ,CAAC,IAAY,EAAE,IAAY,EAAE,QAAwB;IAC3E,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,EAAE;QAAE,OAAO,IAAI,GAAG,IAAI,CAAC;IACvF,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/B,2FAA2F;IAC3F,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC;IAC/E,yEAAyE;IACzE,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9C,0FAA0F;IAC1F,qEAAqE;IACrE,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,GAAG,KAAK,CAAC;IAC/C,4DAA4D;IAC5D,OAAO,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,QAAgB;IACnC,IAAI,CAAC;QACH,OAAO,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,UAAU,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAkB;IACxE,OAAO,CAAC,CAAM,EAAW,EAAE;QACzB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QAExF,8FAA8F;QAC9F,sFAAsF;QACtF,+FAA+F;QAC/F,2FAA2F;QAC3F,mEAAmE;QACnE,IAAI,CAAC,OAAO;YAAE,OAAO,CAAC,CAAC,MAAM,KAAK,EAAE,CAAC;QAErC,8FAA8F;QAC9F,4FAA4F;QAC5F,6FAA6F;QAC7F,2FAA2F;QAC3F,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YAChD,MAAM,IAAI,KAAK,CAAC,iCAAiC,OAAO,kCAAkC,CAAC,CAAC;QAC9F,CAAC;QACD,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,iCAAiC,OAAO,gCAAgC,CAAC,CAAC;QAC5F,CAAC;QAED,6FAA6F;QAC7F,6FAA6F;QAC7F,wFAAwF;QACxF,iFAAiF;QACjF,uFAAuF;QACvF,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,uBAAuB,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;QAE1E,4FAA4F;QAC5F,4FAA4F;QAC5F,0FAA0F;QAC1F,yDAAyD;QACzD,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAE5F,uDAAuD;QACvD,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,CAAC;QAC5C,OAAO,OAAO,IAAI,MAAM,CAAC;IAC3B,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACI,KAAK,UAAU,UAAU,CAC9B,IAA2G,EAC3G,WAA2B,EAC3B,OAAmH,EAAE;IAErH,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,IAAI,CAAC,CAAC;IACnF,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,yBAAyB,IAAI,IAAI,CAAC,CAAC;IAClG,MAAM,OAAO,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;IACxC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,CAAC,KAAK,EAAE,CAAsB,EAAE,EAAE,GAAG,MAAM,IAAA,aAAM,EAAC,IAAuB,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEhI,MAAM,SAAS,CAAC,OAAO,CAAC,CAAC;IACzB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,MAAM,IAAI,CAAC,gBAAgB,CAAC,aAAa,EAAE,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAE9F,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC3B,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,QAAQ,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CACb,2BAA2B,SAAS,sBAAsB,GAAG,UAAU,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,OAAO;kBAChG,+FAA+F;kBAC/F,wEAAwE,CAC3E,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,MAAM,SAAS,CAAC,OAAO,CAAC,CAAC;AAC3B,CAAC"}

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

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

package/dist/orchestrator/templates/wdio.conf.ts

@@ -28,6 +28,26 @@ import * as path from 'node:path';
 import { execSync } from 'node:child_process';
 import PwShapeReporter from './specs/reporters/pw-shape-reporter';
 
+/**
+ * Failure-evidence output. `test-results/` is already gitignored — screenshots and page sources
+ * of a real app routinely contain live data (a signed-in email, a token rendered on screen), so
+ * this directory must never become committable.
+ */
+const EVIDENCE_ROOT = path.join('test-results', 'mobile');
+/** A full logcat is unbounded; only the tail is ever diagnostic. */
+const EVIDENCE_LOG_TAIL_LINES = 500;
+/** ~2 MB of accessibility tree is already far more than anyone reads. */
+const EVIDENCE_PAGE_SOURCE_MAX = 2_000_000;
+
+/** Filesystem-safe path segment from a feature/test title. */
+function evidenceSlug(s: string): string {
+  return String(s)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80) || 'unnamed';
+}
+
 /**
  * Auto-select MOBILE specs and classify each by its target OS (dual-target routing).
  *
@@ -404,9 +424,93 @@ export const config: WebdriverIO.Config = {
   // Connectivity self-heal (#615): onPrepare heals a device wedged by a previous KILLED run
   // (its onComplete never fired) before the session starts; onComplete restores after this run,
   // pass or fail. Both run in the launcher process, so they fire even when the worker/session died.
-  onPrepare: () => { restoreConnectivity('onPrepare'); setShowTouches('onPrepare'); },
+  onPrepare: () => { restoreConnectivity('onPrepare'); setShowTouches('onPrepare'); fs.mkdirSync(EVIDENCE_ROOT, { recursive: true }); },
   onComplete: () => { restoreConnectivity('onComplete'); setShowTouches('onComplete'); },
 
+  /**
+   * Failure evidence. A mobile failure used to reach the report as a single error string — no
+   * image, no tree, no device log — which makes triaging a native UI almost impossible.
+   *
+   * Only runs on failure, so a passing suite pays nothing. Each capture is wrapped SEPARATELY:
+   * one unavailable command (a Flutter page source that blows the buffer, a driver with no log
+   * endpoint) must not cost us the other two, and nothing in here may convert an already-failing
+   * test into a different error.
+   */
+  afterTest: async (
+    test: { title?: string; parent?: string },
+    _context: unknown,
+    result: { passed?: boolean },
+  ): Promise<void> => {
+    if (result?.passed) return;
+
+    // Opt-out for constrained runners (a device farm billing per artifact, a CI box with no disk).
+    // A feature tagged @screenshot:on-failure declares its evidence essential and overrides it.
+    const forced = (globalThis as Record<string, unknown>).__sungenForceEvidence === true;
+    if (!forced && process.env.SUNGEN_MOBILE_EVIDENCE === 'off') return;
+
+    const feature = test?.parent || 'Tests';
+    const title = test?.title || 'test';
+    const dir = path.join(EVIDENCE_ROOT, evidenceSlug(feature), evidenceSlug(title));
+    const files: Array<{ name: string; path: string; contentType: string }> = [];
+
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+    } catch (e) {
+      console.warn(`[sungen] could not create evidence dir ${dir}: ${(e as Error).message}`);
+      return;
+    }
+
+    // 1. Screenshot — the single most useful artifact for a UI failure.
+    try {
+      const shot = path.join(dir, 'screenshot.png');
+      await driver.saveScreenshot(shot);
+      files.push({ name: 'screenshot', path: shot, contentType: 'image/png' });
+    } catch (e) {
+      console.warn(`[sungen] screenshot capture failed: ${(e as Error).message}`);
+    }
+
+    // 2. Page source — the accessibility tree, i.e. WHY a selector did not match. Capped: a
+    //    Flutter/RecyclerView tree can run to tens of MB and there is no value in writing that.
+    try {
+      const src = await driver.getPageSource();
+      const capped = src.length > EVIDENCE_PAGE_SOURCE_MAX
+        ? `${src.slice(0, EVIDENCE_PAGE_SOURCE_MAX)}\n<!-- [sungen] truncated at ${EVIDENCE_PAGE_SOURCE_MAX} of ${src.length} chars -->`
+        : src;
+      if (src.length > EVIDENCE_PAGE_SOURCE_MAX) {
+        console.warn(`[sungen] page source ${src.length} chars — truncated to ${EVIDENCE_PAGE_SOURCE_MAX}`);
+      }
+      const out = path.join(dir, 'page-source.xml');
+      fs.writeFileSync(out, capped, 'utf-8');
+      files.push({ name: 'page-source', path: out, contentType: 'application/xml' });
+    } catch (e) {
+      console.warn(`[sungen] page source capture failed: ${(e as Error).message}`);
+    }
+
+    // 3. Device log — logcat on Android, syslog on iOS. Tail only: a full logcat is unbounded.
+    try {
+      const logType = driver.isIOS ? 'syslog' : 'logcat';
+      const entries = (await driver.getLogs(logType)) as Array<{ message?: string } | string>;
+      const lines = entries.map((l) => (typeof l === 'string' ? l : l?.message || '')).filter(Boolean);
+      const tail = lines.slice(-EVIDENCE_LOG_TAIL_LINES).join('\n');
+      const out = path.join(dir, 'device.log');
+      fs.writeFileSync(out, tail, 'utf-8');
+      files.push({ name: 'device-log', path: out, contentType: 'text/plain' });
+    } catch (e) {
+      console.warn(`[sungen] device log capture failed: ${(e as Error).message}`);
+    }
+
+    // Hand the paths to the reporter so they land in the result's `attachments`. Resolved off
+    // globalThis, not imported — see the note in specs/reporters/pw-shape-reporter.ts.
+    try {
+      const attach = (globalThis as Record<string, unknown>).__sungenAttachEvidence;
+      if (typeof attach === 'function') {
+        (attach as (f: string, t: string, files: typeof files) => void)(feature, title, files);
+      }
+    } catch (e) {
+      console.warn(`[sungen] could not register evidence with the reporter: ${(e as Error).message}`);
+    }
+  },
+
   // iOS + locale: XCUITest's `noReset:false` does NOT actually clear the app's data container
   // (verified live 2026-06-11) — a Flutter app that persisted its language on a previous launch keeps
   // it and ignores the new device locale, so the i18n run asserts the wrong language. Wipe the app

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.27",
+  "version": "3.2.29",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -40,8 +40,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.2.27",
-    "@sungen/driver-ui": "3.2.27",
+    "@sungen/driver-data-factory": "3.2.29",
+    "@sungen/driver-ui": "3.2.29",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

package/src/capabilities/discover.ts

@@ -18,9 +18,12 @@
  * (`--version`, `capability remove`) even when a driver is missing/broken.
  */
 import { createRequire } from 'module';
+import * as fs from 'fs';
 import * as path from 'path';
+import { coreVersion } from '../orchestrator/lockstep-version';
 import { capabilityRegistry } from './registry';
 import { LOCAL_DRIVERS, registerCoreCapability } from './builtins';
+import { loadDriverCatalog, readCapabilities } from '../harness/capability';
 
 /**
  * Driver packages relocated out of core, loaded before the in-core `LOCAL_DRIVERS`. As `db`/`api`
@@ -44,18 +47,116 @@ const EXTERNAL_DRIVERS = ['@sungen/driver-ui', '@sungen/driver-db', '@sungen/dri
 // test-data available out of the box (no `capability add` needed); inert until a field-map/recipe exists.
 const BUNDLED_DRIVERS = new Set(['@sungen/driver-ui', '@sungen/driver-data-factory']);
 
+/** One installed copy of a driver package: where it was found from, and which version lives there. */
+export interface DriverCopy {
+  /** The anchor the lookup was made from — the project's package.json, or core's own file. */
+  anchor: 'project' | 'core';
+  resolved: string;
+  version: string | undefined;
+}
+
+/** `3.2.28-beta.2` and `3.2.28` sit on the same lockstep line; `3.2.20` does not. */
+export function sameVersionLine(a: string | undefined, b: string | undefined): boolean {
+  if (!a || !b || a === 'latest' || b === 'latest') return false;
+  const line = (v: string) => v.split('-')[0];
+  return line(a) === line(b);
+}
+
+/**
+ * Pick which installed copy of a driver to load.
+ *
+ * Project-first is right for an OPT-IN driver: `sungen capability add db` installs into the
+ * project's node_modules, and a globally-installed core would never see it from its own anchor.
+ *
+ * It was wrong for a BUNDLED driver. Core pins `@sungen/driver-ui` to its exact version, but the
+ * project may hold an older copy — a `^` range from an earlier scaffold, a lock file nobody
+ * refreshed — and that copy loaded first, unconditionally. Core 3.2.25 started gating every state
+ * clause on `pattern.states` (SG-E021); driver-ui 3.2.20 predates the field; so
+ * `see [Filter] button is hidden` threw on the very pattern (`is-hidden`) the message told the
+ * author to use. Every `is <state>` step in every project holding a stale driver, on Gherkin that
+ * was correct — and the message blamed the Gherkin.
+ *
+ * So for a bundled driver the copy on core's own version line wins wherever it lives. Only when no
+ * copy is on that line does the first one load — and the caller then warns, because that skew is
+ * exactly the breakage the user is about to see. An unknown core version (`latest`) keeps the old
+ * project-first order: there is no line to match against.
+ */
+export function pickDriverCopy(copies: readonly DriverCopy[], core: string, bundled: boolean): DriverCopy | undefined {
+  if (!copies.length) return undefined;
+  if (bundled && core !== 'latest') {
+    const lockstep = copies.find((c) => sameVersionLine(c.version, core));
+    if (lockstep) return lockstep;
+  }
+  return copies[0];
+}
+
+function readDriverVersion(req: NodeRequire, name: string, resolved: string): string | undefined {
+  // `<pkg>/package.json` is not always exported; fall back to walking up from the entry file.
+  try { return req(`${name}/package.json`)?.version; } catch { /* try the walk */ }
+  let dir = path.dirname(resolved);
+  for (let i = 0; i < 6; i++) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+      if (pkg?.name === name) return pkg.version;
+    } catch { /* keep walking */ }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return undefined;
+}
+
+/** The lockstep contract, in the user's terms, with the one command that restores it. */
+function versionSkewWarning(name: string, loaded: string | undefined, core: string, bypassed?: DriverCopy): string {
+  const fix = `  Fix: run \`sungen update\` in the project (or \`npm i ${name}@${core}\`) so every @sungen/driver-* matches sungen ${core}.`;
+  if (bypassed) {
+    return (
+      `⚠ sungen: the project holds "${name}" ${bypassed.version ?? '(unknown version)'} but sungen is ${core} — ` +
+      `loading core's own ${loaded ?? core} copy instead. The two are published in lockstep; a driver behind core misses ` +
+      `metadata core now requires (for the UI driver: every "is hidden"/"is disabled" clause fails SG-E021 on the pattern that should assert it).\n` + fix
+    );
+  }
+  return (
+    `⚠ sungen: "${name}" ${loaded ?? '(unknown version)'} is loaded against sungen ${core} — the two are published in lockstep, ` +
+    `and a driver on another version line misses metadata core requires (for the UI driver: every "is hidden"/"is disabled" ` +
+    `clause fails SG-E021 on the pattern that should assert it).\n` + fix
+  );
+}
+
 function loadExternalDriver(name: string): void {
-  // Resolve from the user's PROJECT first, then from core's own location. Opt-in drivers
-  // (`sungen capability add db|api`) install into the PROJECT's node_modules — a globally-installed
-  // core (`npm i -g`) wouldn't see them via a core-anchored `require`. The bundled @sungen/driver-ui
-  // is a core dependency (co-located with core), so the second anchor finds it.
-  for (const anchor of [path.join(process.cwd(), 'package.json'), __filename]) {
+  const bundled = BUNDLED_DRIVERS.has(name);
+  // Look from the user's PROJECT and from core's own location. Opt-in drivers (`sungen capability add
+  // db|api`) install into the PROJECT's node_modules — a globally-installed core (`npm i -g`) wouldn't
+  // see them via a core-anchored `require`. The bundled @sungen/driver-ui is a core dependency
+  // (co-located with core), so the second anchor always has a copy on core's version line.
+  const anchors: Array<[DriverCopy['anchor'], string]> = [
+    ['project', path.join(process.cwd(), 'package.json')],
+    ['core', __filename],
+  ];
+  const copies: DriverCopy[] = [];
+  const requires = new Map<string, NodeRequire>();
+  for (const [anchor, file] of anchors) {
     let req: NodeRequire;
-    try { req = createRequire(anchor); } catch { continue; }
+    try { req = createRequire(file); } catch { continue; }
     let resolved: string;
     try { resolved = req.resolve(name); } catch { continue; } // not installed at this anchor → try next
+    if (copies.some((c) => c.resolved === resolved)) continue; // one install seen from both anchors
+    requires.set(resolved, req);
+    copies.push({ anchor, resolved, version: readDriverVersion(req, name, resolved) });
+  }
+
+  const core = coreVersion();
+  const chosen = pickDriverCopy(copies, core, bundled);
+  if (chosen) {
+    if (core !== 'latest' && chosen.version && !sameVersionLine(chosen.version, core)) {
+      console.warn(versionSkewWarning(name, chosen.version, core));
+    } else if (bundled && chosen.anchor === 'core' && copies[0] !== chosen) {
+      // A stale project copy was bypassed. Loading the right one already fixed the compile; the line
+      // is there so the stale dependency gets cleaned up rather than lingering under every future run.
+      console.warn(versionSkewWarning(name, chosen.version, core, copies[0]));
+    }
     try {
-      const mod = req(resolved);
+      const mod = requires.get(chosen.resolved)!(chosen.resolved);
       const register: ((r: typeof capabilityRegistry) => void) | undefined = mod?.sungenDriver?.register ?? mod?.register;
       if (typeof register === 'function') register(capabilityRegistry);
     } catch (e) {
@@ -68,10 +169,10 @@ function loadExternalDriver(name: string): void {
         `  Fix: reinstall it (\`sungen capability add ${name.replace(/^@sungen\/driver-/, '')}\`) or remove it.`,
       );
     }
-    return; // found at this anchor (loaded or warned) — don't fall through to other anchors
+    return;
   }
   // Not resolvable at ANY anchor.
-  if (BUNDLED_DRIVERS.has(name)) {
+  if (bundled) {
     // A bundled default is missing → broken install, not a declined opt-in. Warn loudly so the user
     // sees the real cause instead of a wall of "Unrecognized step pattern".
     console.warn(
@@ -86,9 +187,44 @@ function loadExternalDriver(name: string): void {
   // Opt-in driver not installed — capabilities are opt-in, so skip silently.
 }
 
+/**
+ * Should this driver package load for the project's declared platform?
+ *
+ * Only an **opt-in platform** driver is gated. Three exclusions, each load-bearing:
+ *  - `kind: 'capability'` (api/db/mock/data-factory) is gated by its ANNOTATION TAG, not by
+ *    platform. Gating it here would break `@query`/`@api` on a project that legitimately has both.
+ *  - `bundled: true` (driver-ui) is the BASELINE vocabulary, not a platform choice. Mobile reuses
+ *    the whole web pattern set — click, fill, visibility — on the appium adapter, so skipping
+ *    driver-ui on a `platform: mobile` project would delete almost every step the suite uses.
+ *  - No `platform:` in `qa/capabilities.yaml` → load everything, exactly as before. A project that
+ *    predates the profile, and every `--framework`-override path, must keep working.
+ *
+ * A package the catalog does not know stays ungated: an unknown driver is not evidence of a
+ * platform mismatch, and silently dropping it would be the hardest failure here to diagnose.
+ */
+function servesPlatform(pkg: string, platform: string | undefined): boolean {
+  if (!platform) return true;
+  const meta = Object.values(loadDriverCatalog()).find((m) => m.package === pkg);
+  if (!meta || meta.kind !== 'platform' || meta.bundled) return true;
+  if (meta.id === platform) return true;
+  // Record what the gate dropped. SG-W001 needs it: without the driver's patterns in the registry a
+  // mobile-only step reads as "sungen has no step form for it", which is untrue — the form exists in
+  // a vocabulary this project declined. Recording the SKIP is the honest half; naming the step would
+  // need a static list that rots on the next pattern added.
+  capabilityRegistry.noteGatedDriver(pkg, meta.id, platform);
+  return false;
+}
+
 export function discoverAndRegisterCapabilities(): void {
   if (capabilityRegistry.isPopulated()) return;
-  for (const name of EXTERNAL_DRIVERS) loadExternalDriver(name); // ui (external) — first, default capability
+  // CG-1b — discovery never read the project's platform, so on a machine holding both drivers the
+  // mobile vocabulary was live on web projects and vice versa. `platforms:` on the patterns is what
+  // makes a cross-platform step FAIL WELL; this is what keeps it from being reachable at all.
+  const { platform } = readCapabilities(process.cwd());
+  for (const name of EXTERNAL_DRIVERS) {
+    if (!servesPlatform(name, platform)) continue;
+    loadExternalDriver(name); // ui (external) — first, default capability
+  }
   for (const driver of LOCAL_DRIVERS) driver.register(capabilityRegistry); // db, api (in-core for now)
   registerCoreCapability(capabilityRegistry); // generic layer, always present, registered last
 }

package/src/capabilities/registry.ts

@@ -76,6 +76,10 @@ export interface CapabilityDescriptor {
 
 export class CapabilityRegistry {
   private caps = new Map<string, CapabilityDescriptor>();
+  /** package → the platform it serves, for drivers the platform gate skipped. See `noteGatedDriver`. */
+  private gated = new Map<string, string>();
+  /** The project platform those skips were made FOR — the same value for every entry in `gated`. */
+  private gatedFor: string | undefined;
 
   /** Register (or replace, by id) a capability descriptor. Idempotent by id. */
   register(descriptor: CapabilityDescriptor): void {
@@ -116,9 +120,35 @@ export class CapabilityRegistry {
     return kind ? all.filter((s) => s.kind === kind) : all;
   }
 
+  /**
+   * Record a driver discovery SKIPPED because it does not serve the project's platform.
+   *
+   * Gating removes the driver's patterns from the registry, which is the point — but it also means
+   * a step belonging to that driver reaches SG-W001 ("sungen has no step form for it") instead of
+   * SG-W020 ("this step is mobile-only"). SG-W001's sentence is then false. This is the only fact
+   * available to correct it: patterns were never loaded, so what was skipped is knowable and which
+   * step it owned is not.
+   */
+  noteGatedDriver(pkg: string, serves: string, projectPlatform: string): void {
+    this.gated.set(pkg, serves);
+    this.gatedFor = projectPlatform;
+  }
+
+  /** Drivers skipped by the platform gate, as `[package, platform it serves]`. Empty when nothing was gated. */
+  gatedDrivers(): Array<[string, string]> {
+    return [...this.gated.entries()];
+  }
+
+  /** The project platform the gate applied, or undefined when nothing was gated. */
+  gatedForPlatform(): string | undefined {
+    return this.gatedFor;
+  }
+
   /** Test seam: drop all registrations. */
   _reset(): void {
     this.caps.clear();
+    this.gated.clear();
+    this.gatedFor = undefined;
   }
 }
 

package/src/cli/commands/audit.ts

@@ -92,6 +92,15 @@ function render(r: AuditReport): void {
   for (const c of r.duplicates.clusters.slice(0, 3)) {
     L(`      ${c.sameDataLikely ? '✗ exact' : '○ EP/data family'} (${c.scenarios.length}): ${c.scenarios.slice(0, 3).join(' | ')}${c.scenarios.length > 3 ? ' …' : ''}`);
   }
+  // #694 — printed under the duplicate axis because that is where a reader looks for it, but it
+  // is a DIFFERENT signal: ⑤ clusters identical steps, this catches one id on distinct scenarios.
+  // Marked BLOCKING inline so a red build states its cause without scrolling to the findings.
+  if (r.reusedScenarioIds.length > 0) {
+    L(`      ✗ BLOCKING — ${r.reusedScenarioIds.length} reused scenario id(s): a shared id ships as several deliverable rows under ONE testcase id`);
+    for (const d of r.reusedScenarioIds.slice(0, 3)) {
+      L(`        ${d.id} ×${d.count}${d.file ? ` in ${d.file}` : ''}: ${d.titles.slice(0, 2).join(' | ')}${d.titles.length > 2 ? ' …' : ''}`);
+    }
+  }
   L('');
   L(`  ⑥ Traceability — ${(r.trace.mappedRatio * 100).toFixed(0)}% scenarios linked to viewpoint-overview`);
   L(`      ${r.trace.note}`);

package/src/cli/commands/capability.ts

@@ -98,7 +98,7 @@ export function registerCapabilityCommand(program: Command): void {
   // ── plan (Planner — recommend-only, no install) ──────────────────────────
   cap
     .command('plan')
-    .description('Capability Planner: classify execution modes + @manual reasons (M1–M9) + recommend drivers (no install)')
+    .description('Capability Planner: classify execution modes + @manual reasons (M1–M11) + recommend drivers (no install)')
     .requiredOption('-s, --screen <name>', 'Screen or flow name')
     .option('--json', 'Output the raw plan JSON')
     .action((o: { screen: string; json?: boolean }) => {