@sun-asterisk/sungen 3.0.0-beta.71 → 3.0.0-beta.73

package/src/harness/capability-plan.ts

@@ -0,0 +1,180 @@
+/**
+ * Capability Planner (Phase 2b) — deterministic, recommend-only.
+ *
+ * Classifies each scenario's execution mode + each @manual case by reason code
+ * (M1–M9), maps capability-reasons to drivers, and emits the manual-reason KPI.
+ * Never installs anything (that's `sungen capability add`). See
+ * reports/sungen_phase2b_spec.md.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { loadDriverCatalog } from './capability';
+
+export type ReasonClass = 'capability' | 'keep' | 'flow';
+export interface ReasonDef { code: string; label: string; cls: ReasonClass; drivers: string[] }
+
+export const MANUAL_REASONS: Record<string, ReasonDef> = {
+  M1: { code: 'M1', label: 'Missing data setup',            cls: 'capability', drivers: ['data-factory'] },
+  M2: { code: 'M2', label: 'Missing API/DB assertion',      cls: 'capability', drivers: ['api', 'db'] },
+  M3: { code: 'M3', label: 'Missing mock/network control',  cls: 'capability', drivers: ['mock'] },
+  M4: { code: 'M4', label: 'Missing stable selector/test-id', cls: 'capability', drivers: [] }, // locator contract, no driver
+  M5: { code: 'M5', label: 'External dependency',           cls: 'capability', drivers: ['mail-file', 'contract'] },
+  M6: { code: 'M6', label: 'Visual / UX judgment',          cls: 'keep',       drivers: ['specialized'] },
+  M7: { code: 'M7', label: 'Environment limitation',        cls: 'capability', drivers: [] }, // testability, no driver
+  M8: { code: 'M8', label: 'Not worth automating',          cls: 'keep',       drivers: [] },
+  M9: { code: 'M9', label: 'True human judgment',           cls: 'keep',       drivers: [] },
+  // Not a single-screen driver gap: automatable cross-screen via a flow (/sungen:add-flow).
+  XS: { code: 'XS', label: 'Cross-screen (automate via flow)', cls: 'flow',    drivers: [] },
+};
+
+// Keyword inference (best-effort retrofit). Order matters — first match wins.
+// Cross-screen "deferred to a flow" is checked FIRST: it is not a driver gap on
+// this screen, it is handled by a flow — so it must not recommend a driver.
+const INFER: { code: string; re: RegExp }[] = [
+  { code: 'XS', re: /\b(deferred to a flow|cross[-\s]?screen|in a flow|via a flow)\b/i },
+  { code: 'M4', re: /\b(selector|test[-\s]?id|locator|data-testid)\b/i },
+  { code: 'M3', re: /\b(mock|stub|network|offline|slow network|intercept)\b/i },
+  { code: 'M2', re: /\b(api|endpoint|backend|db|database|server[-\s]?side|via api)\b/i },
+  { code: 'M1', re: /\b(data setup|dataset|seed|test data|empty (category|product|dataset|state)|zero products|forcing an empty|backend\/test data)\b/i },
+  { code: 'M5', re: /\b(external|third[-\s]?party|sandbox|email|mail|payment gateway|invoice|download)\b/i },
+  { code: 'M6', re: /\b(visual|responsive|layout|accessibilit|a11y|keyboard|screen reader|ux|breakpoint)\b/i },
+  { code: 'M7', re: /\b(environment|staging[-\s]?only|infra|env limitation)\b/i },
+  { code: 'M8', re: /\b(not worth|exploratory|one[-\s]?off)\b/i },
+  { code: 'M9', re: /\b(judgment|human|subjective|manual review)\b/i },
+];
+
+interface ParsedScenario { name: string; tags: string[]; manual: boolean; reason: string }
+
+/** Parse scenarios with their tags + the reason comment line above (for @manual). */
+export function parseScenarios(featurePath: string): ParsedScenario[] {
+  if (!fs.existsSync(featurePath)) return [];
+  const lines = fs.readFileSync(featurePath, 'utf-8').split('\n');
+  const out: ParsedScenario[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^\s*Scenario:\s*(.+)$/);
+    if (!m) continue;
+    const tags: string[] = [];
+    let reason = '';
+    // Scan UP over the ADJACENT block (tag line + a directly-above reason comment).
+    // Stop at a blank line so section-divider comments further up aren't captured.
+    for (let j = i - 1; j >= 0 && j >= i - 6; j--) {
+      const l = lines[j].trim();
+      if (l === '') break;
+      if (/^@/.test(l)) tags.unshift(...l.split(/\s+/).filter((t) => t.startsWith('@')));
+      else if (/^#/.test(l)) { if (!reason) reason = l.replace(/^#+\s*/, ''); }
+      else break;
+    }
+    // Scan DOWN for the reason comment placed as the first line inside the body.
+    for (let k = i + 1; k < lines.length && k <= i + 4; k++) {
+      const l = lines[k].trim();
+      if (/^#/.test(l)) { if (!reason) reason = l.replace(/^#+\s*/, ''); break; }
+      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 });
+  }
+  return out;
+}
+
+function explicitCode(tags: string[]): string | undefined {
+  for (const t of tags) {
+    const m = t.match(/^@(?:manual|reason):(M[1-9])$/i);
+    if (m) return m[1].toUpperCase();
+  }
+  return undefined;
+}
+
+export function inferReasonCode(tags: string[], reason: string): { code: string; explicit: boolean; unclassified: boolean } {
+  const ex = explicitCode(tags);
+  if (ex) return { code: ex, explicit: true, unclassified: false };
+  for (const r of INFER) if (r.re.test(reason)) return { code: r.code, explicit: false, unclassified: false };
+  return { code: 'M9', explicit: false, unclassified: true };
+}
+
+function classifyMode(tags: string[]): string {
+  const has = (re: RegExp) => tags.some((t) => re.test(t));
+  if (has(/^@manual\b/i)) return 'manual';
+  if (has(/^@hybrid$/i)) return 'hybrid';
+  if (has(/^@(api|apiassert)$/i)) return 'api';
+  if (has(/^@(mock|network)$/i)) return 'mock';
+  if (has(/^@dbassert$/i)) return 'dbAssert';
+  return 'ui';
+}
+
+export interface CapabilityPlan {
+  screen: string;
+  total: number;
+  modes: Record<string, number>;
+  byReason: Record<string, number>;
+  unclassified: { name: string; reason: string }[];
+  capabilityManual: number;
+  judgmentManual: number;
+  crossScreen: number;            // automatable via a flow — not a single-screen driver gap
+  capabilityManualPct: number;
+  recommendations: { driver: string; pkg: string; reason: string; count: number; scenarios: string[] }[];
+  keep: { code: string; count: number }[];
+}
+
+export function buildPlan(screenDir: string, screenName: string): CapabilityPlan {
+  const featurePath = path.join(screenDir, 'features', `${screenName}.feature`);
+  const scenarios = parseScenarios(featurePath);
+  const catalog = loadDriverCatalog();
+
+  const modes: Record<string, number> = {};
+  const byReason: Record<string, number> = {};
+  const unclassified: CapabilityPlan['unclassified'] = [];
+  // driver → {reasonCode, scenarios}
+  const recByDriver = new Map<string, { reason: string; scenarios: string[] }>();
+  const keepCount: Record<string, number> = {};
+  let capabilityManual = 0, judgmentManual = 0, crossScreen = 0;
+
+  for (const s of scenarios) {
+    const mode = classifyMode(s.tags);
+    modes[mode] = (modes[mode] || 0) + 1;
+    if (mode !== 'manual') continue;
+
+    const { code, unclassified: unc } = inferReasonCode(s.tags, s.reason);
+    byReason[code] = (byReason[code] || 0) + 1;
+    if (unc) unclassified.push({ name: s.name, reason: s.reason || '(no reason comment)' });
+
+    const def = MANUAL_REASONS[code];
+    if (def.cls === 'flow') {
+      crossScreen++;
+    } else if (def.cls === 'capability') {
+      capabilityManual++;
+      for (const d of def.drivers) {
+        const cur = recByDriver.get(d) || { reason: code, scenarios: [] };
+        cur.scenarios.push(s.name);
+        recByDriver.set(d, cur);
+      }
+    } else {
+      judgmentManual++;
+      keepCount[code] = (keepCount[code] || 0) + 1;
+    }
+  }
+
+  const recommendations = [...recByDriver.entries()]
+    .map(([driver, v]) => ({
+      driver,
+      pkg: catalog[driver]?.package || `@sungen/driver-${driver}`,
+      reason: v.reason,
+      count: v.scenarios.length,
+      scenarios: v.scenarios,
+    }))
+    .sort((a, b) => b.count - a.count);
+
+  const manualTotal = modes['manual'] || 0;
+  return {
+    screen: screenName,
+    total: scenarios.length,
+    modes,
+    byReason,
+    unclassified,
+    capabilityManual,
+    judgmentManual,
+    crossScreen,
+    capabilityManualPct: manualTotal ? Math.round((capabilityManual / manualTotal) * 100) : 0,
+    recommendations,
+    keep: Object.entries(keepCount).map(([code, count]) => ({ code, count })).sort((a, b) => b.count - a.count),
+  };
+}

package/src/harness/capability.ts

@@ -0,0 +1,75 @@
+/**
+ * Capability profile + driver catalog (harness-roadmap Phase 2a).
+ *
+ * Sungen core is runtime-agnostic: a project declares its PLATFORM driver (web →
+ * Playwright, mobile → Appium) + any capability drivers in qa/capabilities.yaml.
+ * There is no default runtime — but for back-compat, an ABSENT profile is treated
+ * as `web` (the bundled adapter) with a one-time notice + scaffold.
+ *
+ * This module is metadata + profile I/O only. It never installs or imports a driver.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+
+export interface CapabilityProfile {
+  platform?: string;       // web | mobile | …  (the runtime adapter)
+  enabled: string[];       // driver ids enabled for this project
+  source: 'capabilities.yaml' | 'absent';
+}
+
+export interface DriverMeta {
+  id: string;
+  kind: 'platform' | 'capability';
+  package: string;
+  runtime?: string;
+  adapter?: string;        // registry adapter name (defaults to id)
+  capabilities: string[];
+  unblocks?: string[];
+}
+
+export function capabilitiesPath(cwd: string): string {
+  return path.join(cwd, 'qa', 'capabilities.yaml');
+}
+
+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) : [],
+      source: 'capabilities.yaml',
+    };
+  } catch {
+    return { platform: undefined, enabled: [], source: 'absent' };
+  }
+}
+
+export function writeCapabilities(cwd: string, profile: { platform?: string; enabled: string[] }): string {
+  const p = capabilitiesPath(cwd);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const body =
+    '# Sungen capability profile — which runtime/drivers this project uses.\n' +
+    '# platform: the runtime adapter (web → Playwright, mobile → Appium). No default.\n' +
+    '# enabled: drivers turned on (added via `sungen capability add <driver>`).\n\n' +
+    stringifyYaml({ platform: profile.platform, enabled: profile.enabled });
+  fs.writeFileSync(p, body, 'utf-8');
+  return p;
+}
+
+let _catalog: Record<string, DriverMeta> | null = null;
+export function loadDriverCatalog(): Record<string, DriverMeta> {
+  if (_catalog) return _catalog;
+  const p = path.join(__dirname, 'catalog', 'drivers.yaml');
+  const y = parseYaml(fs.readFileSync(p, 'utf-8')) as { drivers: Record<string, Omit<DriverMeta, 'id'>> };
+  const out: Record<string, DriverMeta> = {};
+  for (const [id, meta] of Object.entries(y.drivers)) out[id] = { id, ...meta };
+  _catalog = out;
+  return out;
+}
+
+export function driverMeta(id: string): DriverMeta | undefined {
+  return loadDriverCatalog()[id];
+}

package/src/harness/catalog/drivers.yaml

@@ -0,0 +1,57 @@
+# Driver Catalog (metadata only — NO driver code is bundled here).
+# Lets Sungen RECOMMEND/RESOLVE a driver that may not be installed yet, and tells
+# `sungen capability add` which package to install. See reports/sungen_phase2a_spec.md.
+#
+# kind: platform → the runtime/codegen adapter for a target (pick ONE per project)
+# kind: capability → an extra ability added on top of a platform (Phase 3)
+# unblocks: manual-reason codes (M1–M9) this driver can resolve (Phase 2b taxonomy)
+
+drivers:
+  web:
+    kind: platform
+    package: "@sungen/driver-web"     # Phase 2a: bundled Playwright adapter serves this (back-compat)
+    runtime: playwright
+    adapter: web                       # registry adapter name
+    capabilities: ["@ui"]
+  mobile:
+    kind: platform
+    package: "@sungen/driver-mobile"
+    runtime: appium
+    adapter: mobile
+    capabilities: ["@ui"]
+
+  api:
+    kind: capability
+    package: "@sungen/driver-api"
+    capabilities: ["@api", "@apiAssert", "@hybrid"]
+    unblocks: [M2]
+  data-factory:
+    kind: capability
+    package: "@sungen/driver-data-factory"
+    capabilities: ["@dataFactory"]
+    unblocks: [M1]
+  db:
+    kind: capability
+    package: "@sungen/driver-db"
+    capabilities: ["@dbAssert"]
+    unblocks: [M2]
+  mock:
+    kind: capability
+    package: "@sungen/driver-mock"
+    capabilities: ["@mock", "@network"]
+    unblocks: [M3]
+  mail-file:
+    kind: capability
+    package: "@sungen/driver-mail-file"
+    capabilities: ["@mail", "@file"]
+    unblocks: [M5]
+  contract:
+    kind: capability
+    package: "@sungen/driver-contract"
+    capabilities: ["@contract"]
+    unblocks: [M5]
+  specialized:
+    kind: capability
+    package: "@sungen/driver-specialized"
+    capabilities: ["@specialized"]
+    unblocks: [M6]

package/src/harness/flow-check.ts

@@ -0,0 +1,99 @@
+/**
+ * Flow first-class checks (flow_firstclass_spec).
+ *
+ * A. Deferral integrity — every screen `@manual` "deferred to a flow (X -> Y)" must
+ *    be backed by a real flow scenario that covers Y (deeply). Otherwise the
+ *    cross-screen (XS) manual is a hidden gap, not "flow-covered".
+ * B. Run-test contract — surface the fragile cross-screen patterns (same-card
+ *    identity scope, shared-state isolation under @parallel) as explicit checks.
+ *
+ * Deterministic + read-only. No test execution, no selector resolution.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { loadScenarios } from './parse';
+import { parseScenarios } from './capability-plan';
+
+const KNOWN_TARGETS = ['cart', 'category', 'brand', 'detail', 'checkout', 'wishlist', 'order', 'payment', 'login'];
+
+export interface Deferral { screen: string; scenario: string; hint: string; targets: string[]; verdict: 'covered' | 'shallow' | 'missing'; via?: string }
+export interface Contract { flow: string; kind: 'SAME-CARD' | 'ISOLATION'; scenario?: string; message: string }
+export interface FlowCheckReport {
+  screens: string[]; flows: string[];
+  deferrals: Deferral[];
+  contracts: Contract[];
+  missing: number;
+}
+
+function listDirs(p: string): string[] {
+  return fs.existsSync(p) ? fs.readdirSync(p, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name) : [];
+}
+function featurePath(base: string, kind: 'screens' | 'flows', name: string): string {
+  return path.join(base, 'qa', kind, name, 'features', `${name}.feature`);
+}
+function featureTags(fp: string): string[] {
+  if (!fs.existsSync(fp)) return [];
+  for (const line of fs.readFileSync(fp, 'utf-8').split('\n')) {
+    const t = line.trim();
+    if (t.startsWith('Feature:')) break;
+    if (t.startsWith('@')) return t.split(/\s+/).filter((x) => x.startsWith('@'));
+  }
+  return [];
+}
+function targetsFromHint(hint: string): string[] {
+  const h = hint.toLowerCase();
+  const hits = KNOWN_TARGETS.filter((k) => h.includes(k));
+  if (hits.length) return hits;
+  // fallback: significant words after "->"
+  const after = h.split('->').pop() || h;
+  return after.split(/[^a-z]+/).filter((w) => w.length > 3 && !['home', 'page', 'flow', 'products', 'product', 'result'].includes(w));
+}
+
+export function buildFlowCheck(cwd: string, onlyFlow?: string): FlowCheckReport {
+  const screens = listDirs(path.join(cwd, 'qa', 'screens'));
+  const flows = (onlyFlow ? [onlyFlow] : listDirs(path.join(cwd, 'qa', 'flows')));
+
+  // Index flow scenarios (name + haystack + depth).
+  const flowScenarios: { flow: string; name: string; haystack: string; deep: boolean }[] = [];
+  for (const f of listDirs(path.join(cwd, 'qa', 'flows'))) {
+    for (const s of loadScenarios(featurePath(cwd, 'flows', f))) {
+      flowScenarios.push({ flow: f, name: s.name, haystack: s.haystack, deep: s.hasDataAssertion });
+    }
+  }
+
+  // A. Deferral integrity (screens).
+  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)));
+      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 });
+    }
+  }
+
+  // B. Run-test contract (per flow).
+  const contracts: Contract[] = [];
+  for (const f of flows) {
+    const fp = featurePath(cwd, 'flows', f);
+    const parallel = featureTags(fp).some((t) => /^@parallel$/i.test(t));
+    const scs = loadScenarios(fp);
+    let cartStateCount = 0;
+    for (const s of scs) {
+      const h = s.haystack;
+      if (/\bremember\b/.test(h) && /(add to cart|view product)/.test(h)) {
+        contracts.push({ flow: f, kind: 'SAME-CARD', scenario: s.name, message: 'remember + Add To Cart/View Product → scope to ONE card at run-test, else the identity proof is hollow.' });
+      }
+      if (/(add to cart|remove|\bcart\b|quantity)/.test(h)) cartStateCount++;
+    }
+    if (parallel && cartStateCount >= 2) {
+      contracts.push({ flow: f, kind: 'ISOLATION', message: `@parallel + ${cartStateCount} cart/state scenarios → give each a fresh browser context, else count/quantity asserts are flaky.` });
+    }
+  }
+
+  return { screens, flows, deferrals, contracts, missing: deferrals.filter((d) => d.verdict === 'missing').length };
+}

package/src/harness/flow-plan.ts

@@ -0,0 +1,135 @@
+/**
+ * Flow Capability Planner (Phase 2c) — flow-aware, deterministic, recommend-only.
+ *
+ * Decomposes a flow into per-screen LEGS (from [Screen:Element] refs), reports each
+ * leg's SELECTOR READINESS + capability, folds in the manual-reason taxonomy
+ * (capability-plan) and the run-test contract (flow-check), and emits a run-test
+ * PLAN. Automates the manual diagnosis done while healing cart-and-filter.
+ * See reports/sungen_phase2c_spec.md.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
+import { MANUAL_REASONS, inferReasonCode } from './capability-plan';
+import { buildFlowCheck, Contract } from './flow-check';
+
+const REF_RE = /\[([A-Za-z][\w ]*?):([\w &.-]+?)\]/g;
+
+interface FlowScenario { name: string; manual: boolean; reason: string; tags: string[]; refs: { screen: string; element: string }[] }
+
+function parseFlowScenarios(featurePath: string): FlowScenario[] {
+  if (!fs.existsSync(featurePath)) return [];
+  const lines = fs.readFileSync(featurePath, 'utf-8').split('\n');
+  const out: FlowScenario[] = [];
+  const idx: number[] = [];
+  lines.forEach((l, i) => { if (/^\s*Scenario:/.test(l)) idx.push(i); });
+  for (let s = 0; s < idx.length; s++) {
+    const i = idx[s];
+    const end = s + 1 < idx.length ? idx[s + 1] : lines.length;
+    const name = lines[i].replace(/^\s*Scenario:\s*/, '').trim();
+    // tags + reason from the lines above + first comment in body
+    const tags: string[] = []; let reason = '';
+    for (let j = i - 1; j >= 0; j--) {
+      const t = lines[j].trim();
+      if (t === '') break;
+      if (/^@/.test(t)) tags.unshift(...t.split(/\s+/).filter((x) => x.startsWith('@')));
+      else if (/^#/.test(t)) { if (!reason) reason = t.replace(/^#+\s*/, ''); }
+      else break;
+    }
+    const body = lines.slice(i, end).join('\n');
+    if (!reason) { const m = body.match(/^\s*#\s*(.+)$/m); if (m) reason = m[1].trim(); }
+    const refs: FlowScenario['refs'] = [];
+    let mm: RegExpExecArray | null;
+    REF_RE.lastIndex = 0;
+    while ((mm = REF_RE.exec(body))) refs.push({ screen: mm[1].trim(), element: mm[2].trim() });
+    out.push({ name, manual: tags.some((t) => /^@manual\b/i.test(t)), reason, tags, refs });
+  }
+  return out;
+}
+
+function selectorKeys(selectorsPath: string): Set<string> {
+  if (!fs.existsSync(selectorsPath)) return new Set();
+  try {
+    const y = parseYaml(fs.readFileSync(selectorsPath, 'utf-8')) || {};
+    return new Set(Object.keys(y).map((k) => k.toLowerCase()));
+  } catch { return new Set(); }
+}
+
+export interface LegPlan {
+  screen: string;
+  scenarios: number;
+  refs: string[];
+  haveKeys: number;
+  readiness: 'ready' | 'partial' | 'missing';
+  touchedByAutomated: boolean;
+}
+export interface FlowPlan {
+  flow: string;
+  total: number;
+  legs: LegPlan[];
+  byReason: Record<string, number>;
+  capabilityManual: number;
+  judgmentManual: number;
+  contracts: Contract[];
+  readiness: 'ready' | 'not-ready';
+  missingLegs: string[];
+  plan: string[];
+}
+
+export function buildFlowPlan(cwd: string, flow: string): FlowPlan {
+  const featurePath = path.join(cwd, 'qa', 'flows', flow, 'features', `${flow}.feature`);
+  const selectorsPath = path.join(cwd, 'qa', 'flows', flow, 'selectors', `${flow}.yaml`);
+  const scenarios = parseFlowScenarios(featurePath);
+  const keys = selectorKeys(selectorsPath);
+
+  // Legs = distinct screen namespaces.
+  const legMap = new Map<string, { scenarios: Set<string>; refs: Set<string>; automated: boolean }>();
+  const byReason: Record<string, number> = {};
+  let capabilityManual = 0, judgmentManual = 0;
+
+  for (const sc of scenarios) {
+    if (sc.manual) {
+      const { code } = inferReasonCode(sc.tags, sc.reason);
+      byReason[code] = (byReason[code] || 0) + 1;
+      const cls = MANUAL_REASONS[code]?.cls;
+      if (cls === 'capability') capabilityManual++; else if (cls === 'keep') judgmentManual++;
+    }
+    for (const r of sc.refs) {
+      const leg = r.screen.toLowerCase();
+      const entry = legMap.get(leg) || { scenarios: new Set(), refs: new Set(), automated: false };
+      entry.scenarios.add(sc.name);
+      entry.refs.add(`${leg}:${r.element.toLowerCase()}`);
+      if (!sc.manual) entry.automated = true;
+      legMap.set(leg, entry);
+    }
+  }
+
+  const legs: LegPlan[] = [...legMap.entries()].map(([screen, e]) => {
+    const refs = [...e.refs];
+    const haveKeys = refs.filter((rk) => keys.has(rk)).length;
+    const readiness: LegPlan['readiness'] = haveKeys === refs.length ? 'ready' : haveKeys === 0 ? 'missing' : 'partial';
+    return { screen, scenarios: e.scenarios.size, refs, haveKeys, readiness, touchedByAutomated: e.automated };
+  }).sort((a, b) => b.scenarios - a.scenarios);
+
+  const missingLegs = legs.filter((l) => l.touchedByAutomated && l.readiness !== 'ready').map((l) => l.screen);
+  const fc = buildFlowCheck(cwd, flow);
+  const contracts = fc.contracts.filter((c) => c.flow === flow);
+
+  const readiness: FlowPlan['readiness'] = missingLegs.length ? 'not-ready' : 'ready';
+  const plan: string[] = [];
+  if (missingLegs.length) {
+    plan.push(`Run \`/sungen:run-test ${flow}\` → Phase 0 generates selectors for: ${missingLegs.join(', ')} (from the live pages).`);
+  }
+  if (contracts.some((c) => c.kind === 'SAME-CARD')) plan.push('Honour SAME-CARD: scope remember + Add To Cart/View Product to ONE card at run-test.');
+  if (contracts.some((c) => c.kind === 'ISOLATION')) plan.push('Honour ISOLATION: fresh browser context per cart/state scenario (@parallel).');
+  const driverReasons = Object.keys(byReason).filter((c) => MANUAL_REASONS[c]?.cls === 'capability');
+  if (driverReasons.length) {
+    const drivers = [...new Set(driverReasons.flatMap((c) => MANUAL_REASONS[c].drivers))];
+    if (drivers.length) plan.push(`Consider drivers (recommend-only): ${drivers.join(', ')} — for capability-manual (${driverReasons.join('/')}).`);
+  } else {
+    plan.push('No capability driver needed — all automated legs are @ui.');
+  }
+  if (readiness === 'ready') plan.unshift('Selectors present for every automated leg — ready to compile + run.');
+
+  return { flow, total: scenarios.length, legs, byReason, capabilityManual, judgmentManual, contracts, readiness, missingLegs, plan };
+}