@sun-asterisk/sungen 3.1.0 → 3.1.2-beta.100

package/dist/orchestrator/templates/specs-test-data.ts

@@ -5,6 +5,8 @@ import yaml from 'yaml';
 
 export class TestDataLoader {
   private data: Record<string, any>;
+  // Data-driven (@cases): when set (via withRow), get() prefers this row's columns.
+  private row?: Record<string, any>;
 
   private constructor(data: Record<string, any>) {
     this.data = data;
@@ -41,23 +43,56 @@ export class TestDataLoader {
   }
 
   get(key: string): string {
-    // Captured/runtime vars (set() below) are stored under their literal — possibly
-    // dotted — key (e.g. "cart.product_name"), so check the flat key first.
-    let current: any = this.data[key];
-    if (current === undefined || current === null) {
-      // Fall back to nested navigation for YAML-structured keys (e.g. "cart.qty_two").
-      current = this.data;
-      for (const part of key.split('.')) {
-        if (current == null || typeof current !== 'object') {
-          throw new Error(`Test data key not found: ${key} (failed at '${part}')`);
-        }
-        current = current[part];
-      }
-    }
-    if (current === undefined || current === null) {
+    const value = this.resolve(key);
+    if (value === undefined || value === null) {
       throw new Error(`Test data key not found: ${key}`);
     }
-    return String(current);
+    return String(value);
+  }
+
+  /**
+   * Resolve a `{{...}}` reference to its raw value. Supports:
+   *  - flat keys (incl. captured runtime vars stored under a literal dotted key);
+   *  - `@cases` row columns (the current row wins);
+   *  - structured paths over nested data AND `@query`-bound result arrays:
+   *      `q.count` / `q.length`  → number of rows
+   *      `q.first.col` / `q.last.col` / `q[2].col` → a specific row's column
+   *      `q.col`                → shorthand for the first row's column
+   */
+  private resolve(key: string): any {
+    // 1. Exact flat key — captured vars (set()) live under a literal, possibly dotted, key.
+    if (this.row && key in this.row && this.row[key] !== undefined && this.row[key] !== null) {
+      return this.row[key];
+    }
+    if (this.data[key] !== undefined && this.data[key] !== null) {
+      return this.data[key];
+    }
+    // 2. Structured path: head from the row (cases) or shared data, then walk segments.
+    const tokens = String(key).replace(/\[(\d+)\]/g, '.$1').split('.');
+    let cur: any = (this.row && tokens[0] in this.row) ? this.row[tokens[0]] : this.data[tokens[0]];
+    for (let i = 1; i < tokens.length && cur != null; i++) cur = TestDataLoader.step(cur, tokens[i]);
+    return cur;
+  }
+
+  /** One navigation step over an array (with count/first/last/index/field-shorthand) or object. */
+  private static step(cur: any, token: string): any {
+    if (Array.isArray(cur)) {
+      if (token === 'count' || token === 'length') return cur.length;
+      if (token === 'first') return cur[0];
+      if (token === 'last') return cur[cur.length - 1];
+      if (/^\d+$/.test(token)) return cur[Number(token)];
+      return cur[0] == null ? undefined : cur[0][token]; // shorthand: first row's field
+    }
+    if (cur && typeof cur === 'object') return cur[token];
+    return undefined;
+  }
+
+  /**
+   * Bind a raw value (e.g. an `@query` result array) under `key` so `{{key.…}}` paths resolve.
+   * Unlike set(), the value is stored as-is (array/object), not coerced to a string.
+   */
+  bind(key: string, value: any): void {
+    this.data[key] = value;
   }
 
   /**
@@ -68,6 +103,32 @@ export class TestDataLoader {
   set(key: string, value: string): void {
     this.data[key] = value;
   }
+
+  /**
+   * Data-driven (@cases): return the list of rows at `key` (after env-overlay merge),
+   * each stamped with `__label` for the test title / report. Throws if missing or not a list.
+   */
+  cases(key: string): Array<Record<string, any>> {
+    const list = this.data[key];
+    if (!Array.isArray(list)) {
+      throw new Error(`@cases dataset "${key}" not found or not a list in test-data (got ${typeof list}).`);
+    }
+    return list.map((row: any, i: number) => {
+      const r: Record<string, any> = (row && typeof row === 'object' && !Array.isArray(row)) ? { ...row } : { value: row };
+      r.__label = String(r.case ?? r.name ?? r.label ?? `row ${i + 1}`);
+      return r;
+    });
+  }
+
+  /**
+   * Data-driven (@cases): a view whose get() prefers the given row's columns and falls
+   * back to the shared data. Used inside the per-row test() loop.
+   */
+  withRow(row: Record<string, any>): TestDataLoader {
+    const view = new TestDataLoader({ ...this.data }); // clone → per-row set() stays isolated
+    view.row = row;
+    return view;
+  }
 }
 
 function loadYamlSync(filePath: string): Record<string, any> | null {

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.1.0",
+  "version": "3.1.2-beta.100",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
   "bin": {
     "sungen": "./bin/sungen.js"
   },
   "scripts": {
-    "build": "tsc && npm run copy-templates",
+    "build": "rm -rf dist && tsc && npm run copy-templates",
     "copy-templates": "mkdir -p dist/generators/test-generator/adapters/playwright/templates/steps && mkdir -p dist/generators/test-generator/templates && mkdir -p dist/orchestrator/templates && mkdir -p dist/dashboard/templates && cp -r src/generators/test-generator/adapters/playwright/templates/*.hbs dist/generators/test-generator/adapters/playwright/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/playwright/templates/steps dist/generators/test-generator/adapters/playwright/templates/ && cp src/generators/test-generator/templates/*.hbs dist/generators/test-generator/templates/ 2>/dev/null || true && cp -r src/orchestrator/templates/* dist/orchestrator/templates/ && cp src/dashboard/templates/index.html dist/dashboard/templates/index.html && mkdir -p dist/harness/catalog && cp src/harness/catalog/*.yaml dist/harness/catalog/",
-    "build:dashboard": "cd dashboard && npm install --silent && npm run build && cd .. && cp dashboard/dist/index.html src/dashboard/templates/index.html",
+    "build:dashboard": "cd ../../dashboard && npm install --silent && npm run build && cd - && cp ../../dashboard/dist/index.html src/dashboard/templates/index.html",
     "dev": "tsx src/cli/index.ts",
-    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts",
+    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts && tsx tests/exporter/run.ts && tsx tests/capabilities/run.ts && tsx tests/openapi/run.ts && tsx tests/packaging/run.ts",
     "test:update": "tsx tests/golden/run.ts --update && tsx tests/audit/run.ts --update && tsx tests/ingest/run.ts --update",
     "prepublishOnly": "npm run build:dashboard && npm run build"
   },
@@ -33,6 +33,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "@sungen/driver-ui": "3.1.2-beta.100",
     "@anthropic-ai/sdk": "^0.71.0",
     "@babel/parser": "^7.28.5",
     "@babel/traverse": "^7.28.5",
@@ -52,37 +53,13 @@
     "yaml": "^2.8.2",
     "zod": "^4.1.13"
   },
-  "devDependencies": {
-    "@playwright/test": "^1.57.0",
-    "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.0",
-    "@types/jsdom": "^27.0.0",
-    "@types/node": "^20",
-    "jsdom": "^27.3.0",
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3",
-    "typescript": "^5"
-  },
   "peerDependencies": {
     "@playwright/test": "^1.57.0"
   },
-  "overrides": {
-    "brace-expansion": "^5.0.6",
-    "uuid": "^11.1.1",
-    "tmp": "^0.2.6",
-    "esbuild": "^0.28.1"
-  },
-  "resolutions": {
-    "brace-expansion": "^5.0.6",
-    "uuid": "^11.1.1",
-    "tmp": "^0.2.6",
-    "esbuild": "^0.28.1"
-  },
   "files": [
     "dist",
     "bin",
     "src",
-    "docs/orchestration-spec.md",
     "README.md",
     "LICENSE"
   ]

package/src/capabilities/builtins.ts

@@ -0,0 +1,85 @@
+/**
+ * In-core capability registrations (Capability SPI).
+ *
+ * `ui` has moved to `@sungen/driver-ui` (R5.4); `db` and `api` still register from here via
+ * `LOCAL_DRIVERS` (they relocate in R5.5/R5.6), and `core` (the generic expect/lint/verification
+ * layer) always stays in core. Discovery (`discover.ts`) loads the external driver(s) first, then
+ * these, then `core` — preserving the historical pattern composition order, so compiled output is
+ * byte-identical (golden + audit snapshots are the proof).
+ */
+import type { CapabilityRegistry } from './registry';
+import type { Sensor, AdvisoryScanInput, GateInput } from './sensor';
+import { lintDataDriven } from '../harness/data-driven-lint';
+import { resolveQuery, lintCatalog } from '../harness/query-catalog';
+import { expectPatterns } from '../generators/test-generator/patterns/expect-patterns';
+
+/** Advisory @cases/@query lint, exposed through the Sensor SPI (generate-time). */
+const dataDrivenLintSensor: Sensor<AdvisoryScanInput> = {
+  id: 'data-driven-lint',
+  capability: 'core',
+  kind: 'advisory',
+  run: ({ dir, cwd }) =>
+    lintDataDriven(dir, cwd).map((w) => ({
+      sensorId: 'data-driven-lint',
+      capability: 'core',
+      scenario: w.scenario,
+      message: w.message,
+      severity: 'warn' as const,
+    })),
+};
+
+/**
+ * Generic `verification` gate sensor: every referenced named query (`@query`) must resolve in its
+ * catalog, and the catalog must lint clean. An unresolved/invalid reference is a gate-level error.
+ * (On a project with no `@query` refs it yields nothing.) `query-catalog` lives in core's harness —
+ * shared with the data-driven advisory lint. The `@api` counterpart now lives in
+ * `@sungen/driver-api`'s `api-verification` gate sensor. Message prefix unchanged → audit byte-identical.
+ */
+const verificationGateSensor: Sensor<GateInput> = {
+  id: 'verification',
+  capability: 'core',
+  kind: 'gate',
+  run: ({ screenName, scenarios, cwd }) => {
+    const findings = [] as ReturnType<Sensor['run']>;
+    const fail = (msg: string) => findings.push({ sensorId: 'verification', capability: 'core', message: `VERIFICATION-FAIL: ${msg}`, severity: 'error' });
+
+    const queryRefs = new Set<string>();
+    for (const s of scenarios) for (const r of s.queryRefs ?? []) queryRefs.add(r);
+    for (const name of queryRefs) {
+      try { resolveQuery(name, screenName, cwd); } catch (e: any) { fail(e?.message || `query "${name}" does not resolve`); }
+    }
+    if (queryRefs.size) {
+      try { for (const err of lintCatalog(screenName, null, cwd).errors) fail(err); } catch { /* no catalog */ }
+    }
+    return findings;
+  },
+};
+
+/**
+ * core — generic, capability-agnostic steps (data-vs-data `expect`) + the advisory @cases/@query
+ * lint and the gate-level `verification` sensor. Stays in core (not a driver) — the always-present
+ * generic layer. All three real capabilities (ui/db/api) now ship as `@sungen/driver-*` packages.
+ */
+export function registerCoreCapability(registry: CapabilityRegistry): void {
+  registry.register({
+    id: 'core',
+    patterns: [...expectPatterns],
+    sensors: [dataDrivenLintSensor, verificationGateSensor],
+  });
+}
+
+/**
+ * In-core driver manifest — now empty: `ui`, `db`, and `api` all ship as `@sungen/driver-*` packages
+ * loaded by discovery (`discover.ts`). Kept (empty) as the seam for any future in-core capability;
+ * `core` itself registers separately via `registerCoreCapability`.
+ */
+export const LOCAL_DRIVERS: ReadonlyArray<{ capability: string; register: (r: CapabilityRegistry) => void }> = [];
+
+/**
+ * @deprecated Use `discoverAndRegisterCapabilities()` from `./discover`. Kept as a thin alias so
+ * existing call-sites/tests don't break during R5; removed once everything routes through discovery.
+ */
+export function registerBuiltinCapabilities(): void {
+  // Lazy import avoids a cycle (discover imports builtins).
+  require('./discover').discoverAndRegisterCapabilities();
+}

package/src/capabilities/context-router.ts

@@ -0,0 +1,66 @@
+/**
+ * ContextRouter (Capability SPI, R1 — skeleton).
+ *
+ * The overload guard: for each unit of work it decides the minimal slice of Context + the relevant
+ * capabilities + the gate to load, so a project with many drivers doesn't gather everything for
+ * every artifact (cost scales by *target*, not *repo × drivers*). See
+ * `docs/spec/sungen_capability_spi_spec.md` §5.
+ *
+ * R1 scope (skeleton, deterministic, not yet enforced in the pipeline): it computes the routing
+ * plan — which capabilities apply (the default/implicit one + any whose annotation tags appear),
+ * and which sensors gate the task. Scope-trimming/token-budget enforcement is wired in a later step;
+ * for now `scope.budget` is a placeholder (null = unbounded) and the plan is advisory.
+ */
+import { capabilityRegistry } from './registry';
+
+export interface RouteTask {
+  /** What is being worked on now. */
+  target: { kind: string; id: string };
+  /** What artifact is being produced/checked: 'feature' | 'scenario' | 'selectors' | 'apis.yaml' | … */
+  artifact: string;
+  /** Capability tags present on the target (e.g. ['@query'], ['@api'], ['@cases']). */
+  tags?: string[];
+}
+
+export interface RoutePlan {
+  /** Applicable capability ids: the default/implicit one + any whose annotations match the tags. */
+  capabilities: string[];
+  /** Gate sensors to run for this task (ids). */
+  gateSensorIds: string[];
+  /** Advisory sensors to run for this task (ids). */
+  advisorySensorIds: string[];
+  /** Scope: the target slice + a token/context budget (null = unbounded for now). */
+  scope: { target: RouteTask['target']; budget: number | null };
+}
+
+class ContextRouter {
+  /** Which capabilities a set of tags activates: the default capability + any owning a present tag. */
+  capabilitiesFor(tags: string[] = []): string[] {
+    const ids = new Set<string>();
+    const def = capabilityRegistry.defaultCapabilityId();
+    if (def) ids.add(def);
+    for (const cap of capabilityRegistry.all()) {
+      if ((cap.annotations ?? []).some((a) => tags.includes(a))) ids.add(cap.id);
+    }
+    return [...ids];
+  }
+
+  /** Compute the routing plan for a task (deterministic). */
+  route(task: RouteTask): RoutePlan {
+    const capabilities = this.capabilitiesFor(task.tags ?? []);
+    // Generic sensors (no capability, or the always-on `core`) run regardless of the task's tags;
+    // capability-specific sensors run only when their capability is in scope.
+    const inScope = (capId?: string) => capId == null || capId === 'core' || capabilities.includes(capId);
+    const gateSensorIds = capabilityRegistry.sensors('gate').filter((s) => inScope(s.capability)).map((s) => s.id);
+    const advisorySensorIds = capabilityRegistry.sensors('advisory').filter((s) => inScope(s.capability)).map((s) => s.id);
+    return {
+      capabilities,
+      gateSensorIds,
+      advisorySensorIds,
+      scope: { target: task.target, budget: null },
+    };
+  }
+}
+
+/** Process-wide singleton. */
+export const contextRouter = new ContextRouter();

package/src/capabilities/context.ts

@@ -0,0 +1,46 @@
+/**
+ * Orchestration phase-hook SPIs (Capability SPI, R1 — phase hooks).
+ *
+ * The kernel owns the pipeline (Plan → Discover → Contextualize → Generate → Gate → Repair →
+ * Deliver); a capability fills the domain-specific phases via these hooks:
+ *  - `DiscoveryProvider` — sources → a slice of the normalized `Context`.
+ *  - `ContextMapper`     — `Context` → generation units + the capability's MODES
+ *                          (ui: screen|flow; api: matrix|flow|async; db: query-catalog).
+ *
+ * R1 scope: these are **declared** (the contract) and attachable to a CapabilityDescriptor, but
+ * the kernel does not consume them yet — the pipeline still runs as before. R2 (driver-ui) is the
+ * first conformer that implements them; the orchestration is rewired to call them then.
+ * See `docs/spec/sungen_capability_spi_spec.md` §3–§6 and `sungen_ui_driver_spec.md`.
+ */
+
+/** Normalized, capability-tagged discovery output. Lazy/sliced — never materialized whole. */
+export interface Context {
+  target: { kind: string; id: string; capability?: string };
+  /** Lazy source handles (spec/viewpoint/openapi/routes/schema/liveSnapshot/figma/…). */
+  sources: Record<string, unknown>;
+  /** Capability-specific normalized facts (ui: elements/states/pageType; api: endpoints; db: tables). */
+  facts: Record<string, unknown>;
+  /** For run-time-connected capabilities (api/db): reachability probe result. */
+  connectivity?: { reachable: boolean; baseUrl?: string; probedAt?: string };
+}
+
+/** One unit of generation work the kernel will drive through Generate → Gate → Repair. */
+export interface GenerationUnit {
+  /** Capability-defined mode: 'screen' | 'flow' | 'matrix' | 'async' | 'query-catalog' | … */
+  mode: string;
+  /** The slice of Context this unit covers (a screen, an endpoint group, a query set, …). */
+  targetSlice: unknown;
+  /** Band weight hint (source-aware) — the kernel supplies the band targets. */
+  weight?: number;
+}
+
+export interface DiscoveryProvider {
+  appliesTo(target: Context['target']): boolean;
+  /** Produce this capability's slice of the Context for the given target + requested scope. */
+  discover(target: Context['target'], scope: unknown): Promise<Partial<Context>>;
+}
+
+export interface ContextMapper {
+  /** Turn the Context into generation units (+ modes), honouring the kernel's band targets. */
+  decompose(ctx: Context, bands?: Record<string, number>): GenerationUnit[];
+}

package/src/capabilities/discover.ts

@@ -0,0 +1,42 @@
+/**
+ * Capability discovery (R5 packaging seam).
+ *
+ * Core registers capabilities without importing any driver package statically. External
+ * `@sungen/driver-*` packages are loaded at runtime via their `sungenDriver.register` entry point;
+ * the capabilities still in core (`db`, `api`) register from `LOCAL_DRIVERS`; the generic `core`
+ * capability registers last. Idempotent (guards on `registry.isPopulated()`).
+ *
+ * Ordering is deterministic and behaviour-preserving: external drivers (currently `@sungen/driver-ui`)
+ * load first, then `LOCAL_DRIVERS` (db → api), then `core` — i.e. the historical ui → db → api → core
+ * composition order, so pattern composition / compiled output is byte-identical.
+ *
+ * A driver that isn't installed is simply skipped (capabilities are opt-in). Errors thrown *inside* a
+ * present driver propagate — only a genuinely absent package is swallowed (resolve-then-require).
+ */
+import { capabilityRegistry } from './registry';
+import { LOCAL_DRIVERS, registerCoreCapability } from './builtins';
+
+/**
+ * Driver packages relocated out of core, loaded before the in-core `LOCAL_DRIVERS`. As `db`/`api`
+ * move to their packages (R5.5/R5.6) they join this list and leave `LOCAL_DRIVERS`; eventually this
+ * becomes a scan of installed `@sungen/driver-*` packages (R5.7).
+ */
+const EXTERNAL_DRIVERS = ['@sungen/driver-ui', '@sungen/driver-db', '@sungen/driver-api'];
+
+function loadExternalDriver(name: string): void {
+  try {
+    require.resolve(name);
+  } catch {
+    return; // not installed — capabilities are opt-in, so skip silently
+  }
+  const mod = require(name); // present: let any error thrown inside the driver propagate (don't mask)
+  const register: ((r: typeof capabilityRegistry) => void) | undefined = mod?.sungenDriver?.register ?? mod?.register;
+  if (typeof register === 'function') register(capabilityRegistry);
+}
+
+export function discoverAndRegisterCapabilities(): void {
+  if (capabilityRegistry.isPopulated()) return;
+  for (const name of EXTERNAL_DRIVERS) 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

@@ -0,0 +1,111 @@
+/**
+ * Capability registry — the extension seam for the microkernel (Capability SPI, R1).
+ *
+ * Replaces hardcoded `this.patterns.push(...)` wiring with **registration**: each capability
+ * (ui · db · api · …) declares what it contributes; the kernel composes it. This is the
+ * "shared framework, pull in what you use" mechanism (`docs/spec/sungen_capability_spi_spec.md`).
+ *
+ * R1 scope (behaviour-preserving): only the **patterns** slice is wired through here — the set of
+ * registered patterns is identical to the old hardcoded list, so compiled output is unchanged
+ * (golden + audit snapshots are the contract). The remaining SPI slices (discovery, contextMapper,
+ * sensors, adapter, viewpoints, runtimeHelpers) are declared on the descriptor for the upcoming
+ * steps but are not consumed yet.
+ */
+import type { StepPattern } from '../generators/test-generator/patterns/types';
+import type { Sensor } from './sensor';
+import type { DiscoveryProvider, ContextMapper } from './context';
+
+export interface CapabilityDescriptor {
+  /** Stable id: 'ui' | 'db' | 'api' | 'core' | … */
+  id: string;
+  /** The implicit/default capability (a scenario with no capability tag). UI sets this. */
+  default?: boolean;
+  /** Annotation tags this capability owns (e.g. ['@query'], ['@api','@hybrid']). */
+  annotations?: string[];
+  /** Step patterns this capability contributes to the compiler. */
+  patterns?: StepPattern[];
+  /** Harness sensors this capability contributes (advisory and/or gate). */
+  sensors?: Sensor[];
+  /** Orchestration phase hooks — declared in R1, consumed by the pipeline from R2 onward. */
+  discovery?: DiscoveryProvider;     // sources → Context slice
+  contextMapper?: ContextMapper;     // Context → generation units + modes
+  /** Provider for this capability's viewpoint catalog (UI: the 17-pattern universal catalog). */
+  viewpoints?: () => unknown;
+  /**
+   * Score-bearing gate computation owned by this capability (UI: viewpoint coverage + assertion
+   * depth). The audit engine calls it and assembles the score from the result. Typed generically
+   * so the registry stays decoupled from harness internals; the caller knows the concrete shape.
+   */
+  gateProvider?: (input: unknown) => unknown;
+  /** Runtime helper file(s) this capability emits into specs/ when it is active for a feature
+   *  (db → specs/db.ts). Emitted via the same sync-when-changed mechanism. */
+  runtimeHelpers?: Array<{ file: string; template: string }>;
+  /** Optional step detector: the capability is "active" for a feature if any step matches —
+   *  for steps that carry no annotation tag (db's declarative `User see [t] row where …`). */
+  detectsStep?: (stepText: string) => boolean;
+  /**
+   * Precondition codegen for this capability's annotations on a scenario (db's `@query:<name>`
+   * → `testData.bind(name, await db.fetchQuery(...))`). Returns raw statements (the compiler
+   * indents) + `boundVars` (the `{{name}}` variables it binds, so the compiler registers them as
+   * runtime-resolved). Keeps `@query` codegen owned by `db`, not hardcoded in the compiler.
+   */
+  preconditionCodegen?: (input: { tags: string[]; screenName: string; cwd: string }) =>
+    Array<{ comment?: string; code: string; boundVars?: string[] }>;
+
+  /**
+   * CLI commands this capability contributes. The CLI calls each with the commander `program`
+   * (typed generically so the registry stays decoupled from commander; the driver knows the shape).
+   * Lets a driver own its authoring commands (api → `sungen api import`) instead of hardcoding them
+   * in core's CLI. Invoked once, after discovery, in `src/cli/index.ts`.
+   */
+  cliCommands?: Array<(program: unknown) => void>;
+
+  // --- Declared for later R-steps; not consumed yet (kept here so the SPI shape is visible). ---
+  // adapter?: string;                  // codegen adapter id (existing adapterRegistry)
+}
+
+export class CapabilityRegistry {
+  private caps = new Map<string, CapabilityDescriptor>();
+
+  /** Register (or replace, by id) a capability descriptor. Idempotent by id. */
+  register(descriptor: CapabilityDescriptor): void {
+    this.caps.set(descriptor.id, descriptor);
+  }
+
+  get(id: string): CapabilityDescriptor | undefined {
+    return this.caps.get(id);
+  }
+
+  /** True once any capability is registered — discovery guards on this (replaces the builtins boolean). */
+  isPopulated(): boolean {
+    return this.caps.size > 0;
+  }
+
+  all(): CapabilityDescriptor[] {
+    return [...this.caps.values()];
+  }
+
+  /** The id of the implicit/default capability (UI), if registered. */
+  defaultCapabilityId(): string | undefined {
+    return this.all().find((c) => c.default)?.id;
+  }
+
+  /** All step patterns contributed by registered capabilities (composition order = registration order). */
+  patterns(): StepPattern[] {
+    return this.all().flatMap((c) => c.patterns ?? []);
+  }
+
+  /** All registered sensors, optionally filtered by kind ('advisory' | 'gate'). */
+  sensors(kind?: Sensor['kind']): Sensor[] {
+    const all = this.all().flatMap((c) => c.sensors ?? []);
+    return kind ? all.filter((s) => s.kind === kind) : all;
+  }
+
+  /** Test seam: drop all registrations. */
+  _reset(): void {
+    this.caps.clear();
+  }
+}
+
+/** Process-wide singleton (mirrors `adapterRegistry`). */
+export const capabilityRegistry = new CapabilityRegistry();

package/src/capabilities/sensor.ts

@@ -0,0 +1,47 @@
+/**
+ * Harness Sensor SPI (Capability SPI, R1 — Sensor step).
+ *
+ * A sensor is a deterministic harness check a capability contributes. The kernel collects all
+ * registered sensors and runs them; findings merge into the harness output. Two kinds:
+ *  - `advisory` — surfaced as warnings (e.g. at `sungen generate`), never blocks.
+ *  - `gate`     — feeds the audit scorecard / pass-fail (migrated from the hardcoded `audit.ts`
+ *                 calls in the next sub-step; gate sensors carry an intent-aware threshold).
+ *
+ * Generic over the input so the same registry holds both generate-time advisory sensors
+ * (which scan a screen/flow dir) and audit-time gate sensors (which read parsed scenarios) —
+ * each sensor declares the input it consumes; callers filter by `kind` and pass the right input.
+ */
+export interface SensorFinding {
+  sensorId: string;
+  capability?: string;
+  scenario?: string;
+  message: string;
+  severity?: 'info' | 'warn' | 'error';
+}
+
+export interface Sensor<I = unknown> {
+  id: string;
+  capability?: string;
+  kind: 'gate' | 'advisory';
+  run(input: I): SensorFinding[];
+}
+
+/** Input for generate-time advisory sensors that scan a screen/flow directory. */
+export interface AdvisoryScanInput {
+  dir: string;
+  cwd: string;
+}
+
+/**
+ * Input for audit-time gate sensors. Intentionally minimal/structural (not the full ScenarioInfo
+ * type) so `src/capabilities` doesn't depend on harness internals — the audit caller passes the
+ * parsed scenarios it already has.
+ */
+export interface GateInput {
+  screenName: string;
+  cwd: string;
+  featureText: string;
+  scenarios: Array<{ name: string; queryRefs?: string[]; apiRefs?: string[] }>;
+  /** UI: universal-viewpoint theme gaps the coverage gate found (generic string list). */
+  universalGaps?: string[];
+}

package/src/cli/commands/challenge.ts

@@ -38,11 +38,15 @@ export function registerChallengeCommand(program: Command): void {
         if (report.collectionClaimSingular.length) {
           for (const f of report.collectionClaimSingular) L(`     ⚠ ${f.scenario}\n        → ${f.suggestion}`);
         } else L('     ✓ none');
-        L('  ② Coverage — over-covered / shallow');
+        L('  ② Data-driven — scenarios that should be one `@cases` (collapse data-variants / cover EP classes)');
+        if (report.dataDriven.length) {
+          for (const f of report.dataDriven) L(`     ⚠ ${f.scenario}\n        → ${f.suggestion}`);
+        } else L('     ✓ none');
+        L('  ③ Coverage — over-covered / shallow');
         if (report.overCovered.length) for (const o2 of report.overCovered) L(`     • ${o2.bucket}: ${o2.note}`);
         if (report.shallowThemes.length) L(`     • shallow themes: ${report.shallowThemes.join(', ')}`);
         if (!report.overCovered.length && !report.shallowThemes.length) L('     ✓ balanced');
-        L('  ③ Novelty — prompts for the `sungen-challenge` agent (≤20% of official, no auto-merge)');
+        L('  ④ Novelty — prompts for the `sungen-challenge` agent (≤20% of official, no auto-merge)');
         for (const p of report.noveltyPrompts) L(`     • ${p}`);
         L('  ── Exploration readiness ──');
         for (const e of report.explorationReadiness) L(`     • ${e}`);

package/src/cli/commands/delivery.ts

@@ -200,11 +200,12 @@ function discoverLocaleVariants(cwd: string, target: DeliveryTarget): LocaleVari
   const prefix = `${target.featureBaseName}-test-result`;
   const variants: LocaleVariant[] = [];
 
-  const basePath = path.join(genDir, `${prefix}.json`);
+  // Base variant: per-target result file if present, else fall back to the global
+  // test-results/results.json (what playwright.config writes by default) via resolveResultsPath.
   variants.push({
     locale: '',
     displayCode: DEFAULT_BASE_LOCALE.toUpperCase(),
-    resultsPath: fs.existsSync(basePath) ? basePath : null,
+    resultsPath: resolveResultsPath(cwd, target),
   });
 
   if (fs.existsSync(genDir)) {

package/src/cli/commands/generate.ts

@@ -4,6 +4,8 @@ import * as fs from 'fs';
 import { CodeGenerator } from '../../generators/test-generator/code-generator';
 import { adapterRegistry } from '../../generators/test-generator/adapters';
 import { scanTestDataSecrets } from '../../harness/secret-scan';
+import { capabilityRegistry } from '../../capabilities/registry';
+import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 import { readCapabilities, writeCapabilities, driverMeta, loadDriverCatalog } from '../../harness/capability';
 
 /**
@@ -182,6 +184,16 @@ export function registerGenerateCommand(program: Command): void {
           console.log(`   Move real secrets to an env overlay / CI secret; keep test-data placeholders only.`);
         }
 
+        // Advisory harness sensors (e.g. @cases/@query lint) — run via the Capability SPI,
+        // never block generation. Each capability registers its own; the kernel just runs them.
+        discoverAndRegisterCapabilities();
+        const advisorySensors = capabilityRegistry.sensors('advisory');
+        const ddWarnings = scanDirs.flatMap((d) => advisorySensors.flatMap((s) => s.run({ dir: d, cwd })));
+        if (ddWarnings.length) {
+          console.log(`\n⚠️  Data-driven lint (@cases / @query) — review:`);
+          for (const w of ddWarnings.slice(0, 20)) console.log(`   ${w.scenario ? w.scenario + ': ' : ''}${w.message}`);
+        }
+
         console.log(`Next step: npx playwright test --ui\n`);
       } catch (error) {
         console.error('Error:', error instanceof Error ? error.message : error);