@sun-asterisk/sungen 3.1.2-beta.99 → 3.2.0-beta.141

package/src/harness/capability-plan.ts

@@ -36,7 +36,9 @@ const INFER: { code: string; re: RegExp }[] = [
   { 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 },
+  // "email" alone is too greedy (every subscription test mentions it) → require a real external-mail
+  // signal (verification mail / OTP / inbox), so an API/DB-oracle test isn't misread as M5.
+  { code: 'M5', re: /\b(external|third[-\s]?party|sandbox|payment gateway|invoice|download|verification (e?mail|link)|otp|mailbox|inbox|e?mail link)\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 },
@@ -102,6 +104,54 @@ export function inferReasonCode(tags: string[], reason: string): { code: string;
   return { code: 'M9', explicit: false, unclassified: true };
 }
 
+/** The reason code inferred ONLY from the reason text, ignoring any explicit @manual:Mx tag. */
+export function inferFromText(reason: string): string | undefined {
+  for (const r of INFER) if (r.re.test(reason)) return r.code;
+  return undefined;
+}
+
+export interface ReasonMismatch { scenario: string; explicit: string; inferred: string }
+
+/**
+ * (TQ-9) @manual scenarios whose explicit `@manual:Mx` disagrees with the code inferred from
+ * the reason text — a mis-tag that makes the Capability Planner recommend the wrong driver
+ * (e.g. tagged `M1` data-setup but the reason describes a DB/API assertion → `M2`). Advisory:
+ * surfaced so the reason code — and therefore the driver suggestion — can be trusted.
+ */
+export function manualReasonMismatches(featurePath: string): ReasonMismatch[] {
+  if (!fs.existsSync(featurePath)) return [];
+  const lines = fs.readFileSync(featurePath, 'utf-8').split('\n');
+  const out: ReasonMismatch[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^\s*Scenario:\s*(.+)$/);
+    if (!m) continue;
+    // Tags on the adjacent line(s) above.
+    const tags: string[] = [];
+    for (let j = i - 1; j >= 0 && j >= i - 4; 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)) continue;
+      else break;
+    }
+    if (!tags.some((t) => /^@manual\b/i.test(t))) continue;
+    const explicit = explicitCode(tags);
+    if (!explicit) continue;
+    // FULL reason block — every comment line in the body before the first real step (the
+    // driver-relevant signal — "subscribers table", "API/persistence" — is often not line 1).
+    const parts: string[] = [];
+    for (let k = i + 1; k < lines.length && k <= i + 16; k++) {
+      const l = lines[k].trim();
+      if (/^#/.test(l)) parts.push(l.replace(/^#+\s*/, ''));
+      else if (l === '') continue;
+      else break;
+    }
+    const inferred = inferFromText(parts.join(' '));
+    if (inferred && inferred !== explicit) out.push({ scenario: m[1].trim(), explicit, inferred });
+  }
+  return out;
+}
+
 function classifyMode(tags: string[]): string {
   const has = (re: RegExp) => tags.some((t) => re.test(t));
   if (has(/^@manual\b/i)) return 'manual';

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

@@ -109,6 +109,26 @@ export function lintDataDriven(screenDir: string, cwd: string = process.cwd()):
     }
   }
 
+  // --- orphan test-data: a top-level key never referenced (dead data — generated but not
+  //     materialized into a scenario). Referenced = a `{{key…}}` in any step, a `@cases:<key>`
+  //     dataset, or an override value `…={{key…}}` on an @api/@query annotation.
+  const usedHeads = new Set<string>();
+  const usedDatasets = new Set<string>();
+  for (const sc of scenarios) {
+    for (const r of collectRefs(sc)) usedHeads.add(r.split(/[.[]/)[0]);
+    for (const t of sc.tags || []) {
+      const cm = t.match(/^@cases:(.+)$/);
+      if (cm) usedDatasets.add(cm[1].trim());
+      const om = t.match(/^@(?:api|query):[A-Za-z_]\w*\((.*)\)$/);
+      if (om) for (const ref of om[1].matchAll(/\{\{\s*([^}]+?)\s*\}\}/g)) usedHeads.add(ref[1].split(/[.[]/)[0].trim());
+    }
+  }
+  for (const k of topKeys) {
+    if (!usedHeads.has(k) && !usedDatasets.has(k)) {
+      warns.push({ message: `test-data key "${k}" is defined but never referenced ({{${k}}}, a @cases dataset, or an override) — dead data: bind it into a scenario or remove it.` });
+    }
+  }
+
   // Catalog-level lint (SELECT-only, params declared/used, datasource present).
   try {
     for (const e of lintCatalog(screenName, null, cwd).errors) warns.push({ message: e });

package/src/harness/flow-check.ts

@@ -49,17 +49,26 @@ function targetsFromHint(hint: string): string[] {
   return after.split(/[^a-z]+/).filter((w) => w.length > 3 && !['home', 'page', 'flow', 'products', 'product', 'result'].includes(w));
 }
 
-export function buildFlowCheck(cwd: string, onlyFlow?: string): FlowCheckReport {
-  const screens = listDirs(path.join(cwd, 'qa', 'screens'));
-  const flows = (onlyFlow ? [onlyFlow] : listDirs(path.join(cwd, 'qa', 'flows')));
+export interface FlowScenario { flow: string; name: string; haystack: string; deep: boolean }
 
-  // Index flow scenarios (name + haystack + depth).
-  const flowScenarios: { flow: string; name: string; haystack: string; deep: boolean }[] = [];
+/** Index every flow's scenarios (name + haystack + whether it carries a data assertion).
+ *  Shared so the screen audit can credit a cross-screen theme covered deeply by a flow (TQ-4). */
+export function loadFlowScenarios(cwd: string): FlowScenario[] {
+  const out: FlowScenario[] = [];
   for (const f of listDirs(path.join(cwd, 'qa', 'flows'))) {
     for (const s of loadScenarios(featurePath(cwd, 'flows', f))) {
-      flowScenarios.push({ flow: f, name: s.name, haystack: s.haystack, deep: s.hasDataAssertion });
+      out.push({ flow: f, name: s.name, haystack: s.haystack, deep: s.hasDataAssertion });
     }
   }
+  return out;
+}
+
+export function buildFlowCheck(cwd: string, onlyFlow?: string): FlowCheckReport {
+  const screens = listDirs(path.join(cwd, 'qa', 'screens'));
+  const flows = (onlyFlow ? [onlyFlow] : listDirs(path.join(cwd, 'qa', 'flows')));
+
+  // Index flow scenarios (name + haystack + depth).
+  const flowScenarios = loadFlowScenarios(cwd);
 
   // A. Deferral integrity (screens).
   const deferrals: Deferral[] = [];

package/src/harness/intent.ts

@@ -21,18 +21,29 @@ export interface IntentProfile {
   focus: IntentFocus;
   riskTier: 'high' | 'normal' | 'low';
   tierScope: 'tier-1' | 'full';
+  /** End-user override (AO-6): HTTP methods the API gate treats as business-critical (depth-required).
+   *  Default (undefined → the gate's POST/PUT/PATCH/DELETE) lets a project mark e.g. GET as critical. */
+  businessCriticalMethods?: string[];
+  /** TQ-10: surface "enable driver X to automate N @manual" suggestions (recommend-only). Default on;
+   *  set `capability_suggestions: off` in qa/context.md to silence. */
+  capabilitySuggestions: boolean;
   source: 'context.md' | 'default';
 }
 
 const DEFAULT_INTENT: IntentProfile = {
-  focus: 'functional', riskTier: 'normal', tierScope: 'full', source: 'default',
+  focus: 'functional', riskTier: 'normal', tierScope: 'full', capabilitySuggestions: true, source: 'default',
 };
 
 const FOCI: IntentFocus[] = ['functional', 'e-commerce', 'security', 'smoke'];
 
 /** Resolve project root from a screen/flow dir (…/qa/screens/<name>). */
 export function projectRootFromScreenDir(screenDir: string): string {
-  return path.resolve(screenDir, '..', '..', '..');
+  // The project root is the parent of the `qa/` dir — depth-agnostic, so it works for screens/flows
+  // (qa/screens/<x>, 3 deep) AND api flows (qa/api/flows/<flow>, 4 deep). A fixed `../../..` returned
+  // `<root>/qa` for the deeper api-flow path, breaking catalog resolution (cwd off by one).
+  const parts = screenDir.split(path.sep);
+  const qa = parts.lastIndexOf('qa');
+  return qa > 0 ? parts.slice(0, qa).join(path.sep) : path.resolve(screenDir, '..', '..', '..');
 }
 
 export function readIntent(projectRoot: string): IntentProfile {
@@ -45,6 +56,13 @@ export function readIntent(projectRoot: string): IntentProfile {
     const m = text.match(new RegExp(`(?:^|\\n)\\s*${key}\\s*:\\s*([a-z0-9-]+)`));
     return m?.[1];
   };
+  // A comma/space/slash list (e.g. `business_critical_methods: post, put, patch, delete, get`).
+  const grabList = (key: string): string[] | undefined => {
+    const m = text.match(new RegExp(`(?:^|\\n)\\s*${key}\\s*:\\s*([a-z0-9,\\s/-]+)`));
+    if (!m) return undefined;
+    const items = m[1].split(/[,\s/]+/).map((s) => s.trim().toUpperCase()).filter(Boolean);
+    return items.length ? items : undefined;
+  };
 
   const focusRaw = grab('focus');
   const focus = (FOCI.includes(focusRaw as IntentFocus) ? focusRaw : DEFAULT_INTENT.focus) as IntentFocus;
@@ -53,6 +71,9 @@ export function readIntent(projectRoot: string): IntentProfile {
   const scope = grab('tier_scope');
   const tierScope = (['tier-1', 'full'].includes(scope as string) ? scope : DEFAULT_INTENT.tierScope) as IntentProfile['tierScope'];
 
-  const found = focusRaw || risk || scope;
-  return { focus, riskTier, tierScope, source: found ? 'context.md' : 'default' };
+  const businessCriticalMethods = grabList('business_critical_methods');
+  const capRaw = grab('capability_suggestions');
+  const capabilitySuggestions = capRaw !== 'off'; // default on; only an explicit `off` silences it
+  const found = focusRaw || risk || scope || businessCriticalMethods || capRaw;
+  return { focus, riskTier, tierScope, businessCriticalMethods, capabilitySuggestions, source: found ? 'context.md' : 'default' };
 }

package/src/harness/ledger.ts

@@ -13,6 +13,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { reportSlug } from './unit-paths';
 
 export interface LedgerEvent {
   ts: string;
@@ -60,7 +61,7 @@ export function latestRunEvents(events: LedgerEvent[]): LedgerEvent[] {
 }
 
 function ledgerPath(screen: string): string {
-  return path.join(process.cwd(), '.sungen', 'ledger', `${screen}.jsonl`);
+  return path.join(process.cwd(), '.sungen', 'ledger', `${reportSlug(screen)}.jsonl`);
 }
 
 export function recordEvent(screen: string, ev: Omit<LedgerEvent, 'ts'> & { ts?: string }): string {
@@ -117,7 +118,7 @@ export function buildReport(screen: string, opts: { allRuns?: boolean } = {}): L
   // Pull audit signals if present
   let coveredCritical: number | null = null;
   let scenarioCount: number | null = null;
-  const auditPath = path.join(process.cwd(), '.sungen', 'reports', `${screen}-audit.json`);
+  const auditPath = path.join(process.cwd(), '.sungen', 'reports', `${reportSlug(screen)}-audit.json`);
   if (fs.existsSync(auditPath)) {
     try {
       const a = JSON.parse(fs.readFileSync(auditPath, 'utf-8'));

package/src/harness/manifest.ts

@@ -11,6 +11,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { createHash } from 'crypto';
+import { featureBasename, reportSlug } from './unit-paths';
 
 export interface SpecSection { name: string; hash: string }
 export interface ManifestEntry { scenario: string; vpCode?: string; section: string; specHash: string }
@@ -97,7 +98,7 @@ function parseFeatureSections(featurePath: string): { scenario: string; vpCode?:
 
 export function buildManifest(screenDir: string, screenName: string): Manifest {
   const specPath = path.join(screenDir, 'requirements', 'spec.md');
-  const featurePath = path.join(screenDir, 'features', `${screenName}.feature`);
+  const featurePath = path.join(screenDir, 'features', `${featureBasename(screenName)}.feature`);
   const specSections = parseSpecSections(specPath);
   const specMap: Record<string, string> = {};
   for (const s of specSections) specMap[s.name] = s.hash;
@@ -159,7 +160,7 @@ export function diffManifest(screenDir: string, screenName: string, manifest: Ma
 }
 
 export function manifestPath(screenName: string): string {
-  return path.join(process.cwd(), '.sungen', 'manifest', `${screenName}.json`);
+  return path.join(process.cwd(), '.sungen', 'manifest', `${reportSlug(screenName)}.json`);
 }
 export function loadManifest(screenName: string): Manifest | null {
   const p = manifestPath(screenName);

package/src/harness/parse.ts

@@ -33,6 +33,7 @@ export interface ScenarioInfo {
   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)
+  requiresCaps?: string[];    // @requires:<cap> — automation-ready but needs an opt-in driver (TQ-11)
 }
 
 /** Format-tolerant: is this token an ID (project's scheme), not a prose word?
@@ -112,6 +113,8 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
   // 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]); }
+  // @requires:<cap> — automation-ready, needs an opt-in driver (TQ-11).
+  const requiresCaps = tags.filter((t) => /^@requires:/i.test(t)).map((t) => t.slice('@requires:'.length).trim().toLowerCase()).filter(Boolean);
   let priority: Priority = 'unknown';
   for (const t of tags) if (PRIORITY_TAGS[t]) priority = PRIORITY_TAGS[t];
 
@@ -169,6 +172,7 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
     casesDataset,
     queryRefs: queryRefs.size ? [...queryRefs] : undefined,
     apiRefs: apiRefs.size ? [...apiRefs] : undefined,
+    requiresCaps: requiresCaps.length ? requiresCaps : undefined,
   };
 }
 

package/src/harness/quality-gates.ts

@@ -85,7 +85,7 @@ export function negativeSideEffect(scenarios: ScenarioInfo[]): string[] {
   for (const s of scenarios) {
     if (s.manual) continue;                 // @manual is a legitimate deferral (oracle checked by #4 manual-oracle)
     if (!NEG_TITLE.test(s.name)) continue;
-    const proven = /\bcount\b|tohavecount|table with|is hidden|are hidden|not complete|message is hidden/.test(s.stepsText);
+    const proven = /\bcount\b|ok_count|status_counts|tohavecount|table with|is hidden|are hidden|not complete|message is hidden/.test(s.stepsText);
     if (!proven) flagged.push(s.name.slice(0, 80));
   }
   return flagged;

package/src/harness/repair.ts

@@ -0,0 +1,75 @@
+/**
+ * Repair planner (#343) — the consumer of the `repair` capability SPI.
+ *
+ * Gathers the unit-capability's fix rules and matches them against the audit findings (always) and
+ * the latest Playwright failures (best-effort), turning them into a concrete fix plan. Deterministic:
+ * the AI repair loop and a human get the same proposals. Backs `sungen repair`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { capabilityRegistry } from '../capabilities/registry';
+import { discoverAndRegisterCapabilities } from '../capabilities/discover';
+import { scoringCapabilityFor } from './audit';
+
+export interface RepairProposal { source: 'audit' | 'runtime'; signal: string; ruleId: string; fix: string }
+export interface RepairPlan {
+  capability: string | undefined;
+  rulesAvailable: number;
+  proposals: RepairProposal[];
+  unmatched: string[];     // findings/failures with no matching rule (need a human)
+}
+
+/** Collect failure messages from a Playwright JSON result file (best-effort, defensive). */
+function failuresFromResult(file: string): string[] {
+  const out: string[] = [];
+  try {
+    const r = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const visit = (suite: any) => {
+      for (const sp of suite.specs ?? []) {
+        for (const t of sp.tests ?? []) {
+          for (const res of t.results ?? []) {
+            if (res.status === 'failed' || res.status === 'timedOut') {
+              const msg = res.error?.message || res.errors?.[0]?.message || res.status;
+              out.push(`${sp.title}: ${String(msg).split('\n')[0].slice(0, 200)}`);
+            }
+          }
+        }
+      }
+      for (const s of suite.suites ?? []) visit(s);
+    };
+    for (const s of r.suites ?? []) visit(s);
+  } catch { /* missing/!json → no runtime signals */ }
+  return out;
+}
+
+/**
+ * Build the repair plan for a unit.
+ * @param unitId      capability-resolution id (`api/<area>`, `flows/<flow>`, or a screen)
+ * @param reportName  the bare name used for `.sungen/reports/<name>-audit.json` (+ test-result)
+ * @param generatedDir the unit's specs/generated dir (for runtime failures); optional
+ */
+export function planRepair(unitId: string, reportName: string, cwd: string, generatedDir?: string): RepairPlan {
+  discoverAndRegisterCapabilities();
+  const capId = scoringCapabilityFor(unitId, capabilityRegistry.defaultCapabilityId());
+  const rules = (capId ? capabilityRegistry.get(capId)?.repair?.rules : undefined) ?? [];
+
+  const signals: { source: 'audit' | 'runtime'; text: string }[] = [];
+  const auditPath = path.join(cwd, '.sungen', 'reports', `${reportName}-audit.json`);
+  if (fs.existsSync(auditPath)) {
+    try { for (const f of JSON.parse(fs.readFileSync(auditPath, 'utf8')).findings ?? []) signals.push({ source: 'audit', text: String(f) }); } catch { /* ignore */ }
+  }
+  if (generatedDir && fs.existsSync(generatedDir)) {
+    for (const f of fs.readdirSync(generatedDir)) {
+      if (/test-result.*\.json$/.test(f)) for (const msg of failuresFromResult(path.join(generatedDir, f))) signals.push({ source: 'runtime', text: msg });
+    }
+  }
+
+  const proposals: RepairProposal[] = [];
+  const unmatched: string[] = [];
+  for (const s of signals) {
+    const rule = rules.find((r) => r.match.test(s.text));
+    if (rule) proposals.push({ source: s.source, signal: s.text, ruleId: rule.id, fix: rule.fix });
+    else unmatched.push(s.text);
+  }
+  return { capability: capId, rulesAvailable: rules.length, proposals, unmatched };
+}

package/src/harness/script-check.ts

@@ -16,6 +16,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { loadScenarios, ScenarioInfo } from './parse';
+import { featureBasename } from './unit-paths';
 
 export interface ScriptCheckResult {
   screen: string;
@@ -67,6 +68,9 @@ export function analyzeFaithfulness(specSrc: string, automatedTitles: Set<string
   const hollowSteps: { test: string; step: string }[] = [];
   for (const blk of extractTestBlocks(specSrc)) {
     if (!automatedTitles.has(blk.title)) continue; // only non-@manual scenarios
+    // TQ-11 — a capability-pending @requires scenario compiles to a `test.skip(true, …)` stub:
+    // it intentionally proves nothing here (it runs once the driver is added), so it is not a bypass.
+    if (blk.body.some((l) => /\btest\.skip\(\s*true\b/.test(l))) continue;
     const body = blk.body;
     // An assertion is a Playwright `expect(...)` OR a Data Driver DB assertion
     // (`db.assertRow/assertNoRow/assertCount/...`) — a DB check is a real oracle, so a
@@ -106,9 +110,18 @@ function normalize(src: string): string {
     .trim();
 }
 
-function findSpec(dir: string, name: string, flowMode: boolean): string | null {
+/** The unit kind — drives the generated-spec subdir + the qa source dir. */
+export type UnitKind = 'screen' | 'flow' | 'api';
+
+/** Generated-spec subdir for a unit: screen → <name>, flow → flows/<name>, api → api/<name>. */
+function specSubdir(dir: string, name: string, kind: UnitKind): string {
+  return kind === 'flow' ? path.join(dir, 'flows', name) : kind === 'api' ? path.join(dir, 'api', name) : path.join(dir, name);
+}
+
+function findSpec(dir: string, name: string, kind: UnitKind): string | null {
   // Screens compile to  <dir>/<name>/<feature>.spec.ts
   // Flows   compile to  <dir>/flows/<name>/<feature>.spec.ts
+  // Api     compile to  <dir>/api/<name>/<feature>.spec.ts
   // Scope the search to THIS target's own subdir — otherwise the first spec of
   // ANY other screen/flow is returned, which (for an uncompiled flow) falsely
   // reports the wrong screen's tests as drift.
@@ -121,19 +134,19 @@ function findSpec(dir: string, name: string, flowMode: boolean): string | null {
       else if (e.name.endsWith('.spec.ts')) hits.push(p);
     }
   };
-  const scoped = flowMode ? path.join(dir, 'flows', name) : path.join(dir, name);
+  const scoped = specSubdir(dir, name, kind);
   if (!fs.existsSync(scoped)) return null; // no spec for this target (e.g. not compiled yet)
   walk(scoped);
   return hits[0] ?? null;
 }
 
-export async function runScriptCheck(screenDir: string, screenName: string, flowMode: boolean): Promise<ScriptCheckResult> {
-  const featurePath = path.join(screenDir, 'features', `${screenName}.feature`);
+export async function runScriptCheck(screenDir: string, screenName: string, kind: UnitKind): Promise<ScriptCheckResult> {
+  const featurePath = path.join(screenDir, 'features', `${featureBasename(screenName)}.feature`);
   const scenarios = loadScenarios(featurePath);
   const automated = scenarios.filter((s) => !s.manual);
   const manual = scenarios.filter((s) => s.manual);
 
-  const committedSpec = findSpec(path.join(process.cwd(), 'specs', 'generated'), screenName, flowMode);
+  const committedSpec = findSpec(path.join(process.cwd(), 'specs', 'generated'), screenName, kind);
 
   const findings: string[] = [];
   let specTitles: string[] = [];
@@ -167,10 +180,14 @@ export async function runScriptCheck(screenDir: string, screenName: string, flow
     try {
       const { CodeGenerator } = require('../generators/test-generator/code-generator');
       const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'sungen-scriptcheck-'));
-      const qaSourceDir = path.join(process.cwd(), 'qa', flowMode ? 'flows' : 'screens');
-      const gen = new CodeGenerator({ framework: 'playwright', screenName, runtimeData: true, flowMode });
+      const qaSourceDir = path.join(process.cwd(), 'qa', kind === 'flow' ? 'flows' : kind === 'api' ? 'api' : 'screens');
+      // api units derive their unit id (api/<area>) from the feature path — like `generate --api`;
+      // screen/flow pass screenName + flowMode explicitly (unchanged → byte-identical regenerate).
+      const gen = kind === 'api'
+        ? new CodeGenerator({ framework: 'playwright', runtimeData: true })
+        : new CodeGenerator({ framework: 'playwright', screenName, runtimeData: true, flowMode: kind === 'flow' });
       await gen.generateAllTests(qaSourceDir, tmp, [featurePath]);
-      const fresh = findSpec(tmp, screenName, flowMode);
+      const fresh = findSpec(tmp, screenName, kind);
       if (fresh) {
         const a = normalize(specSrc);
         const b = normalize(fs.readFileSync(fresh, 'utf-8'));

package/src/harness/sensors.ts

@@ -111,6 +111,11 @@ export interface DepthResult {
   businessCriticalShallow: number;   // = depth-required scenarios that are shallow
   bcDepthRatio: number;              // fraction of depth-required scenarios with a real data assertion
   shallowBusinessCritical: { name: string; category?: string }[];
+  // @manual scenarios that would be business-critical if automated (match a data-theme).
+  // They are EXCLUDED from bcDepthRatio, so deferring them to @manual collapses the
+  // denominator and inflates the ratio toward 1.0 — reported so a high ratio on a tiny
+  // denominator isn't misread as "all good" (TQ-3).
+  deferredBusinessCritical: number;
   // Depth-as-Gate (harness-roadmap P1)
   focus: string;                     // intent focus driving the threshold
   threshold: number;                 // required bcDepthRatio for this focus
@@ -124,6 +129,16 @@ const DEPTH_THRESHOLDS: Record<string, number> = {
 };
 const WARN_ONLY_FOCUS = new Set(['smoke']);
 
+/** The required businessDepth ratio for a focus (default `functional` = 0.7). Shared so a capability
+ *  gate (e.g. the API gate, which computes its own depth) uses the SAME thresholds as the UI gate. */
+export function depthThresholdFor(focus: string): number {
+  return DEPTH_THRESHOLDS[focus] ?? DEPTH_THRESHOLDS.functional;
+}
+/** Whether a depth miss only WARNs (vs FAILs) for a focus (smoke). */
+export function depthWarnOnly(focus: string): boolean {
+  return WARN_ONLY_FOCUS.has(focus);
+}
+
 /**
  * Depth = do DATA-correctness scenarios actually assert DATA (not just visibility)?
  * "Depth-required" is CATALOG-DRIVEN: only scenarios matching a theme whose
@@ -151,6 +166,8 @@ export function assertionDepth(
 
   const required = nonManual.filter(isDepthRequired);
   const reqShallow = required.filter((s) => s.shallow);
+  // Business-critical scenarios deferred to @manual (match a data-theme but excluded above).
+  const deferredBusinessCritical = scenarios.filter((s) => s.manual && isDepthRequired(s)).length;
   // No data-theme scenarios on this screen → depth is not the binding constraint
   // (the viewpoint gate already flags missing data themes). Don't double-penalize.
   const ratio = required.length ? 1 - reqShallow.length / required.length : 1;
@@ -167,12 +184,64 @@ export function assertionDepth(
     businessCriticalShallow: reqShallow.length,
     bcDepthRatio: ratio,
     shallowBusinessCritical: reqShallow.map((s) => ({ name: s.name, category: s.category })),
+    deferredBusinessCritical,
     focus,
     threshold,
     verdict,
   };
 }
 
+// ---------- Sensor 2b: Automatable-@manual (TQ-2) ----------
+
+export interface AutomatableManualResult {
+  manualTotal: number;                                  // all @manual scenarios
+  automatable: number;                                  // @manual that are actually automatable
+  scenarios: { name: string; category?: string }[];     // the automatable ones (to surface)
+}
+
+// Genuine-judgment markers (M6/M8/M9 territory): visual/responsive/a11y/mock/network/
+// external/empty-state — these legitimately stay @manual (or need a future driver).
+const JUDGMENT_MARKER =
+  /\b(visual|responsive|layout|breakpoint|mobile|tablet|viewport|accessib|a11y|keyboard|screen reader|focus order|\baria\b|empty[- ]?(state|product|list|category|cart)|no[- ]?result|missing (image|product|data)|placeholder|fallback|slow|failing|offline|network|loading|spinner|external|new tab|video tutorial|email|mailbox|download|payment gateway|exploratory|not worth)\b/;
+
+/**
+ * Automatable-@manual (TQ-2) — a `@manual` scenario whose steps are fully DSL-expressible
+ * (it carries a real data assertion) and shows no genuine-judgment marker is *automatable*:
+ * it was deferred (typically cross-screen → a flow) rather than truly un-automatable. Leaving
+ * it `@manual` creates a non-running duplicate AND inflates businessDepth (it's excluded from
+ * the ratio). The UI analog of the API driver's `api-manual-automatable`.
+ */
+export function automatableManual(scenarios: ScenarioInfo[]): AutomatableManualResult {
+  const manual = scenarios.filter((s) => s.manual);
+  const automatable = manual.filter((s) => s.hasDataAssertion && !JUDGMENT_MARKER.test(s.haystack));
+  return {
+    manualTotal: manual.length,
+    automatable: automatable.length,
+    scenarios: automatable.map((s) => ({ name: s.name, category: s.category })),
+  };
+}
+
+// ---------- TQ-4: deferral-aware coverage credit ----------
+
+/**
+ * Which of the given gate gap-themes are deeply covered by a FLOW scenario (a cross-screen
+ * deferral the flow actually fulfils). Returns theme → covering flow. The screen audit uses
+ * this to credit an inherently-cross-screen theme to the flow that owns it, instead of
+ * double-counting it as a screen gap. A flow scenario covers a theme when its haystack hits
+ * the theme keywords AND it carries a data assertion (`deep`).
+ */
+export function flowCoveredThemes(
+  gaps: { theme: string; keywords: string[] }[],
+  flowScenarios: { flow: string; haystack: string; deep: boolean }[],
+): { theme: string; flow: string }[] {
+  const out: { theme: string; flow: string }[] = [];
+  for (const g of gaps) {
+    const hit = flowScenarios.find((s) => s.deep && g.keywords.some((k) => s.haystack.includes(k.toLowerCase())));
+    if (hit) out.push({ theme: g.theme, flow: hit.flow });
+  }
+  return out;
+}
+
 /** Collect data-correctness themes (depth.requires) for a page-type + universal. */
 export function dataThemesFor(catalog: Catalog, pageType: string | null): CatalogTheme[] {
   const themes: CatalogTheme[] = [];
@@ -384,8 +453,8 @@ const CLAIM_RULES: ClaimRule[] = [
     // "double-click does not create two orders" — not a per-feature keyword.
     claim: 'no-side-effect/no-duplicate',
     title: /(?=.*\b(submit|sen[dt]|resend|resubmit|re-?fire|re-?issue|re-?post|repost|create|charge|order|payment|\bpay\b|email|request|\botp\b|insert|register|book|duplicate|double[- ]?submit|again|twice)\b)(?=.*(\bno\b|\bnot\b|n['’]t\b|\bnever\b|\bwithout\b|\bcannot\b|prevent|block|avoid|reject|disabl|\bdeny\b|denies|\bkhông\b|\bchưa\b))/i,
-    proof: /\bcount\b|row with \{\{|table with|tohavecount|is hidden|are hidden|not complete|no longer/,
-    need: 'a record/request-count proof (count stays at one, e.g. `User see [Table] row with {{count}}`) or @manual with a request-count oracle',
+    proof: /\bcount\b|ok_count|status_counts|row with \{\{|table with|tohavecount|is hidden|are hidden|not complete|no longer/,
+    need: 'a record/request-count proof (count stays at one, e.g. `User see [Table] row with {{count}}`, an API `{{name.ok_count}}` invariant, or a `@query` DB count) or @manual with a request-count oracle',
     hint: 'a "does-not-happen / does-not-repeat" claim about a state-changing action is NOT proven by a terminal `see [...] page` — that page is identical whether or not the action (re-)fired. Prove the side-effect count is unchanged, or mark @manual with a setup→action→assert-no-duplicate oracle.',
     severity: 'fail',
   },

package/src/harness/trace.ts

@@ -13,6 +13,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { reportSlug } from './unit-paths';
 import { segmentRuns, latestRunEvents, LedgerEvent } from './ledger';
 
 interface ManualItem { scenario: string; reason: string }
@@ -22,7 +23,7 @@ function readJson(p: string): any | null {
 }
 
 function readLedger(screen: string): any[] {
-  const p = path.join(process.cwd(), '.sungen', 'ledger', `${screen}.jsonl`);
+  const p = path.join(process.cwd(), '.sungen', 'ledger', `${reportSlug(screen)}.jsonl`);
   if (!fs.existsSync(p)) return [];
   return fs.readFileSync(p, 'utf-8').split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
 }
@@ -76,7 +77,7 @@ export function buildTrace(screenDir: string, screenName: string): TraceReport {
   const recordedSteps = [...new Set(ledger.map((e) => e.step.replace(/:\d+$/, '')))];
   const missingSteps = EXPECTED_PHASES.filter((p) => !recordedSteps.includes(p));
 
-  const auditRaw = readJson(path.join(process.cwd(), '.sungen', 'reports', `${screenName}-audit.json`));
+  const auditRaw = readJson(path.join(process.cwd(), '.sungen', 'reports', `${reportSlug(screenName)}-audit.json`));
   let audit: TraceReport['audit'] = null;
   if (auditRaw) {
     const subs: Record<string, number> = {
@@ -91,7 +92,7 @@ export function buildTrace(screenDir: string, screenName: string): TraceReport {
     };
   }
 
-  const scRaw = readJson(path.join(process.cwd(), '.sungen', 'reports', `${screenName}-script-check.json`));
+  const scRaw = readJson(path.join(process.cwd(), '.sungen', 'reports', `${reportSlug(screenName)}-script-check.json`));
   const drift = scRaw ? scRaw.drift : null;
 
   const manual = parseManual(path.join(screenDir, 'features', `${screenName}.feature`));

package/src/harness/unit-paths.ts

@@ -0,0 +1,14 @@
+/**
+ * Unit-path helpers (api-flow fix). A unit id may be a bare name (`orders`, `login`) or a nested
+ * api-flow id (`flows/<flow>`). Two derivations the harness/CLI need:
+ *  - featureBasename: the `.feature` filename — the LAST path segment (`flows/x` → `x`), so
+ *    `<dir>/features/<basename>.feature` resolves (the bug: the full id looked for
+ *    `features/flows/x.feature` → 0 scenarios).
+ *  - reportSlug: a flat key for `.sungen/reports/<slug>-*.json` + `.sungen/ledger/<slug>.jsonl`
+ *    (`flows/x` → `flows-x`), so artifacts never nest under a `flows/` subdir and read/write agree.
+ * Bare names (no slash) are unchanged by both → no regression for screens/flows/areas.
+ */
+import * as path from 'path';
+
+export const featureBasename = (unit: string): string => path.basename(unit);
+export const reportSlug = (unit: string): string => unit.replace(/[\\/]+/g, '-');

package/src/index.ts

@@ -8,7 +8,9 @@
 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';
+export type { Context, DiscoveryProvider, ContextMapper, GenerationUnit, RepairProvider, RepairRule } from './capabilities/context';
+export { discoverUnitContext } from './orchestrator/context-discovery';
+export type { DiscoveredContext } from './orchestrator/context-discovery';
 
 // --- Step-pattern authoring (a driver contributes step patterns via its descriptor) ---
 export type { PatternContext, StepPattern, StepTemplateData } from './generators/test-generator/patterns/types';
@@ -25,6 +27,6 @@ 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 { loadCatalog, viewpointGate, assertionDepth, dataThemesFor, depthThresholdFor, depthWarnOnly } from './harness/sensors';
 export type { Catalog, GateResult, DepthResult } from './harness/sensors';
 export type { ScenarioInfo, ViewpointEntry } from './harness/parse';

package/src/orchestrator/ai-rules-updater.ts

@@ -47,6 +47,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['claude-skill-selector-fix.md', '.claude/skills/sungen-selector-fix/SKILL.md'],
   ['claude-skill-tc-review.md', '.claude/skills/sungen-tc-review/SKILL.md'],
   ['claude-skill-harness-audit.md', '.claude/skills/sungen-harness-audit/SKILL.md'],
+  ['claude-skill-api-design.md', '.claude/skills/sungen-api-design/SKILL.md'],
   ['claude-skill-ingest-legacy.md', '.claude/skills/sungen-ingest-legacy/SKILL.md'],
   ['claude-skill-viewpoint.md', '.claude/skills/sungen-viewpoint/SKILL.md'],
   ['claude-skill-viewpoint-group-a-data-entry.md', '.claude/skills/sungen-viewpoint/group-a-data-entry.md'],
@@ -79,6 +80,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['github-skill-sungen-selector-fix.md', '.github/skills/sungen-selector-fix/SKILL.md'],
   ['github-skill-sungen-tc-review.md', '.github/skills/sungen-tc-review/SKILL.md'],
   ['github-skill-sungen-harness-audit.md', '.github/skills/sungen-harness-audit/SKILL.md'],
+  ['github-skill-sungen-api-design.md', '.github/skills/sungen-api-design/SKILL.md'],
   ['github-skill-sungen-ingest-legacy.md', '.github/skills/sungen-ingest-legacy/SKILL.md'],
   ['github-skill-sungen-viewpoint.md', '.github/skills/sungen-viewpoint/SKILL.md'],
   ['github-skill-sungen-viewpoint-group-a-data-entry.md', '.github/skills/sungen-viewpoint/group-a-data-entry.md'],