@sun-asterisk/sungen 3.2.24-beta.2 → 3.2.24-beta.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.24-beta.2",
+  "version": "3.2.24-beta.4",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -39,8 +39,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.2.24-beta.2",
-    "@sungen/driver-ui": "3.2.24-beta.2",
+    "@sungen/driver-data-factory": "3.2.24-beta.4",
+    "@sungen/driver-ui": "3.2.24-beta.4",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

package/src/cli/commands/audit.ts

@@ -4,17 +4,8 @@ import * as fs from 'fs';
 import { runAudit, AuditReport, catalogIdFromScreenDir } from '../../harness/audit';
 import { reportSlug } from '../../harness/unit-paths';
 import { acceptViewpointBaseline } from '../../harness/viewpoint-baseline';
+import { findUnitDir } from '../resolve-unit';
 
-function findScreenDir(name: string): string | null {
-  // `name` may be a bare screen/flow/area, or an api unit id (`api/<area>`, `api/flows/<flow>`).
-  const candidates = [
-    path.join(process.cwd(), 'qa', 'screens', name),
-    path.join(process.cwd(), 'qa', 'flows', name),
-    path.join(process.cwd(), 'qa', 'api', name),         // qa/api/<area> or qa/api/flows/<flow>
-  ];
-  for (const c of candidates) if (fs.existsSync(c)) return c;
-  return null;
-}
 
 function bar(ratio: number, width = 20): string {
   const n = Math.round(ratio * width);
@@ -60,7 +51,9 @@ function render(r: AuditReport): void {
     // axis read as a contradiction.
     const inv = r.flowInventory;
     if (inv) {
-      L(`      flows: ${inv.covered.length}/${inv.covered.length + inv.uncovered.length} declared covered → flowCoverage ${(inv.ratio * 100).toFixed(0)}%`
+      const auto = inv.covered.filter((c) => c.automated).length;
+      L(`      flows: ${inv.covered.length}/${inv.covered.length + inv.uncovered.length} declared covered, ${auto} with automated evidence`
+        + (inv.manualOnly.length ? ` (manual-only: ${inv.manualOnly.map((f) => f.id).join(', ')})` : '')
         + (inv.accounted.length ? `   (${inv.accounted.map((f) => `${f.id}=${f.status}`).join(', ')})` : ''));
     }
     L(`      handoffs asserted: ${fq.handoffs.asserted}/${fq.handoffs.total}${fq.offGoal.length ? `   ⚠ off-goal scenarios: ${fq.offGoal.length} (${fq.offGoalCategories.join(', ')})` : ''}`);
@@ -143,7 +136,7 @@ export function registerAuditCommand(program: Command): void {
       try {
         const name = options.screen || options.api || options.area;
         if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
-        const dir = findScreenDir(name);
+        const dir = findUnitDir(name);
         if (!dir) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
 
         const report = runAudit(dir, name);

package/src/cli/commands/capability.ts

@@ -9,6 +9,7 @@ import {
 import { buildPlan, MANUAL_REASONS } from '../../harness/capability-plan';
 import { adapterRegistry } from '../../generators/test-generator/adapters';
 import { emitMobileRuntime, installMobileDriver } from '../../orchestrator/mobile-runtime-scaffolder';
+import { findUnitDir, resolveUnit } from '../resolve-unit';
 
 /** The running CLI's (core) version — opt-in drivers install in lockstep with it (not `@latest`). */
 function coreVersion(): string {
@@ -97,13 +98,6 @@ function verifyCapabilityDriver(pkg: string, cwd: string): void {
   }
 }
 
-function findScreenDir(name: string): string | null {
-  const s = path.join(process.cwd(), 'qa', 'screens', name);
-  if (fs.existsSync(s)) return s;
-  const f = path.join(process.cwd(), 'qa', 'flows', name);
-  if (fs.existsSync(f)) return f;
-  return null;
-}
 
 export function registerCapabilityCommand(program: Command): void {
   const cap = program
@@ -143,9 +137,10 @@ export function registerCapabilityCommand(program: Command): void {
     .option('--json', 'Output the raw plan JSON')
     .action((o: { screen: string; json?: boolean }) => {
       try {
-        const dir = findScreenDir(o.screen);
-        if (!dir) throw new Error(`Screen/flow not found: qa/screens/${o.screen} or qa/flows/${o.screen}`);
-        const plan = buildPlan(dir, o.screen);
+        const resolved = resolveUnit(o.screen);
+        if (!resolved) throw new Error(`Screen/flow not found: qa/screens/${o.screen} or qa/flows/${o.screen}`);
+        // The catalog unit id carries the unit KIND, which gates which drivers can serve it.
+        const plan = buildPlan(resolved.dir, o.screen, resolved.unitId);
 
         const outDir = path.join(process.cwd(), '.sungen', 'reports');
         fs.mkdirSync(outDir, { recursive: true });
@@ -170,6 +165,12 @@ export function registerCapabilityCommand(program: Command): void {
             L(`     • ${r.count} @manual:${r.reason} → enable \`${r.driver}\` (${r.pkg}) → would unblock ${r.count}`);
           }
         }
+        if (plan.unavailable.length) {
+          L('  Cannot help here (driver does not support this unit kind — do NOT install):');
+          for (const r of plan.unavailable) {
+            L(`     • ${r.count} @manual:${r.reason} → \`${r.driver}\` has no ${r.unitKind} support; automate the behaviour on the owning SCREEN unit instead`);
+          }
+        }
         if (plan.keep.length) {
           L(`  Keep manual (judgment floor — do NOT automate): ${plan.keep.map((k) => `${k.code}×${k.count} (${MANUAL_REASONS[k.code].label})`).join(', ')}`);
         }

package/src/cli/commands/challenge.ts

@@ -2,14 +2,8 @@ import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
 import { buildChallenge, renderChallengeMarkdown } from '../../harness/challenge';
+import { findUnitDir } from '../resolve-unit';
 
-function findScreenDir(name: string): string | null {
-  const screen = path.join(process.cwd(), 'qa', 'screens', name);
-  if (fs.existsSync(screen)) return screen;
-  const flow = path.join(process.cwd(), 'qa', 'flows', name);
-  if (fs.existsSync(flow)) return flow;
-  return null;
-}
 
 export function registerChallengeCommand(program: Command): void {
   program
@@ -19,7 +13,7 @@ export function registerChallengeCommand(program: Command): void {
     .option('--json', 'Output the raw JSON report')
     .action((o) => {
       try {
-        const dir = findScreenDir(o.screen);
+        const dir = findUnitDir(o.screen);
         if (!dir) throw new Error(`Screen/flow not found: qa/screens/${o.screen} or qa/flows/${o.screen}`);
         const report = buildChallenge(dir, o.screen);
 

package/src/cli/commands/depth-lint.ts

@@ -3,16 +3,8 @@ import * as path from 'path';
 import * as fs from 'fs';
 import { runDepthLint, renderDepthLint } from '../../harness/depth-lint';
 import { reportSlug } from '../../harness/unit-paths';
+import { findUnitDir } from '../resolve-unit';
 
-function findScreenDir(name: string): string | null {
-  const candidates = [
-    path.join(process.cwd(), 'qa', 'screens', name),
-    path.join(process.cwd(), 'qa', 'flows', name),
-    path.join(process.cwd(), 'qa', 'api', name),
-  ];
-  for (const c of candidates) if (fs.existsSync(c)) return c;
-  return null;
-}
 
 export function registerDepthLintCommand(program: Command): void {
   program
@@ -24,7 +16,7 @@ export function registerDepthLintCommand(program: Command): void {
       try {
         const name = options.screen;
         if (!name) throw new Error('Provide --screen <name>');
-        const dir = findScreenDir(name);
+        const dir = findUnitDir(name);
         if (!dir) throw new Error(`Not found: qa/screens/${name} or qa/flows/${name}`);
 
         const report = runDepthLint(dir, name);

package/src/cli/commands/gate.ts

@@ -2,16 +2,8 @@ import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
 import { runGate, renderGate, GatePhase } from '../../harness/journey';
+import { findUnitDir } from '../resolve-unit';
 
-function findScreenDir(name: string): string | null {
-  const candidates = [
-    path.join(process.cwd(), 'qa', 'screens', name),
-    path.join(process.cwd(), 'qa', 'flows', name),
-    path.join(process.cwd(), 'qa', 'api', name),
-  ];
-  for (const c of candidates) if (fs.existsSync(c)) return c;
-  return null;
-}
 
 const PHASES: GatePhase[] = ['create', 'run', 'deliver'];
 
@@ -28,7 +20,7 @@ export function registerGateCommand(program: Command): void {
         if (!name) throw new Error('Provide --screen <name>');
         const phase = options.phase as GatePhase;
         if (!PHASES.includes(phase)) throw new Error(`Provide --phase <${PHASES.join('|')}>`);
-        if (!findScreenDir(name)) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
+        if (!findUnitDir(name)) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
 
         const verdict = runGate(process.cwd(), name, phase);
         if (options.json) console.log(JSON.stringify(verdict, null, 2));

package/src/cli/commands/journey.ts

@@ -3,16 +3,8 @@ import * as path from 'path';
 import * as fs from 'fs';
 import { runJourney, waive, signoff, renderJourneyBoard, rollupJourney, renderRollupBoard } from '../../harness/journey';
 import { reportSlug } from '../../harness/unit-paths';
+import { findUnitDir } from '../resolve-unit';
 
-function findScreenDir(name: string): string | null {
-  const candidates = [
-    path.join(process.cwd(), 'qa', 'screens', name),
-    path.join(process.cwd(), 'qa', 'flows', name),
-    path.join(process.cwd(), 'qa', 'api', name),
-  ];
-  for (const c of candidates) if (fs.existsSync(c)) return c;
-  return null;
-}
 
 export function registerJourneyCommand(program: Command): void {
   program
@@ -41,7 +33,7 @@ export function registerJourneyCommand(program: Command): void {
 
         const name = options.screen;
         if (!name) throw new Error('Provide --screen <name> (or --all for the roll-up)');
-        if (!findScreenDir(name)) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
+        if (!findUnitDir(name)) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
 
         const report = options.waive
           ? waive(process.cwd(), name, options.waive, options.reason || '')

package/src/cli/commands/manifest.ts

@@ -2,14 +2,8 @@ import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
 import { buildManifest, diffManifest, loadManifest, saveManifest } from '../../harness/manifest';
+import { findUnitDir } from '../resolve-unit';
 
-function findScreenDir(name: string): string | null {
-  for (const p of ['screens', 'flows', 'api']) {
-    const d = path.join(process.cwd(), 'qa', p, name);
-    if (fs.existsSync(d)) return d;
-  }
-  return null;
-}
 
 export function registerManifestCommand(program: Command): void {
   program
@@ -24,7 +18,7 @@ export function registerManifestCommand(program: Command): void {
       try {
         const name = options.screen || options.api || options.area;
         if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
-        const dir = findScreenDir(name);
+        const dir = findUnitDir(name);
         if (!dir) throw new Error(`Not found: qa/screens|flows|api/${name}`);
 
         if (options.diff) {

package/src/cli/commands/next.ts

@@ -0,0 +1,96 @@
+/**
+ * `sungen next [unit]` — the hand-back every command ends with.
+ *
+ * The next step is derived from what the project HOLDS, not from which command just ran, so a
+ * session cannot lose the thread by finishing somewhere that has no footer of its own (#597).
+ */
+import { Command } from 'commander';
+import * as fs from 'fs';
+import * as path from 'path';
+import { readUnitState, UnitState } from '../../harness/next-step';
+import { resolveUnit, resolveUnitCandidates, AmbiguousUnitError } from '../resolve-unit';
+
+/** Every unit the project holds, so `sungen next` with no argument still answers. */
+function allUnits(cwd: string): Array<{ name: string; kind: UnitState['kind']; dir: string }> {
+  const out: Array<{ name: string; kind: UnitState['kind']; dir: string }> = [];
+  for (const [dir, kind] of [['screens', 'screen'], ['flows', 'flow'], ['api', 'api']] as const) {
+    const base = path.join(cwd, 'qa', dir);
+    try {
+      for (const e of fs.readdirSync(base, { withFileTypes: true })) {
+        if (e.isDirectory()) out.push({ name: e.name, kind, dir: path.join(base, e.name) });
+      }
+    } catch { /* the project may not use this unit kind */ }
+  }
+  return out;
+}
+
+function render(s: UnitState): void {
+  const L = console.log;
+  L('');
+  L(`━━━ Next steps: ${s.unit} (${s.kind}) ━━━`);
+  L('');
+  const held = [
+    s.hasSpec && 'spec', s.hasViewpoint && 'viewpoint',
+    s.kind === 'flow' && s.hasContract && (s.hasFlowInventory ? 'contract+inventory' : 'contract (phases only)'),
+    s.scenarioCount > 0 && `${s.scenarioCount} scenarios`,
+    s.hasSelectors && (s.selectorsArePlaceholder ? 'selectors (placeholder)' : 'selectors'),
+    s.compiled && 'compiled', s.hasResults && 'results', s.hasDeliverable && 'deliverable',
+  ].filter(Boolean);
+  L(`  state: ${held.length ? held.join(' · ') : '(nothing yet)'}`);
+  if (s.audit) L(`  audit: ${s.audit.overall}/10 [${s.audit.gateStatus}] · ${s.audit.findings.length} finding(s)`);
+  L('');
+  for (const st of s.steps) {
+    const mark = st.kind === 'blocked' ? '⛔' : st.kind === 'optional' ? '○' : '→';
+    L(`  ${mark} ${st.command}`);
+    L(`     ${st.because}`);
+  }
+  L('');
+}
+
+export function registerNextCommand(program: Command): void {
+  program
+    .command('next [unit]')
+    .description('What to do next for a unit (or every unit), derived from the project state')
+    .option('--json', 'Machine-readable output')
+    .action((unit: string | undefined, o: { json?: boolean }) => {
+      try {
+        const cwd = process.cwd();
+        let states: UnitState[];
+        if (unit) {
+          const resolved = resolveUnit(unit, cwd);
+          if (!resolved) {
+            console.error(`Error: no unit named "${unit}" under qa/screens, qa/flows or qa/api.`);
+            process.exit(1);
+          }
+          states = [readUnitState(cwd, resolved.dir, unit, resolved.kind)];
+        } else {
+          const units = allUnits(cwd);
+          if (units.length === 0) {
+            console.error('Error: this project holds no units yet — run `sungen add --screen <name> --path <url>` or `sungen add-flow --flow <name> --path <url>`.');
+            process.exit(1);
+          }
+          // A name in two places is ambiguous; report it rather than answering for one of them.
+          states = units.map((u) => {
+            if (resolveUnitCandidates(u.name, cwd).length > 1) throw new AmbiguousUnitError(u.name, resolveUnitCandidates(u.name, cwd));
+            return readUnitState(cwd, u.dir, u.name, u.kind);
+          });
+        }
+        if (o.json) {
+          console.log(JSON.stringify(states.length === 1 ? states[0] : states, null, 2));
+          return;
+        }
+        for (const s of states) render(s);
+      } catch (e) {
+        console.error(`Error: ${e instanceof Error ? e.message : e}`);
+        process.exit(1);
+      }
+    });
+}
+
+/**
+ * The one-line hand-back every command prints last. Kept deliberately small: it points at the
+ * resolver instead of restating a next step, so no command can drift from the real state.
+ */
+export function printHandBack(unit?: string): void {
+  console.log(`Next: sungen next${unit ? ` ${unit}` : ''}`);
+}

package/src/cli/index.ts

@@ -27,6 +27,7 @@ import { registerFeedbackCommand } from './commands/feedback';
 import { registerQaFeedbackCommand } from './commands/qa-feedback';
 import { registerScriptCheckCommand } from './commands/script-check';
 import { registerTraceCommand } from './commands/trace';
+import { registerNextCommand } from './commands/next';
 import { registerChallengeCommand } from './commands/challenge';
 import { registerBlindspotCommand } from './commands/blindspot';
 import { registerCapabilityCommand } from './commands/capability';
@@ -74,6 +75,7 @@ async function main() {
   registerQaFeedbackCommand(program);
   registerScriptCheckCommand(program);
   registerTraceCommand(program);
+  registerNextCommand(program);
   registerChallengeCommand(program);
   registerBlindspotCommand(program);
   registerCapabilityCommand(program);
@@ -96,6 +98,35 @@ async function main() {
   // say so (stderr, so `--json` output stays parseable).
   program.hook('preAction', () => { warnAssetsDrift(process.cwd()); });
 
+  // #597 — the hand-back, once, for EVERY command. It used to be hardcoded per command and only
+  // two of twenty-nine printed one, so a run that finished anywhere else finished in silence:
+  // `capability add` ended with a blank line and the session stopped mid-workflow. Adding a
+  // footer to the other twenty-seven would repeat the mistake in bulk.
+  //
+  // It hangs off `process.on('exit')` rather than a postAction hook because several commands
+  // exit with a MEANINGFUL code (`depth-lint` returns 2 when there are deepen candidates) and
+  // `process.exit` skips commander's hooks entirely — a postAction version printed for `audit`
+  // and silently not for `depth-lint`, which is the same class of gap all over again.
+  //
+  // It points at `sungen next` instead of restating a step, so it can never drift from the real
+  // project state. Skipped on a hard error (code 1): there the error message is the actionable
+  // thing, and burying it under a footer helps nobody. `--json` keeps stdout parseable.
+  let handBack: { unit?: string; json: boolean } | null = null;
+  program.hook('preAction', (_thisCommand, actionCommand) => {
+    if (actionCommand.name() === 'next') return;            // `next` IS the answer
+    const opts = actionCommand.opts() as Record<string, unknown>;
+    const unit = [opts.screen, opts.flow, opts.area].find((v) => typeof v === 'string' && v)
+      ?? (typeof actionCommand.args?.[0] === 'string' ? actionCommand.args[0] : undefined);
+    handBack = { unit: unit as string | undefined, json: opts.json === true };
+  });
+  process.on('exit', (code) => {
+    if (!handBack || code === 1) return;
+    const line = `\nNext: sungen next${handBack.unit ? ` ${handBack.unit}` : ''}`;
+    // stderr under --json so the hand-back never lands in the parsed payload.
+    if (handBack.json) process.stderr.write(`${line}\n`);
+    else process.stdout.write(`${line}\n`);
+  });
+
   await program.parseAsync(process.argv);
 }
 

package/src/cli/resolve-unit.ts

@@ -0,0 +1,72 @@
+/**
+ * One resolver for "which unit does this name mean?", shared by every command.
+ *
+ * Seven commands each had their own copy, and all seven searched `qa/screens/` FIRST. So a
+ * directory at `qa/screens/<name>/` SHADOWED a real flow of the same name — and the failure was
+ * silent, not loud: `sungen audit` resolved to the phantom screen, found no feature file, and
+ * reported 0 scenarios with no contract and no scored axis. A run that dropped the entire quality
+ * gate looked like a suite with nothing in it.
+ *
+ * That shape is not hypothetical: the mock driver resolves its catalog from
+ * `qa/screens/<unit>/mock/mocks.yaml` only, so making a mock work for a flow means creating
+ * exactly that phantom directory (#597).
+ *
+ * A name resolving to two units is ambiguous, and ambiguity is reported rather than resolved by
+ * search order.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export type UnitKind = 'screen' | 'flow' | 'api';
+
+const KINDS: Array<{ kind: UnitKind; dir: string }> = [
+  { kind: 'screen', dir: 'screens' },
+  { kind: 'flow', dir: 'flows' },
+  { kind: 'api', dir: 'api' },       // qa/api/<area> or qa/api/flows/<flow>
+];
+
+export interface ResolvedUnit {
+  dir: string;
+  kind: UnitKind;
+  /** Catalog unit id relative to qa/: `<screen>` · `flows/<f>` · `api/<a>` · `api/flows/<f>`. */
+  unitId: string;
+}
+
+/** Every unit directory this name matches, in `screens, flows, api` order. */
+export function resolveUnitCandidates(name: string, cwd = process.cwd()): ResolvedUnit[] {
+  const out: ResolvedUnit[] = [];
+  for (const { kind, dir } of KINDS) {
+    const p = path.join(cwd, 'qa', dir, name);
+    if (!fs.existsSync(p)) continue;
+    out.push({ dir: p, kind, unitId: kind === 'screen' ? name : `${dir}/${name}` });
+  }
+  return out;
+}
+
+export class AmbiguousUnitError extends Error {
+  constructor(public readonly name: string, public readonly candidates: ResolvedUnit[]) {
+    super(
+      `"${name}" names ${candidates.length} units: ${candidates.map((c) => `qa/${c.kind === 'screen' ? 'screens/' : ''}${c.unitId}`).join(' and ')}.\n`
+      + '  Resolving this by search order silently picks one and drops the other unit\'s feature,\n'
+      + '  contract and scored axes — a report with 0 scenarios rather than an error. Rename one,\n'
+      + '  or remove the directory that should not exist (a stray `qa/screens/<flow-name>/`\n'
+      + '  created to satisfy a screen-only driver is the usual cause).',
+    );
+    this.name = 'AmbiguousUnitError';
+  }
+}
+
+/**
+ * The single unit this name means. Throws `AmbiguousUnitError` when several match; returns null
+ * when none do (callers report "unit not found" with their own guidance).
+ */
+export function resolveUnit(name: string, cwd = process.cwd()): ResolvedUnit | null {
+  const found = resolveUnitCandidates(name, cwd);
+  if (found.length > 1) throw new AmbiguousUnitError(name, found);
+  return found[0] ?? null;
+}
+
+/** Back-compat shape for the callers that only want the directory. */
+export function findUnitDir(name: string, cwd = process.cwd()): string | null {
+  return resolveUnit(name, cwd)?.dir ?? null;
+}

package/src/harness/audit.ts

@@ -25,7 +25,7 @@ import { getProvenance, Provenance } from './provenance';
 import { specCoverage, SpecCoverageResult, parseSpecClauses, restatedRequirementSources } from './spec-coverage';
 import { downstreamScope, manualOracle, readText, DownstreamResult, ManualOracleResult,
   negativeSideEffect, sourceBacked, crossArtifactOwnership, isolationRisk, serialCascadeRisk } from './quality-gates';
-import { viewpointLedger, parseViewpointItems, browserGestureSubstitutions, LedgerResult } from './viewpoint-ledger';
+import { viewpointLedger, parseViewpointItems, browserGestureSubstitutions, viewpointIntegrity, LedgerResult } from './viewpoint-ledger';
 import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 import { contextRouter } from '../capabilities/context-router';
@@ -315,7 +315,11 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // "weakest: flowCoverage 100% — fix it to lift the number", which is not fixable advice (#595).
   const axisDefs: Array<{ key: string; value: number; weight: number; applicable: boolean; critical: boolean; byDesign?: boolean }> = [
     flowScored
-      ? { key: 'flowCoverage', value: inventory ? Math.min(inventory.ratio, flowQ.phaseRatio) : flowQ.phaseRatio, weight: 0.22, applicable: true, critical: true }
+      // A declared flow claimed only by @manual scenarios is ACCOUNTED FOR but nothing runs, so
+      // it cannot count the same as an automated one — `covered` was collapsing three very
+      // different states into one number (#599). Half credit: the design work is real, the
+      // regression evidence is not.
+      ? { key: 'flowCoverage', value: inventory ? Math.min((inventory.ratio + inventory.automatedRatio) / 2, flowQ.phaseRatio) : flowQ.phaseRatio, weight: 0.22, applicable: true, critical: true }
       : { key: 'coverage', value: coverage, weight: 0.22, applicable: !!gate.pageType && gate.themesTotal > 0, critical: true },
     { key: 'specFR', value: specRatio, weight: 0.15, applicable: spec.hasSpec && spec.frTotal > 0, critical: true },
     { key: 'atomicLedger', value: ledger.ratio, weight: 0.13, applicable: ledger.hasViewpoint && ledger.total > 0 && !viewpointMoved, critical: true },
@@ -416,6 +420,27 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     if (!flowQ.contract!.minimalGuarantee) {
       findings.push('FLOW-GUARANTEE-MISSING: the contract declares no `minimalGuarantee:` — the postcondition that must hold in EVERY flow, including failure ("no second account for the same email", "no verification mail on a rejected submit"). Exception/guard scenarios have nothing to assert against without it; add it (and `successGuarantee:` for the goal-reached side).');
     }
+    // #599 — integrity of the DECLARATION itself: three ways it can be internally wrong while
+    // every coverage number still reads well.
+    {
+      const testDataDir = path.join(screenDir, 'test-data');
+      const extra: Array<{ label: string; text: string }> = [];
+      try {
+        for (const f of fs.readdirSync(testDataDir).filter((x) => x.endsWith('.yaml'))) {
+          extra.push({ label: `test-data/${f}`, text: readTextFile(path.join(testDataDir, f)) ?? '' });
+        }
+      } catch { /* api units and fresh scaffolds carry none */ }
+      const vi = viewpointIntegrity(viewpointPath, scenarios.map((sc) => sc.vpId ?? '').filter(Boolean), extra);
+      for (const d of vi.duplicateIds.slice(0, 4)) {
+        findings.push(`VIEWPOINT-ID-REUSED: "${d.id}" labels ${d.count} different claims (${d.texts.map((t) => `"${t.slice(0, 44)}…"`).join(' · ')}). The ledger then counts ${d.count} items while traceability sees ONE id, so both the coverage arithmetic and "which test proves this?" go wrong — and neither number looks suspicious. Give each atomic claim its own id; several ids may share a flow.`);
+      }
+      for (const d of vi.danglingRefs.slice(0, 5)) {
+        findings.push(`TRACE-REF-DANGLING: ${d.where} cites "${d.ref}", which no scenario carries. Nothing breaks at runtime, so a wrong pointer survives every refactor and quietly misleads the next maintainer. Fix the reference, or the scenario id it was meant to name.`);
+      }
+      if (vi.uniformPriority) {
+        findings.push(`VIEWPOINT-PRIORITY-UNIFORM: all ${vi.uniformPriority.rows} rows of the Priority Viewpoints table are "${vi.uniformPriority.levels[0]}". That is a formality, not a priority: nothing can be selected for a smoke run and the release conversation has no input. Rank by business impact and risk — the basic flow and the data-integrity guards are not the same bet as an exit path a screen suite already covers.`);
+      }
+    }
     // #595 — a viewpoint item naming a browser-level gesture, answered with an in-app control.
     for (const g of browserGestureSubstitutions(viewpointPath, scenarios).slice(0, 4)) {
       findings.push(`VIEWPOINT-GESTURE-SUBSTITUTED: the viewpoint asks for "${g.gesture}" ("${g.item.slice(0, 80)}…") but the suite exercises an in-app control instead. They are different mechanisms — an app button runs the screen's own re-hydrate logic, browser history does not, and a defect that only shows on history navigation lives in exactly that gap. The step vocabulary has no reload/back step (#593), so defer it with \`@manual\` naming the gesture rather than substituting silently.`);
@@ -436,6 +461,9 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
       for (const f of inventory.uncovered) {
         findings.push(`FLOW-UNCOVERED: declared flow ${f.id}${f.branchFrom ? ` (branches from ${f.branchFrom})` : ''} has status \`covered\` but no scenario carries its id — write it, or change its status to \`deferred\` / \`pending-clarification\` / \`out-of-scope\` WITH a reason. Silence is the one option the inventory removes.`);
       }
+      if (inventory.manualOnly.length > 0) {
+        findings.push(`FLOW-MANUAL-ONLY: ${inventory.manualOnly.length} declared flow(s) are claimed only by @manual scenarios — ${inventory.manualOnly.map((f) => f.id).join(', ')}. They are accounted for, but NOTHING RUNS for them: a regression run would not notice if any of these broke. \`status: covered\` says the flow was thought about; it does not say the suite can catch a regression in it, so flowCoverage credits them at half. Either automate them (check the capability plan for a driver that would) or say plainly in the delivery that this flow's evidence is a manual procedure.`);
+      }
       for (const u of inventory.undeclared.slice(0, 6)) {
         findings.push(`FLOW-UNDECLARED: "${u.scenario}" claims flow id ${u.id}, which the contract's inventory does not declare — a phase id invented for one scenario inflates the flow count without adding branch coverage. Either declare ${u.id} as a real flow (branch point + own outcome), or fold the scenario into the flow it actually belongs to.`);
       }
@@ -586,11 +614,19 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // 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, screenName);
+    // The catalog unit id (`flows/<f>`, `api/<a>`) carries the unit KIND, which gates which
+    // drivers can serve it at all.
+    const plan = buildPlan(screenDir, screenName, catalogScreenName);
     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.`);
     }
+    // Named, not dropped: without this the scenarios read as "nothing could help", and the
+    // operator's only clue was an install that dead-ends (#597).
+    if (plan.unavailable.length) {
+      const un = plan.unavailable.map((r) => `${r.driver} (would automate ${r.count})`).join(' · ');
+      findings.push(`CAPABILITY-UNAVAILABLE: ${un} — ${plan.unavailable.length === 1 ? 'that driver does' : 'those drivers do'} not support a ${plan.unavailable[0].unitKind} unit, so ${plan.unavailable.length === 1 ? 'it' : 'they'} cannot automate these scenarios here. Do NOT install: the scenarios stay @manual until the driver gains ${plan.unavailable[0].unitKind} support. Automating the same behaviour on the owning SCREEN unit is the available route today.`);
+    }
   }
   // 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.

package/src/harness/capability-plan.ts

@@ -8,7 +8,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { loadDriverCatalog } from './capability';
+import { loadDriverCatalog, unitKindOf, driverServesUnit } from './capability';
 import { readTextFile } from './read-text';
 import { featureFilesFor } from './unit-paths';
 
@@ -190,12 +190,21 @@ export interface CapabilityPlan {
   crossScreen: number;            // automatable via a flow — not a single-screen driver gap
   capabilityManualPct: number;
   recommendations: { driver: string; pkg: string; reason: string; count: number; scenarios: string[] }[];
+  /**
+   * Drivers that WOULD have been recommended but cannot serve this unit kind. Surfaced, never
+   * dropped: the scenarios stay manual for a reason the operator needs to know, and a silent
+   * omission would read as "nothing could help here" (#597).
+   */
+  unavailable: { driver: string; reason: string; count: number; unitKind: string }[];
   keep: { code: string; count: number }[];
 }
 
-export function buildPlan(screenDir: string, screenName: string): CapabilityPlan {
+export function buildPlan(screenDir: string, screenName: string, unitId = screenName): CapabilityPlan {
   const scenarios = featureFilesFor(screenDir, screenName).flatMap(parseScenarios);
   const catalog = loadDriverCatalog();
+  // Recommending a driver that cannot serve this unit KIND costs an install, a dead end and a
+  // manual rollback — which is exactly what the mock driver (screen-only) did on a flow (#597).
+  const unitKind = unitKindOf(unitId);
 
   const modes: Record<string, number> = {};
   const byReason: Record<string, number> = {};
@@ -230,7 +239,17 @@ export function buildPlan(screenDir: string, screenName: string): CapabilityPlan
     }
   }
 
-  const recommendations = [...recByDriver.entries()]
+  const servable = [...recByDriver.entries()].filter(([d]) => driverServesUnit(d, unitKind));
+  const unavailable = [...recByDriver.entries()]
+    .filter(([d]) => !driverServesUnit(d, unitKind))
+    .map(([driver, v]) => ({
+      driver,
+      reason: v.reason,
+      count: v.scenarios.length,
+      unitKind,
+    }))
+    .sort((a, b) => b.count - a.count);
+  const recommendations = servable
     .map(([driver, v]) => ({
       driver,
       pkg: catalog[driver]?.package || `@sungen/driver-${driver}`,
@@ -252,6 +271,7 @@ export function buildPlan(screenDir: string, screenName: string): CapabilityPlan
     crossScreen,
     capabilityManualPct: manualTotal ? Math.round((capabilityManual / manualTotal) * 100) : 0,
     recommendations,
+    unavailable,
     keep: Object.entries(keepCount).map(([code, count]) => ({ code, count })).sort((a, b) => b.count - a.count),
   };
 }

package/src/harness/capability.ts

@@ -73,6 +73,28 @@ export interface DriverMeta {
   bundled?: boolean;       // shipped as a core dependency — present without `capability add`
   capabilities: string[];
   unblocks?: string[];
+  /**
+   * Unit kinds this driver can actually serve. Absent = all kinds.
+   *
+   * A driver that only resolves its config from one unit shape must say so, or the capability
+   * planner recommends it for a unit it can never serve — which is what happened with the mock
+   * driver on a flow: install, dead end, manual rollback (#597).
+   */
+  units?: Array<'screen' | 'flow' | 'api'>;
+}
+
+/** The unit kind of a catalog unit id: `flows/<f>` → flow, `api/<a>` → api, else screen. */
+export function unitKindOf(catalogUnitId: string): 'screen' | 'flow' | 'api' {
+  const seg = catalogUnitId.split('/')[0];
+  if (seg === 'api') return 'api';
+  if (seg === 'flows') return 'flow';
+  return 'screen';
+}
+
+/** Can this driver serve that unit kind? Unknown driver → assume yes (nothing to gate on). */
+export function driverServesUnit(driverId: string, kind: 'screen' | 'flow' | 'api'): boolean {
+  const units = driverMeta(driverId)?.units;
+  return !units || units.includes(kind);
 }
 
 export function capabilitiesPath(cwd: string): string {

package/src/harness/catalog/drivers.yaml

@@ -61,6 +61,11 @@ drivers:
     status: shipped
     capabilities: ["@mock", "@network"]
     unblocks: [M3]
+    # `units:` is the unit KINDS this driver can actually serve. Absent → all kinds.
+    # The mock driver resolves its catalog from qa/screens/<unit>/mock/mocks.yaml only
+    # (mockCatalogPath is hardcoded to that shape), so it cannot serve a flow. Recommending
+    # it for one sent an operator through an install, a dead end and a manual rollback (#597).
+    units: [screen]
   mail-file:
     kind: capability
     package: "@sungen/driver-mail-file"