@sun-asterisk/sungen 3.2.24-beta.1 → 3.2.24-beta.3

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/exporters/feature-parser.ts

@@ -189,13 +189,19 @@ export function splitVpAndName(scenarioName: string): { vpId?: string; category1
  *
  * Flow ids carry the use-case decomposition (#592) and group by it, so the deliverable shows
  * the reviewer WHICH flow each case belongs to instead of collapsing a whole journey into one
- * "Function" block: `FL-BF-*` → Basic Flow, `FL-AF0n-*` → Alternate Flow, `FL-EF0n-*` →
- * Exception Flow. The flat scheme keeps its old mapping (`FL-HP`/`FL-ER` functional,
- * `FL-EH` guards → Accessing).
+ * "Function" block: `BF` → Basic Flow, `AF0n` → Alternate Flow, `EF0n` → Exception Flow. The
+ * flat scheme keeps its old mapping (`HP`/`ER` functional, `EH` guards → Accessing).
+ * The phase may sit anywhere in the id: a project whose viewpoint declares themes writes a
+ * COMPOUND id (`VP-SEC-EF02-001`) carrying theme AND phase (#595).
  */
 export function mapVpToCategory2(vpId: string | undefined, scenarioName?: string): string {
   if (!vpId) return 'Function';
-  const flow = vpId.match(/^(?:VP-)?FL-([A-Z]{2})\d*(?:-|$)/i);
+  // The phase segment, wherever it sits in the id. A project whose viewpoint declares themes
+  // uses a COMPOUND id — `VP-SEC-EF02-001` carries both the theme (traceability) and the phase
+  // (flow) — and anchoring on `FL-` missed every one of them, so a use-case suite still grouped
+  // as Accessing/Function (#595). The phase wins over the theme here: a flow deliverable is read
+  // flow by flow.
+  const flow = vpId.match(/(?:^|-)(?:FL-)?(BF|AF|EF|HP|ER|EH|UI)\d*(?=-|$)/i);
   if (flow) {
     const phase = flow[1].toUpperCase();
     if (phase === 'BF') return 'Basic Flow';

package/src/harness/audit.ts

@@ -10,7 +10,7 @@ import * as path from 'path';
 import * as fs from 'fs';
 import { loadUnitScenarios, readUnitFeatureText, parseViewpointOverview, ScenarioInfo, ViewpointEntry } from './parse';
 import { checkViewpointBaseline, ViewpointBaseline } from './viewpoint-baseline';
-import { flowQuality, statefulDepthFor, continuityGaps, FlowQualityResult } from './flow-contract';
+import { flowQuality, statefulDepthFor, continuityGaps, flowInventory, misfiledPhases, FlowQualityResult, InventoryResult } from './flow-contract';
 import { featureFilesFor } from './unit-paths';
 import {
   loadCatalog, viewpointGate, assertionDepth, dataThemesFor, depthThresholdFor, coverageBalance, duplicateClusters, traceability, claimProof, taxonomyLint,
@@ -22,10 +22,10 @@ import { manualReasonMismatches, MANUAL_REASONS, buildPlan } from './capability-
 import { readCapabilities, verificationScopeFindings } from './capability';
 import { readIntent, projectRootFromScreenDir, IntentProfile } from './intent';
 import { getProvenance, Provenance } from './provenance';
-import { specCoverage, SpecCoverageResult, parseSpecClauses } from './spec-coverage';
+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, LedgerResult } from './viewpoint-ledger';
+import { viewpointLedger, parseViewpointItems, browserGestureSubstitutions, LedgerResult } from './viewpoint-ledger';
 import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 import { contextRouter } from '../capabilities/context-router';
@@ -50,6 +50,8 @@ export interface AuditReport {
   ledger: LedgerResult;         // atomic viewpoint-item coverage (per-bullet status)
   viewpointBaseline: ViewpointBaseline; // is the yardstick still the accepted one? (#557)
   flowQuality?: FlowQualityResult;      // #569 — flow contract verification (flows only)
+  /** #595 — coverage per DECLARED FLOW; absent when the contract declares no `flows:`. */
+  flowInventory?: InventoryResult;
   calibration: {                // #8 — multi-axis score so a high overall can't hide a weak axis
     axes: Record<string, number>;
     weakest: { axis: string; value: number };
@@ -73,7 +75,7 @@ export interface AuditReport {
      * `specFR` and `atomicLedger` entirely — so a flow's real coverage axis was never printed
      * while `balance`, which carried no weight, was.
      */
-    axes: Array<{ key: string; value: number; weight: number; applicable: boolean; critical: boolean }>;
+    axes: Array<{ key: string; value: number; weight: number; applicable: boolean; critical: boolean; byDesign?: boolean }>;
     formula: string;
   };
   gateStatus: 'PASS' | 'FAIL';
@@ -83,6 +85,23 @@ export interface AuditReport {
   spec: SpecCoverageResult;     // G2 — spec-clause coverage (FR + validation-trigger matrix)
 }
 
+/**
+ * Every unit name this project holds (screens + flows + api areas). Used to answer "does the
+ * project actually contain the spec this one says its requirements come from?".
+ */
+export function projectUnitDirs(projectRoot: string): string[] {
+  const out: string[] = [];
+  for (const kind of ['screens', 'flows', 'api']) {
+    const dir = path.join(projectRoot, 'qa', kind);
+    try {
+      for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (e.isDirectory()) out.push(e.name);
+      }
+    } catch { /* the project may not use this unit kind */ }
+  }
+  return out;
+}
+
 /** The catalog-resolution id for a unit dir (relative to qa/): screen · flows/<flow> · api/<area> · api/flows/<flow>. */
 export function catalogIdFromScreenDir(screenDir: string): string {
   const parts = screenDir.split(path.sep);
@@ -223,6 +242,12 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // businessDepth headroom: it can reach 1.0 only when all three are exercised, so a present-but-
   // shallow flow can't claim a perfect score (floor 0.5 — assertion depth still dominates).
   const isUiFlow = isUiFlowUnit;
+  // #595 — coverage per DECLARED FLOW, when the contract declares its inventory. Phase
+  // coverage answers "is there at least one exception scenario?"; a reviewer counting the use
+  // case's flows asks "are all eleven of them accounted for?". Those gave 100% and ~40% on the
+  // same suite, and the reviewer was measuring the right thing.
+  const inventory: InventoryResult | null = flowQ.contract ? flowInventory(flowQ.contract, scenarios) : null;
+  const misfiled = flowQ.contract ? misfiledPhases(flowQ.contract, scenarios, flowQ.contract.phases[0] ?? 'BF') : [];
   let flowDepth = isUiFlow ? flowRegressionDepth(scenarios) : { stateful: false, countProof: false, teardown: false, multiSource: false, ratio: 1, missing: [] } as FlowDepthResult;
   // Contract-declared statefulness generalizes the cart-hardcoded vocabulary: a flow that
   // mutates ANY named collection (order, application, submission …) gets the same three
@@ -284,9 +309,13 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   //     so a flow can finally EARN the coverage axis instead of always losing it to
   //     PAGE-TYPE-UNDETERMINED (or worse, being judged against a form checklist).
   const flowScored = flowQ.hasContract;
-  const axisDefs: Array<{ key: string; value: number; weight: number; applicable: boolean; critical: boolean }> = [
+  // `byDesign` separates "this unit supplied no evidence" from "this axis does not apply to
+  // this KIND of unit". Only the first is a reason to cap the score: a contract flow can never
+  // supply balance evidence, so capping for it held every flow at 8.9 forever and printed
+  // "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: flowQ.phaseRatio, weight: 0.22, applicable: true, critical: true }
+      ? { key: 'flowCoverage', value: inventory ? Math.min(inventory.ratio, 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 },
@@ -297,7 +326,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     // exceptions) — that is the shape of a well-decomposed use case, not neglected business
     // core. `flowCoverage` already measures whether the journey's phases are covered, so
     // balance carries no independent evidence for a contract flow (#592).
-    { key: 'balance', value: balanceScore, weight: 0.06, applicable: !flowScored, critical: false },
+    { key: 'balance', value: balanceScore, weight: 0.06, applicable: !flowScored, critical: false, byDesign: flowScored },
   ];
   const scored = axisDefs.filter((a) => a.applicable);
   const weightSum = scored.reduce((t, a) => t + a.weight, 0) || 1;
@@ -316,7 +345,22 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   let cap = 10;
   if (weakestCritical && weakestCritical.value < 0.5) cap = CAP_SEVERE;
   else if (weakestCritical && weakestCritical.value < 0.7) cap = CAP_WEAK;
-  const missingEvidence = axisDefs.filter((a) => !a.applicable).map((a) => a.key);
+  const missingEvidence = axisDefs.filter((a) => !a.applicable && !a.byDesign).map((a) => a.key);
+  // Phase coverage is WEAK evidence of flow coverage: a phase counts as covered as soon as
+  // one scenario carries it, so `flowCoverage 100%` on a fifteen-flow use case meant only
+  // "each of BF/AF/EF appears at least once". Until the contract declares its inventory, the
+  // axis cannot be certified complete — so it is partial evidence and holds the top mark down,
+  // instead of printing 100% next to a finding that says we cannot actually tell (#595).
+  if (flowScored && !inventory) missingEvidence.push('flowCoverage (phase-only — no `flows:` inventory)');
+  // A requirement list hand-restated from spec documents the project does not hold makes
+  // `specFR 100%` a certificate over an unverifiable universe: the clause that was never
+  // copied across can never be reported missing. That is partial evidence, so it holds the
+  // top mark down rather than reading as complete FR coverage (#595).
+  const restated = restatedRequirementSources(readText(specPath) ?? '', projectUnitDirs(projectRootFromScreenDir(screenDir)));
+  if (restated.sources.length > 0 && restated.missing.length > 0) {
+    missingEvidence.push(`specFR (restated from absent specs: ${restated.missing.join(', ')})`);
+  }
+  const notApplicableByDesign = axisDefs.filter((a) => !a.applicable && a.byDesign).map((a) => a.key);
   if (missingEvidence.length > 0) cap = Math.min(cap, CAP_PARTIAL_EVIDENCE);
   const rawOverall = Math.min(weighted * 10, cap);
   const capped = weakestCritical ? weighted * 10 > cap : false;
@@ -372,6 +416,37 @@ 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).');
     }
+    // #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.`);
+    }
+    // #595 — a flow whose requirement list is a hand restatement of the screen specs it
+    // traverses. `specFR` read 100% over two restated FRs while the guard clause the flow most
+    // needed had never entered the system. Name the source documents so the completeness of the
+    // restatement becomes a question someone can answer.
+    if (restated.sources.length > 0 && restated.missing.length > 0) {
+      findings.push(`SPEC-RESTATED-UNVERIFIED: this flow's requirements are restated from ${restated.sources.length} source spec(s) the project does not hold [${restated.missing.join(', ')}]. specFR ${spec.frCovered}/${spec.frTotal} therefore certifies coverage of the RESTATEMENT, not of those documents — whatever was not copied across is invisible here, and a guard clause that never entered the flow spec can never be reported missing. Add the screen units (\`sungen add --screen …\`) so their FRs are checkable, or record in the flow spec which of their requirements are deliberately out of this flow's scope.`);
+    }
+    // #595 — the flow inventory. Without it, "the phases are covered" was allowed to stand in
+    // for "the use case's flows are covered", and a reviewer who counted flows read the same
+    // suite as roughly half done.
+    if (!inventory) {
+      findings.push('FLOW-INVENTORY-MISSING: the contract declares `phases:` but no `flows:` inventory, so coverage can only be measured per PHASE — and a phase counts as covered as soon as ONE scenario carries it. Declare each flow of the use case (`id`, `branchFrom`, `outcome`, `status`) so a flow nobody wrote is a named gap instead of a silent absence. Enumerate them with the step x risk matrix in the `sungen-tc-generation` skill.');
+    } else {
+      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.`);
+      }
+      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.`);
+      }
+      for (const f of inventory.accounted.filter((x) => !x.reason)) {
+        findings.push(`FLOW-STATUS-UNREASONED: declared flow ${f.id} is \`${f.status}\` with no \`reason:\` — a deferral nobody can audit is the same as a missing flow. Say what blocks it (a capability, an open question for the BA, another suite that owns it).`);
+      }
+    }
+    // #595 — a phase id used for something that is not that kind of flow.
+    for (const m of misfiled.slice(0, 6)) {
+      findings.push(`FLOW-PHASE-MISFILED: "${m.scenario}" carries flow id ${m.id} but ${m.why}. Re-file it under the flow it belongs to; the phase count is not the flow count.`);
+    }
     // #580 P9 — a release-critical flow must carry its Final-Inspection selection.
     if (flowQ.contract!.golden && !/@golden\b/i.test(featureText)) {
       findings.push(`GOLDEN-MISSING: the contract declares \`golden: true\` (release-critical) but no scenario is tagged @golden — Final Inspection (\`sungen inspect\`) will have nothing to run for this flow. Tag the happy-path scenario(s) that prove the outcome.`);
@@ -511,11 +586,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.
@@ -610,7 +693,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     scenarioCount: scenarios.length,
     gate, depth, claim, taxonomy, balance, duplicates, trace, spec,
     taxonomyMismatch, downstream, manualOracle: manualOracleResult, automatableManual: autoManual, flowDepth, oracle, ledger, viewpointBaseline, calibration,
-    ...(isUiFlow ? { flowQuality: flowQ } : {}),
+    ...(isUiFlow ? { flowQuality: flowQ, flowInventory: inventory ?? undefined } : {}),
     score: {
       overall: Math.round(overall * 10) / 10,
       coverage: Math.round(coverage * 100) / 100,
@@ -622,7 +705,8 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
       // flow) that carried no weight at all.
       axes: axisDefs.map((a) => ({ ...a, weight: a.applicable ? a.weight / weightSum : 0 })),
       formula: `overall = (${scored.map((a) => `${(a.weight / weightSum).toFixed(2)}*${a.key}`).join(' + ')}) * 10`
-        + (missingEvidence.length ? ` — n/a (no evidence): ${missingEvidence.join(', ')}` : ''),
+        + (missingEvidence.length ? ` — n/a (no evidence): ${missingEvidence.join(', ')}` : '')
+        + (notApplicableByDesign.length ? ` — n/a for this unit kind: ${notApplicableByDesign.join(', ')}` : ''),
     },
     gateStatus,
     findings,

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"