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

package/dist/orchestrator/templates/ai-src/skills/sungen-tc-generation/SKILL.md

@@ -690,6 +690,42 @@ core, AF→behaviour, EF→validation/security) and traces them to the viewpoint
 `FL-EF` priority rows. Declare `phases: [BF, AF, EF]` in the contract; the FIRST phase is the
 Basic Flow and is the one that must reach `outcome`.
 
+**Declare the flow INVENTORY, not just the phases.** `phases: [BF, AF, EF]` says which
+vocabulary the suite uses; it cannot say how many flows the use case has — a phase counts as
+covered the moment ONE scenario carries it, so a fifteen-flow use case with three scenarios
+reported full phase coverage while a reviewer counting flows read it as a third done. List every
+flow in the contract, and give each one a status:
+
+```yaml
+flows:
+  - id: BF
+    outcome: "The successGuarantee — verified, recorded, signed in"
+    status: covered
+  - id: AF02
+    branchFrom: "BF step 4, before submitting"
+    outcome: "Re-enters BF at step 4 with the buffer restored"
+    status: covered
+  - id: EF08
+    branchFrom: "BF step 1, the control tapped twice"
+    outcome: "One request, one record"
+    status: pending-clarification      # the spec is silent — ASK, never assume a guard
+    reason: "The guard lives in ST_AUTH_001's spec, which this project does not hold."
+```
+
+Four statuses, and **silence is not one of them**: `covered` · `deferred` · `pending-clarification`
+(the behaviour is not agreed yet, so no scenario can be right) · `out-of-scope` (another suite owns
+it). Anything but `covered` needs a `reason:` — a deferral nobody can audit is the same as a
+missing flow. `sungen audit` then measures `flowCoverage` per DECLARED FLOW and reports
+`FLOW-UNCOVERED` (declared, nobody wrote it), `FLOW-UNDECLARED` (a scenario claiming a flow id the
+inventory never declares), `FLOW-STATUS-UNREASONED` and `FLOW-INVENTORY-MISSING`.
+
+**One flow, one id — a viewpoint is not a flow.** Several scenarios may prove one flow: give them
+the same flow id and different sequence numbers (`VP-VAL-EF01-001`, `VP-VAL-EF01-002`), never a
+fresh flow id per assertion. Two shapes the audit reports as `FLOW-PHASE-MISFILED`: an `EF` that
+reaches the outcome with nothing failing (that is a success-path postcondition, so it belongs to
+the BF), and an `AF` with no branch point (it walks the basic path asserting extra content — also
+the BF's). Both inflate the flow count while adding no branch coverage.
+
 **Declare once, then declare only the differences.** Actor · Trigger · Goal · Precondition ·
 `successGuarantee` · `minimalGuarantee` are use-case-level: they live in `flow-contract.yaml`
 and are never repeated per flow. Each flow in `test-viewpoint.md` then states only three things:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.24-beta.1",
+  "version": "3.2.24-beta.2",
   "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.1",
-    "@sungen/driver-ui": "3.2.24-beta.1",
+    "@sungen/driver-data-factory": "3.2.24-beta.2",
+    "@sungen/driver-ui": "3.2.24-beta.2",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

package/src/cli/commands/audit.ts

@@ -39,7 +39,9 @@ function render(r: AuditReport): void {
   const width = Math.max(...r.score.axes.map((a) => a.key.length));
   for (const a of r.score.axes) {
     const label = a.key.padEnd(width);
-    if (!a.applicable) { L(`    ${label} ${' '.repeat(20)}  n/a — no evidence`); continue; }
+    // Two different n/a: this unit supplied nothing, vs this axis does not apply to this KIND
+    // of unit. Only the first is something an author can act on.
+    if (!a.applicable) { L(`    ${label} ${' '.repeat(20)}  n/a — ${a.byDesign ? 'not applicable to a contract flow' : 'no evidence'}`); continue; }
     L(`    ${label} ${bar(a.value)} ${(a.value * 100).toFixed(0)}%${verdictOf[a.key] ?? ''}`);
   }
   L(`    (${r.score.formula})`);
@@ -52,7 +54,15 @@ function render(r: AuditReport): void {
     const fq = r.flowQuality;
     L(`  ①F Flow contract — goal: ${fq.contract!.goal}`);
     L(`      outcome [${fq.contract!.outcome.screen}]: ${fq.outcomeProven ? '✓ proven (automated data assertion)' : fq.outcomeManualOnly ? '⚠ manual-only' : '✗ UNPROVEN'}`);
-    L(`      phases: ${fq.phases.map((p) => `${p.phase}=${p.covered ? (p.automated ? '✓' : 'manual') : '✗'}`).join('  ')}  → flowCoverage ${(fq.phaseRatio * 100).toFixed(0)}%`);
+    L(`      phases: ${fq.phases.map((p) => `${p.phase}=${p.covered ? (p.automated ? '✓' : 'manual') : '✗'}`).join('  ')}  → phase coverage ${(fq.phaseRatio * 100).toFixed(0)}%`);
+    // The inventory, when declared, is the coverage that counts — phase coverage is only
+    // "each of BF/AF/EF appears at least once" and printing it as `flowCoverage` next to a 89%
+    // 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)}%`
+        + (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(', ')})` : ''}`);
     L('');
   }
@@ -103,7 +113,14 @@ function render(r: AuditReport): void {
     if (na.length) L(`      not scored (no evidence in this unit): ${na.join(', ')}`);
     L(`      weakest: ${r.calibration.weakest.axis} ${(r.calibration.weakest.value * 100).toFixed(0)}%${r.calibration.inflated ? '  ⚠ SCORE-INFLATED-BY-BREADTH' : ''}`);
     if (r.calibration.cappedAt !== undefined) {
-      L(`      ⚠ score held at ${r.calibration.cappedAt.toFixed(1)} by the weakest axis — fix it to lift the number`);
+      // Only blame the weakest axis when it IS weak. A cap for missing evidence printed
+      // "held by the weakest axis — fix it" next to "weakest: flowCoverage 100%", which sent
+      // authors hunting for a defect in a maxed-out axis (#595). The SCORE-CAPPED finding
+      // carries the real reason; say which kind of cap this is.
+      const weak = r.calibration.weakest.value < 0.7;
+      L(weak
+        ? `      ⚠ score held at ${r.calibration.cappedAt.toFixed(1)} by the weakest axis — fix it to lift the number`
+        : `      ⚠ score held at ${r.calibration.cappedAt.toFixed(1)} — no axis is weak; see the SCORE-CAPPED finding for what evidence is missing`);
     }
     L('');
   }

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.`);
@@ -610,7 +685,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 +697,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/flow-contract.ts

@@ -27,6 +27,21 @@ import { parse as parseYaml } from 'yaml';
 import { ScenarioInfo } from './parse';
 import { readTextFile } from './read-text';
 
+/** One declared flow of the use case: a branch point, its own steps, its own outcome. */
+export interface FlowDecl {
+  /** The flow id as the use-case document numbers it — `BF`, `AF01`, `EF03`. */
+  id: string;
+  /** Where it leaves the basic flow (`BF step 2`). Omitted for the basic flow itself. */
+  branchFrom?: string;
+  /** Its OWN outcome/postcondition — what is different about where this flow ends. */
+  outcome?: string;
+  status: 'covered' | 'deferred' | 'pending-clarification' | 'out-of-scope';
+  /** Why, for anything other than `covered` — a deferral with no reason is a silent gap. */
+  reason?: string;
+}
+
+const FLOW_STATUSES = new Set(['covered', 'deferred', 'pending-clarification', 'out-of-scope']);
+
 export interface FlowContract {
   goal: string;
   actor?: string;
@@ -43,6 +58,18 @@ export interface FlowContract {
   /** Journey phases this flow declares. Default [HP, ER, EH]; UI is allowed but
    *  never demanded (presentation is the balance axis's business, not coverage's). */
   phases: string[];
+  /**
+   * The use case's declared flow inventory — the answer to "how many flows does this use
+   * case HAVE?". `phases:` alone cannot answer it: a phase is present as soon as ONE
+   * scenario carries it, so a fifteen-flow use case with three scenarios reported full
+   * phase coverage. With an inventory, coverage is measured per DECLARED FLOW and a flow
+   * nobody wrote is a named gap instead of a silent absence (#595).
+   *
+   * `status` is what keeps a gap honest: every flow ends up `covered`, `deferred`,
+   * `pending-clarification` (an open question for the BA — the behaviour is not agreed yet,
+   * so no scenario can be right) or `out-of-scope`. Absent → `covered` is expected.
+   */
+  flows?: FlowDecl[];
   /** The mutated collection (cart, order, application …) — enables regression dims. */
   stateful?: string;
   budgets?: Record<string, number>;
@@ -117,6 +144,23 @@ export function loadFlowContract(unitDir: string): { contract: FlowContract | nu
       successGuarantee: raw.successGuarantee !== undefined ? String(raw.successGuarantee) : (raw.success_guarantee !== undefined ? String(raw.success_guarantee) : undefined),
       minimalGuarantee: raw.minimalGuarantee !== undefined ? String(raw.minimalGuarantee) : (raw.minimal_guarantee !== undefined ? String(raw.minimal_guarantee) : undefined),
       phases,
+      flows: Array.isArray(raw.flows)
+        ? (raw.flows as Array<Record<string, unknown>>)
+            .filter((f) => f && typeof f === 'object' && f.id)
+            .map((f) => {
+              const status = String(f.status ?? 'covered').toLowerCase();
+              if (!FLOW_STATUSES.has(status)) {
+                errors.push(`flows[${String(f.id)}].status "${status}" is not one of covered|deferred|pending-clarification|out-of-scope`);
+              }
+              return {
+                id: String(f.id).toUpperCase(),
+                branchFrom: f.branchFrom !== undefined ? String(f.branchFrom) : (f.branch_from !== undefined ? String(f.branch_from) : undefined),
+                outcome: f.outcome !== undefined ? String(f.outcome) : undefined,
+                status: (FLOW_STATUSES.has(status) ? status : 'covered') as FlowDecl['status'],
+                reason: f.reason !== undefined ? String(f.reason) : undefined,
+              };
+            })
+        : undefined,
       stateful: raw.stateful !== undefined ? String(raw.stateful).toLowerCase() : undefined,
       budgets: (raw.budgets && typeof raw.budgets === 'object') ? raw.budgets as Record<string, number> : undefined,
       external: Array.isArray(raw.external)
@@ -130,7 +174,9 @@ export function loadFlowContract(unitDir: string): { contract: FlowContract | nu
         : undefined,
       golden: raw.golden === true,
     },
-    errors: [],
+    // Shape errors found while reading the inventory (a bad `status:`) are REPORTED with the
+    // contract, not swallowed — the contract is still usable, the typo is not silently ignored.
+    errors,
   };
 }
 
@@ -145,6 +191,22 @@ function touchesOutcome(s: ScenarioInfo, outcomeScreen: string): boolean {
   return namespacesInOrder(s).includes(outcomeScreen);
 }
 
+/**
+ * Does the scenario ARRIVE at the outcome, as opposed to merely naming it?
+ *
+ * A guard scenario asserts the outcome screen is *absent* (`[Complete:Title] header is hidden`)
+ * — the strongest thing it can say — so "the outcome namespace appears somewhere in the steps"
+ * counts it as reaching a screen it exists to prove unreachable.
+ */
+function reachesOutcome(s: ScenarioInfo, outcomeScreen: string): boolean {
+  // Per STEP, from the structured list — `stepsText` is one space-joined blob, so any negation
+  // anywhere in the scenario would suppress every positive assertion in it.
+  const steps = (s.steps ?? []).map((st) => st.text.toLowerCase());
+  if (steps.length === 0) return touchesOutcome(s, outcomeScreen);
+  return steps.some((t) => t.includes(`[${outcomeScreen}`)
+    && !/\b(is hidden|is not visible|does not exist|is absent|no longer)\b/.test(t));
+}
+
 /** Phase of a scenario: its declared phase token (FL-HP-001 / VP-FLOW-ER-02 / MS-EH-005)
  *  when present, else vocabulary detection. */
 export function phaseOf(s: ScenarioInfo, declared: string[]): string | null {
@@ -163,6 +225,101 @@ export function phaseOf(s: ScenarioInfo, declared: string[]): string | null {
   return null;
 }
 
+/** The flow id a scenario claims: the `AF02`/`EF11`/`BF` segment of its viewpoint id. */
+export function flowIdOf(s: ScenarioInfo, declaredPhases: string[]): string | null {
+  const tokens = new Set(declaredPhases.map(phaseToken));
+  for (const seg of (s.vpId ?? '').toUpperCase().split('-')) {
+    if (tokens.has(phaseToken(seg))) return seg;
+  }
+  return null;
+}
+
+export interface InventoryResult {
+  /** Declared → the scenarios claiming it. A declared flow with none is a NAMED gap. */
+  covered: Array<{ id: string; scenarios: string[] }>;
+  /** Declared `covered` but nothing written — the silent-absence case, now named. */
+  uncovered: FlowDecl[];
+  /** Declared with a non-covered status, carried into the report so it stays visible. */
+  accounted: FlowDecl[];
+  /** A scenario's flow id that the inventory never declares — an id invented for one
+   *  assertion (an "EF" that is really a success postcondition, an "AF" that is really a
+   *  content check on the basic path). */
+  undeclared: Array<{ id: string; scenario: string }>;
+  /** Covered declared flows / declared flows that OUGHT to be covered. */
+  ratio: number;
+}
+
+/**
+ * Coverage per DECLARED FLOW, which is not the same question as coverage per phase.
+ *
+ * A phase is "covered" the moment one scenario carries it, so a use case decomposed into
+ * fifteen flows reported `BF=✓ AF=✓ EF=✓ → 100%` on three scenarios. Reviewers reading the
+ * suite counted the flows instead and got a very different number (#595). When the contract
+ * declares its inventory, this measures the thing the reviewer measures — and every gap is
+ * named, which is what makes "no silent missing flow" checkable rather than aspirational.
+ */
+export function flowInventory(contract: FlowContract, scenarios: ScenarioInfo[]): InventoryResult | null {
+  if (!contract.flows || contract.flows.length === 0) return null;
+  const byId = new Map<string, string[]>();
+  const undeclared: Array<{ id: string; scenario: string }> = [];
+  const declaredIds = new Set(contract.flows.map((f) => f.id));
+  for (const s of scenarios) {
+    const id = flowIdOf(s, contract.phases);
+    if (!id) continue;
+    if (!declaredIds.has(id)) { undeclared.push({ id, scenario: s.name }); continue; }
+    byId.set(id, [...(byId.get(id) ?? []), s.name]);
+  }
+  const expected = contract.flows.filter((f) => f.status === 'covered');
+  const covered = expected.filter((f) => (byId.get(f.id) ?? []).length > 0)
+    .map((f) => ({ id: f.id, scenarios: byId.get(f.id)! }));
+  return {
+    covered,
+    uncovered: expected.filter((f) => (byId.get(f.id) ?? []).length === 0),
+    accounted: contract.flows.filter((f) => f.status !== 'covered'),
+    undeclared,
+    ratio: expected.length ? covered.length / expected.length : 1,
+  };
+}
+
+/**
+ * A phase id used for something that is not that kind of flow.
+ *
+ * Two shapes, both seen on a real suite that the phase check scored 100%:
+ *   - an `EF` scenario that REACHES the contract outcome. An exception flow is blocked by
+ *     definition; one that completes the journey is a success-path postcondition wearing an
+ *     exception's id ("the buffer does not survive a finalized registration").
+ *   - an `AF` scenario with no branch: it walks the basic path and asserts extra content on
+ *     it. An alternate flow needs a point where the actor does something else; without one it
+ *     is an assertion belonging to the basic flow ("the shared component renders the new-email
+ *     copy").
+ * Both inflate the flow count while adding no branch coverage, which is exactly what makes a
+ * suite look complete to the harness and thin to a reviewer.
+ */
+export function misfiledPhases(
+  contract: FlowContract, scenarios: ScenarioInfo[], basicPhase: string,
+): Array<{ scenario: string; id: string; why: string }> {
+  const out: Array<{ scenario: string; id: string; why: string }> = [];
+  const outcome = contract.outcome.screen;
+  for (const s of scenarios) {
+    const id = flowIdOf(s, contract.phases);
+    if (!id || phaseToken(id) === phaseToken(basicPhase)) continue;
+    const ph = phaseToken(id);
+    if (ph === 'EF' && reachesOutcome(s, outcome)) {
+      // An error-then-recover flow legitimately ends at the outcome — it is the recovery that
+      // is being proven, and a guard flow is blocked rather than "failed". Only a scenario with
+      // no failure and no block at all is misfiled.
+      const failed = /\b(error|invalid|duplicate|reject|fail|denied|blocked|expired|refuse|unauthenticat|unauthoriz|redirect|guard|without (?:a |an |the )?\w+|not skippable|forces? \w+ to restart)\w*/i.test(s.haystack);
+      if (!failed) {
+        out.push({ scenario: s.name, id, why: `reaches the outcome screen [${outcome}] and nothing in it fails — this is a success-path postcondition, not an exception flow` });
+      }
+    }
+    if (ph === 'AF' && !/\b(back|cancel|return|instead|abandon|second tab|another tab|skip|leave|exit|retry|edit)\w*/i.test(s.haystack)) {
+      out.push({ scenario: s.name, id, why: 'no branch point — it walks the basic path and asserts extra content on it, so the assertion belongs to the basic flow' });
+    }
+  }
+  return out;
+}
+
 /**
  * Verify the suite against the contract. Deterministic; a flow without a contract
  * returns hasContract:false and neutral values (the audit reports the checklist).

package/src/harness/spec-coverage.ts

@@ -202,3 +202,41 @@ export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featur
 
   return { hasSpec: true, frTotal: frs.length, frCovered, uncoveredMust, inferredOnly, triggerGaps, verdict };
 }
+
+/**
+ * A flow's requirement list that is a HAND RESTATEMENT of the screen specs it traverses.
+ *
+ * A flow spec typically cites its requirements as belonging elsewhere — "ST_AUTH_002 FR-001",
+ * "restated here in flow terms". That restatement is lossy by construction, and nothing checked
+ * it: on a real run the flow spec restated two of the screens' FRs, `specFR` read **2/2 = 100%**,
+ * and the guard clause the flow most needed (a double-submit rule in one of those screen specs)
+ * had never entered the system at all. The axis was certifying complete coverage of a
+ * hand-truncated universe — a worse failure than a missing scenario, because the number said the
+ * opposite.
+ *
+ * So: name the source documents the flow says its requirements come from, and say plainly which
+ * of them the project does not hold. Whether the restatement is complete is then a question
+ * someone can answer, instead of one nothing was asking.
+ */
+export function restatedRequirementSources(specText: string, availableUnits: string[]): {
+  restated: boolean; sources: string[]; missing: string[];
+} {
+  // "these ... originate in the SCREEN specs", "restated here", "per ST_AUTH_002 FR-001".
+  const restated = /\brestate[sd]?\b|\boriginate[sd]? in\b|\bderived from the (?:screen|per-screen) spec/i.test(specText);
+  // External document ids carrying their own requirement number: `ST_AUTH_002 FR-001`,
+  // `SCR-1-SYS-0001.FR-3`. Two+ segments and an uppercase head, so a bare `FR-001` (the flow's
+  // own) never matches.
+  // A citation may name SEVERAL documents at once — "ST_AUTH_002/ST_AUTH_004 FR-001" — so match
+  // the whole slash/comma-joined run and split it. Capturing only the token adjacent to the
+  // requirement number silently dropped every sibling.
+  const DOC = '[A-Z][A-Z0-9]*(?:[_-][A-Z0-9]+)+';
+  const cite = new RegExp(`\\b((?:${DOC})(?:\\s*[/,]\\s*(?:${DOC}))*)[\\s.]+(?:FR|NFR|BR)-\\d+`, 'g');
+  const sources = [...new Set(
+    [...specText.matchAll(cite)].flatMap((m) => m[1].split(/\s*[/,]\s*/)).map((x) => x.trim()).filter(Boolean),
+  )];
+  if (!restated && sources.length === 0) return { restated: false, sources: [], missing: [] };
+  const norm = (x: string): string => x.toLowerCase().replace(/[^a-z0-9]/g, '');
+  const have = availableUnits.map(norm);
+  const missing = sources.filter((src) => !have.some((u) => u.includes(norm(src)) || norm(src).includes(u)));
+  return { restated, sources, missing };
+}

package/src/harness/viewpoint-ledger.ts

@@ -94,3 +94,45 @@ export function viewpointLedger(viewpointPath: string, scenarios: ScenarioInfo[]
 
   return { hasViewpoint: true, total: items.length, covered, ratio: items.length ? covered / items.length : 1, missing };
 }
+
+/**
+ * A viewpoint item that names a BROWSER-LEVEL gesture, met by an in-app control instead.
+ *
+ * "Browser back button from Basic Info Confirmation to Basic Info — values must be restored"
+ * was answered with `User click [Confirmation:Back] button`. Those are different mechanisms: an
+ * app button runs the screen's own re-hydrate logic, browser history does not, and a defect
+ * that only appears on history navigation lives exactly in the gap. The ledger counted the item
+ * covered because the words matched, so the substitution was invisible (#595).
+ *
+ * The language has no reload/back step at all (#593), so the honest outcome is a `@manual`
+ * deferral naming the gesture — not a silent swap.
+ */
+const BROWSER_GESTURES: Array<{ gesture: string; re: RegExp; appSubstitute: RegExp }> = [
+  { gesture: 'browser back', re: /\bbrowser(?:'s)?[ -]?(?:back|history)\b|\bhistory[ -]back\b/i,
+    appSubstitute: /\bclick \[[^\]]*back[^\]]*\]/i },
+  { gesture: 'browser reload/refresh', re: /\b(?:page |browser )?(?:reload|refresh)(?:ing|ed|es)?\b/i,
+    appSubstitute: /\bis on \[[^\]]+\] page\b/i },
+  { gesture: 'closing and reopening the tab', re: /\bclos(?:e|ing) (?:and reopen\w*\s*)?the tab\b|\breopen\w* the tab\b/i,
+    appSubstitute: /\bis on \[[^\]]+\] page\b/i },
+];
+
+export function browserGestureSubstitutions(
+  viewpointPath: string, scenarios: ScenarioInfo[],
+): Array<{ gesture: string; item: string }> {
+  const out: Array<{ gesture: string; item: string }> = [];
+  // Judged PER SCENARIO, not over the whole file: a @manual scenario elsewhere that merely
+  // mentions the gesture in passing (explaining a tooling limit) silenced the check for an
+  // item that an automated scenario had quietly substituted.
+  const deferred = scenarios.filter((s) => s.manual).map((s) => s.haystack);
+  const automated = scenarios.filter((s) => !s.manual).map((s) => s.haystack);
+  for (const item of parseViewpointItems(viewpointPath)) {
+    for (const g of BROWSER_GESTURES) {
+      if (!g.re.test(item.text)) continue;
+      // A @manual scenario whose own subject IS the gesture is the honest answer.
+      if (deferred.some((h) => g.re.test(h))) break;
+      if (automated.some((h) => g.appSubstitute.test(h))) out.push({ gesture: g.gesture, item: item.text });
+      break;
+    }
+  }
+  return out;
+}

package/src/orchestrator/templates/ai-src/commands/create-test.md

@@ -42,8 +42,19 @@ plus **both** postconditions: `successGuarantee` (true when the goal is reached)
 `minimalGuarantee` (what must still hold when the journey FAILS). Exception flows assert against
 the second one; with no `minimalGuarantee` they can only prove "an error appeared"
 (`FLOW-GUARANTEE-MISSING`). Then declare `phases:` — `[BF, AF, EF]` for a use-case decomposition
-(the first phase is the Basic Flow) — and enumerate flows with the step × risk matrix in the
-`sungen-tc-generation` skill.
+(the first phase is the Basic Flow). Then enumerate the use case's flows with the step × risk
+matrix in the `sungen-tc-generation` skill and **write them into the contract's `flows:`
+inventory**, each with a `status:` (`covered` / `deferred` / `pending-clarification` /
+`out-of-scope`) and a `reason:` for anything but `covered`. Without the inventory, coverage can
+only be measured per phase — and a phase counts as covered as soon as ONE scenario carries it, so
+a fifteen-flow use case scores 100% on three scenarios (`FLOW-INVENTORY-MISSING`, and the top mark
+is withheld).
+
+A risk the specs do NOT settle is `pending-clarification` with the question written down — never a
+scenario asserting invented behaviour, and never a silent omission. If the flow's requirements are
+restated from screen specs the project does not hold, say so: the audit reports
+`SPEC-RESTATED-UNVERIFIED` because `specFR 100%` over a hand-copied list certifies the copy, not
+the source.
 
 ---