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

package/src/harness/audit.ts

@@ -11,7 +11,7 @@ import * as fs from 'fs';
 import { loadScenarios, parseViewpointOverview, ScenarioInfo, ViewpointEntry } from './parse';
 import {
   loadCatalog, viewpointGate, assertionDepth, dataThemesFor, coverageBalance, duplicateClusters, traceability, claimProof, taxonomyLint,
-  GateResult, DepthResult, BalanceResult, DuplicateResult, TraceResult, ClaimProofResult, TaxonomyResult,
+  GateResult, DepthResult, BalanceResult, DuplicateResult, TraceResult, ClaimProofResult, TaxonomyResult, Catalog,
 } from './sensors';
 import { readIntent, projectRootFromScreenDir, IntentProfile } from './intent';
 import { getProvenance, Provenance } from './provenance';
@@ -19,6 +19,9 @@ import { specCoverage, SpecCoverageResult, parseSpecClauses } from './spec-cover
 import { downstreamScope, manualOracle, readText, DownstreamResult, ManualOracleResult,
   negativeSideEffect, sourceBacked, crossArtifactOwnership } from './quality-gates';
 import { viewpointLedger, parseViewpointItems, LedgerResult } from './viewpoint-ledger';
+import { capabilityRegistry } from '../capabilities/registry';
+import { discoverAndRegisterCapabilities } from '../capabilities/discover';
+import { contextRouter } from '../capabilities/context-router';
 
 export interface AuditReport {
   screen: string;
@@ -63,13 +66,23 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
 
   const scenarios: ScenarioInfo[] = loadScenarios(featurePath);
   const viewpoints: ViewpointEntry[] = parseViewpointOverview(viewpointPath);
-  const catalog = loadCatalog();
+  // The viewpoint catalog is owned by the default (UI) capability via the SPI; falls back to the
+  // in-core loader if no capability provides one. Same catalog content → identical scores (R2).
+  discoverAndRegisterCapabilities();
+  const defaultCap = capabilityRegistry.defaultCapabilityId();
+  const catalog = ((defaultCap && capabilityRegistry.get(defaultCap)?.viewpoints?.()) as Catalog | undefined) || loadCatalog();
   const spec = specCoverage(specPath, scenarios, featureText);
 
-  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);
+  // The viewpoint coverage gate + assertion depth are owned by the default (UI) capability and
+  // obtained via its `gateProvider` (R2.2b). Same functions underneath → byte-identical gate/depth
+  // → identical score. Falls back to the in-core functions if no capability provides them.
+  const uiGate = (defaultCap && capabilityRegistry.get(defaultCap)?.gateProvider) as
+    ((i: { scenarios: ScenarioInfo[]; viewpoints: ViewpointEntry[]; catalog: Catalog; focus: typeof intent.focus }) => { gate: GateResult; depth: DepthResult }) | undefined;
+  const provided = uiGate?.({ scenarios, viewpoints, catalog, focus: intent.focus });
+  const gate = provided?.gate ?? viewpointGate(scenarios, viewpoints, catalog);
+  const depth = provided?.depth ?? assertionDepth(scenarios, dataThemesFor(catalog, gate.pageType), intent.focus);
   const claim = claimProof(scenarios, intent.focus);
   const taxonomy = taxonomyLint(scenarios);
   const balance = coverageBalance(scenarios);
@@ -125,9 +138,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   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).`);
-  }
+  // (UNIVERSAL viewpoint-gap finding now emitted by the `ui` gate sensor — see the gate block below.)
   for (const g of spec.triggerGaps) {
     findings.push(`TRIGGER-UNCOVERED: spec validates "${g.constraint}"${g.code ? ` (${g.code})` : ''} on [${g.required.join(', ')}] but scenarios only exercise it on [${g.found.join(', ') || 'none'}] → add a ${g.missing.join(', ')}-trigger scenario for this constraint (don't collapse the trigger × input matrix).`);
   }
@@ -157,6 +168,24 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     findings.push(`UNSOURCEABLE-SCENARIO: "${u}" doesn't trace to any FR / viewpoint item — link it to a source, or tag it @exploration (not part of the official suite).`);
   }
 
+  // Capability gate sensors (Capability SPI): the ContextRouter scopes WHICH gate sensors run to
+  // the capabilities this feature actually uses — generic ('core') + the default UI + any whose
+  // annotation tags appear (e.g. @query). Today core+ui gate sensors are always in scope, so this
+  // is behaviour-identical; it bounds the set as capability-specific gate sensors (@api, …) are
+  // added. Each runs over the audit context; an 'error' finding fails the gate.
+  const featureTags = [
+    ...(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 gateSensorFindings = capabilityRegistry.sensors('gate')
+    .filter((s) => routedGateIds.includes(s.id))
+    .flatMap((s) => s.run({ screenName, cwd: projectRootFromScreenDir(screenDir), featureText, scenarios, universalGaps: gate.universalGaps }));
+  // Each gate sensor's message carries its own code prefix (VERIFICATION-FAIL / UNIVERSAL / …)
+  // → push verbatim.
+  for (const f of gateSensorFindings) findings.push(f.message);
+  const gateSensorError = gateSensorFindings.some((f) => f.severity === 'error');
+
   // #8 — multi-axis calibration: a high overall must not hide a weak axis.
   const manualCompleteness = manualOracleResult.manualTotal
     ? 1 - manualOracleResult.insufficient.length / manualOracleResult.manualTotal : 1;
@@ -180,7 +209,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // Gate spans coverage (viewpoint themes), depth, claim-proof, spec-clause coverage,
   // AND taxonomy-match (scenarios must use the project's viewpoint IDs when defined).
   const gateStatus: 'PASS' | 'FAIL' =
-    gate.gaps.length === 0 && depth.verdict !== 'fail' && claim.verdict !== 'fail' && spec.verdict !== 'fail' && !taxonomyMismatch ? 'PASS' : 'FAIL';
+    gate.gaps.length === 0 && depth.verdict !== 'fail' && claim.verdict !== 'fail' && spec.verdict !== 'fail' && !taxonomyMismatch && !gateSensorError ? 'PASS' : 'FAIL';
 
   return {
     screen: screenName,

package/src/harness/catalog/drivers.yaml

@@ -1,21 +1,37 @@
 # 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 docs/spec/sungen_phase2a_spec.md.
+# `sungen capability add` which package to install. See docs/spec/sungen_phase2a_spec.md
+# and docs/spec/sungen_packaging_spec.md (R5 — the capability SPI + npm packages).
 #
-# 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)
+# Two axes:
+#   kind: platform   → HOW tests run (runtime/codegen adapter). Pick ONE per project.
+#   kind: capability → WHAT extra thing is verified, added on top of a platform.
+# Fields:
+#   status:    shipped → published as an npm package (R5);  planned → not built yet.
+#   bundled:   true → installed automatically (a dependency of @sun-asterisk/sungen),
+#              so `capability add` is unnecessary.
+#   unblocks:  manual-reason codes (M1–M9) this driver resolves (Phase 2b taxonomy).
+#
+# R5 status: the three real capabilities ship as packages — @sungen/driver-ui (web UI,
+# bundled as the default), @sungen/driver-db, @sungen/driver-api. The web *platform*
+# entry below points at @sungen/driver-ui (the UI step vocabulary + viewpoint gate); the
+# Playwright codegen *adapter* itself is still in-core (Phase 2a). Mobile + the remaining
+# capabilities are planned. See the "Platform axis & mobile evolution" section of the
+# packaging spec for the `sungen init --platform <web|mobile>` roadmap.
 
 drivers:
   web:
     kind: platform
-    package: "@sungen/driver-web"     # Phase 2a: bundled Playwright adapter serves this (back-compat)
-    runtime: playwright
-    adapter: web                       # registry adapter name
+    package: "@sungen/driver-ui"       # R5: web UI capability (step patterns + viewpoint gate)
+    status: shipped
+    bundled: true                       # @sun-asterisk/sungen depends on it → UI works out of the box
+    runtime: playwright                 # codegen adapter still in-core (Phase 2a)
+    adapter: web                        # registry adapter name
     capabilities: ["@ui"]
   mobile:
     kind: platform
     package: "@sungen/driver-mobile"
+    status: planned                     # PoC on the feat/mobile branch (Appium / Flutter)
     runtime: appium
     adapter: mobile
     capabilities: ["@ui"]
@@ -23,35 +39,42 @@ drivers:
   api:
     kind: capability
     package: "@sungen/driver-api"
+    status: shipped
     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"
+    status: shipped
     capabilities: ["@dbAssert"]
     unblocks: [M2]
+  data-factory:
+    kind: capability
+    package: "@sungen/driver-data-factory"
+    status: planned
+    capabilities: ["@dataFactory"]
+    unblocks: [M1]
   mock:
     kind: capability
     package: "@sungen/driver-mock"
+    status: planned
     capabilities: ["@mock", "@network"]
     unblocks: [M3]
   mail-file:
     kind: capability
     package: "@sungen/driver-mail-file"
+    status: planned
     capabilities: ["@mail", "@file"]
     unblocks: [M5]
   contract:
     kind: capability
     package: "@sungen/driver-contract"
+    status: planned
     capabilities: ["@contract"]
     unblocks: [M5]
   specialized:
     kind: capability
     package: "@sungen/driver-specialized"
+    status: planned
     capabilities: ["@specialized"]
     unblocks: [M6]

package/src/harness/challenge.ts

@@ -34,6 +34,8 @@ export interface ChallengeReport {
   shallowThemes: string[];
   // Depth critic
   collectionClaimSingular: ChallengeFinding[];
+  // Data-driven critic — @cases-worthy gaps (spec-independent)
+  dataDriven: ChallengeFinding[];
   // Novelty critic (deterministic prompts → AI agent fills candidates)
   noveltyPrompts: string[];
   // Roll-up
@@ -47,6 +49,10 @@ const PLURAL_NOUN = /\b(cards|items|products|rows|results|prices|entries|records
 const QUANTIFIER = /\b(all|every|each)\b/i;
 const DISPLAY_VERB = /\b(displays?|shows?|lists?|grid|contains?)\b/i;
 
+// Title lexicon implying a CLASS of inputs (→ a data-driven @cases candidate). Used by
+// Detector A. Spec-independent — reads the title, not the spec.
+const INPUT_CLASS_LEXICON = /\b(invalid|formats?|boundary|range|min|max|too (?:long|short)|special char|each|various|classes)\b/i;
+
 /** Risk lenses the Novelty critic prompts the AI to explore (beyond the catalog). */
 const NOVELTY_LENSES = [
   'double-submit / rapid repeat of the primary action (duplicate side-effects?)',
@@ -88,17 +94,49 @@ export function buildChallenge(screenDir: string, screenName: string): Challenge
     }
   }
 
-  // 3. Novelty critic — deterministic prompts; the AI agent expands these into candidates.
+  // 3. Data-driven critic — surface @cases-worthy gaps (spec-independent).
+  const dataDriven: ChallengeFinding[] = [];
+  const clustered = new Set<string>();
+  // Detector B (high precision): ≥2 non-@cases scenarios sharing the SAME step skeleton
+  // (stepSkeleton normalizes {{vars}}/quoted values) → they differ only by data → collapse.
+  const bySkeleton = new Map<string, ScenarioInfo[]>();
+  for (const s of scenarios) {
+    if (s.manual || s.casesDataset || !s.stepSkeleton) continue;
+    (bySkeleton.get(s.stepSkeleton) ?? bySkeleton.set(s.stepSkeleton, []).get(s.stepSkeleton)!).push(s);
+  }
+  for (const group of bySkeleton.values()) {
+    if (group.length < 2) continue;
+    group.forEach((s) => clustered.add(s.name));
+    dataDriven.push({
+      scenario: group.map((s) => s.name).join(' | '),
+      issue: `${group.length} scenarios share the same steps and differ only by input value (data-variants).`,
+      suggestion: `Collapse into ONE \`@cases:<dataset>\` — ${group.length} rows in test-data, each \`{{col}}\` a column. See Gherkin → Advanced → Data-driven.`,
+    });
+  }
+  // Detector A (advisory): a lone scenario whose title implies a class of inputs → suggest @cases.
+  for (const s of scenarios) {
+    if (s.manual || s.casesDataset || clustered.has(s.name)) continue;
+    if (INPUT_CLASS_LEXICON.test(s.name)) {
+      dataDriven.push({
+        scenario: s.name,
+        issue: 'Title reads like a CLASS of inputs (validation/boundary/error) but tests a single value.',
+        suggestion: 'Consider `@cases` to cover the EP/boundary classes (one row per valid/invalid class), not just one value.',
+      });
+    }
+  }
+
+  // 4. Novelty critic — deterministic prompts; the AI agent expands these into candidates.
   const noveltyPrompts = NOVELTY_LENSES.map((l) => `Find 1 non-obvious, valuable scenario via: ${l}`);
 
   // Roll-up — exploration readiness signals (not a fake score).
   const explorationReadiness: string[] = [];
+  if (dataDriven.length) explorationReadiness.push(`${dataDriven.length} data-driven gap(s) — scenarios that should be one \`@cases\` (collapse data-variants / cover EP-boundary classes).`);
   if (collectionClaimSingular.length) explorationReadiness.push(`${collectionClaimSingular.length} title↔assertion gap(s) — deterministic depth critic flagged these; an AI Business-Depth critic should confirm + fix.`);
   if (overCovered.length) explorationReadiness.push(`${overCovered.length} possibly over-covered area(s) — rebalance toward correctness.`);
   if (shallowThemes.length) explorationReadiness.push(`Shallow themes: ${shallowThemes.join(', ')}.`);
   explorationReadiness.push('Novelty candidates are NOT generated deterministically — run the `sungen-challenge` agent (Claude) or its inline criteria (Copilot) to propose them, then QA accept/reject (≤20% of official, no auto-merge).');
 
-  return { screen: screenName, overCovered, shallowThemes, collectionClaimSingular, noveltyPrompts, explorationReadiness };
+  return { screen: screenName, overCovered, shallowThemes, collectionClaimSingular, dataDriven, noveltyPrompts, explorationReadiness };
 }
 
 /** Render the Challenge Report as Markdown (advisory — not part of the official suite). */
@@ -114,6 +152,13 @@ export function renderChallengeMarkdown(r: ChallengeReport): string {
   } else lines.push('_none_');
   lines.push('');
 
+  lines.push('## Data-driven — scenarios that should be `@cases` (one test case, many inputs)');
+  if (r.dataDriven.length) {
+    lines.push('| Scenario(s) | Issue | Suggested |', '|---|---|---|');
+    for (const f of r.dataDriven) lines.push(`| ${f.scenario} | ${f.issue} | ${f.suggestion} |`);
+  } else lines.push('_none_');
+  lines.push('');
+
   lines.push('## Coverage — possibly over-covered / shallow');
   if (r.overCovered.length) for (const o of r.overCovered) lines.push(`- **${o.bucket}** — ${o.note}`);
   if (r.shallowThemes.length) lines.push(`- Shallow themes: ${r.shallowThemes.join(', ')}`);

package/src/harness/data-driven-lint.ts

@@ -0,0 +1,119 @@
+/**
+ * Deterministic lint for the data-driven features (`@cases` + `@query`).
+ *
+ * Advisory (warn, never block) — surfaced after `sungen generate`. Catches the silent
+ * footguns: a `{{var}}` in a @cases scenario that is neither a row column nor a top-level
+ * key, a name collision that shadows a top-level value, inconsistent dataset rows, and a
+ * @query whose param has no value / whose name doesn't resolve.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
+import { GherkinParser, ParsedScenario } from '../generators/gherkin-parser';
+import { resolveQuery, lintCatalog } from './query-catalog';
+
+export interface DataDrivenWarning {
+  scenario?: string;
+  message: string;
+}
+
+const ROW_META = new Set(['case', 'name', 'label', '__label']);
+
+/** Collect the inner text of every `{{…}}` reference in a scenario's steps. */
+function collectRefs(sc: ParsedScenario): string[] {
+  const refs = new Set<string>();
+  for (const st of sc.steps || []) {
+    for (const m of (st.text || '').matchAll(/\{\{\s*([^}]+?)\s*\}\}/g)) refs.add(m[1]);
+  }
+  return [...refs];
+}
+
+/** Keys overridden in a `@query:name(a=…,b=…)` annotation. */
+function overrideKeys(raw?: string): Set<string> {
+  const out = new Set<string>();
+  if (!raw) return out;
+  for (const part of raw.split(',')) {
+    const eq = part.indexOf('=');
+    if (eq > 0) out.add(part.slice(0, eq).trim());
+  }
+  return out;
+}
+
+/** Lint the @cases/@query usage of one screen/flow directory. Returns advisory warnings. */
+export function lintDataDriven(screenDir: string, cwd: string = process.cwd()): DataDrivenWarning[] {
+  const base = path.basename(screenDir);
+  const isFlow = path.basename(path.dirname(screenDir)) === 'flows';
+  const screenName = isFlow ? `flows/${base}` : base;
+  const featurePath = path.join(screenDir, 'features', `${base}.feature`);
+  if (!fs.existsSync(featurePath)) return [];
+
+  let scenarios: ParsedScenario[];
+  try {
+    scenarios = new GherkinParser().parseFeatureFile(featurePath).scenarios || [];
+  } catch {
+    return [];
+  }
+
+  const tdPath = path.join(screenDir, 'test-data', `${base}.yaml`);
+  const td: Record<string, any> = tdPath && fs.existsSync(tdPath) ? parseYaml(fs.readFileSync(tdPath, 'utf8')) || {} : {};
+  const topKeys = new Set(Object.keys(td));
+  const warns: DataDrivenWarning[] = [];
+
+  for (const sc of scenarios) {
+    const tags: string[] = sc.tags || [];
+    const refs = collectRefs(sc);
+
+    // --- @cases -----------------------------------------------------------
+    const casesTag = tags.find((t) => t.startsWith('@cases:'));
+    if (casesTag) {
+      const ds = casesTag.slice('@cases:'.length).trim();
+      const rows = td[ds];
+      if (!Array.isArray(rows)) {
+        warns.push({ scenario: sc.name, message: `@cases:${ds} → dataset "${ds}" is missing or not a list in test-data.` });
+      } else {
+        const colSets = rows.map((r) => new Set(Object.keys(r || {}).filter((k) => !ROW_META.has(k))));
+        const allCols = new Set<string>();
+        colSets.forEach((s) => s.forEach((c) => allCols.add(c)));
+        for (const c of allCols) {
+          const missing = colSets.filter((s) => !s.has(c)).length;
+          if (missing) warns.push({ scenario: sc.name, message: `@cases:${ds} → column "${c}" is missing in ${missing}/${rows.length} row(s) — rows are inconsistent.` });
+          if (topKeys.has(c)) warns.push({ scenario: sc.name, message: `@cases:${ds} → "${c}" is both a dataset column and a top-level test-data key — the row value shadows the top-level one.` });
+        }
+        for (const r of refs) {
+          const head = r.split(/[.[]/)[0];
+          if (!allCols.has(head) && !topKeys.has(head)) {
+            warns.push({ scenario: sc.name, message: `@cases:${ds} → {{${r}}} is neither a dataset column nor a top-level test-data key.` });
+          }
+        }
+      }
+    }
+
+    // --- @query -----------------------------------------------------------
+    for (const t of tags) {
+      const m = t.match(/^@query:([A-Za-z_][A-Za-z0-9_]*)(?:\((.*)\))?$/);
+      if (!m) continue;
+      const name = m[1];
+      const overrides = overrideKeys(m[2]);
+      let entry;
+      try {
+        entry = resolveQuery(name, screenName, cwd);
+      } catch (e: any) {
+        warns.push({ scenario: sc.name, message: e?.message || `@query:${name} → cannot resolve query.` });
+        continue;
+      }
+      for (const p of entry.params || []) {
+        if (!overrides.has(p) && !topKeys.has(p)) {
+          warns.push({ scenario: sc.name, message: `@query:${name} → param "${p}" has no value: not in the annotation and not a top-level test-data key.` });
+        }
+      }
+    }
+  }
+
+  // Catalog-level lint (SELECT-only, params declared/used, datasource present).
+  try {
+    for (const e of lintCatalog(screenName, null, cwd).errors) warns.push({ message: e });
+  } catch {
+    /* no catalog → nothing to lint */
+  }
+  return warns;
+}

package/src/harness/parse.ts

@@ -30,6 +30,9 @@ export interface ScenarioInfo {
   haystack: string;           // lowercase name + steps text (for keyword coverage)
   stepsText: string;          // lowercase steps ONLY (name excluded) — for claim-proof
   vpId?: string;              // raw leading ID token of the title (project's scheme: VP0-001, MS-HP-001, VP-LIST-001)
+  casesDataset?: string;      // @cases:<dataset> — data-driven; one scenario expands to N row-tests
+  queryRefs?: string[];       // named queries referenced by this scenario (inline `query [name]` + @query: tags)
+  apiRefs?: string[];         // named API endpoints referenced by this scenario (@api: tags)
 }
 
 /** Format-tolerant: is this token an ID (project's scheme), not a prose word?
@@ -98,6 +101,17 @@ 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 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.
+  const queryRefs = new Set<string>();
+  for (const t of tags) if (t.startsWith('@query:')) { const m = t.slice('@query:'.length).match(/^([A-Za-z_][A-Za-z0-9_]*)/); if (m) queryRefs.add(m[1]); }
+  for (const step of (sc.steps as ParsedStep[]) || []) {
+    for (const m of (step.text || '').matchAll(/\bquery\s+\[([A-Za-z_][A-Za-z0-9_]*)\]/gi)) queryRefs.add(m[1]);
+  }
+  // Named-API references: @api:<name>[(overrides)] tags.
+  const apiRefs = new Set<string>();
+  for (const t of tags) if (t.startsWith('@api:')) { const m = t.slice('@api:'.length).match(/^([A-Za-z_][A-Za-z0-9_]*)/); if (m) apiRefs.add(m[1]); }
   let priority: Priority = 'unknown';
   for (const t of tags) if (PRIORITY_TAGS[t]) priority = PRIORITY_TAGS[t];
 
@@ -152,6 +166,9 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
     haystack: textParts.join(' ').toLowerCase(),
     stepsText: stepTextParts.join(' ').toLowerCase(),
     vpId,
+    casesDataset,
+    queryRefs: queryRefs.size ? [...queryRefs] : undefined,
+    apiRefs: apiRefs.size ? [...apiRefs] : undefined,
   };
 }
 

package/src/harness/script-check.ts

@@ -15,7 +15,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { loadScenarios } from './parse';
+import { loadScenarios, ScenarioInfo } from './parse';
 
 export interface ScriptCheckResult {
   screen: string;
@@ -146,10 +146,13 @@ export async function runScriptCheck(screenDir: string, screenName: string, flow
   }
 
   // A. Structural 1:1
+  // A @cases scenario emits ONE source test() inside a per-row loop, titled
+  // `<name> — ${__row.__label}` — match that literal title, not the bare name.
+  const expectedTitle = (s: ScenarioInfo) => (s.casesDataset ? `${s.name} — ${'${'}__row.__label}` : s.name);
   const specTitleSet = new Set(specTitles);
-  const scenTitleSet = new Set(automated.map((s) => s.name));
-  const missingInSpec = automated.filter((s) => !specTitleSet.has(s.name)).map((s) => s.name);
-  const extraInSpec = specTitles.filter((t) => !scenTitleSet.has(t));
+  const expectedSet = new Set(automated.map(expectedTitle));
+  const missingInSpec = automated.filter((s) => !specTitleSet.has(expectedTitle(s))).map((s) => s.name);
+  const extraInSpec = specTitles.filter((t) => !expectedSet.has(t));
   const countMatch = committedSpec ? automated.length === specTitles.length : false;
   if (committedSpec && !countMatch) {
     findings.push(`Count mismatch: ${automated.length} automated scenarios vs ${specTitles.length} test() blocks.`);
@@ -193,7 +196,7 @@ export async function runScriptCheck(screenDir: string, screenName: string, flow
 
   // C. Anti-bypass / faithfulness
   const { assertionlessTests, hollowSteps } = committedSpec
-    ? analyzeFaithfulness(specSrc, scenTitleSet)
+    ? analyzeFaithfulness(specSrc, expectedSet)
     : { assertionlessTests: [], hollowSteps: [] };
   for (const t of assertionlessTests) {
     findings.push(`BYPASS: test "${t}" has 0 assertions (action-only — proves nothing). The testcase is not really automated.`);

package/src/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Public API of `@sun-asterisk/sungen` — the capability SPI plus the shared compiler/harness surface
+ * that capability drivers (`@sungen/driver-*`) build against. Drivers import from here; core never
+ * imports from a driver (discovery loads them at runtime). Keep this surface small and intentional.
+ */
+
+// --- Capability SPI ---
+export { capabilityRegistry, CapabilityRegistry } from './capabilities/registry';
+export type { CapabilityDescriptor } from './capabilities/registry';
+export type { Sensor, SensorFinding, AdvisoryScanInput, GateInput } from './capabilities/sensor';
+export type { Context, DiscoveryProvider, ContextMapper, GenerationUnit } from './capabilities/context';
+
+// --- Step-pattern authoring (a driver contributes step patterns via its descriptor) ---
+export type { PatternContext, StepPattern, StepTemplateData } from './generators/test-generator/patterns/types';
+export type { MappedStep } from './generators/test-generator/step-mapper';
+export type { ParsedStep } from './generators/gherkin-parser';
+export { getPathCode, inferPath, resolvePathVariables } from './generators/test-generator/utils/path-inference';
+
+// --- Precondition-annotation override grammar (shared by the @query / @api driver codegen) ---
+export { parseQueryOverrides } from './harness/annotation-overrides';
+
+// --- Named-query catalog (shared: the DB driver's codegen + core's data-driven advisory lint) ---
+export { resolveQuery, compileQuery, lintCatalog } from './harness/query-catalog';
+export type { QueryEntry } from './harness/query-catalog';
+
+// --- Shared harness: viewpoint catalog + coverage gate / assertion depth ---
+// (the UI capability's gateProvider composes these; they also back core's ingest + audit fallback)
+export { loadCatalog, viewpointGate, assertionDepth, dataThemesFor } from './harness/sensors';
+export type { Catalog, GateResult, DepthResult } from './harness/sensors';
+export type { ScenarioInfo, ViewpointEntry } from './harness/parse';

package/src/orchestrator/templates/ai-instructions/claude-agent-challenge.md

@@ -15,11 +15,12 @@ Run `sungen challenge --screen <name>` (Bash) and read its report (`.sungen/repo
 - `.sungen/reports/<name>-audit.json` — what the gate already measured.
 - Blind-spot patterns — run `sungen blindspot list --prompt` (Bash) and check the suite against each known pattern.
 
-## Three critics
+## Four critics
 
 1. **Coverage critic** — viewpoints that are missing or covered only shallowly; areas over-covered with low value (e.g. many subscription edge cases while cart correctness is thin). Recommend rebalancing, not just adding.
 2. **Business-Depth critic** — scenarios whose **title claims more than the steps prove** (a set/collection asserted by one element; "correct X" asserted by mere visibility). For each, give the exact deep step to add. Confirm or dismiss the deterministic flags from `sungen challenge`.
-3. **Novelty critic** — 3–5 **non-obvious, valuable** scenarios outside the existing pattern, via risk lenses (double-submit, partial-load, boundary/unusual data, concurrency/back-button, historical incidents). Each must map to a risk or viewpoint and explain why it isn't a duplicate.
+3. **Data-driven critic** — surface `@cases`-worthy gaps, *spec-independent*: (a) **confirm the deterministic collapse suggestions** (`sungen challenge` flags ≥2 scenarios with the same step skeleton → propose the one `@cases:<dataset>` with the rows + a `case` label each); (b) for any action reaching a backend/logic (login, search, create, an API/error path), propose the **corner/error matrix** as `@cases` rows — *invalid · empty · boundary · injection · duplicate · not-found · unauthorized · malformed · rate-limit* — picking the family that fits the screen. These are the cases a spec/viewpoint usually under-specifies.
+4. **Novelty critic** — 3–5 **non-obvious, valuable** scenarios outside the existing pattern, via risk lenses (double-submit, partial-load, boundary/unusual data, concurrency/back-button, historical incidents). Each must map to a risk or viewpoint and explain why it isn't a duplicate.
 
 ## Guardrails (hard)
 - **Read-only.** Never edit the feature or any file. You return findings; the QA/orchestrator decides.

package/src/orchestrator/templates/ai-instructions/claude-cmd-create-test.md

@@ -31,9 +31,10 @@ Parse **name** from `$ARGUMENTS`. If missing, ask the user.
    **Screen**: Verify `qa/screens/<name>/` exists. If not → `/sungen:add-screen` first.
 2. Check if `.feature` file already has scenarios.
    - If yes → use `AskUserQuestion` to ask the update mode (see `sungen-tc-generation` skill — mode depends on which tiers already exist).
-   - If no → fresh creation. Use `AskUserQuestion` to ask generation scope:
-     - **Tier 1 — Critical & High priority** — ~10-15 scenarios/section covering happy paths, core validation, security basics **(Recommended)**
-     - **Full coverage — All tiers at once** — generates Tier 1 + 2 + 3 in one run. Large output (~40-60 scenarios/section), best for experienced users who want complete coverage immediately
+   - If no → fresh creation. **Write the feature file incrementally** (successive `Write`/`Edit`, ≈10-15 scenarios per call) — never emit the whole suite in one response, or it can exceed the model's output-token cap (`API Error: Claude's response exceeded the N output token maximum`). Use `AskUserQuestion` to ask generation scope:
+     - **Tier 1 — Critical & High priority** — ~10-15 scenarios/section: happy paths, core validation, security basics **(Recommended)**
+     - **Full coverage (incremental)** — Tier 1 + 2 + 3, written tier-by-tier in batches (`Write` T1 → `Edit` append T2 → `Edit` append T3). Safe on any output-token budget.
+     - **Full coverage (single pass)** — generate everything in one go (~40-60 scenarios/section). Faster, but **only if you raised your output cap** (`CLAUDE_CODE_MAX_OUTPUT_TOKENS ≥ 64000`) — otherwise it errors mid-generation. For power users on a high-token model/config.
 3. **Read project context + screen requirements**
 
    **Project context** — check `qa/context.md` (project root, not screen-specific):

package/src/orchestrator/templates/ai-instructions/claude-skill-gherkin-syntax.md

@@ -102,6 +102,22 @@ User see [Table] table match data:
 
 Row scope: `see [Ref] row in [Table] table with {{v}}` enters scope. Subsequent `see [Col] column with {{v}}` checks cell in that row. Use `table match data:` for multi-row verification.
 
+### Database verification (optional Data Driver)
+
+Read-only DB-state checks. **Prefer named queries** — SQL lives in `qa/screens/<screen>/database/queries.yaml` (reviewed once, parameterized). Invoke with the `@query:<name>` annotation; it binds the result rows to `{{name}}`, then assert with `expect`:
+
+```gherkin
+@query:active_user                 # precondition: run query, bind {{active_user}}
+@query:orders(buyer={{email}})     # …with explicit param override
+Scenario: ...
+  Then expect {{active_user.count}} is at least {{one}}   # ≥1 row
+  And  expect {{active_user.first.status}} is "active"     # first row's column
+  And  expect {{orders.count}} is {{expected}}             # exact count
+  And  User see [Total] text is {{orders.first.total}}     # UI ↔ DB
+```
+
+Path access on a bound result: `{{q.count}}`/`{{q.length}}`, `{{q.first.col}}`, `{{q.last.col}}`, `{{q[2].col}}`, `{{q.col}}` (= first row's col). `expect A is B` also supports `is at least` / `is at most` / `is not`. Tier-2 declarative (trivial inline, no catalog): `User see [<table>] row where [<col>] is {{v}} [has [<col2>] = "x"]`, `… no row where …`, `… count is {{n}}`. Full grammar + catalog/datasource/secret rules → **Advanced → Database** doc. Only emit DB steps when the project has a `database/` catalog / `datasources.yaml`.
+
 ### States
 
 `hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty` `loading` `selected` `sorted ascending` `sorted descending`
@@ -195,6 +211,31 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | `@afterEach` | Hook: runs after each test → `test.afterEach()` (custom cleanup) |
 | `@afterAll` | Hook: runs once after all tests → `test.afterAll()` |
 | `@flow` | Mark feature as E2E flow (cross-screen testing) |
+| `@cases:dataset` | Data-driven: run the scenario once per row of the `dataset` LIST in test-data → one `test()` per row |
+| `@query:name` | Database: run the named query from `database/queries.yaml` (precondition) and bind its rows to `{{name}}`; assert with `expect {{name.count}} …` + path access. Override params `@query:name(p={{v}})`. Repeatable. (Optional Data Driver — see Database verification above) |
+| `@api:name` | API: run the named request from `api/apis.yaml` (precondition) and bind the response to `{{name}}`; assert with `expect {{name.status}} …` + path access (`{{name.body.<path>}}`). Override params `@api:name(p={{v}})`. Repeatable. (Optional API Driver) |
+
+### Data-driven scenarios (`@cases`)
+
+For one test case × many inputs (email/format/boundary validation, decision tables), tag the
+scenario `@cases:<dataset>` and reference each row's columns as `{{col}}`. Put the rows as a LIST
+in test-data — NOT inline; data stays runtime + env-overlayable.
+
+```gherkin
+@high @cases:email_validation
+Scenario: VP-VAL-001 The email field rejects invalid formats
+  When User fill [Email] field with {{email}}
+  Then User see [Login Error] message with {{expected_error}}
+```
+```yaml
+# test-data/<screen>.yaml
+email_validation:
+  - { case: "no @",    email: "plainaddress", expected_error: "Invalid email" }
+  - { case: "valid",   email: "ok@x.com",     expected_error: "" }
+```
+An optional `case`/`name`/`label` column labels each run. Each row → its own pass/fail. Prefer
+`@cases` over duplicating a scenario per value. (Gherkin `Scenario Outline`/`Examples` is NOT
+supported — use `@cases`.)
 
 ### Pass-through tags (filter at runtime via Playwright --grep)
 

package/src/orchestrator/templates/ai-instructions/claude-skill-tc-generation.md

@@ -6,6 +6,9 @@ user-invocable: false
 
 ## ⚠️ Gotchas — read before generating
 
+- **Write incrementally — never emit the whole suite in one response.** Build the `.feature` in batches via successive `Write`/`Edit` (≈10–15 scenarios per call). For **Full coverage**, write tier-by-tier: `Write` Tier 1 → `Edit` append Tier 2 → `Edit` append Tier 3.
+  → One huge `Write` can exceed the model's output-token cap → `API Error: Claude's response exceeded the N output token maximum`. Single-pass full coverage only fits when `CLAUDE_CODE_MAX_OUTPUT_TOKENS ≥ 64000`; otherwise batch. Batching also lets the audit/reviewer run per batch — higher quality.
+
 - `spec_figma.md` exists → read file only, **NEVER** call `mcp__figma__*`
   → PAT auth flow already done by `sungen-capture` (mode figma-pat); re-calling fails or duplicates work.
 
@@ -54,6 +57,25 @@ user-invocable: false
   OR condition: generate 1 scenario per branch where that branch alone triggers the outcome.
   → Happy-path only = missing the most common multi-condition implementation bug.
 
+- **Many inputs, same steps → ONE data-driven scenario (`@cases`), not N copies:**
+  When a rule needs lots of inputs with the *same* step shape (email/format validation,
+  BVA boundary triples, EP classes, decision-table rows), tag one scenario `@cases:<dataset>`,
+  reference each row's columns as `{{col}}`, and put the rows as a LIST in test-data:
+  ```gherkin
+  @high @cases:email_validation
+  Scenario: VP-VAL-001 The email field rejects invalid formats
+    When User fill [Email] field with {{email}}
+    Then User see [Error] message with {{expected_error}}
+  ```
+  ```yaml
+  email_validation:
+    - { case: "no @",  email: "plainaddress", expected_error: "Invalid email" }
+    - { case: "valid", email: "ok@x.com",     expected_error: "" }
+  ```
+  → one `test()` per row, each labelled by `case`. Adding inputs = editing test-data (no recompile),
+  and env overlays apply. Prefer this over duplicating a scenario per value. (Gherkin
+  `Scenario Outline`/`Examples` is NOT supported — use `@cases`.)
+
 ---
 
 ## Tier System

package/src/orchestrator/templates/ai-instructions/claude-skill-tc-review.md

@@ -120,6 +120,7 @@ Build a mapping table: for each applicable group, does the feature have a matchi
 - **EP**: keep only **one representative** per invalid class; same-class duplicates → flag as redundant.
 - **BVA**: spec defines min/max → cover `min-1`, `min`, `max`, `max+1` (Maxlength, counts…).
 - Error messages must match the spec **word-for-word**, not generic.
+- **Data-driven (`@cases`)**: a `@cases:<dataset>` scenario legitimately covers many inputs in ONE scenario (one row per EP class / boundary / rule). Do **not** flag it as "too few negative cases" or as duplication — instead review the **dataset rows**: are all EP classes / boundary triples present, each labelled, expected values exact? N near-identical scenarios that differ only by input value → flag and recommend collapsing to `@cases`.
 
 ---