@sun-asterisk/sungen 3.2.0 → 3.2.1-beta.1

package/src/generators/test-generator/adapters/appium/templates/test-file.hbs

@@ -0,0 +1,226 @@
+{{#if platform}}
+// sungen:platform={{platform}}
+{{/if}}
+{{#if runtimeData}}
+
+const testData = TestDataLoader.load('{{screenName}}', '{{featureFileName}}');
+{{/if}}
+{{#if singleAuthRole}}
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+// ── @auth (mobile) ──────────────────────────────────────────────────────────
+// App-agnostic auth: the framework supplies the MECHANISM; each app supplies the DATA via a
+// gitignored contract at specs/.auth-mobile/<role>.json:
+//   { "authedMarker": {type,value},                 // present ⟺ already logged in
+//     "credentials": { ... },                        // referenced as {{key}} in step values
+//     "loginSteps": [ {action:"tap"|"fill"|"wait", selector:{type,value}, value?} ] }
+// ensureAuth is idempotent (skips when already logged in) and fail-loud (throws → the @auth spec is
+// blocked, never silently run logged-out). See MOBILE_INTEGRATION_PLAN.md §Phase 5.1.
+function __authSelector(s: { type: string; value: string }): string {
+  switch (s.type) {
+    case 'accessibility-id': case 'testid': case 'label': case 'placeholder': case 'text': return '~' + s.value;
+    case 'android-uiautomator': return 'android=' + s.value;
+    case 'ios-predicate': return '-ios predicate string:' + s.value;
+    case 'id': return 'id=' + s.value;
+    case 'xpath': case 'locator': default: return s.value;
+  }
+}
+function __authInterpolate(v: string, creds: Record<string, unknown> = {}): string {
+  return String(v).replace(/\{\{\s*(\w+)\s*\}\}/g, (_m, k) => (creds[k] != null ? String(creds[k]) : ''));
+}
+// Robust mobile text entry: Flutter often ignores a single setValue, and W3C key-streams can drop a
+// char — so we type, read back, and retry once. Masked (password) fields can't be verified → trusted.
+async function __robustFill(el: WebdriverIO.Element, value: string): Promise<void> {
+  await el.click();
+  try { await el.clearValue(); } catch { /* not clearable */ }
+  await el.setValue(value);
+  let got = '';
+  try { got = (await el.getText()) || (await el.getAttribute('text')) || ''; } catch { /* ignore */ }
+  const masked = /[•●*]/.test(got);
+  if (!masked && got.replace(/\s/g, '') !== value.replace(/\s/g, '')) {
+    try { await el.clearValue(); } catch { /* ignore */ }
+    await el.addValue(value);
+  }
+}
+async function __ensureAuth(role: string): Promise<void> {
+  const cfgPath = path.join(process.cwd(), 'specs', '.auth-mobile', role + '.json');
+  const rel = path.relative(process.cwd(), cfgPath);
+  if (!fs.existsSync(cfgPath)) {
+    throw new Error(`@auth:${role} requires ${rel} (loginSteps + credentials + a login-state marker). See MOBILE_INTEGRATION_PLAN.md §Phase 5.1.`);
+  }
+  const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
+  const present = async (marker: { type: string; value: string } | undefined, timeout = 6000): Promise<boolean> => {
+    if (!marker) return false;
+    try { await $(__authSelector(marker)).waitForDisplayed({ timeout }); return true; }
+    catch { return false; }
+  };
+  const absent = async (marker: { type: string; value: string } | undefined, timeout = 8000): Promise<boolean> => {
+    if (!marker) return true;
+    try { await $(__authSelector(marker)).waitForDisplayed({ reverse: true, timeout }); return true; }
+    catch { return false; }
+  };
+  const runSteps = async (steps: any[]): Promise<void> => {
+    for (const step of (steps || [])) {
+      // Selector-less actions first (no element to find).
+      if (step.action === 'hideKeyboard') { try { await driver.hideKeyboard(); } catch { /* no keyboard shown */ } continue; }
+      if (step.action === 'back') { try { await driver.back(); } catch { /* nothing to dismiss */ } continue; }
+      const el = await $(__authSelector(step.selector));
+      await el.waitForDisplayed();
+      if (step.action === 'fill') await __robustFill(el, __authInterpolate(step.value, cfg.credentials));
+      else if (step.action === 'tap') await el.click();
+      // 'wait' = just the waitForDisplayed above
+    }
+  };
+
+  // ── Mode A: navigation-based (preferred) ──────────────────────────────────
+  // For apps whose login state is NOT visible on the post-relaunch landing screen (e.g. a Flutter
+  // app that always opens on Home). We navigate to a DECISION screen (loginEntrySteps, e.g. My Page
+  // → Account Settings) and read `loggedOutMarker` there (present ⟺ logged out, e.g. the Login
+  // button). loginSteps then start FROM that decision screen.
+  if (cfg.loginEntrySteps && cfg.loggedOutMarker) {
+    await runSteps(cfg.loginEntrySteps);
+    if (!(await present(cfg.loggedOutMarker, 8000))) return; // logged-out marker absent ⟹ already logged in (noReset)
+    await runSteps(cfg.loginSteps);
+    // Verify: a credentials error means rejection; the login form staying put (logged-out marker
+    // never disappears) means it didn't submit. Success = the form navigated away with no error.
+    if (await present(cfg.errorMarker, 3000)) {
+      throw new Error(`@auth:${role} login rejected (error shown) — check credentials.email/password in ${rel}.`);
+    }
+    if (!(await absent(cfg.loggedOutMarker, 8000))) {
+      throw new Error(`@auth:${role} login did not complete (still on the login screen) — check loginSteps in ${rel}.`);
+    }
+    return;
+  }
+
+  // ── Mode B: legacy authedMarker (present on the landing screen ⟺ logged in) ──
+  const markerPresent = async (): Promise<boolean> => present(cfg.authedMarker, 6000);
+  if (await markerPresent()) return; // idempotent — already authenticated (session kept by noReset)
+  await runSteps(cfg.loginSteps);
+  if (!(await markerPresent())) {
+    throw new Error(`@auth:${role} login failed — verify credentials / loginSteps / authedMarker in ${rel}.`);
+  }
+}
+{{/if}}
+
+{{#if featureDescription}}
+/**
+ * Feature: {{featureName}}
+ * {{featureDescription}}
+ */
+{{/if}}
+describe('{{featureName}}', () => {
+{{#if singleAuthRole}}
+  // @auth:{{singleAuthRole}} — authenticate ONCE before any scenario; the session persists across
+  // the per-scenario relaunch below (noReset:true). Throws (blocks the spec) if login can't be done.
+  before(async () => {
+{{#if appPackage}}
+    // Relaunch to a known launch screen first — the session may attach to the app in any state.
+    // Platform-aware id (NOT the Android literal): on iOS a @platform:mobile feature's app is the
+    // dual-id bundle id — a literal appPackage here would throw and block the whole spec.
+    // (__resolveAppId is a hoisted function declaration in this describe scope.)
+    const __AUTH_APP__ = __resolveAppId();
+    try { await driver.terminateApp(__AUTH_APP__); } catch { /* not running */ }
+    await driver.activateApp(__AUTH_APP__);
+{{/if}}
+    await __ensureAuth('{{singleAuthRole}}');
+  });
+
+{{/if}}
+{{#if appPackage}}
+  // Multi-app: this feature's app (from the `Path:` line). Reset to its launch screen before each
+  // scenario so one `wdio run` can host screens from different apps — each spec launches its own.
+  // The `Path:` holds the ANDROID package (or, for an @platform:ios feature, the iOS bundle id).
+  const __APP_PKG_DEFAULT__ = '{{appPackage}}';
+{{#if iosBundleId}}
+  // Per-feature iOS bundle id from the dual-id `Path: <androidPkg>/<activity> | <iosBundleId>` —
+  // app ids differ per OS (e.g. an iOS `.dev` flavor), and keeping it in the feature file makes the
+  // spec self-describing + lets one iOS run host multiple apps.
+  const __IOS_BUNDLE__ = '{{iosBundleId}}';
+{{/if}}
+  // Platform-aware app id: an @platform:mobile spec runs on BOTH OSes. On iOS prefer the feature's own
+  // bundle id (dual-id Path), then the session cap (IOS_BUNDLE_ID in wdio.conf), then the Path value;
+  // on Android (or any non-iOS session) use the Path package unchanged.
+  function __resolveAppId(): string {
+    if (typeof driver !== 'undefined' && driver.isIOS) {
+      const caps = (driver.requestedCapabilities || {}) as Record<string, string>;
+      return {{#if iosBundleId}}__IOS_BUNDLE__ || {{/if}}caps['appium:bundleId'] || caps['bundleId'] || __APP_PKG_DEFAULT__;
+    }
+    return __APP_PKG_DEFAULT__;
+  }
+  beforeEach(async () => {
+    const __APP_PKG__ = __resolveAppId();
+    try { await driver.terminateApp(__APP_PKG__); } catch { /* app may not be running yet */ }
+    await driver.activateApp(__APP_PKG__);
+    // Settle after a cold (re)launch: a Flutter app first renders a BLANK accessibility skeleton
+    // (nested FrameLayout/View, no content-desc) for several seconds before the real tree appears.
+    // That skeleton is static, so a "two equal reads" check alone false-positives on it and we'd
+    // proceed before any element exists (→ every find fails). So require the tree to (a) contain
+    // rendered content — at least one non-empty content-desc/text — AND (b) be stable across two
+    // reads. A generous timeout covers slow cold renders on a stressed emulator. Best-effort: a
+    // timeout never fails the scenario, it just falls through to the step's own auto-wait.
+    let __prevSrc = '';
+    await driver
+      .waitUntil(
+        async () => {
+          const src = await driver.getPageSource();
+          const hasContent = /content-desc="[^"]+"|\btext="[^"]+"/.test(src);
+          const stable = hasContent && src === __prevSrc;
+          __prevSrc = src;
+          return stable;
+        },
+        { timeout: 30000, interval: 400, timeoutMsg: 'UI did not settle (no rendered content)' },
+      )
+      .catch(() => { /* best-effort — fall through to per-step auto-wait */ });
+{{#if backgroundSteps}}
+    // Background runs here (inside beforeEach) — the app resets to its launch screen every scenario,
+    // so Background setup (nav, dismiss launch promos…) must re-run after each relaunch, not once.
+{{#each backgroundSteps}}
+{{#if comment}}
+    // {{comment}}
+{{/if}}
+{{code}}
+{{/each}}
+{{/if}}
+  });
+
+{{/if}}
+{{#unless appPackage}}
+{{#if backgroundSteps}}
+  before(async () => {
+{{#each backgroundSteps}}
+{{#if comment}}
+    // {{comment}}
+{{/if}}
+{{code}}
+{{/each}}
+  });
+
+{{/if}}
+{{/unless}}
+{{#if beforeAll}}
+{{beforeAll}}
+
+{{/if}}
+{{#if afterEach}}
+{{afterEach}}
+
+{{/if}}
+{{#if afterAll}}
+{{afterAll}}
+
+{{/if}}
+{{#if authGroups}}
+{{#each authGroups}}
+{{#each scenarios}}
+{{this}}
+
+{{/each}}
+{{/each}}
+{{else}}
+{{#each scenarios}}
+{{this}}
+
+{{/each}}
+{{/if}}
+});

package/src/generators/test-generator/adapters/index.ts

@@ -1,12 +1,19 @@
 export { TestGeneratorAdapter, TestFileData, ScenarioData, StepTemplateData, LocatorExpression } from './adapter-interface';
 export { AdapterRegistry, adapterRegistry, DriverNotInstalledError } from './adapter-registry';
 export { PlaywrightAdapter } from './playwright/playwright-adapter';
+export { AppiumAdapter } from './appium/appium-adapter';
 
 // Auto-register built-in adapters
 import { adapterRegistry } from './adapter-registry';
 import { PlaywrightAdapter } from './playwright/playwright-adapter';
+import { AppiumAdapter } from './appium/appium-adapter';
 
 adapterRegistry.register('playwright', () => new PlaywrightAdapter());
 // Phase 2a: platform alias. `web` is the bundled Playwright adapter (back-compat
 // baseline) until it is externalized to @sungen/driver-web in a later cut.
 adapterRegistry.register('web', () => new PlaywrightAdapter());
+// MOB-2: the Appium codegen adapter — template strings only, NO appium/wdio dep in core.
+// `platform: mobile` (qa/capabilities.yaml) loads @sungen/driver-mobile (the SPI capability)
+// and selects this adapter (the runtime codegen). `appium` is the explicit alias.
+adapterRegistry.register('mobile', () => new AppiumAdapter());
+adapterRegistry.register('appium', () => new AppiumAdapter());

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

@@ -76,7 +76,7 @@ function extractCleanupFlags(tags: string[]): { overlay?: boolean; forms?: boole
 const FUNCTIONAL_TAG_PREFIXES = [
   '@parallel', '@cleanup:', '@auth:', '@manual', '@no-auth',
   '@steps:', '@extend:', '@screenshot:', '@beforeAll', '@afterEach', '@afterAll',
-  '@flow', '@cases:',
+  '@flow', '@cases:', '@deferred:', '@owned-by:',
 ];
 
 function extractPassThroughTags(scenarioTags: string[], featureTags: string[]): string | undefined {
@@ -173,7 +173,8 @@ function getEffectiveAuthRole(
  * @manual at scenario level → skip that scenario
  */
 function isManual(tags: string[]): boolean {
-  return tags.some(tag => tag === '@manual');
+  // @deferred:flow is owned by a flow → not automated on this screen, so it skips like @manual (H6).
+  return tags.some(tag => tag === '@manual' || tag === '@deferred:flow');
 }
 
 /**

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

@@ -1,9 +1,9 @@
 import { ParsedStep } from '../gherkin-parser';
 import { TemplateEngine } from './template-engine';
+import { adapterRegistry } from './adapters';
 import { PatternRegistry, PatternContext } from './patterns';
 import { SelectorResolver } from './utils/selector-resolver';
 import { DataResolver } from './utils/data-resolver';
-import * as path from 'path';
 
 export interface MappedStep {
   code: string; // Generated Playwright code
@@ -35,15 +35,18 @@ export class StepMapper {
   private inRowScope: boolean = false;
   private rowScopeTable: string = '';
 
-  constructor(options: { verbose?: boolean; baseURL?: string; featureName?: string; screenName?: string; featurePath?: string; runtimeData?: boolean } = {}) {
+  constructor(options: { verbose?: boolean; baseURL?: string; featureName?: string; screenName?: string; featurePath?: string; runtimeData?: boolean; framework?: string } = {}) {
     this.verbose = options.verbose ?? false;
     this.baseURL = options.baseURL || null;  // null means path-only navigation
     this.featureName = options.featureName;
     this.screenName = options.screenName;
     this.featurePath = options.featurePath;
-    // Use Playwright templates as default for pattern-based generation
-    const playwrightTemplatesDir = path.join(__dirname, 'adapters', 'playwright', 'templates');
-    this.templateEngine = new TemplateEngine(playwrightTemplatesDir);
+    // Render step templates from the ACTIVE adapter's template set (web→Playwright,
+    // mobile→Appium). The adapter owns its templatesDir; resolving it here keeps step
+    // rendering and the file skeleton (code-generator) on the same framework.
+    const framework = options.framework || 'web';
+    const templatesDir = adapterRegistry.getAdapter(framework).templatesDir;
+    this.templateEngine = new TemplateEngine(templatesDir);
     this.patternRegistry = new PatternRegistry();
     this.selectorResolver = new SelectorResolver(undefined, options.screenName);
     this.dataResolver = new DataResolver(undefined, options.screenName, options.runtimeData);

package/src/generators/test-generator/template-engine.ts

@@ -168,6 +168,18 @@ export class TemplateEngine {
       const dialogRootContent = fs.readFileSync(dialogRootPath, 'utf-8');
       Handlebars.registerPartial('dialog-root', dialogRootContent);
     }
+
+    // Adapter-agnostic: register any OTHER top-level partial in partials/ by its basename
+    // (the named registrations above are playwright's; the appium adapter ships
+    // appium-selector / appium-selector-expr). Idempotent — re-registering by name is harmless.
+    const partialsDir = path.join(this.stepsTemplatesDir, 'partials');
+    if (fs.existsSync(partialsDir)) {
+      for (const f of fs.readdirSync(partialsDir)) {
+        if (!f.endsWith('.hbs')) continue;
+        const name = f.replace(/\.hbs$/, '');
+        Handlebars.registerPartial(name, fs.readFileSync(path.join(partialsDir, f), 'utf-8'));
+      }
+    }
   }
 
   private loadTemplate(templateName: string, isStepTemplate: boolean = false): HandlebarsTemplateDelegate {
@@ -179,7 +191,7 @@ export class TemplateEngine {
     
     // Try to find template in organized folders
     if (isStepTemplate) {
-      const folders = ['actions', 'assertions', 'navigation', 'setup', 'partials'];
+      const folders = ['actions', 'assertions', 'navigation', 'setup', 'gestures', 'partials'];
       
       for (const folder of folders) {
         const templatePath = path.join(baseDir, folder, `${templateName}.hbs`);

package/src/harness/audit.ts

@@ -12,8 +12,8 @@ import { loadScenarios, parseViewpointOverview, ScenarioInfo, ViewpointEntry } f
 import { featureBasename } from './unit-paths';
 import {
   loadCatalog, viewpointGate, assertionDepth, dataThemesFor, depthThresholdFor, coverageBalance, duplicateClusters, traceability, claimProof, taxonomyLint,
-  automatableManual, flowCoveredThemes,
-  GateResult, DepthResult, BalanceResult, DuplicateResult, TraceResult, ClaimProofResult, TaxonomyResult, Catalog, AutomatableManualResult,
+  automatableManual, flowCoveredThemes, flowRegressionDepth, oracleStrength,
+  GateResult, DepthResult, BalanceResult, DuplicateResult, TraceResult, ClaimProofResult, TaxonomyResult, Catalog, AutomatableManualResult, FlowDepthResult, OracleStrengthResult,
 } from './sensors';
 import { loadFlowScenarios } from './flow-check';
 import { manualReasonMismatches, MANUAL_REASONS, buildPlan } from './capability-plan';
@@ -22,7 +22,7 @@ import { readIntent, projectRootFromScreenDir, IntentProfile } from './intent';
 import { getProvenance, Provenance } from './provenance';
 import { specCoverage, SpecCoverageResult, parseSpecClauses } from './spec-coverage';
 import { downstreamScope, manualOracle, readText, DownstreamResult, ManualOracleResult,
-  negativeSideEffect, sourceBacked, crossArtifactOwnership } from './quality-gates';
+  negativeSideEffect, sourceBacked, crossArtifactOwnership, isolationRisk } from './quality-gates';
 import { viewpointLedger, parseViewpointItems, LedgerResult } from './viewpoint-ledger';
 import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
@@ -42,6 +42,8 @@ export interface AuditReport {
   downstream: DownstreamResult; // downstream screens referenced but under-covered
   manualOracle: ManualOracleResult; // @manual scenarios lacking setup/action/oracle
   automatableManual: AutomatableManualResult; // @manual that is actually automatable (deferred, not judgment) — TQ-2
+  flowDepth: FlowDepthResult;   // H3 — stateful-flow regression depth (count / teardown / multi-source)
+  oracle: OracleStrengthResult; // H4 — facet-oracle strength (weak name-substring vs title/detail/API/DB)
   ledger: LedgerResult;         // atomic viewpoint-item coverage (per-bullet status)
   calibration: {                // #8 — multi-axis score so a high overall can't hide a weak axis
     axes: Record<string, number>;
@@ -81,9 +83,28 @@ function catalogIdFromScreenDir(screenDir: string): string {
  * future `mobile/<x>` or `perf/<x>` unit routes to that capability with no core change. `flows/<flow>`
  * has no `flows` capability → default (UI), which is correct (flows are a UI concept).
  */
-export function scoringCapabilityFor(catalogScreenName: string, defaultCap: string | undefined): string | undefined {
+export function scoringCapabilityFor(catalogScreenName: string, defaultCap: string | undefined, platform?: string): string | undefined {
   const seg = catalogScreenName.split('/')[0];
-  return seg && capabilityRegistry.get(seg) ? seg : defaultCap;
+  // Path segment wins (api/<area> → api). Then the active platform capability (mobile → mobile),
+  // when a driver registered one with that id. Else the default (web/bare screen → ui — unchanged,
+  // since `web` has no capability of its own). See docs/spec/sungen-platform-capability-routing-spec.md.
+  if (seg && capabilityRegistry.get(seg)) return seg;
+  if (platform && capabilityRegistry.get(platform)) return platform;
+  return defaultCap;
+}
+
+/**
+ * H7 — senior-grade band. The top decile (≥9) is reserved for suites that ALSO clear the senior
+ * axes: a stateful flow with FULL regression depth (count + teardown + multi-source), no weak facet
+ * oracle, and no parallel-cart isolation risk. Otherwise the score is held just below 9 (8.9), so
+ * "≥9" means senior-grade — not merely "themes covered". Neutral for screens/api (no signals → 10).
+ */
+export function seniorBandedOverall(
+  rawOverall: number,
+  s: { flowStateful: boolean; flowRatio: number; oracleWeak: number; isolationRisk: boolean },
+): number {
+  const seniorGrade = (!s.flowStateful || s.flowRatio >= 1) && s.oracleWeak === 0 && !s.isolationRisk;
+  return Math.min(rawOverall, seniorGrade ? 10 : 8.9);
 }
 
 export function runAudit(screenDir: string, screenName: string): AuditReport {
@@ -106,8 +127,11 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // UI capability). A capability that provides no catalog/gate falls back to the in-core UI
   // functions, so UI units — and api units until AO-2 adds the api providers — are byte-identical.
   discoverAndRegisterCapabilities();
+  // The active platform (web | mobile | …) activates its own capability for scoring + sensor routing.
+  // `web` has no capability of its own → scoringCap stays the default `ui` (byte-identical).
+  const platform = readCapabilities(projectRootFromScreenDir(screenDir)).platform;
   const defaultCap = capabilityRegistry.defaultCapabilityId();
-  const scoringCapId = scoringCapabilityFor(catalogScreenName, defaultCap);
+  const scoringCapId = scoringCapabilityFor(catalogScreenName, defaultCap, platform);
   const scoringCap = scoringCapId ? capabilityRegistry.get(scoringCapId) : undefined;
   const catalog = (scoringCap?.viewpoints?.() as Catalog | undefined) || loadCatalog();
   const spec = specCoverage(specPath, scenarios, featureText);
@@ -157,16 +181,43 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const ownership = crossArtifactOwnership(screenDir, scenarios);
   const unsourced = sourceBacked(scenarios, parseSpecClauses(specPath).frs.map((f) => f.id), parseViewpointItems(viewpointPath).map((i) => i.text), viewpoints.map((v) => v.id), featureText);
 
+  // H3 — stateful-flow regression depth. For a UI flow whose scenarios mutate a cart/checkout
+  // collection, the regression dimensions (count/quantity proof · teardown · multi-source) cap the
+  // businessDepth headroom: it can reach 1.0 only when all three are exercised, so a present-but-
+  // shallow flow can't claim a perfect score (floor 0.5 — assertion depth still dominates).
+  const isUiFlow = /^flows\//.test(catalogScreenName);
+  const flowDepth = isUiFlow ? flowRegressionDepth(scenarios) : { stateful: false, countProof: false, teardown: false, multiSource: false, ratio: 1, missing: [] } as FlowDepthResult;
+  const FLOW_DEPTH_FLOOR = 0.5;
+  // H4 — oracle strength: a weak facet oracle (name-substring "proves" category/brand membership)
+  // caps businessDepth the same way (floor 0.5). A suite with no facet claim, or a strong oracle, is
+  // neutral (ratio 1 → no cap), so existing snapshots are unaffected.
+  const oracle = oracleStrength(scenarios);
+  const ORACLE_FLOOR = 0.5;
+
   // Sub-scores
   const coverage = gate.coverageRatio;
-  const businessDepth = depth.bcDepthRatio;
-  const balanceScore = balance.coreCount + balance.secondaryCount > 0
-    ? Math.min(1, balance.coreCount / Math.max(1, balance.secondaryCount))
-    : 1;
+  const businessDepth = 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,
+  );
+  // 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
+    ? 0.5
+    : balance.coreCount + balance.secondaryCount > 0
+      ? Math.min(1, balance.coreCount / Math.max(1, balance.secondaryCount))
+      : 1;
   const traceScore = 0.5 * trace.withVpCodeRatio + 0.5 * trace.mappedRatio;
 
   // Business-weighted overall (coverage + depth dominate)
-  const overall = (0.4 * coverage + 0.3 * businessDepth + 0.15 * balanceScore + 0.15 * traceScore) * 10;
+  const rawOverall = (0.4 * coverage + 0.3 * businessDepth + 0.15 * balanceScore + 0.15 * traceScore) * 10;
+  // H7 — senior-grade band: the top decile (≥9) is reserved for suites that also clear the senior
+  // axes — a stateful flow with FULL regression depth (count + teardown + multi-source), no weak
+  // facet oracle, and no parallel-cart isolation risk. Otherwise the score is held just below 9, so
+  // "≥9" means senior-grade, not merely "themes covered". Neutral for screens/api (no signals).
+  const isoRisk = isolationRisk(featureText, flowDepth.stateful);
+  const overall = seniorBandedOverall(rawOverall, { flowStateful: flowDepth.stateful, flowRatio: flowDepth.ratio, oracleWeak: oracle.weak.length, isolationRisk: isoRisk });
 
   const findings: string[] = [];
   for (const c of flowCredits) {
@@ -187,6 +238,23 @@ 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
+  // (@cleanup:cart / @isolate / a "Given … empty cart" background / fresh context).
+  if (isoRisk) {
+    findings.push('ISOLATION-RISK: this @parallel flow mutates the cart but has no per-scenario isolation → cart/count/quantity asserts can go flaky when scenarios share state. Add `@cleanup:cart` (or `@isolate`, or a `Given User has an empty cart` background) so each scenario starts clean.');
+  }
+  if (flowDepth.stateful && flowDepth.missing.length) {
+    const how: Record<string, string> = {
+      'count-proof': 'assert the cart ROW COUNT / item QUANTITY (e.g. `... table with {{two_rows}}`, `Quantity column with {{qty}}`), not just the row presence',
+      'teardown': 'add a REMOVE/clear scenario that returns the cart to its empty state (the inverse operation)',
+      'multi-source': 'add to the cart from EVERY source on the page (the main list AND the recommended/related rail), not just one',
+    };
+    findings.push(`FLOW-DEPTH: this stateful flow exercises ${3 - flowDepth.missing.length}/3 regression dimensions — missing [${flowDepth.missing.join(', ')}] → ${flowDepth.missing.map((m) => how[m]).join('; ')}. (businessDepth is capped until covered.)`);
+  }
+  for (const w of oracle.weak) {
+    findings.push(`ORACLE-WEAK: "${w.name}" — ${w.hint}`);
+  }
   for (const u of claim.unproven) {
     const tag = u.severity === 'fail' ? 'CLAIM-UNPROVEN' : 'CLAIM-WEAK';
     findings.push(`${tag}: "${u.name}" — title claims [${u.claim}] but steps lack ${u.need}. ${u.hint}`);
@@ -194,7 +262,9 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   for (const m of taxonomy.mislabeled) {
     findings.push(`VP-MISLABEL: "${m.name}" is coded VP-${m.current} but reads as ${m.suggested} (signal: "${m.signal}") → re-tag VP-${m.suggested}-NNN so the coverage matrix isn't skewed.`);
   }
-  if (balance.imbalanced) {
+  if (balance.unclassifiedRatio > 0.4) {
+    findings.push(`TAXONOMY-UNCLASSIFIED: ${balance.note} → align the VP-<CATEGORY> codes with the catalog (or extend the bucket keywords) so coverage-balance is meaningful.`);
+  } else if (balance.imbalanced) {
     findings.push(`BALANCE: ${balance.note} Stop expanding secondary viewpoints until business-core gaps are filled.`);
   }
   if (trace.mappedRatio < 0.5) {
@@ -273,7 +343,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     ...(scenarios.some((s) => s.queryRefs && s.queryRefs.length) ? ['@query'] : []),
     ...(scenarios.some((s) => s.apiRefs && s.apiRefs.length) ? ['@api'] : []),
   ];
-  const routedGateIds = contextRouter.route({ target: { kind: 'screen', id: screenName }, artifact: 'feature', tags: featureTags }).gateSensorIds;
+  const routedGateIds = contextRouter.route({ target: { kind: 'screen', id: screenName }, artifact: 'feature', tags: featureTags, platform }).gateSensorIds;
   const gateSensorFindings = capabilityRegistry.sensors('gate')
     .filter((s) => routedGateIds.includes(s.id))
     .flatMap((s) => s.run({ screenName: catalogScreenName, cwd: projectRootFromScreenDir(screenDir), featureText, scenarios, universalGaps: gate.universalGaps }));
@@ -315,7 +385,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     screen: screenName,
     scenarioCount: scenarios.length,
     gate, depth, claim, taxonomy, balance, duplicates, trace, spec,
-    taxonomyMismatch, downstream, manualOracle: manualOracleResult, automatableManual: autoManual, ledger, calibration,
+    taxonomyMismatch, downstream, manualOracle: manualOracleResult, automatableManual: autoManual, flowDepth, oracle, ledger, calibration,
     score: {
       overall: Math.round(overall * 10) / 10,
       coverage: Math.round(coverage * 100) / 100,

package/src/harness/capability-plan.ts

@@ -56,7 +56,7 @@ export function classifyReason(text: string): string {
   return '';
 }
 
-interface ParsedScenario { name: string; tags: string[]; manual: boolean; reason: string }
+interface ParsedScenario { name: string; tags: string[]; manual: boolean; reason: string; deferredToFlow: boolean; ownedBy?: string }
 
 /** Parse scenarios with their tags + the reason comment line above (for @manual). */
 export function parseScenarios(featurePath: string): ParsedScenario[] {
@@ -84,7 +84,10 @@ export function parseScenarios(featurePath: string): ParsedScenario[] {
       else if (l === '') continue;
       else break; // a real step → stop
     }
-    out.push({ name: m[1].trim(), tags, manual: tags.some((t) => /^@manual\b/i.test(t)), reason });
+    const deferredToFlow = tags.some((t) => /^@deferred:flow$/i.test(t));
+    const ownedBy = (tags.find((t) => /^@owned-by:/i.test(t)) || '').slice('@owned-by:'.length) || undefined;
+    // @deferred:flow accounts like @manual on the screen (owned by a flow, not automated here) (H6).
+    out.push({ name: m[1].trim(), tags, manual: tags.some((t) => /^@manual\b/i.test(t)) || deferredToFlow, reason, deferredToFlow, ownedBy });
   }
   return out;
 }

package/src/harness/catalog/drivers.yaml

@@ -31,7 +31,7 @@ drivers:
   mobile:
     kind: platform
     package: "@sungen/driver-mobile"
-    status: planned                     # PoC on the feat/mobile branch (Appium / Flutter)
+    status: shipped                     # @sungen/driver-mobile — Appium/WebdriverIO, gesture steps + web-parity gate
     runtime: appium
     adapter: mobile
     capabilities: ["@ui"]

package/src/harness/flow-check.ts

@@ -74,14 +74,23 @@ export function buildFlowCheck(cwd: string, onlyFlow?: string): FlowCheckReport
   const deferrals: Deferral[] = [];
   for (const sc of screens) {
     for (const s of parseScenarios(featurePath(cwd, 'screens', sc))) {
-      if (!s.manual || !/deferred to a flow/i.test(s.reason)) continue;
-      const targets = targetsFromHint(s.reason);
-      const matches = flowScenarios.filter((fs2) => targets.some((t) => fs2.haystack.includes(t)));
+      // A deferral is the first-class `@deferred:flow` tag (H6) OR the legacy `@manual` + a
+      // "deferred to a flow" comment (back-compat). Either marks a cross-screen case owned by a flow.
+      const isDeferral = s.deferredToFlow || (s.manual && /deferred to a flow/i.test(s.reason));
+      if (!isDeferral) continue;
+      // Targets come from the comment hint; a tag-only @deferred:flow (no comment) falls back to the
+      // scenario TITLE so the covering flow scenario can still be located.
+      const targets = targetsFromHint([s.reason, s.name].join(' '));
+      // `@owned-by:<flow>` names the owner explicitly → only that flow's scenarios can cover it
+      // (a false @owned-by is then surfaced as missing). Else any flow may cover it (legacy).
+      const pool = s.ownedBy ? flowScenarios.filter((fs2) => fs2.flow === s.ownedBy) : flowScenarios;
+      const matches = pool.filter((fs2) => targets.some((t) => fs2.haystack.includes(t)));
       let verdict: Deferral['verdict'] = 'missing';
       let via: string | undefined;
       if (matches.some((m) => m.deep)) { verdict = 'covered'; via = matches.find((m) => m.deep)!.flow; }
       else if (matches.length) { verdict = 'shallow'; via = matches[0].flow; }
-      deferrals.push({ screen: sc, scenario: s.name, hint: s.reason, targets, verdict, via });
+      const hint = s.ownedBy ? `${s.reason || 'deferred to a flow'} (owned-by: ${s.ownedBy})` : s.reason;
+      deferrals.push({ screen: sc, scenario: s.name, hint, targets, verdict, via });
     }
   }
 

package/src/harness/parse.ts

@@ -34,6 +34,8 @@ export interface ScenarioInfo {
   queryRefs?: string[];       // named queries referenced by this scenario (inline `query [name]` + @query: tags)
   apiRefs?: string[];         // named API endpoints referenced by this scenario (@api: tags)
   requiresCaps?: string[];    // @requires:<cap> — automation-ready but needs an opt-in driver (TQ-11)
+  deferredToFlow?: boolean;   // @deferred:flow — owned by a flow, not automated on this screen (H6)
+  ownedByFlow?: string;       // @owned-by:<flow> — the flow that owns this deferred scenario (H6)
 }
 
 /** Format-tolerant: is this token an ID (project's scheme), not a prose word?
@@ -101,7 +103,10 @@ const PRIORITY_TAGS: Record<string, Priority> = { '@high': 'high', '@normal': 'n
 
 function classifyScenario(sc: ParsedScenario): ScenarioInfo {
   const tags = sc.tags || [];
-  const manual = tags.includes('@manual');
+  const deferredToFlow = tags.includes('@deferred:flow');
+  const ownedByFlow = (tags.find((t: string) => /^@owned-by:/i.test(t)) || '').slice('@owned-by:'.length) || undefined;
+  // @deferred:flow is owned by a flow → not automated on this screen, so it accounts like @manual (H6).
+  const manual = tags.includes('@manual') || deferredToFlow;
   const casesTag = tags.find((t) => t.startsWith('@cases:'));
   const casesDataset = casesTag ? casesTag.slice('@cases:'.length).trim() : undefined;
   // Named-query references: @query:<name>[(overrides)] tags + inline `query [name]` step refs.
@@ -118,7 +123,10 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
   let priority: Priority = 'unknown';
   for (const t of tags) if (PRIORITY_TAGS[t]) priority = PRIORITY_TAGS[t];
 
-  const codeMatch = sc.name.match(/\bVP-([A-Z]+)-\d+/i);
+  // Category is everything between `VP-` and the final `-<sequence>` — INCLUDING hyphens, so
+  // compound categories (VP-LIST-DISPLAY-01, VP-ADD-TO-CART-03, VP-PRODUCT-DISCOVERY-02) parse,
+  // not just single-word ones. A single-word category (VP-CART-001) still works. (H1)
+  const codeMatch = sc.name.match(/\bVP-([A-Z]+(?:-[A-Z]+)*)-\d+/i);
   const vpCode = codeMatch ? codeMatch[0].toUpperCase() : undefined;
   const category = codeMatch ? codeMatch[1].toUpperCase() : undefined;
   // Project-scheme ID: the leading token of the title (VP0-001 / MS-HP-001 / VP-LIST-001).
@@ -173,6 +181,8 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
     queryRefs: queryRefs.size ? [...queryRefs] : undefined,
     apiRefs: apiRefs.size ? [...apiRefs] : undefined,
     requiresCaps: requiresCaps.length ? requiresCaps : undefined,
+    deferredToFlow: deferredToFlow || undefined,
+    ownedByFlow,
   };
 }
 

package/src/harness/quality-gates.ts

@@ -20,7 +20,10 @@ function downstreamRoutes(specText: string): string[] {
   const routes = new Set<string>();
   for (const line of specText.split('\n')) {
     if (!/success|navigat|to \(|→/i.test(line)) continue;
-    for (const m of line.matchAll(/`?(\/[a-z][a-z0-9/_-]+)`?/gi)) {
+    // A real route's leading `/` sits at a path boundary (start, whitespace, backtick, quote, paren),
+    // NOT after a letter/digit. The lookbehind rejects prose slashes like "text/icon" or
+    // "category/brand" that aren't routes at all (H2 — they produced /icon, /button, /brand).
+    for (const m of line.matchAll(/(?<![A-Za-z0-9])(\/[a-z][a-z0-9/_-]+)`?/gi)) {
       const r = m[1];
       if (r !== ownRoute && r.split('/').length > ownRoute.split('/').length - 0) routes.add(r);
     }
@@ -29,6 +32,16 @@ function downstreamRoutes(specText: string): string[] {
   return [...routes].filter((r) => r !== ownRoute && (!ownRoute || r.startsWith(ownRoute + '/') || r.split('/').length >= 3));
 }
 
+/**
+ * H5 — a @parallel stateful (cart-mutating) flow with NO per-scenario isolation is flaky: scenarios
+ * share state, so cart count/quantity asserts race. Mitigations: @cleanup:cart, @isolate, a fresh
+ * browser context, or a "Given … empty cart" background. Returns true when the risk is unmitigated.
+ */
+export function isolationRisk(featureText: string, stateful: boolean): boolean {
+  if (!stateful || !/@parallel\b/i.test(featureText)) return false;
+  return !/@cleanup:cart\b|@isolate\b|empty cart|fresh (?:browser )?context|new context/i.test(featureText);
+}
+
 export function downstreamScope(specText: string, scenarios: ScenarioInfo[]): DownstreamResult {
   const routes = downstreamRoutes(specText);
   const underCovered: { route: string; slug: string }[] = [];