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

package/src/cli/commands/script-check.ts

@@ -2,28 +2,32 @@ import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
 import { runScriptCheck } from '../../harness/script-check';
+import { reportSlug } from '../../harness/unit-paths';
 
 export function registerScriptCheckCommand(program: Command): void {
   program
     .command('script-check')
     .description('Verify the generated Playwright spec is a faithful 1:1 of the Gherkin feature (no hand-edit / stale drift)')
     .option('-s, --screen <name>', 'Screen or flow name')
+    .option('--api <name>', 'API-first area or api flow (qa/api/<name>)')
+    .option('--area <name>', 'Alias of --api — an API-first area (qa/api/<name>)')
     .option('--json', 'Output raw JSON')
     .action(async (options) => {
       try {
-        const name = options.screen;
-        if (!name) throw new Error('Provide --screen <name>');
+        const name = options.screen || options.api || options.area;
+        if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
         const screen = path.join(process.cwd(), 'qa', 'screens', name);
         const flow = path.join(process.cwd(), 'qa', 'flows', name);
-        const flowMode = !fs.existsSync(screen) && fs.existsSync(flow);
-        const dir = fs.existsSync(screen) ? screen : (fs.existsSync(flow) ? flow : null);
-        if (!dir) throw new Error(`Screen/flow not found: ${name}`);
+        const api = path.join(process.cwd(), 'qa', 'api', name);
+        const kind = fs.existsSync(screen) ? 'screen' : fs.existsSync(flow) ? 'flow' : fs.existsSync(api) ? 'api' : null;
+        const dir = kind === 'screen' ? screen : kind === 'flow' ? flow : kind === 'api' ? api : null;
+        if (!dir || !kind) throw new Error(`Not found: qa/screens|flows|api/${name}`);
 
-        const r = await runScriptCheck(dir, name, flowMode);
+        const r = await runScriptCheck(dir, name, kind);
 
         const outDir = path.join(process.cwd(), '.sungen', 'reports');
         fs.mkdirSync(outDir, { recursive: true });
-        fs.writeFileSync(path.join(outDir, `${name}-script-check.json`), JSON.stringify(r, null, 2), 'utf-8');
+        fs.writeFileSync(path.join(outDir, `${reportSlug(name)}-script-check.json`), JSON.stringify(r, null, 2), 'utf-8');
 
         if (options.json) { console.log(JSON.stringify(r, null, 2)); process.exit(r.status === 'OK' ? 0 : 2); }
 
@@ -39,7 +43,7 @@ export function registerScriptCheckCommand(program: Command): void {
         if (r.findings.length) { L('  findings:'); for (const f of r.findings) L(`    • ${f}`); }
         else L('  ✓ The test code faithfully reflects the Gherkin (1:1).');
         L('');
-        if (r.drift === 'drift') L('  → Fix: re-run `sungen generate --screen ' + name + '` (or /sungen:run-test) so the spec matches the feature. Never hand-edit generated specs.');
+        if (r.drift === 'drift') L(`  → Fix: re-run \`sungen generate --${kind === 'api' ? 'api' : kind === 'flow' ? 'flow' : 'screen'} ${name}\` (or /sungen:run-test) so the spec matches the feature. Never hand-edit generated specs.`);
         L('');
         process.exit(r.status === 'OK' ? 0 : 2);
       } catch (error) {

package/src/cli/commands/trace.ts

@@ -8,16 +8,19 @@ export function registerTraceCommand(program: Command): void {
     .command('trace')
     .description('Visualise the executed test-design process (workflow/skill steps, repair loops), find bottlenecks, and show where to focus human review')
     .option('-s, --screen <name>', 'Screen or flow name')
+    .option('--api <name>', 'API-first area or api flow (qa/api/<name>)')
+    .option('--area <name>', 'Alias of --api — an API-first area (qa/api/<name>)')
     .option('--json', 'Output raw JSON')
     .option('--mermaid', 'Print only the Mermaid flowchart')
     .action((options) => {
       try {
-        const name = options.screen;
-        if (!name) throw new Error('Provide --screen <name>');
+        const name = options.screen || options.api || options.area;
+        if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
         const screen = path.join(process.cwd(), 'qa', 'screens', name);
         const flow = path.join(process.cwd(), 'qa', 'flows', name);
-        const dir = fs.existsSync(screen) ? screen : (fs.existsSync(flow) ? flow : null);
-        if (!dir) throw new Error(`Screen/flow not found: ${name}`);
+        const api = path.join(process.cwd(), 'qa', 'api', name);
+        const dir = fs.existsSync(screen) ? screen : fs.existsSync(flow) ? flow : fs.existsSync(api) ? api : null;
+        if (!dir) throw new Error(`Not found: qa/screens|flows|api/${name}`);
 
         const r = buildTrace(dir, name);
         if (options.json) { console.log(JSON.stringify(r, null, 2)); return; }

package/src/cli/index.ts

@@ -26,6 +26,8 @@ import { registerChallengeCommand } from './commands/challenge';
 import { registerBlindspotCommand } from './commands/blindspot';
 import { registerCapabilityCommand } from './commands/capability';
 import { registerFlowCheckCommand } from './commands/flow-check';
+import { registerContextCommand } from './commands/context';
+import { registerRepairCommand } from './commands/repair';
 import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 
@@ -64,6 +66,8 @@ async function main() {
   registerBlindspotCommand(program);
   registerCapabilityCommand(program);
   registerFlowCheckCommand(program);
+  registerContextCommand(program);
+  registerRepairCommand(program);
   registerIngestCommand(program);
   registerEvalCommand(program);
 

package/src/generators/test-generator/code-generator.ts

@@ -6,6 +6,7 @@ import { TestGeneratorAdapter, adapterRegistry } from './adapters';
 import { transformToRuntimeData } from './utils/runtime-data-transformer';
 import { capabilityRegistry } from '../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
+import { readCapabilities } from '../../harness/capability';
 
 /**
  * Filter base scenario steps for @extend: only keep Given→When steps.
@@ -88,6 +89,40 @@ function extractPassThroughTags(scenarioTags: string[], featureTags: string[]):
   return unique.map(t => `'${t}'`).join(', ');
 }
 
+/**
+ * Derive a feature's unit from its source path: the catalog-resolution id (relative to qa/), the
+ * output subdir, and whether it is a UI flow. Recognizes the api-first project model:
+ *   qa/screens/<screen>/features/…        → id `<screen>`            (subdir `<screen>`)
+ *   qa/flows/<flow>/features/…            → id `flows/<flow>`        (subdir `flows/<flow>`, isFlow)
+ *   qa/api/<area>/features/…              → id `api/<area>`          (subdir `api/<area>`)
+ *   qa/api/flows/<flow>/features/…        → id `api/flows/<flow>`    (subdir `api/flows/<flow>`)
+ * api-first units are NOT UI flows (no cross-screen namespacing) — they resolve their own api/db catalogs.
+ */
+function deriveUnitFromFeaturePath(sourceFile: string): { unitId: string; outputSubdir: string; isFlow: boolean } {
+  const parts = path.dirname(sourceFile).split(path.sep);
+  const qa = parts.lastIndexOf('qa');
+  if (qa >= 0 && parts[qa + 1] === 'api') {
+    if (parts[qa + 2] === 'flows' && parts[qa + 3]) {
+      const id = `api/flows/${parts[qa + 3]}`;
+      return { unitId: id, outputSubdir: id, isFlow: false };
+    }
+    if (parts[qa + 2]) {
+      const id = `api/${parts[qa + 2]}`;
+      return { unitId: id, outputSubdir: id, isFlow: false };
+    }
+  }
+  const flowsIndex = parts.indexOf('flows');
+  const screensIndex = parts.indexOf('screens');
+  if (flowsIndex >= 0 && flowsIndex < parts.length - 1) {
+    const f = parts[flowsIndex + 1];
+    return { unitId: `flows/${f}`, outputSubdir: `flows/${f}`, isFlow: true };
+  }
+  if (screensIndex >= 0 && screensIndex < parts.length - 1) {
+    return { unitId: parts[screensIndex + 1], outputSubdir: parts[screensIndex + 1], isFlow: false };
+  }
+  return { unitId: '', outputSubdir: '', isFlow: false };
+}
+
 /**
  * Check for @screenshot:on-failure tag
  */
@@ -141,6 +176,19 @@ function isManual(tags: string[]): boolean {
   return tags.some(tag => tag === '@manual');
 }
 
+/**
+ * Capabilities a scenario declares via `@requires:<cap>` (TQ-11) — automation-ready work that
+ * needs an opt-in driver (e.g. `@requires:db`, `@requires:api`). When the cap is enabled the
+ * scenario compiles to a real test; when absent it compiles to a clean `test.skip` stub (no
+ * driver imports) so the run never breaks and the case is visible as "pending capability".
+ */
+function requiresCaps(tags: string[]): string[] {
+  return tags
+    .filter(t => /^@requires:/i.test(t))
+    .map(t => t.slice('@requires:'.length).trim().toLowerCase())
+    .filter(Boolean);
+}
+
 /**
  * Check for multiple auth tags and log warning
  */
@@ -210,29 +258,16 @@ export class CodeGenerator {
       fileName = this.featureNameToFileName(feature.name);
     }
     
-    // Extract screen/flow name from source file path for output subdirectory
-    // qa/screens/{screenName}/features/{featureName}.feature -> screenName
-    // qa/flows/{flowName}/features/{featureName}.feature -> flows/flowName
-    let outputSubdir = '';
-    if (feature.sourceFile) {
-      const sourceDir = path.dirname(feature.sourceFile);
-      const parts = sourceDir.split(path.sep);
-      const flowsIndex = parts.indexOf('flows');
-      const screensIndex = parts.indexOf('screens');
-      if (flowsIndex >= 0 && flowsIndex < parts.length - 2) {
-        outputSubdir = path.join('flows', parts[flowsIndex + 1]);
-      } else if (screensIndex >= 0 && screensIndex < parts.length - 2) {
-        outputSubdir = parts[screensIndex + 1];
-      }
-    }
+    // Output subdirectory from the source path (screens / flows / api-first areas+flows).
+    const outputSubdir = feature.sourceFile ? deriveUnitFromFeaturePath(feature.sourceFile).outputSubdir : '';
 
     // Build output path with subdirectory
     const filePath = outputSubdir
       ? path.join(outputDir, outputSubdir, fileName)
       : path.join(outputDir, fileName);
 
-    // Compute relative path from output file back to specs/generated/
-    const depth = outputSubdir ? outputSubdir.split(path.sep).length : 0;
+    // Compute relative path from output file back to specs/generated/ (subdir uses '/').
+    const depth = outputSubdir ? outputSubdir.split('/').length : 0;
     const basePath = depth > 0 ? Array(depth).fill('..').join('/') : '..';
 
     // Serial + @cleanup tags → need cleanupPage import from base
@@ -336,12 +371,22 @@ export class CodeGenerator {
    */
   private capabilityPreconditions(scenario: ParsedScenario): Array<{ comment?: string; code: string; boundVars?: string[] }> {
     discoverAndRegisterCapabilities();
+    const tags = scenario.tags || [];
     const out: Array<{ comment?: string; code: string; boundVars?: string[] }> = [];
     for (const cap of capabilityRegistry.all()) {
       if (!cap.preconditionCodegen) continue;
-      out.push(...cap.preconditionCodegen({ tags: scenario.tags || [], screenName: this.queryScreenName, cwd: process.cwd() }));
-    }
-    return out;
+      out.push(...cap.preconditionCodegen({ tags, screenName: this.queryScreenName, cwd: process.cwd() }));
+    }
+    // Order by each precondition's annotation position on the scenario (not capability-registry order),
+    // so a cross-capability sequence runs as authored — e.g. `@api:pay @concurrent:2 @query:charge_count`
+    // mutates THEN reads the DB (the idempotency cross-check). Stable: ties keep their original order.
+    const pos = (p: { boundVars?: string[] }): number => {
+      const name = p.boundVars?.[0];
+      if (!name) return tags.length;
+      const i = tags.findIndex((t) => new RegExp(`^@\\w+:${name}\\b`).test(t));
+      return i < 0 ? tags.length : i;
+    };
+    return out.map((p, i) => ({ p, i })).sort((a, b) => pos(a.p) - pos(b.p) || a.i - b.i).map((x) => x.p);
   }
 
   /**
@@ -382,27 +427,23 @@ export class CodeGenerator {
       featureName = this.featureNameToFileName(feature.name).replace('.spec.ts', '');
     }
     
-    // Derive screen/flow name from source file path when not explicitly set
-    // qa/screens/{screenName}/features/{featureName}.feature -> screenName
-    // qa/flows/{flowName}/features/{featureName}.feature -> flowName
+    // Derive the unit from the source path when not explicitly set. `unitId` is the catalog/test-data
+    // resolution id relative to qa/ (`<screen>` · `flows/<flow>` · `api/<area>` · `api/flows/<flow>`);
+    // `effectiveScreenName` is the bare name for UI screen-context (selector/data namespacing).
     let effectiveScreenName = this.screenName;
     let isFlowFeature = !!this.options.flowMode;
+    let unitId = isFlowFeature ? `flows/${effectiveScreenName || ''}` : (effectiveScreenName || '');
     if (!this.screenName && feature.sourceFile) {
-      const sourceDir = path.dirname(feature.sourceFile);
-      const parts = sourceDir.split(path.sep);
-      const flowsIndex = parts.indexOf('flows');
-      const screensIndex = parts.indexOf('screens');
-      if (flowsIndex >= 0 && flowsIndex < parts.length - 2) {
-        effectiveScreenName = parts[flowsIndex + 1];
-        isFlowFeature = true;
-      } else if (screensIndex >= 0 && screensIndex < parts.length - 2) {
-        effectiveScreenName = parts[screensIndex + 1];
-        isFlowFeature = false;
+      const u = deriveUnitFromFeaturePath(feature.sourceFile);
+      if (u.unitId) {
+        unitId = u.unitId;
+        isFlowFeature = u.isFlow;
+        effectiveScreenName = u.unitId.split('/').pop() || u.unitId; // bare name (no api/ or flows/ prefix)
+        this.stepMapper.setScreenContext(effectiveScreenName);
       }
-      this.stepMapper.setScreenContext(effectiveScreenName);
     }
-    // Catalog-resolution screen name for @query binds (flows are prefixed `flows/`).
-    this.queryScreenName = isFlowFeature ? `flows/${effectiveScreenName}` : (effectiveScreenName || '');
+    // Catalog + test-data resolution id (flows → `flows/<flow>`, api-first → `api/<area>` / `api/flows/<flow>`).
+    this.queryScreenName = unitId;
 
     // Reset flow mode per feature to prevent state leak in --all mode
     this.stepMapper.setFlowMode(isFlowFeature);
@@ -466,6 +507,10 @@ export class CodeGenerator {
     // Generate all scenarios with feature tags for inheritance
     // Skip scenarios tagged with @manual
     // Track auth role per scenario for grouping
+    // TQ-11 — enabled capabilities (qa/capabilities.yaml): a @requires:<cap> scenario whose cap is
+    // absent compiles to a skip stub instead of a real test (read once per feature).
+    const enabledCaps = new Set<string>(readCapabilities(process.cwd()).enabled.map(d => d.toLowerCase()));
+
     const renderedScenarios: Array<{ code: string; authRole?: string }> = [];
     for (const scenario of feature.scenarios) {
       if (isManual(scenario.tags)) {
@@ -480,6 +525,16 @@ export class CodeGenerator {
         continue;
       }
 
+      // TQ-11 — @requires:<cap> with the cap NOT enabled → emit a clean skip stub (no driver
+      // imports, so the spec still loads), visible as skipped-with-reason. With the cap enabled it
+      // falls through and compiles as a real test.
+      const reqAbsent = requiresCaps(scenario.tags).filter(c => !enabledCaps.has(c));
+      if (reqAbsent.length) {
+        if (this.options.verbose) console.log(`  ⏸ Pending capability (${reqAbsent.join(', ')}): ${scenario.name}`);
+        renderedScenarios.push({ code: this.generateRequiresSkipStub(scenario.name, reqAbsent), authRole: undefined });
+        continue;
+      }
+
       // Resolve auth tags for @extend scenarios (same logic as generateScenario)
       let authFeatureTags = feature.tags || [];
       if (scenario.extendsName) {
@@ -553,7 +608,7 @@ export class CodeGenerator {
       cleanupConfig,
       screenshotOnFailure,
       runtimeData: this.options.runtimeData,
-      screenName: isFlowFeature ? `flows/${effectiveScreenName}` : effectiveScreenName,
+      screenName: this.queryScreenName, // catalog/test-data id (screen · flows/<flow> · api/<area>)
       featureFileName: featureName,
       isParallel,
       flowMode: isFlowFeature,
@@ -615,6 +670,21 @@ export class CodeGenerator {
     return renderMap[hookType]();
   }
 
+  /**
+   * TQ-11 — a `@requires:<cap>` scenario whose capability is NOT enabled. Emits a real `test()`
+   * that skips itself with an actionable reason, and references NO driver runtime (so the spec
+   * loads even though the driver isn't installed). Once the cap is added + regenerated, the
+   * scenario compiles to its full automated body instead.
+   */
+  private generateRequiresSkipStub(name: string, caps: string[]): string {
+    const reason = `requires ${caps.join(' + ')} — run \`sungen capability add ${caps.join(' ')}\` to automate this`;
+    return [
+      `  test(${JSON.stringify(name)}, async () => {`,
+      `    test.skip(true, ${JSON.stringify(reason)});`,
+      `  });`,
+    ].join('\n');
+  }
+
   private async generateScenario(
     scenario: ParsedScenario,
     hasBackground: boolean,
@@ -705,8 +775,8 @@ export class CodeGenerator {
       }
     }
 
-    // Capability preconditions (db `@query:<name>` → bind {{name}}; computed above) run BEFORE the
-    // scenario's own steps — prepend them, indenting the capability-supplied statements.
+    // Capability preconditions (db `@query:<name>` / api `@api:<name>` → bind {{name}}; computed
+    // above) run BEFORE the scenario's own steps — prepend them, indenting the capability statements.
     if (preconditions.length) {
       steps.unshift(...preconditions.map((p) => ({ comment: p.comment, code: this.indentCode(p.code, 4) })));
     }
@@ -729,7 +799,12 @@ export class CodeGenerator {
     // global `testData` transform that runs next on the rest of the file leaves it alone.
     // The loop header's `testData.cases()/withRow()` are literal code (no markers) → untouched.
     if (casesDataset && this.options.runtimeData) {
-      return transformToRuntimeData(rendered, 'rowData');
+      // AP-3: capability preconditions (`@api`/`@query`) and value assertions (`expect {{x}} is {{y}}`)
+      // emit LITERAL `testData.get/bind/set(…)` (not markers), so the marker transform above misses
+      // them. Rewrite those to the per-row `rowData` view — each row then fires its own `@api` call
+      // with that row's input and asserts that row's expected status/body (the success/failure matrix).
+      // `testData.cases()/withRow()` (the global loader, no `.get/.bind/.set`) is intentionally left alone.
+      return transformToRuntimeData(rendered, 'rowData').replace(/\btestData\.(get|bind|set)\(/g, 'rowData.$1(');
     }
     return rendered;
   }

package/src/harness/annotation-overrides.ts

@@ -3,7 +3,9 @@
  *
  * Parses `name(a={{x}},b="lit",c=3)` overrides into a map of JS expressions, e.g.
  * `{ a: "testData.get('x')", b: "\"lit\"", c: "3" }`. Used by the DB and API capability drivers'
- * precondition codegen; lives in core so both drivers (and core's `api` until R5.6) can share it.
+ * precondition codegen; lives in core so both drivers can share it. Gherkin tags carry no whitespace,
+ * so values are single tokens — flows thread a prior response via a whole-value ref, e.g.
+ * `@api:get_profile(token={{login.body.token}})`, with the auth scheme declared in the catalog header.
  */
 export function parseQueryOverrides(raw?: string): Record<string, string> {
   const out: Record<string, string> = {};

package/src/harness/audit.ts

@@ -9,10 +9,15 @@
 import * as path from 'path';
 import * as fs from 'fs';
 import { loadScenarios, parseViewpointOverview, ScenarioInfo, ViewpointEntry } from './parse';
+import { featureBasename } from './unit-paths';
 import {
-  loadCatalog, viewpointGate, assertionDepth, dataThemesFor, coverageBalance, duplicateClusters, traceability, claimProof, taxonomyLint,
-  GateResult, DepthResult, BalanceResult, DuplicateResult, TraceResult, ClaimProofResult, TaxonomyResult, Catalog,
+  loadCatalog, viewpointGate, assertionDepth, dataThemesFor, depthThresholdFor, coverageBalance, duplicateClusters, traceability, claimProof, taxonomyLint,
+  automatableManual, flowCoveredThemes,
+  GateResult, DepthResult, BalanceResult, DuplicateResult, TraceResult, ClaimProofResult, TaxonomyResult, Catalog, AutomatableManualResult,
 } from './sensors';
+import { loadFlowScenarios } from './flow-check';
+import { manualReasonMismatches, MANUAL_REASONS, buildPlan } from './capability-plan';
+import { readCapabilities } from './capability';
 import { readIntent, projectRootFromScreenDir, IntentProfile } from './intent';
 import { getProvenance, Provenance } from './provenance';
 import { specCoverage, SpecCoverageResult, parseSpecClauses } from './spec-coverage';
@@ -36,6 +41,7 @@ export interface AuditReport {
   taxonomyMismatch: boolean;    // scenarios use IDs not in the project's test-viewpoint.md
   downstream: DownstreamResult; // downstream screens referenced but under-covered
   manualOracle: ManualOracleResult; // @manual scenarios lacking setup/action/oracle
+  automatableManual: AutomatableManualResult; // @manual that is actually automatable (deferred, not judgment) — TQ-2
   ledger: LedgerResult;         // atomic viewpoint-item coverage (per-bullet status)
   calibration: {                // #8 — multi-axis score so a high overall can't hide a weak axis
     axes: Record<string, number>;
@@ -57,32 +63,84 @@ export interface AuditReport {
   spec: SpecCoverageResult;     // G2 — spec-clause coverage (FR + validation-trigger matrix)
 }
 
+/** The catalog-resolution id for a unit dir (relative to qa/): screen · flows/<flow> · api/<area> · api/flows/<flow>. */
+function catalogIdFromScreenDir(screenDir: string): string {
+  const parts = screenDir.split(path.sep);
+  const qa = parts.lastIndexOf('qa');
+  if (qa >= 0) {
+    if (parts[qa + 1] === 'api' && parts[qa + 2] === 'flows' && parts[qa + 3]) return `api/flows/${parts[qa + 3]}`;
+    if (parts[qa + 1] === 'api' && parts[qa + 2]) return `api/${parts[qa + 2]}`;
+    if (parts[qa + 1] === 'flows' && parts[qa + 2]) return `flows/${parts[qa + 2]}`;
+  }
+  return path.basename(screenDir);
+}
+
+/**
+ * The capability that owns SCORING for a unit (AO-1): the first path segment of the unit id when it
+ * is a registered capability (`api/<area>` → `api`), else the default (UI) capability. Generic — a
+ * future `mobile/<x>` or `perf/<x>` unit routes to that capability with no core change. `flows/<flow>`
+ * has no `flows` capability → default (UI), which is correct (flows are a UI concept).
+ */
+export function scoringCapabilityFor(catalogScreenName: string, defaultCap: string | undefined): string | undefined {
+  const seg = catalogScreenName.split('/')[0];
+  return seg && capabilityRegistry.get(seg) ? seg : defaultCap;
+}
+
 export function runAudit(screenDir: string, screenName: string): AuditReport {
-  const featurePath = path.join(screenDir, 'features', `${screenName}.feature`);
+  // The feature filename is the unit's LAST segment — an api flow (`flows/<flow>`) lives at
+  // `<dir>/features/<flow>.feature`, not `features/flows/<flow>.feature` (which found 0 scenarios).
+  const featurePath = path.join(screenDir, 'features', `${featureBasename(screenName)}.feature`);
   const viewpointPath = path.join(screenDir, 'requirements', 'test-viewpoint.md');
+  // Catalog-resolution id (for the @api/@query gate sensors): the unit's path relative to qa/ —
+  // `flows/<flow>`, `api/<area>`, `api/flows/<flow>`, else the bare screen. A bare screen matches
+  // the old behaviour (so the audit-sample snapshot is unchanged); flows/api now resolve correctly.
+  const catalogScreenName = catalogIdFromScreenDir(screenDir);
 
   const specPath = path.join(screenDir, 'requirements', 'spec.md');
   const featureText = fs.existsSync(featurePath) ? fs.readFileSync(featurePath, 'utf-8') : '';
 
   const scenarios: ScenarioInfo[] = loadScenarios(featurePath);
   const viewpoints: ViewpointEntry[] = parseViewpointOverview(viewpointPath);
-  // 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).
+  // AO-1 — capability-routed scoring: the viewpoint catalog + score-bearing gate are owned by the
+  // unit's capability, resolved from the unit id (`api/<area>` → `api`; screen/flow → the default
+  // UI capability). A capability that provides no catalog/gate falls back to the in-core UI
+  // functions, so UI units — and api units until AO-2 adds the api providers — are byte-identical.
   discoverAndRegisterCapabilities();
   const defaultCap = capabilityRegistry.defaultCapabilityId();
-  const catalog = ((defaultCap && capabilityRegistry.get(defaultCap)?.viewpoints?.()) as Catalog | undefined) || loadCatalog();
+  const scoringCapId = scoringCapabilityFor(catalogScreenName, defaultCap);
+  const scoringCap = scoringCapId ? capabilityRegistry.get(scoringCapId) : undefined;
+  const catalog = (scoringCap?.viewpoints?.() as Catalog | undefined) || loadCatalog();
   const spec = specCoverage(specPath, scenarios, featureText);
 
   // P3 — intent profile from qa/context.md drives the depth threshold (focus).
   const intent = readIntent(projectRootFromScreenDir(screenDir));
-  // 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 });
+  // The score-bearing gate (viewpoint coverage + assertion depth) is the scoring capability's
+  // `gateProvider`; same functions underneath → byte-identical gate/depth → identical score. Falls
+  // back to the in-core functions if the capability provides none.
+  // A capability gate may need project context (the API gate resolves endpoint methods from the
+  // catalog) + the focus depth threshold (so it scores depth with the SAME bar as the UI gate).
+  const capGate = scoringCap?.gateProvider as
+    ((i: { scenarios: ScenarioInfo[]; viewpoints: ViewpointEntry[]; catalog: Catalog; focus: typeof intent.focus; cwd: string; screenName: string; threshold: number; businessCriticalMethods?: string[] }) => { gate: GateResult; depth: DepthResult }) | undefined;
+  const provided = capGate?.({ scenarios, viewpoints, catalog, focus: intent.focus, cwd: projectRootFromScreenDir(screenDir), screenName: catalogScreenName, threshold: depthThresholdFor(intent.focus), businessCriticalMethods: intent.businessCriticalMethods });
   const gate = provided?.gate ?? viewpointGate(scenarios, viewpoints, catalog);
   const depth = provided?.depth ?? assertionDepth(scenarios, dataThemesFor(catalog, gate.pageType), intent.focus);
+
+  // TQ-4 — deferral-aware coverage credit: an inherently cross-screen theme (cart / detail /
+  // filter correctness) belongs in a FLOW, not on the screen. When a flow deeply covers a screen
+  // gate gap, credit it to the flow instead of double-counting it as a screen gap. Screens only
+  // (a flow/api unit is not credited by sibling flows); mutates the gate before coverage is scored.
+  const flowCredits: { theme: string; flow: string }[] = [];
+  const isScreenUnit = !/^(flows|api)\//.test(catalogScreenName);
+  if (isScreenUnit && gate.gaps.length) {
+    const flowScenarios = loadFlowScenarios(projectRootFromScreenDir(screenDir));
+    if (flowScenarios.length) {
+      for (const c of flowCoveredThemes(gate.gaps, flowScenarios)) {
+        const i = gate.gaps.findIndex((g) => g.theme === c.theme);
+        if (i >= 0) { gate.gaps.splice(i, 1); gate.themesCovered++; flowCredits.push(c); }
+      }
+      gate.coverageRatio = gate.themesTotal ? gate.themesCovered / gate.themesTotal : 1;
+    }
+  }
   const claim = claimProof(scenarios, intent.focus);
   const taxonomy = taxonomyLint(scenarios);
   const balance = coverageBalance(scenarios);
@@ -93,6 +151,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // #2 downstream-scope + #4 manual-oracle
   const downstream = downstreamScope(readText(specPath), scenarios);
   const manualOracleResult = manualOracle(featureText);
+  const autoManual = automatableManual(scenarios); // TQ-2 — @manual that is really automatable
   const ledger = viewpointLedger(viewpointPath, scenarios, featureText);
   const negSideEffect = negativeSideEffect(scenarios);
   const ownership = crossArtifactOwnership(screenDir, scenarios);
@@ -110,6 +169,9 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const overall = (0.4 * coverage + 0.3 * businessDepth + 0.15 * balanceScore + 0.15 * traceScore) * 10;
 
   const findings: string[] = [];
+  for (const c of flowCredits) {
+    findings.push(`COVERED-VIA-FLOW: critical theme "${c.theme}" is not covered on this screen but is deeply covered by flow "${c.flow}" — cross-screen depth correctly owned by the flow, so it is credited (not a screen gap). Verify with \`sungen flow-check\`.`);
+  }
   for (const g of gate.gaps) {
     if (g.status === 'shallow') {
       findings.push(`GATE: critical theme "${g.theme}" is covered only by SHALLOW scenarios (no data assertion) → deepen with \`... with {{value}}\` / \`table ... with {{value}}\` (count @manual cross-screen too).`);
@@ -154,6 +216,40 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   for (const m of manualOracleResult.insufficient.slice(0, 8)) {
     findings.push(`MANUAL-STEPS-INSUFFICIENT: "${m}" — a @manual scenario needs setup · action · observable expected · oracle/tool (not just a one-line note).`);
   }
+  // TQ-2 — automatable @manual: deferred (usually cross-screen) but fully DSL-expressible.
+  for (const m of autoManual.scenarios.slice(0, 8)) {
+    findings.push(`MANUAL-AUTOMATABLE: "${m.name}" is @manual but its steps are fully automatable (a data assertion, no visual/mock/a11y judgment) → generate it as an AUTOMATED flow scenario (or tag @manual:Mx with a real capability reason). Don't leave a non-running @manual duplicate of a flow scenario.`);
+  }
+  // TQ-9 — manual reason-code mismatch: an explicit @manual:Mx that disagrees with the reason
+  // text makes the capability planner recommend the wrong driver. Surface it so the code is fixed.
+  for (const mm of manualReasonMismatches(featurePath).slice(0, 8)) {
+    const label = MANUAL_REASONS[mm.inferred]?.label ?? (mm.inferred === 'XS' ? 'Cross-screen (→ flow)' : mm.inferred);
+    findings.push(`MANUAL-REASON-MISMATCH: "${mm.scenario}" is tagged @manual:${mm.explicit} but its reason reads as ${mm.inferred} (${label}) → fix the code so \`sungen capability plan\` recommends the right driver to automate it.`);
+  }
+  // TQ-10 — surface the Capability Planner recommendation (recommend-only; never installs). Silenced
+  // by `capability_suggestions: off` in qa/context.md. Reuses the planner (trustworthy after TQ-9).
+  if (intent.capabilitySuggestions) {
+    const plan = buildPlan(screenDir, featureBasename(screenName));
+    if (plan.recommendations.length) {
+      const recs = plan.recommendations.map((r) => `\`sungen capability add ${r.driver}\` (automates ${r.count})`).join(' · ');
+      findings.push(`CAPABILITY-SUGGESTION: ${plan.capabilityManual} @manual scenario(s) are capability-manual (a driver could automate them) — ${recs}. Recommend-only: nothing is installed automatically; the ${plan.judgmentManual} judgment-manual (M6/M8/M9) correctly stay manual.`);
+    }
+  }
+  // TQ-11b — automation-ready (pending capability): @requires:<cap> scenarios whose cap isn't enabled.
+  // They are NOT manual (real steps, compiled the moment the cap is added) — surface them distinctly.
+  {
+    const enabledCaps = new Set(readCapabilities(projectRootFromScreenDir(screenDir)).enabled.map((d) => d.toLowerCase()));
+    const pending = scenarios.filter((s) => (s.requiresCaps ?? []).some((c) => !enabledCaps.has(c)));
+    if (pending.length) {
+      const caps = [...new Set(pending.flatMap((s) => (s.requiresCaps ?? []).filter((c) => !enabledCaps.has(c))))];
+      findings.push(`AUTOMATION-READY-PENDING: ${pending.length} scenario(s) are automation-ready but need a capability — \`sungen capability add ${caps.join(' ')}\` to run them. They are skipped (not manual, not a gap) until the driver is enabled.`);
+    }
+  }
+  // TQ-3 — businessDepth de-inflation: a high ratio on a tiny denominator because business-critical
+  // scenarios were deferred to @manual is misleading. Surface the deferral so 1.0 isn't read as "done".
+  if (depth.deferredBusinessCritical > 0 && depth.deferredBusinessCritical >= depth.businessCriticalTotal) {
+    findings.push(`DEPTH-DEFERRED: businessDepth ${businessDepth.toFixed(2)} is computed over only ${depth.businessCriticalTotal} on-screen scenario(s); ${depth.deferredBusinessCritical} business-critical scenario(s) are deferred to @manual (excluded from the ratio). Automate them in a flow and verify with \`sungen flow-check\` — this ratio is NOT "all business depth covered".`);
+  }
   if (ledger.hasViewpoint && ledger.missing.length) {
     const sample = ledger.missing.slice(0, 6).map((m) => m.id || `"${m.text}"`).join(', ');
     findings.push(`VIEWPOINT-ITEM-MISSING: ${ledger.missing.length}/${ledger.total} atomic viewpoint items have no covering scenario (${(ledger.ratio * 100).toFixed(0)}% covered) — e.g. ${sample}. Cover each item or mark it deferred/spec-gap.`);
@@ -180,7 +276,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   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 }));
+    .flatMap((s) => s.run({ screenName: catalogScreenName, 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);
@@ -200,7 +296,11 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   };
   const weakestEntry = Object.entries(axes).sort((a, b) => a[1] - b[1])[0];
   const weakest = { axis: weakestEntry[0], value: weakestEntry[1] };
-  const inflated = overall >= 8 && weakest.value < 0.6;
+  // Inflated when breadth hides a weak axis, OR when businessDepth is high but rests on a
+  // denominator collapsed by deferral-to-@manual (TQ-3): the headline depth can't be trusted.
+  const depthInflated =
+    businessDepth >= 0.9 && depth.deferredBusinessCritical >= depth.businessCriticalTotal && depth.deferredBusinessCritical > 0;
+  const inflated = (overall >= 8 && weakest.value < 0.6) || depthInflated;
   if (inflated) {
     findings.push(`SCORE-INFLATED-BY-BREADTH: overall ${Math.round(overall * 10) / 10}/10 but the weakest axis "${weakest.axis}" is ${(weakest.value * 100).toFixed(0)}% — breadth is hiding a weak dimension. Raise "${weakest.axis}" before trusting the headline.`);
   }
@@ -215,7 +315,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     screen: screenName,
     scenarioCount: scenarios.length,
     gate, depth, claim, taxonomy, balance, duplicates, trace, spec,
-    taxonomyMismatch, downstream, manualOracle: manualOracleResult, ledger, calibration,
+    taxonomyMismatch, downstream, manualOracle: manualOracleResult, automatableManual: autoManual, ledger, calibration,
     score: {
       overall: Math.round(overall * 10) / 10,
       coverage: Math.round(coverage * 100) / 100,