@sun-asterisk/sungen 3.1.2 → 3.2.0-beta.142

package/src/harness/audit.ts

@@ -9,16 +9,24 @@
 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,
+  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';
 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;
@@ -33,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>;
@@ -54,22 +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);
-  const catalog = loadCatalog();
+  // 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 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);
 
-  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 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);
@@ -80,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);
@@ -97,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).`);
@@ -125,9 +200,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).`);
   }
@@ -143,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.`);
@@ -157,6 +264,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: 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);
+  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;
@@ -171,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.`);
   }
@@ -180,13 +309,13 @@ 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,
     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,

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/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/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

@@ -32,6 +32,8 @@ export interface ScenarioInfo {
   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)
+  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?
@@ -102,12 +104,17 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
   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> tags + inline `query [name]` step refs.
+  // 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 n = t.slice('@query:'.length).trim(); if (n) queryRefs.add(n); }
+  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]); }
+  // @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];
 
@@ -164,6 +171,8 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
     vpId,
     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;