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

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, 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 };
@@ -67,6 +69,13 @@ export interface AuditReport {
     businessDepth: number;      // 0..1
     balance: number;            // 0..1
     traceability: number;       // 0..1
+    /**
+     * Every axis considered, in weight order, with the renormalised weight it actually
+     * carried. The five legacy fields above are a fixed subset that omitted `flowCoverage`,
+     * `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; byDesign?: boolean }>;
     formula: string;
   };
   gateStatus: 'PASS' | 'FAIL';
@@ -76,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);
@@ -216,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
@@ -277,16 +309,24 @@ 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 },
     { key: 'businessDepth', value: businessDepth, weight: 0.20, applicable: true, critical: true },
     { key: 'claimProof', value: claim.ratio, weight: 0.15, applicable: claim.withClaims > 0, critical: true },
     { key: 'traceability', value: traceScore, weight: 0.09, applicable: viewpoints.length > 0 && !viewpointMoved, critical: false },
-    { key: 'balance', value: balanceScore, weight: 0.06, applicable: true, critical: false },
+    // A use-case decomposition is EF-heavy by construction (1 basic flow, N alternates, N
+    // 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, byDesign: flowScored },
   ];
   const scored = axisDefs.filter((a) => a.applicable);
   const weightSum = scored.reduce((t, a) => t + a.weight, 0) || 1;
@@ -305,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;
@@ -313,7 +368,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // axes — a stateful flow with FULL regression depth (count + teardown + multi-source), no weak
   // facet oracle, and no parallel-cart isolation risk. Otherwise the score is held just below 9, so
   // "≥9" means senior-grade, not merely "themes covered". Neutral for screens/api (no signals).
-  const isoRisk = isolationRisk(featureText, flowDepth.stateful);
+  const isoRisk = isolationRisk(featureText, flowDepth.stateful, flowQ.contract?.stateful);
   const overall = seniorBandedOverall(rawOverall, { flowStateful: flowDepth.stateful, flowRatio: flowDepth.ratio, oracleWeak: oracle.weak.length, isolationRisk: isoRisk });
 
   const findings: string[] = [];
@@ -356,6 +411,42 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     for (const x of flowQ.sit.filter((v) => v.mockOnly).slice(0, 4)) {
       findings.push(`SIT-MOCK-ONLY: "${x.name}" touches the external system "${x.external}" but is verified only against mocks — Pass (Mocked) says nothing about the real vendor behaviour. Re-verify on the real dependency before calling it Done (the delivery's External Dependency Tracking table holds the checklist).`);
     }
+    // #592 W1 — an Exception Flow asserts against the Minimal Guarantee; without the
+    // declaration there is no anchor and its assertions are guesswork.
+    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.`);
@@ -364,6 +455,13 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
       findings.push(`FLOW-HANDOFF-SHALLOW: only ${flowQ.handoffs.asserted}/${flowQ.handoffs.total} cross-screen transitions are followed by an assertion in the new screen — carried state (the thing a flow exists to verify) is unproven at the handoff. businessDepth is capped until asserted.`);
     }
   }
+  // #592 W5 — a continuity mechanism proved on one side only.
+  if (isUiFlow) {
+    const scenarioTexts = scenarios.map((s) => `${s.name} ${s.stepsText}`);
+    for (const g of continuityGaps(parseViewpointItems(viewpointPath).map((i) => i.text), scenarioTexts).slice(0, 4)) {
+      findings.push(`CONTINUITY-ONE-SIDED: the viewpoint claims "${g.claim}" but the suite proves only the ${g.missing === 'loss' ? 'SURVIVING' : 'LOSING'} side — a persistence mechanism has two sides and testing one is testing half the mechanism. Add the ${g.missing === 'loss' ? 'loss' : 'persistence'} scenario (e.g. ${g.missing === 'loss' ? 'reload / clear storage between the steps and assert the values are gone' : 'return to the step and assert the values are restored'}).`);
+    }
+  }
   if (isUiFlow) {
     // Flows defer more than screens, so an UNCODED @manual is costlier here: the capability
     // planner cannot route it to the driver that would automate it (password-reset: 11/22
@@ -399,7 +497,8 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // isolation, else count/quantity asserts go flaky. Warn (advisory) when no mitigation is present
   // (@cleanup:cart / @isolate / a "Given … empty cart" background / fresh context).
   if (isoRisk) {
-    findings.push('ISOLATION-RISK: this @parallel flow mutates the cart but has no per-scenario isolation → cart/count/quantity asserts can go flaky when scenarios share state. Add `@cleanup:cart` (or `@isolate`, or a `Given User has an empty cart` background) so each scenario starts clean.');
+    const what = flowQ.contract?.stateful ?? 'cart';
+    findings.push(`ISOLATION-RISK: this @parallel flow mutates ${what} but has no per-scenario isolation → count/quantity/state asserts can go flaky when scenarios share it. Add \`@cleanup:${what}\` (or \`@isolate\`, a fresh context, or \`{{$timestamp}}\` data) so each scenario starts clean.`);
   }
   // #414 — serial-cascade masking: an @serial suite of independent (re-navigating) scenarios hides
   // failures, because Playwright's describe.serial SKIPS everything after the first red. Isolation is
@@ -409,12 +508,19 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     findings.push(`SERIAL-CASCADE-RISK: this \`@serial\` suite has ${cascadeN} INDEPENDENT scenarios (each re-navigates via Background) that don't need a shared-page sequence. \`describe.serial\` SKIPS every test after the first failure → one early red MASKS the rest as never-run. **Drop \`@serial\`** — the default per-scenario isolation runs every scenario and isolates failures. Keep \`@serial\` only for a genuinely stateful ordered sequence (where scenario N depends on N-1's state).`);
   }
   if (flowDepth.stateful && flowDepth.missing.length) {
+    // The advice names the collection the CONTRACT declared. It used to say "the cart" whatever
+    // the flow mutated, so a registration journey was told to "add to the cart from EVERY
+    // source" — advice its author could not act on (#592).
+    const what = flowQ.contract?.stateful ?? 'cart';
     const how: Record<string, string> = {
-      'count-proof': 'assert the cart ROW COUNT / item QUANTITY (e.g. `... table with {{two_rows}}`, `Quantity column with {{qty}}`), not just the row presence',
-      'teardown': 'add a REMOVE/clear scenario that returns the cart to its empty state (the inverse operation)',
-      'multi-source': 'add to the cart from EVERY source on the page (the main list AND the recommended/related rail), not just one',
+      'count-proof': `assert the ${what} ROW COUNT / item QUANTITY (e.g. \`... table with {{two_rows}}\`, \`Quantity column with {{qty}}\`), not just the row presence`,
+      'teardown': `prove the INVERSE operation — the ${what} returning to its empty/absent state (a remove or clear for a collection; a lapse, expiry, reset or loss for a state machine)`,
+      'multi-source': `exercise EVERY source that feeds the ${what} (the main list AND the recommended/related rail), not just one`,
     };
-    findings.push(`FLOW-DEPTH: this stateful flow exercises ${3 - flowDepth.missing.length}/3 regression dimensions — missing [${flowDepth.missing.join(', ')}] → ${flowDepth.missing.map((m) => how[m]).join('; ')}. (businessDepth is capped until covered.)`);
+    // How many dimensions this flow can HAVE — the ratio is renormalised over the applicable
+    // ones, so "2/3" would misreport a flow that only has two to begin with.
+    const dims = flowDepth.ratio < 1 ? Math.round(flowDepth.missing.length / (1 - flowDepth.ratio)) : 3;
+    findings.push(`FLOW-DEPTH: this stateful flow (${what}) exercises ${dims - flowDepth.missing.length}/${dims} applicable regression dimensions — missing [${flowDepth.missing.join(', ')}] → ${flowDepth.missing.map((m) => how[m]).join('; ')}. (businessDepth is capped until covered.)`);
   }
   for (const w of oracle.weak) {
     findings.push(`ORACLE-WEAK: "${w.name}" — ${w.hint}`);
@@ -428,7 +534,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   }
   if (balance.unclassifiedRatio > 0.4) {
     findings.push(`TAXONOMY-UNCLASSIFIED: ${balance.note} → align the VP-<CATEGORY> codes with the catalog (or extend the bucket keywords) so coverage-balance is meaningful.`);
-  } else if (balance.imbalanced) {
+  } else if (balance.imbalanced && !flowScored) {
     findings.push(`BALANCE: ${balance.note} Stop expanding secondary viewpoints until business-core gaps are filled.`);
   }
   if (trace.mappedRatio < 0.5) {
@@ -454,7 +560,9 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // "nothing found" quietly excluding the specFR axis while the evidence sits in the file.
   if (spec.hasSpec && spec.frTotal === 0 && /@spec:/i.test(featureText)) {
     const cited = [...new Set([...featureText.matchAll(/@spec:([A-Za-z0-9.-]+)/g)].map((m) => m[1].toUpperCase()))];
-    findings.push(`SPEC-IDS-UNPARSED: the feature cites ${cited.length} requirement id(s) via @spec: (${cited.slice(0, 5).join(', ')}${cited.length > 5 ? ', …' : ''}) but requirements/spec.md yielded ZERO parseable requirement declarations — the spec likely declares ids in a scheme the parser cannot read. Declare each requirement on its own line as \`<ID>: <clause>\` (bullet/bold/backtick all fine; the id must end in a number) so the MUST-coverage gate and the specFR axis can run.`);
+    findings.push(isUiFlow
+      ? `SPEC-IDS-UNPARSED: the feature cites ${cited.length} requirement id(s) via @spec: (${cited.slice(0, 5).join(', ')}${cited.length > 5 ? ', …' : ''}) that this FLOW's requirements/spec.md does not declare. That is normal when the ids belong to the SCREEN specs the flow traverses — but it means nothing here can verify them: the specFR axis and the MUST-coverage gate stay off for this unit. To gate the flow on them, restate each as \`<ID>: <clause>\` in the flow's own spec (a one-line restatement per id is enough).`
+      : `SPEC-IDS-UNPARSED: the feature cites ${cited.length} requirement id(s) via @spec: (${cited.slice(0, 5).join(', ')}${cited.length > 5 ? ', …' : ''}) but requirements/spec.md yielded ZERO parseable requirement declarations — the spec likely declares ids in a scheme the parser cannot read. Declare each requirement on its own line as \`<ID>: <clause>\` (bullet/bold/backtick all fine; the id must end in a number) so the MUST-coverage gate and the specFR axis can run.`);
   }
   if (taxonomyMismatch) {
     findings.push(`VP-TAXONOMY-MISMATCH: only ${(trace.mappedRatio * 100).toFixed(0)}% of scenarios use the viewpoint IDs declared in test-viewpoint.md — scenarios invented a generic VP-<CAT> scheme. Re-tag to the project's viewpoint IDs so the coverage matrix is accurate.`);
@@ -577,14 +685,20 @@ 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,
       businessDepth: Math.round(businessDepth * 100) / 100,
       balance: Math.round(balanceScore * 100) / 100,
       traceability: Math.round(traceScore * 100) / 100,
-      formula: 'overall = (0.4*coverage + 0.3*businessDepth + 0.15*balance + 0.15*traceability) * 10',
+      // Built from the axes ACTUALLY scored, with the renormalised weights — a hardcoded
+      // string drifted from the real calculation and printed axes (`balance` on a contract
+      // 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(', ')}` : '')
+        + (notApplicableByDesign.length ? ` — n/a for this unit kind: ${notApplicableByDesign.join(', ')}` : ''),
     },
     gateStatus,
     findings,