@sun-asterisk/sungen 3.2.25 → 3.2.26

package/src/harness/audit.ts

@@ -27,6 +27,8 @@ import { specCoverage, SpecCoverageResult, parseSpecClauses, restatedRequirement
 import { downstreamScope, manualOracle, readText, DownstreamResult, ManualOracleResult,
   negativeSideEffect, sourceBacked, crossArtifactOwnership, isolationRisk, serialCascadeRisk } from './quality-gates';
 import { viewpointLedger, parseViewpointItems, browserGestureSubstitutions, viewpointIntegrity, LedgerResult } from './viewpoint-ledger';
+import { specBranches, unenumeratedBranches, sameOracleClusters, permissionPairGaps, awaitingSeedData, unconsideredRisks, MULTI_SCREEN_RISKS } from './spec-branches';
+const MULTI_SCREEN_RISK_COUNT = MULTI_SCREEN_RISKS.length;
 import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 import { contextRouter } from '../capabilities/context-router';
@@ -65,6 +67,12 @@ export interface AuditReport {
   score: {
     overall: number;            // 0..10, business-weighted over the APPLICABLE axes
     notApplicable?: string[];   // axes with no evidence — excluded, not scored as 1.0
+    /**
+     * Why each excluded axis is excluded. "No evidence" and "evidence WITHHELD pending review"
+     * are different states with different remedies, and reporting both as "no evidence" told the
+     * author of a 93%-covered ledger to go write the viewpoint they had just written (#657).
+     */
+    naReasons?: Record<string, string>;
     cappedAt?: number;          // set when a weak critical axis holds the score down
     coverage: number;           // 0..1
     businessDepth: number;      // 0..1
@@ -76,7 +84,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; byDesign?: boolean }>;
+    axes: Array<{ key: string; value: number; weight: number; applicable: boolean; critical: boolean; byDesign?: boolean; withheld?: boolean }>;
     formula: string;
   };
   gateStatus: 'PASS' | 'FAIL';
@@ -196,7 +204,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const isUiFlowUnit = /^flows\//.test(catalogScreenName);
   const flowQ: FlowQualityResult = isUiFlowUnit
     ? flowQuality(screenDir, scenarios)
-    : { hasContract: false, errors: [], outcomeProven: false, outcomeManualOnly: false, offGoal: [], offGoalRatio: 0, offGoalCategories: [], phases: [], phaseRatio: 1, handoffs: { total: 0, asserted: 0, ratio: 1 }, sit: [] };
+    : { hasContract: false, errors: [], outcomeProven: false, outcomeManualOnly: false, offGoal: [], offGoalRatio: 0, offGoalCategories: [], phases: [], phaseRatio: 1, danglingPhaseRefs: [], handoffs: { total: 0, asserted: 0, ratio: 1 }, sit: [] };
   const gateCatalog = (flowQ.hasContract && !declaredPageType(viewpointText, catalog))
     ? { ...catalog, page_types: {} } as Catalog
     : catalog;
@@ -230,7 +238,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // #1 taxonomy-match: when the project defines a viewpoint taxonomy, scenarios must use it.
   const taxonomyMismatch = viewpoints.length > 0 && trace.withVpCode > 0 && trace.mappedRatio < 0.6;
   // #2 downstream-scope + #4 manual-oracle
-  const downstream = downstreamScope(readText(specPath), scenarios);
+  const downstream = downstreamScope(readText(specPath), scenarios, featureText);
   const manualOracleResult = manualOracle(featureText);
   const autoManual = automatableManual(scenarios); // TQ-2 — @manual that is really automatable
   const ledger = viewpointLedger(viewpointPath, scenarios, featureText);
@@ -331,7 +339,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // 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 }> = [
+  const axisDefs: Array<{ key: string; value: number; weight: number; applicable: boolean; critical: boolean; byDesign?: boolean; withheld?: boolean }> = [
     flowScored
       // A declared flow claimed only by @manual scenarios is ACCOUNTED FOR but nothing runs, so
       // it cannot count the same as an automated one — `covered` was collapsing three very
@@ -340,10 +348,10 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
       ? { key: 'flowCoverage', value: inventory ? Math.min((inventory.ratio + inventory.automatedRatio) / 2, flowQ.phaseRatio) : flowQ.phaseRatio, weight: 0.22, applicable: true, critical: true }
       : { key: 'coverage', value: coverage, weight: 0.22, applicable: !!gate.pageType && gate.themesTotal > 0, critical: true },
     { key: 'specFR', value: specRatio, weight: 0.15, applicable: spec.hasSpec && spec.frTotal > 0, critical: true },
-    { key: 'atomicLedger', value: ledger.ratio, weight: 0.13, applicable: ledger.hasViewpoint && ledger.total > 0 && !viewpointMoved, critical: true },
+    { key: 'atomicLedger', value: ledger.ratio, weight: 0.13, applicable: ledger.hasViewpoint && ledger.total > 0 && !viewpointMoved, critical: true, withheld: viewpointMoved && ledger.hasViewpoint && ledger.total > 0 },
     { 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: 'traceability', value: traceScore, weight: 0.09, applicable: viewpoints.length > 0 && !viewpointMoved, critical: false, withheld: viewpointMoved && viewpoints.length > 0 },
     // 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
@@ -394,10 +402,24 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const overall = seniorBandedOverall(rawOverall, { flowStateful: flowDepth.stateful, flowRatio: flowDepth.ratio, oracleWeak: oracle.weak.length, isolationRisk: isoRisk });
 
   const findings: string[] = [];
+  // A baseline that could not be compared was re-recorded rather than reported as an edit.
+  // Migrating in silence would be the same sin one level down, so it is stated.
+  if (viewpointBaseline.reparsed) {
+    findings.push(`VIEWPOINT-BASELINE-REPARSED: the recorded baseline for this unit was written by an earlier version whose viewpoint parser had a different granularity, so its ids cannot be compared with today's. \`test-viewpoint.md\` itself is unchanged — the file is now fingerprinted by its own bytes, which no parser upgrade can move, and the baseline has been re-recorded against it. \`atomicLedger\` and \`traceability\` count normally. If you DID edit the viewpoint since ${viewpointBaseline.recordedAt?.slice(0, 10) ?? 'it was accepted'}, review that diff yourself — this one migration could not tell an edit from the parser change.`);
+  }
   if (capped) {
     const why = weakestCritical && weakestCritical.value < 0.7
       ? `"${weakestCritical.key}" is ${(weakestCritical.value * 100).toFixed(0)}% — a weak axis is a hole, not something the other axes can average away`
-      : `this unit supplies no evidence for [${missingEvidence.join(', ')}], and a top mark has to rest on complete evidence`;
+      : (() => {
+        const held = axisDefs.filter((a) => a.withheld).map((a) => a.key);
+        const absent = missingEvidence.filter((k) => !held.includes(k.replace(/ .*$/, '')));
+        const parts = [];
+        if (absent.length) parts.push(`supplies no evidence for [${absent.join(', ')}]`);
+        // An axis WAS measured and is being held — saying "no evidence" here sends the author
+        // to write a declaration that already exists, when the actual next move is to review a diff.
+        if (held.length) parts.push(`has [${held.join(', ')}] measured but WITHHELD until the changed viewpoint baseline is reviewed and accepted`);
+        return `this unit ${parts.join(', and ')}, and a top mark has to rest on complete evidence`;
+      })();
     findings.push(`SCORE-CAPPED: overall held at ${cap.toFixed(1)} because ${why}.`);
   }
   if (viewpointBaseline.status === 'changed') {
@@ -622,6 +644,9 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   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.`);
   }
+  for (const a of downstream.absent.slice(0, 5)) {
+    findings.push(`NAV-TARGET-ABSENT: the spec declares "${a.route}" as a navigation target and NO scenario mentions it — not even a page assertion. Testing the render conditions of the region that links there does not test the link: a click-through case is what proves the destination. Add one, or record why this flow does not own it.`);
+  }
   for (const d of downstream.underCovered) {
     findings.push(`DOWNSTREAM-SCOPE-MISSING: "${d.route}" is a navigation target but is covered only by a page-nav assertion — cover its content/guards, or scaffold it (\`sungen add --screen ${d.slug}\`).`);
   }
@@ -670,6 +695,46 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   if (depth.deferredBusinessCritical > 0 && depth.deferredBusinessCritical >= depth.businessCriticalTotal) {
     findings.push(`DEPTH-DEFERRED: businessDepth ${businessDepth.toFixed(2)} is computed over only ${depth.businessCriticalTotal} on-screen scenario(s); ${depth.deferredBusinessCritical} business-critical scenario(s) are deferred to @manual (excluded from the ratio). Automate them in a flow and verify with \`sungen flow-check\` — this ratio is NOT "all business depth covered".`);
   }
+  // #630 — the branches the spec ENUMERATES must each have a scenario. Narrative guidance for
+  // this already existed and was missed three times in three flows, so the check is an enforced
+  // enumeration rather than another sentence.
+  {
+    const branches = specBranches(readText(specPath) ?? '');
+    for (const b of unenumeratedBranches(branches, featureText).slice(0, 6)) {
+      findings.push(`SPEC-BRANCH-UNCOVERED: the spec enumerates "${b.label}" (${b.source}) and no scenario cites it. A mutually-exclusive branch is only covered when its OWN arm is verified — covering a sibling arm proves nothing about this one. Write it, or record the exclusion in the feature so the omission is a decision.`);
+    }
+    for (const c of sameOracleClusters(scenarios).slice(0, 4)) {
+      findings.push(`BRANCH-OVERCLAIMED: ${c.scenarios.length} scenarios assert an identical oracle (${c.scenarios.slice(0, 3).join(' | ')}${c.scenarios.length > 3 ? ' …' : ''}) — "${c.oracle}". They verify one branch several times while the coverage sheet counts them as ${c.scenarios.length}. Give each the assertion that distinguishes ITS branch, or merge them.`);
+    }
+  }
+  // #651 F1-7 — the fixed risk catalog, reconciled. SPEC-BRANCH-UNCOVERED enforces the branches a
+  // spec DECLARES; this is the half a spec is often silent about, which a reviewer catches and a
+  // generator does not. Consideration counts from anywhere the author reasons — a declared flow's
+  // branch point or reason, a scenario, the viewpoint — so "thought about, does not apply" is a
+  // one-line answer rather than a scenario nobody needs.
+  if (flowQ.hasContract) {
+    const unconsidered = unconsideredRisks(flowQ.contract!, scenarios, viewpointText);
+    if (unconsidered.length > 0) {
+      const list = unconsidered.map((r) => `${r.label} (${r.why})`).join(' · ');
+      findings.push(`RISK-FAMILY-UNCONSIDERED: ${unconsidered.length} of ${MULTI_SCREEN_RISK_COUNT} multi-screen risk families are not mentioned anywhere in this flow's contract, viewpoint or scenarios — ${list}. Each is a question, not a demand: if it does not apply here, record that in the \`flows:\` inventory as \`out-of-scope\` with the reason and it stops being asked. A flow is "enough" when every family has an answer, and a silent family is the one nobody weighed.`);
+    }
+  }
+  // #630 — a deny-side security case with no allow-side counterpart cannot tell a working guard
+  // from a feature that is broken for everyone.
+  for (const g of permissionPairGaps(scenarios).slice(0, 4)) {
+    findings.push(`PERMISSION-PAIR-MISSING: "${g.scenario}" proves the content is hidden when permission is denied, but no scenario proves it is SHOWN when permission is granted. If the code hid it unconditionally this would still pass — the pair is the test, the way min-1/min/max/max+1 is the test for a boundary. Add the allow-side case${g.subject.length ? ` for [${g.subject.join(', ')}]` : ''}.`);
+  }
+  // #630 — a scenario blocked on unseeded data is a DATA task, not unfinished test design.
+  {
+    const tdDir = path.join(screenDir, 'test-data');
+    let tdText = '';
+    try {
+      for (const f of fs.readdirSync(tdDir).filter((x) => x.endsWith('.yaml'))) tdText += `${readText(path.join(tdDir, f)) ?? ''}\n`;
+    } catch { /* no test-data yet */ }
+    for (const a of awaitingSeedData(tdText, scenarios).slice(0, 4)) {
+      findings.push(`AWAITING-SEED-DATA: \`${a.key}\` is still a placeholder and ${a.scenarios.length} scenario(s) reference it (${a.scenarios.slice(0, 2).join(' | ')}${a.scenarios.length > 2 ? ' …' : ''}). These are Pending for a DATA reason, not an unresolved design — seed the value (or move it to \`<unit>.<env>.yaml\`) and they become runnable as written.`);
+    }
+  }
   // #622 — a claim that names a count, proved by fewer assertions than it names. The count sits
   // in the viewpoint CLAIM, so both the title-level and the claim-level shape are checked.
   for (const g of ledger.partial.slice(0, 5)) {
@@ -791,7 +856,12 @@ 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(', ')}` : '')
+        + (() => {
+          const held = new Set(axisDefs.filter((a) => a.withheld).map((a) => a.key));
+          const absent = missingEvidence.filter((k) => !held.has(k.replace(/ .*$/, '')));
+          return (absent.length ? ` — n/a (no evidence): ${absent.join(', ')}` : '')
+            + (held.size ? ` — measured but held: ${[...held].join(', ')}` : '');
+        })()
         + (notApplicableByDesign.length ? ` — n/a for this unit kind: ${notApplicableByDesign.join(', ')}` : ''),
     },
     gateStatus,

package/src/harness/flow-contract.ts

@@ -40,6 +40,13 @@ export interface FlowDecl {
   reason?: string;
 }
 
+/** One declared journey phase. `scenarios:` is the author naming its evidence directly. */
+export interface FlowPhaseDecl {
+  id: string;
+  description?: string;
+  scenarios?: string[];
+}
+
 const FLOW_STATUSES = new Set(['covered', 'deferred', 'pending-clarification', 'out-of-scope']);
 
 export interface FlowContract {
@@ -58,6 +65,12 @@ 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 phases as DECLARED, when the contract uses the object form. A phase may name the
+   * scenarios that carry it — direct evidence, rather than the harness inferring coverage from
+   * id segments — and that is what a project which writes `phases:` this way is telling us.
+   */
+  phaseDetails?: FlowPhaseDecl[];
   /**
    * 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
@@ -94,6 +107,8 @@ export interface FlowQualityResult {
   /** Off-goal categories, for the split suggestion ("VP-FILTER-* looks like its own flow"). */
   offGoalCategories: string[];
   phases: { phase: string; covered: boolean; automated: boolean }[];
+  /** Phase-declared scenario refs that match no scenario — a phase whose evidence does not exist. */
+  danglingPhaseRefs: Array<{ phase: string; ref: string }>;
   /** Covered-and-automated phases / declared phases (UI excluded) — the flow coverage axis. */
   phaseRatio: number;
   /** Cross-namespace transitions followed by an assertion / all transitions. */
@@ -130,9 +145,34 @@ export function loadFlowContract(unitDir: string): { contract: FlowContract | nu
     errors.push('missing `outcome.screen:` — the screen namespace that carries the final proof');
   }
   if (errors.length > 0) return { contract: null, errors };
-  const phases = Array.isArray(raw.phases) && raw.phases.length > 0
-    ? (raw.phases as unknown[]).map((x) => String(x).toUpperCase())
-    : DEFAULT_PHASES;
+  // `phases:` comes in two shapes, and the loader used to assume the first. A real project
+  // declared the RICHER one — each phase an object with `name`, `description` and an explicit
+  // `scenarios:` list — and `String(x).toUpperCase()` turned every one of them into
+  // `[OBJECT OBJECT]`. Nothing matched, phase coverage read 0%, the score fell to 6.9, and the
+  // report said only that the phases were uncovered. Garbage in place of an error is the worst
+  // of both: the author sees a broken number with no cause (#657).
+  //
+  // The object form is the better declaration — it names the scenarios that carry the phase
+  // instead of leaving the harness to infer them from ids — so it is read, not merely tolerated.
+  const phaseDetails: FlowPhaseDecl[] = Array.isArray(raw.phases)
+    ? (raw.phases as unknown[]).map((x, i) => {
+      if (x !== null && typeof x === 'object') {
+        const o = x as Record<string, unknown>;
+        const name = o.name ?? o.id ?? o.phase;
+        if (name === undefined) {
+          errors.push(`phases[${i}] is an object with no \`name:\` (or \`id:\`) — a phase needs a label`);
+          return { id: `PHASE${i + 1}` };
+        }
+        return {
+          id: String(name).toUpperCase(),
+          description: o.description !== undefined ? String(o.description) : undefined,
+          scenarios: Array.isArray(o.scenarios) ? (o.scenarios as unknown[]).map((v) => String(v)) : undefined,
+        };
+      }
+      return { id: String(x).toUpperCase() };
+    })
+    : [];
+  const phases = phaseDetails.length > 0 ? phaseDetails.map((p) => p.id) : DEFAULT_PHASES;
   return {
     contract: {
       goal: String(raw.goal),
@@ -144,6 +184,7 @@ 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,
+      ...(phaseDetails.some((p) => p.scenarios || p.description) ? { phaseDetails } : {}),
       flows: Array.isArray(raw.flows)
         ? (raw.flows as Array<Record<string, unknown>>)
             .filter((f) => f && typeof f === 'object' && f.id)
@@ -209,8 +250,17 @@ function reachesOutcome(s: ScenarioInfo, outcomeScreen: string): boolean {
 
 /** 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 {
+export function phaseOf(s: ScenarioInfo, declared: string[], details?: FlowPhaseDecl[]): string | null {
   const id = (s.vpId ?? '').toUpperCase();
+  // When a phase NAMES its scenarios, that list is the mapping — the author has already done
+  // the assignment, and inferring it from id segments instead would ignore them. A phase called
+  // "Cross-screen data" shares no token with `VP-LOGIC-002`; only the declaration connects them.
+  for (const ph of details ?? []) {
+    if (ph.scenarios?.some((ref) => {
+      const r = ref.trim().toUpperCase();
+      return r === id || (r.length > 0 && s.name.toUpperCase().includes(r));
+    })) return ph.id;
+  }
   // A DECLARED phase wins, matched on the id's segments with the branch number removed —
   // so the use-case vocabulary (VP-EF01-01, VP-AF02-01: one id per Exception/Alternate
   // Flow) resolves to its phase exactly like the flat HP/ER/EH form does.
@@ -350,7 +400,7 @@ export function flowQuality(unitDir: string, scenarios: ScenarioInfo[]): FlowQua
   const neutral: FlowQualityResult = {
     hasContract: false, errors, outcomeProven: false, outcomeManualOnly: false,
     offGoal: [], offGoalRatio: 0, offGoalCategories: [],
-    phases: [], phaseRatio: 1, handoffs: { total: 0, asserted: 0, ratio: 1 }, sit: [],
+    phases: [], phaseRatio: 1, danglingPhaseRefs: [], handoffs: { total: 0, asserted: 0, ratio: 1 }, sit: [],
   };
   if (!contract) return neutral;
 
@@ -367,7 +417,7 @@ export function flowQuality(unitDir: string, scenarios: ScenarioInfo[]): FlowQua
   const basic = declaredPhases.filter((p) => p !== 'UI')[0];
   const offGoalScenarios = scenarios.filter((s) => {
     if (touchesOutcome(s, outcomeScreen)) return false;
-    const ph = phaseOf(s, declaredPhases);
+    const ph = phaseOf(s, declaredPhases, contract.phaseDetails);
     // Any NON-basic declared phase (guards, error recovery, alternate branches) legitimately
     // stops before the outcome — that is what a branch IS. Only an unclassified scenario that
     // never reaches the outcome is evidence of a second business goal.
@@ -383,7 +433,7 @@ export function flowQuality(unitDir: string, scenarios: ScenarioInfo[]): FlowQua
   // phase that must reach the declared outcome, whether the project spells it HP or BF.
   const basicPhase = demanded[0];
   const phases = demanded.map((phase) => {
-    const inPhase = scenarios.filter((s) => phaseOf(s, declaredPhases) === phase);
+    const inPhase = scenarios.filter((s) => phaseOf(s, declaredPhases, contract.phaseDetails) === phase);
     // The basic flow must additionally prove the outcome — a data assertion elsewhere is not the goal.
     const relevant = phase === basicPhase ? inPhase.filter((s) => touchesOutcome(s, outcomeScreen)) : inPhase;
     return {
@@ -396,6 +446,17 @@ export function flowQuality(unitDir: string, scenarios: ScenarioInfo[]): FlowQua
     ? phases.filter((p) => p.covered && p.automated).length / demanded.length
     : 1;
 
+  // A phase that names a scenario which does not exist is a declaration pointing at nothing:
+  // the phase reads covered in the contract and is empty in the suite. Same class as a dangling
+  // traceability ref — the map, not the territory.
+  const known = new Set(scenarios.flatMap((s) => [s.vpId?.toUpperCase(), s.name.toUpperCase()].filter(Boolean) as string[]));
+  const danglingPhaseRefs = (contract.phaseDetails ?? []).flatMap((ph) => (ph.scenarios ?? [])
+    .filter((ref) => {
+      const r = ref.trim().toUpperCase();
+      return !known.has(r) && !scenarios.some((s) => s.name.toUpperCase().includes(r));
+    })
+    .map((ref) => ({ phase: ph.id, ref })));
+
   // --- Handoff integrity: no blind tail after a cross-namespace transition. ---
   // A transition counts as asserted when ANY assertion follows it — in the entered
   // namespace or later. Demanding the assertion in the entered namespace itself
@@ -439,7 +500,7 @@ export function flowQuality(unitDir: string, scenarios: ScenarioInfo[]): FlowQua
     outcomeProven, outcomeManualOnly,
     offGoal: offGoalScenarios.map((s) => s.name.slice(0, 80)),
     offGoalRatio, offGoalCategories,
-    phases, phaseRatio, handoffs, sit,
+    phases, phaseRatio, danglingPhaseRefs, handoffs, sit,
   };
 }
 
@@ -460,7 +521,24 @@ export interface ContinuityGap { claim: string; missing: 'loss' | 'persistence'
 
 const CONTINUITY_CLAIM = /\b(buffer(?:s|ed|ing)?|persist(?:s|ed|ence)?|round[- ]?trips?|restor(?:e|es|ed|ation)|carr(?:y|ied|ies)|retain(?:s|ed)?|session[- ]?storage|local[- ]?storage)\b/i;
 const SIDE_PERSIST = /\b(restor(?:e|es|ed)|persist(?:s|ed)?|unchanged|same value|round[- ]?trips?|re-?hydrat\w*|still (?:shows|holds)|carr(?:y|ied|ies)|retain(?:s|ed)?|prefilled|pre-?filled)\b/i;
-const SIDE_LOSS = /\b(lose|loses|lost|cleared?|clears|discard\w*|reload\w*|refresh\w*|expire\w*|empty|blank|not restored|no longer|wiped?|reset)\b/i;
+// A LOSS CONSTRUCTION, not a word list. `reset` and `expire` are domain NOUNS — every claim in a
+// password-*reset* flow contains "reset", and every token flow contains "expire", so a bare-word
+// list marked all of them as promising that state is lost and then demanded the missing half.
+// A field report hit exactly that: the two sides of its mechanism were both written (in two
+// different scenarios, which this already handles) and CONTINUITY-ONE-SIDED fired anyway (#630).
+// The state has to be the thing that goes: `is cleared`, `loses the values`, `no longer holds`.
+const SIDE_LOSS = new RegExp([
+  '\\b(?:lose|loses|losing|lost)\\b',
+  '\\b(?:is|are|gets?|got|becomes?|will be|was|were)\\s+(?:lost|cleared|emptied|discarded|wiped|reset|blanked)\\b',
+  '\\b(?:clears|clearing|discards|discarding|wipes|wiping)\\b',
+  '\\b(?:does|do|did)\\s+not\\s+(?:survive|persist|remain|carry)\\b',
+  '\\bnot\\s+(?:restored|retained|preserved|kept)\\b',
+  '\\bno longer\\b',
+  '\\bcomes? up (?:empty|blank)\\b',
+  // The triggers that CAUSE the loss still count when the claim names them as such.
+  '\\b(?:on|after) (?:a )?(?:reload|refresh)\\b',
+  '\\breload(?:ing|s|ed)? (?:the )?(?:page|screen|form|tab)\\b',
+].join('|'), 'i');
 
 /**
  * Continuity claims in the viewpoint file whose feature proves only ONE side.

package/src/harness/quality-gates.ts

@@ -14,24 +14,46 @@ import { readTextFile } from './read-text';
 export interface DownstreamResult {
   downstreamRoutes: string[];                 // success/navigation targets ≠ own route
   underCovered: { route: string; slug: string }[]; // referenced only by a bare page-nav
+  /**
+   * Declared navigation targets NO scenario mentions at all. These used to be skipped as "out of
+   * this screen's scope", which is right for a screen and wrong for a FLOW: a field report found a
+   * dashboard whose spec declared four click-through destinations and whose suite tested only the
+   * render conditions of the regions containing them — the navigation itself had no case, and
+   * nothing said so (#630).
+   */
+  absent: { route: string; slug: string }[];
 }
 
 /** Routes the spec hands off to (Navigation Flow / success), other than the screen's own route. */
 function downstreamRoutes(specText: string): string[] {
   const ownRoute = (specText.match(/\*\*Route\*\*\s*:\s*`?(\/[^\s`]+)/) || [])[1] || '';
   const routes = new Set<string>();
+  const negated = new Set<string>();
   for (const line of specText.split('\n')) {
     if (!/success|navigat|to \(|→/i.test(line)) continue;
     // A real route's leading `/` sits at a path boundary (start, whitespace, backtick, quote, paren),
     // NOT after a letter/digit. The lookbehind rejects prose slashes like "text/icon" or
     // "category/brand" that aren't routes at all (H2 — they produced /icon, /button, /brand).
+    let negRun = false;      // inside a "…, not `/a`/`/b`" list
+    let prevEnd = 0;
     for (const m of line.matchAll(/(?<![A-Za-z0-9])(\/[a-z][a-z0-9/_-]+)`?/gi)) {
       const r = m[1];
+      // "the destination is `/a/b` (singular, not `/a/bs` as this spec assumed)" declares ONE
+      // target and CORRECTS another. A spec that says where a route is NOT is doing the reader a
+      // service; extracting the disowned one and demanding a test for it punishes the correction.
+      // The negation carries across a LIST — "not `/x`/`/y`" disowns both, not just the first.
+      const before = line.slice(Math.max(0, m.index - 24), m.index);
+      const gap = line.slice(prevEnd, m.index);
+      prevEnd = m.index + m[0].length;
+      if (/\b(?:not|instead of|rather than|no longer|never|không)\s*[`'"(\[]*\s*$/i.test(before)) negRun = true;
+      else if (negRun && !/^[`'"\s)\]]*[/,]?\s*(?:or|hoặc)?\s*[`'"(\[]*$/i.test(gap)) negRun = false;
+      if (negRun) { negated.add(r); continue; }
       if (r !== ownRoute && r.split('/').length > ownRoute.split('/').length - 0) routes.add(r);
     }
   }
+  for (const n of negated) if (!routes.has(n)) routes.delete(n);
   // keep only routes that extend beyond the own route (a distinct downstream surface)
-  return [...routes].filter((r) => r !== ownRoute && (!ownRoute || r.startsWith(ownRoute + '/') || r.split('/').length >= 3));
+  return [...routes].filter((r) => !negated.has(r) && r !== ownRoute && (!ownRoute || r.startsWith(ownRoute + '/') || r.split('/').length >= 3));
 }
 
 /**
@@ -100,9 +122,27 @@ export function sameScreenName(slug: string, label: string): boolean {
   return i >= 5 && i / Math.min(a.length, b.length) >= 0.6;
 }
 
-export function downstreamScope(specText: string, scenarios: ScenarioInfo[]): DownstreamResult {
-  const routes = downstreamRoutes(specText);
+export function downstreamScope(
+  specText: string, scenarios: ScenarioInfo[], featureText = '',
+): DownstreamResult {
+  const all = downstreamRoutes(specText);
+  // A one-segment route that other declared routes are BUILT ON is a prefix, not a destination:
+  // a spec noting that "every route is served under a `/xx/` locale prefix (e.g. `/xx/register`)"
+  // was read as declaring `/xx/` a navigation target, and no suite will ever "navigate to" it.
+  // Structural, so it catches any mount point — locale, tenant, api version — without a list.
+  const mounts = all.filter((r) => {
+    const segs = r.split('/').filter(Boolean);
+    return segs.length === 1 && all.some((o) => o !== r && o.startsWith(r.endsWith('/') ? r : `${r}/`));
+  });
+  // The same destination written twice — once bare, once under the mount the spec documents —
+  // is one navigation target, and reporting both doubles the work it asks for.
+  const routes = all.filter((r) => !mounts.includes(r)
+    && !mounts.some((m) => {
+      const bare = r.slice(m.replace(/\/$/, '').length);
+      return bare.startsWith('/') && all.includes(bare);
+    }));
   const underCovered: { route: string; slug: string }[] = [];
+  const absent: { route: string; slug: string }[] = [];
   for (const route of routes) {
     const slug = (route.split('/').filter(Boolean).pop() || route).toLowerCase();
     // Referenced when the route/slug appears literally, OR when any `[Ref]` in the suite
@@ -112,16 +152,34 @@ export function downstreamScope(specText: string, scenarios: ScenarioInfo[]): Do
     const refs = scenarios.filter((s) =>
       s.haystack.includes(slug) || s.haystack.includes(route.toLowerCase()) ||
       labelsOf(s).some((l) => sameScreenName(slug, l)));
-    if (!refs.length) continue; // not referenced at all — out of this screen's scope entirely
+    if (!refs.length) {
+      // A scenario's haystack is its name + steps, so a route documented in a @manual scenario's
+      // tester procedure — a COMMENT — looks like nothing at all. That route is accounted for: a
+      // person has been told to check it. Reporting "no scenario mentions it, add one" over a
+      // deliberate manual deferral is the false positive this whole round is about, so absence is
+      // measured against the feature TEXT, comments included (#651 follow-up).
+      if (!featureText.toLowerCase().includes(route.toLowerCase())) absent.push({ route, slug });
+      continue;
+    }
     // Substantively covered only if some scenario OPERATES on the downstream — i.e. it
     // starts there (`is on [<downstream>]`) — not merely navigates to it as a terminal
     // `see [<downstream>] page` assertion. The latter just proves the transition.
+    // Two shapes prove the screen's CONTENT was checked, not just its route:
+    //   - the suite OPENS ON it (`is on [Registration] page`), and
+    //   - it asserts an element NAMESPACED to it (`see [Registration:Submit] button`) — the
+    //     namespace names the screen, so the assertion is about that screen by construction.
+    // Only the first counted, so a scenario that navigated there and then asserted the screen's
+    // own elements was still reported "covered only by a page-nav assertion" (#630). The field
+    // report's hypothesis — that the parser reads one line after the nav and stops — is still not
+    // what happens: there is no line window, and both shapes are matched over the whole scenario.
     const contentCovered = refs.some((s) =>
       [...s.haystack.matchAll(/\bis on \[([^\]]+)\]/g)]
-        .some((m) => sameScreenName(slug, m[1].split(':')[0])));
+        .some((m) => sameScreenName(slug, m[1].split(':')[0]))
+      || [...s.haystack.matchAll(/\bsee \[([^\]:]+):[^\]]+\]/g)]
+        .some((m) => sameScreenName(slug, m[1])));
     if (!contentCovered) underCovered.push({ route, slug });
   }
-  return { downstreamRoutes: routes, underCovered };
+  return { downstreamRoutes: routes, underCovered, absent };
 }
 
 // ---------- #4 Manual-oracle ----------