@sun-asterisk/sungen 2.7.0-beta.1 → 3.0.0-beta.72

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

@@ -14,6 +14,20 @@ export class DataResolver {
   private screenName?: string;
   private runtimeMode: boolean;
   private flowMode: boolean = false;
+  // Vars captured at runtime via `User remember [X] as {{var}}`. References to
+  // these skip YAML validation (they don't exist in test-data.yaml) and resolve
+  // to testData.get('var') — populated by the capture step's testData.set('var', …).
+  private capturedVars = new Set<string>();
+
+  /** Register a variable name produced by a capture step (scenario-scoped). */
+  registerCaptured(name: string): void {
+    this.capturedVars.add(name);
+  }
+
+  /** Clear captured vars — call at the start of each scenario. */
+  clearCaptured(): void {
+    this.capturedVars.clear();
+  }
 
   constructor(testDataDir?: string, screenName?: string, runtimeMode: boolean = false) {
     this.testDataDir = testDataDir || path.join(process.cwd(), 'qa', 'test-data');
@@ -36,6 +50,12 @@ export class DataResolver {
    * @returns The resolved value
    */
   resolveData(dataRef: string, featureName?: string): string {
+    // Captured vars exist only at runtime → emit a marker (→ testData.get) and
+    // skip YAML validation. Requires runtime mode (capture writes testData.set).
+    if (this.capturedVars.has(dataRef)) {
+      return DataResolver.encodeMarker(dataRef);
+    }
+
     if (this.runtimeMode) {
       this.validateDataRef(dataRef, featureName);
       return DataResolver.encodeMarker(dataRef);

package/src/generators/test-generator/utils/runtime-data-transformer.ts

@@ -39,6 +39,14 @@ export function transformToRuntimeData(code: string): string {
     }
   );
 
+  // Pass 3: Bare-identifier context — any marker left after the string/regex passes
+  // sits as a bare token in a numeric position (e.g. `toHaveCount(__marker__)` from the
+  // table/list count templates). testData.get() returns a string, so coerce with Number().
+  code = code.replace(
+    /__SUNGEN_TD_([A-Za-z0-9_]+)__/g,
+    (_, enc) => `Number(testData.get('${decodeKey(enc)}'))`
+  );
+
   return code;
 }
 

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

@@ -312,12 +312,19 @@ export class SelectorResolver {
     const key = SelectorResolver.generateKey(label);
     const selectorFile = this.loadNewSelectorFile(featureName);
 
+    // Flow refs are namespaced "Screen:Element". The namespace is ONLY for selector-key
+    // lookup (key keeps it) — it is NOT part of the DOM accessible name. Strip it for any
+    // name/label fallback (auto-infer or entry without an explicit `name`). Bug #243.
+    const displayLabel = this.flowMode && label.includes(':')
+      ? label.slice(label.indexOf(':') + 1).trim()
+      : label;
+
     // Try nth-suffixed key first: hay.gui.loi.cam.on--3
     if (nth && nth > 0) {
       const nthKey = `${key}--${nth}`;
       const nthEntry = selectorFile[nthKey];
       if (nthEntry) {
-        return this.resolveFromEntry(nthEntry, label);
+        return this.resolveFromEntry(nthEntry, displayLabel);
       }
     }
 
@@ -327,7 +334,7 @@ export class SelectorResolver {
       const typedKey = `${key}--${normalizedType}`;
       const typedEntry = selectorFile[typedKey];
       if (typedEntry) {
-        return this.resolveFromEntry(typedEntry, label);
+        return this.resolveFromEntry(typedEntry, displayLabel);
       }
 
       // If normalized differs from original, also try original as-is
@@ -335,7 +342,7 @@ export class SelectorResolver {
         const originalKey = `${key}--${elementType}`;
         const originalEntry = selectorFile[originalKey];
         if (originalEntry) {
-          return this.resolveFromEntry(originalEntry, label);
+          return this.resolveFromEntry(originalEntry, displayLabel);
         }
       }
     }
@@ -343,12 +350,12 @@ export class SelectorResolver {
     // Fallback to base key
     const entry = selectorFile[key];
     if (entry) {
-      return this.resolveFromEntry(entry, label);
+      return this.resolveFromEntry(entry, displayLabel);
     }
 
     // Auto-infer locator from elementType when no exact YAML entry exists
     if (elementType) {
-      const inferred = SelectorResolver.inferFromElementType(elementType, label);
+      const inferred = SelectorResolver.inferFromElementType(elementType, displayLabel);
       if (inferred) {
         return inferred;
       }
@@ -357,7 +364,7 @@ export class SelectorResolver {
     // Last resort: find any suffixed key matching key--*
     const suffixedKeys = Object.keys(selectorFile).filter(k => k.startsWith(`${key}--`));
     if (suffixedKeys.length > 0) {
-      return this.resolveFromEntry(selectorFile[suffixedKeys[0]], label);
+      return this.resolveFromEntry(selectorFile[suffixedKeys[0]], displayLabel);
     }
 
     const tried: string[] = [];

package/src/harness/audit.ts

@@ -0,0 +1,112 @@
+/**
+ * Harness Audit — runs all sensors over a screen's test-design artifacts and
+ * produces a structured report + a business-weighted quality score.
+ *
+ * The score is INTENTIONALLY weighted toward business-critical coverage/depth
+ * (not breadth), so it surfaces the gaps a count-based view hides. See
+ * docs/orchestration-spec.md §5 and reports/sungen_home_gherkin_viewpoint_coverage_review.md.
+ */
+import * as path from 'path';
+import { loadScenarios, parseViewpointOverview, ScenarioInfo, ViewpointEntry } from './parse';
+import {
+  loadCatalog, viewpointGate, assertionDepth, dataThemesFor, coverageBalance, duplicateClusters, traceability,
+  GateResult, DepthResult, BalanceResult, DuplicateResult, TraceResult,
+} from './sensors';
+import { readIntent, projectRootFromScreenDir, IntentProfile } from './intent';
+
+export interface AuditReport {
+  screen: string;
+  scenarioCount: number;
+  gate: GateResult;
+  depth: DepthResult;
+  balance: BalanceResult;
+  duplicates: DuplicateResult;
+  trace: TraceResult;
+  score: {
+    overall: number;            // 0..10, business-weighted
+    coverage: number;           // 0..1
+    businessDepth: number;      // 0..1
+    balance: number;            // 0..1
+    traceability: number;       // 0..1
+    formula: string;
+  };
+  gateStatus: 'PASS' | 'FAIL';
+  findings: string[];           // human-actionable, what the Repair loop would target
+  intent: IntentProfile;        // P3 — the intent profile that drove the thresholds
+}
+
+export function runAudit(screenDir: string, screenName: string): AuditReport {
+  const featurePath = path.join(screenDir, 'features', `${screenName}.feature`);
+  const viewpointPath = path.join(screenDir, 'requirements', 'test-viewpoint.md');
+
+  const scenarios: ScenarioInfo[] = loadScenarios(featurePath);
+  const viewpoints: ViewpointEntry[] = parseViewpointOverview(viewpointPath);
+  const catalog = loadCatalog();
+
+  const gate = viewpointGate(scenarios, viewpoints, catalog);
+  // P3 — intent profile from qa/context.md drives the depth threshold (focus).
+  const intent = readIntent(projectRootFromScreenDir(screenDir));
+  const depth = assertionDepth(scenarios, dataThemesFor(catalog, gate.pageType), intent.focus);
+  const balance = coverageBalance(scenarios);
+  const duplicates = duplicateClusters(scenarios);
+  const trace = traceability(scenarios, viewpoints);
+
+  // 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 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 findings: string[] = [];
+  for (const g of gate.gaps) {
+    if (g.status === 'shallow') {
+      findings.push(`GATE: critical theme "${g.theme}" is covered only by SHALLOW scenarios (no data assertion) → deepen with \`... with {{value}}\` / \`table ... with {{value}}\` (count @manual cross-screen too).`);
+    } else {
+      findings.push(`GATE: critical theme "${g.theme}" for page-type "${gate.pageType}" has NO covering scenario → generate it (often cross-screen → consider add-flow).`);
+    }
+  }
+  if (depth.businessCriticalShallow > 0) {
+    const tag = depth.verdict === 'fail' ? 'DEPTH-FAIL' : depth.verdict === 'warn' ? 'DEPTH-WARN' : 'DEPTH';
+    findings.push(
+      `${tag}: ${depth.businessCriticalShallow}/${depth.businessCriticalTotal} data-correctness scenarios assert only visibility ` +
+      `(ratio ${depth.bcDepthRatio.toFixed(2)} < threshold ${depth.threshold.toFixed(2)} for focus "${depth.focus}") → ` +
+      `add data assertions (\`... with {{value}}\`, \`see all ... contain {{v}}\`) or, if cross-screen, defer to a flow with @manual + reason.`,
+    );
+  }
+  if (balance.imbalanced) {
+    findings.push(`BALANCE: ${balance.note} Stop expanding secondary viewpoints until business-core gaps are filled.`);
+  }
+  if (trace.mappedRatio < 0.5) {
+    findings.push(`TRACE: ${trace.note}`);
+  }
+  if (gate.universalGaps.length) {
+    findings.push(`UNIVERSAL: missing theme(s): ${gate.universalGaps.join(', ')} (low priority reminder).`);
+  }
+
+  // Gate now spans coverage (viewpoint themes) AND depth (data-correctness).
+  // A depth 'fail' (below the intent threshold) fails the gate; 'warn' does not.
+  const gateStatus: 'PASS' | 'FAIL' =
+    gate.gaps.length === 0 && depth.verdict !== 'fail' ? 'PASS' : 'FAIL';
+
+  return {
+    screen: screenName,
+    scenarioCount: scenarios.length,
+    gate, depth, balance, duplicates, trace,
+    score: {
+      overall: Math.round(overall * 10) / 10,
+      coverage: Math.round(coverage * 100) / 100,
+      businessDepth: Math.round(businessDepth * 100) / 100,
+      balance: Math.round(balanceScore * 100) / 100,
+      traceability: Math.round(traceScore * 100) / 100,
+      formula: 'overall = (0.4*coverage + 0.3*businessDepth + 0.15*balance + 0.15*traceability) * 10',
+    },
+    gateStatus,
+    findings,
+    intent,
+  };
+}

package/src/harness/blindspot.ts

@@ -0,0 +1,51 @@
+/**
+ * Blind-Spot Memory (harness-roadmap P5).
+ *
+ * A deterministic harness reliably repeats whatever its rules/viewpoints miss. When
+ * a QA (or the challenge critic) finds a recurring gap, don't just patch one test —
+ * promote it to a reusable PATTERN here. Loop 1 (generation pre-gate) and Loop 2
+ * (challenge critic) read these so the same blind spot doesn't come back.
+ *
+ * Store: .sungen/blindspots/blindspots.jsonl (append-only, project-local).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface Blindspot {
+  ts: string;
+  pattern: string;    // short name, e.g. "add-action-no-duplicate-check"
+  rule: string;       // the generalised rule to apply next time
+  example?: string;   // a concrete instance that motivated it
+  screen?: string;    // where it was first noticed
+  source?: string;    // 'qa' | 'challenge' | 'feedback'
+}
+
+function storePath(): string {
+  return path.join(process.cwd(), '.sungen', 'blindspots', 'blindspots.jsonl');
+}
+
+export function addBlindspot(entry: Omit<Blindspot, 'ts'> & { ts?: string }): string {
+  const p = storePath();
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const full: Blindspot = { ts: entry.ts ?? new Date().toISOString(), ...entry };
+  fs.appendFileSync(p, JSON.stringify(full) + '\n', 'utf-8');
+  return p;
+}
+
+export function listBlindspots(): Blindspot[] {
+  const p = storePath();
+  if (!fs.existsSync(p)) return [];
+  return fs.readFileSync(p, 'utf-8').split('\n').filter(Boolean).map((l) => {
+    try { return JSON.parse(l) as Blindspot; } catch { return null; }
+  }).filter(Boolean) as Blindspot[];
+}
+
+/** Compact bullet list for injecting into generator / critic prompts. */
+export function blindspotsForPrompt(): string {
+  const all = listBlindspots();
+  if (!all.length) return '';
+  // De-dupe by pattern (latest rule wins).
+  const byPattern = new Map<string, Blindspot>();
+  for (const b of all) byPattern.set(b.pattern, b);
+  return [...byPattern.values()].map((b) => `- [${b.pattern}] ${b.rule}`).join('\n');
+}

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]