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

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;
@@ -34,9 +49,27 @@ export interface FlowContract {
   precondition?: string;
   outcome: { screen: string; assertion?: string };
   value?: string;
+  /** Postcondition when the goal IS reached — the business value, not "API 200". */
+  successGuarantee?: string;
+  /** Postcondition that holds in EVERY flow, INCLUDING failure — the question
+   *  "if this fails, what must still be true?" that Exception Flows assert against.
+   *  Without it an EF has no anchor and its assertions are guesswork (#592). */
+  minimalGuarantee?: string;
   /** 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>;
@@ -72,6 +105,9 @@ export interface FlowQualityResult {
 
 const DEFAULT_PHASES = ['HP', 'ER', 'EH'];
 
+/** The phase token of a flow id segment, branch number removed: `EF01` → `EF`, `HP` → `HP`. */
+const phaseToken = (seg: string): string => seg.replace(/\d+$/, '').toUpperCase();
+
 export function flowContractPath(unitDir: string): string {
   return path.join(unitDir, 'requirements', 'flow-contract.yaml');
 }
@@ -105,7 +141,26 @@ export function loadFlowContract(unitDir: string): { contract: FlowContract | nu
       precondition: raw.precondition !== undefined ? String(raw.precondition) : undefined,
       outcome: { screen: String(outcome!.screen).toLowerCase(), assertion: outcome!.assertion !== undefined ? String(outcome!.assertion) : undefined },
       value: raw.value !== undefined ? String(raw.value) : undefined,
+      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)
@@ -119,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,
   };
 }
 
@@ -134,12 +191,32 @@ 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 {
   const id = (s.vpId ?? '').toUpperCase();
+  // 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.
+  const segs = id.split('-').map(phaseToken);
   for (const ph of declared) {
-    if (new RegExp(`(^|-)${ph}(-|$)`).test(id)) return ph;
+    if (segs.includes(phaseToken(ph))) return ph;
   }
   const hay = s.haystack;
   if (declared.includes('EH') && /\b(direct access|without (a |the )?(submit|login)|browser back|refresh|expired|tamper|unauthoriz|redirect(ed)? (back )?to|guard)\b/.test(hay)) return 'EH';
@@ -148,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).
@@ -171,10 +343,14 @@ export function flowQuality(unitDir: string, scenarios: ScenarioInfo[]): FlowQua
   // --- Scope creep: a scenario that never touches the outcome and is not a ----
   // guard/error phase is evidence of a SECOND business goal in this flow.
   const declaredPhases = contract.phases;
+  const basic = declaredPhases.filter((p) => p !== 'UI')[0];
   const offGoalScenarios = scenarios.filter((s) => {
     if (touchesOutcome(s, outcomeScreen)) return false;
     const ph = phaseOf(s, declaredPhases);
-    return ph !== 'EH' && ph !== 'ER';    // guards/error-recovery legitimately stop early
+    // 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.
+    return ph === null || ph === basic;
   });
   const offGoalRatio = scenarios.length ? offGoalScenarios.length / scenarios.length : 0;
   const offGoalCategories = Array.from(new Set(
@@ -182,10 +358,13 @@ export function flowQuality(unitDir: string, scenarios: ScenarioInfo[]): FlowQua
 
   // --- Phase coverage: the flow's coverage axis (UI never demanded) -----------
   const demanded = declaredPhases.filter((p) => p !== 'UI');
+  // The FIRST declared phase is the Basic Flow (the primer allows exactly one) — it is the
+  // 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);
-    // HP must additionally prove the outcome — a data assertion elsewhere is not the goal.
-    const relevant = phase === 'HP' ? inPhase.filter((s) => touchesOutcome(s, outcomeScreen)) : inPhase;
+    // 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 {
       phase,
       covered: relevant.length > 0,
@@ -243,6 +422,47 @@ export function flowQuality(unitDir: string, scenarios: ScenarioInfo[]): FlowQua
   };
 }
 
+/**
+ * A continuity claim states that data SURVIVES a step boundary (buffered, persists,
+ * round-trips, restored). Every such mechanism has two sides, and a suite that proves
+ * only the surviving side has not tested the mechanism — it has tested the happy half.
+ *
+ * Field report (#592): the viewpoint declared "basic-info values are buffered in
+ * sessionStorage … a page reload or session-storage clear between those steps LOSES the
+ * buffered data". The suite proved back-navigation RESTORES the values and never proved a
+ * reload loses them — one mechanism, one side. The QA framework caught it by construction
+ * (AF-02 "giữ được" beside EF-11 "mất"); this sensor catches it deterministically.
+ *
+ * Advisory. Reported per claim, naming which side is missing.
+ */
+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;
+
+/**
+ * Continuity claims in the viewpoint file whose feature proves only ONE side.
+ * `claims` are the viewpoint's atomic item texts; `scenarioTexts` are per-scenario
+ * name+steps blobs (a claim's two sides may live in different scenarios).
+ */
+export function continuityGaps(claims: string[], scenarioTexts: string[]): ContinuityGap[] {
+  const out: ContinuityGap[] = [];
+  const anySide = (re: RegExp) => scenarioTexts.some((t) => re.test(t));
+  for (const claim of claims) {
+    if (!CONTINUITY_CLAIM.test(claim)) continue;
+    // Only judge a claim that itself names BOTH sides, or names the loss side: a claim that
+    // only ever promises persistence has no second side to demand.
+    const claimNamesLoss = SIDE_LOSS.test(claim);
+    if (!claimNamesLoss) continue;
+    const provesPersist = anySide(SIDE_PERSIST);
+    const provesLoss = anySide(SIDE_LOSS);
+    if (provesPersist && !provesLoss) out.push({ claim: claim.slice(0, 110), missing: 'loss' });
+    else if (provesLoss && !provesPersist) out.push({ claim: claim.slice(0, 110), missing: 'persistence' });
+  }
+  return out;
+}
+
 /**
  * Generalized stateful regression depth: the contract names the mutated collection,
  * so the three dims (count-proof · teardown · multi-source) stop being cart-only.
@@ -251,11 +471,37 @@ export function statefulDepthFor(collection: string, scenarios: ScenarioInfo[]):
   const hay = scenarios.map((s) => s.haystack);
   const any = (re: RegExp) => hay.some((h) => re.test(h));
   const noun = collection.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const countProof = any(new RegExp(`\\b(quantity|qty|row count|count|number of|two (rows|lines|items)|\\d+ (rows|lines|items))\\b`)) ;
-  const teardown = any(/\b(remove|delete|clear|cancel|withdraw)(?:s|d|ed|ing|n)?\b/) && any(new RegExp(`\\b(empty|emptied|no items|zero|removed|cleared|cancelled|withdrawn|0 items)\\b|empty[- ]${noun}`));
-  const adds = hay.filter((h) => new RegExp(`\\b(add|submit|create|place).{0,40}${noun}|${noun}.{0,40}\\b(add|submit|create|place)`).test(h));
-  const multiSource = any(/\b(recommended|related|you may also|another source|both sources|second (list|source))\b/) && adds.length > 0;
-  const dims: Array<[string, boolean]> = [['count-proof', countProof], ['teardown', teardown], ['multi-source', multiSource]];
-  const missing = dims.filter(([, v]) => !v).map(([k]) => k);
-  return { countProof, teardown, multiSource, missing, ratio: (dims.length - missing.length) / dims.length };
+
+  // Not every stateful flow is a COLLECTION. A cart accumulates rows, so counting them and
+  // feeding them from several sources are real regression dimensions; a registration state
+  // machine has neither, and demanding them produced advice no author could act on ("add to
+  // the cart from EVERY source" on a signup journey — #592). So each dimension is demanded
+  // only where the suite shows the vocabulary that makes it meaningful, and the ratio is
+  // renormalised over the applicable ones — the same "absent evidence scores nothing" rule
+  // the score axes already follow.
+  const accumulates = any(new RegExp(`\\b(rows?|items?|lines?|entries|quantity|qty|count)\\b`)) ||
+    any(new RegExp(`\\b${noun}\\s+(?:rows?|items?|lines?|count)\\b`));
+  const hasSources = any(/\b(recommended|related|you may also|another source|second (?:list|source)|from (?:the )?(?:list|rail|grid))\b/);
+
+  const countProof = any(/\b(quantity|qty|row count|count|number of|two (?:rows|lines|items)|\d+ (?:rows|lines|items))\b/);
+  // The inverse operation. A collection's is remove/clear; a state machine's is lose, expire,
+  // reset, restart, invalidate — and the outcome side below already accepted `lost`/`gone`
+  // while the verb side had no `lose`, so a suite proving exactly that was told it had not
+  // (#592: "add a REMOVE scenario" on a registration journey that already proves the buffer
+  // is lost and the link expires).
+  const teardown = any(/\b(remove|delete|clear|cancel|withdraw|abandon|lapse|expire|lose|lost|reset|restart|discard|invalidate|revert)(?:s|d|es|ed|ing|n)?\b/) &&
+    any(new RegExp(`\\b(empty|emptied|no items|zero|removed|cleared|cancelled|withdrawn|lost|gone|0 items|does not exist|no longer|awaiting|restart)\\b|empty[- ]${noun}`));
+  const multiSource = hasSources &&
+    any(new RegExp(`\\b(add|submit|create|place).{0,40}${noun}|${noun}.{0,40}\\b(add|submit|create|place)`));
+
+  const dims: Array<[string, boolean, boolean]> = [
+    ['count-proof', countProof, accumulates],
+    ['teardown', teardown, true],
+    ['multi-source', multiSource, hasSources || accumulates],
+  ];
+  const applicable = dims.filter(([, , app]) => app);
+  const missing = applicable.filter(([, v]) => !v).map(([k]) => k);
+  const ratio = applicable.length ? (applicable.length - missing.length) / applicable.length : 1;
+  return { countProof, teardown, multiSource, missing, ratio };
 }
+

package/src/harness/parse.ts

@@ -65,7 +65,10 @@ export function idPrefix(id: string): string {
  * QA to re-tag scenarios that were already correct.
  */
 function isViewpointId(s: string): boolean {
-  return isIdLike(s) || /^VP-[A-Z][A-Z0-9]*$/i.test(s);
+  // `FL-BF` / `FL-EF` are category ids exactly like `VP-LOGIC` — a flow declaring its
+  // phases under the FL- family had NO parsed viewpoints at all, which silently zeroed
+  // taxonomy and excluded traceability (#592).
+  return isIdLike(s) || /^(?:VP|FL)-[A-Z][A-Z0-9]*$/i.test(s);
 }
 
 export function parseViewpointOverview(filePath: string): ViewpointEntry[] {
@@ -141,6 +144,19 @@ export function parseViewpointOverview(filePath: string): ViewpointEntry[] {
 
 const PRIORITY_TAGS: Record<string, Priority> = { '@high': 'high', '@normal': 'normal', '@low': 'low' };
 
+/**
+ * Background steps EXECUTE for every scenario, so a sensor that reads only a scenario's own
+ * steps mis-measures the suite: a flow whose start state lives in `Background: Given User is
+ * on [Registration] page` looked like no scenario ever opened there, and downstream-scope
+ * reported the entry screen as merely navigated-to (#592). Prepending them here fixes every
+ * sensor at once — the same steps the runtime prepends.
+ */
+function withBackground(sc: ParsedScenario, background?: ParsedScenario): ParsedScenario {
+  const bg = background?.steps ?? [];
+  if (bg.length === 0) return sc;
+  return { ...sc, steps: [...bg, ...((sc.steps as ParsedStep[]) || [])] } as ParsedScenario;
+}
+
 function classifyScenario(sc: ParsedScenario): ScenarioInfo {
   const tags = sc.tags || [];
   const deferredToFlow = tags.includes('@deferred:flow');
@@ -171,7 +187,10 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
   // not just single-word ones. A single-word category (VP-CART-001) still works. (H1)
   // Flows use journey-phase ids (FL-HP-001 / FL-ER-002) — the VP- anchor rejected them, so every
   // flow scenario had NO category and the whole suite bucketed `other` (taxonomy=0%, #569).
-  const codeMatch = sc.name.match(/\b(?:VP|FL)-([A-Z]+(?:-[A-Z]+)*)-\d+/i);
+  // Segments may carry digits: the use-case framework numbers its flows (VP-AF02-01,
+  // VP-EF11-01 — one id per Alternate/Exception Flow), and `[A-Z]+` also silently truncated
+  // VP-I18N-001 to no category at all (the `18` broke the class mid-segment).
+  const codeMatch = sc.name.match(/\b(?:VP|FL)-([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*)-\d+/i);
   const vpCode = codeMatch ? codeMatch[0].toUpperCase() : undefined;
   const category = codeMatch ? codeMatch[1].toUpperCase() : undefined;
   // Project-scheme ID: the leading token of the title (VP0-001 / MS-HP-001 / VP-LIST-001).
@@ -245,7 +264,7 @@ export function loadScenarios(featurePath: string): ScenarioInfo[] {
   const feature = parser.parseFeatureFile(featurePath);
   return (feature.scenarios || [])
     .filter((s) => !s.stepsName && !s.hookType) // skip @steps/@hook blocks
-    .map(classifyScenario);
+    .map((s) => classifyScenario(withBackground(s, feature.background)));
 }
 
 /**

package/src/harness/quality-gates.ts

@@ -39,9 +39,20 @@ function downstreamRoutes(specText: string): string[] {
  * share state, so cart count/quantity asserts race. Mitigations: @cleanup:cart, @isolate, a fresh
  * browser context, or a "Given … empty cart" background. Returns true when the risk is unmitigated.
  */
-export function isolationRisk(featureText: string, stateful: boolean): boolean {
+export function isolationRisk(featureText: string, stateful: boolean, collection = 'cart'): boolean {
   if (!stateful || !/@parallel\b/i.test(featureText)) return false;
-  return !/@cleanup:cart\b|@isolate\b|empty cart|fresh (?:browser )?context|new context/i.test(featureText);
+  // What discharges the risk is isolation of THE MUTATED COLLECTION — so the cleanup tag has
+  // to name it (`@cleanup:cart` for a cart; `@cleanup:registration` for a registration flow).
+  // A cleanup of something else (`@cleanup:overlay`) leaves the shared state shared.
+  // Collection-independent mechanisms count for any flow: an explicit @isolate, a fresh
+  // browser context, unique data per run, or a Background restoring an empty start state.
+  // The collection is contract-declared now, so this no longer assumes a cart (#592: a
+  // registration flow was told it "mutates the cart"); `cart` stays the default for suites
+  // whose statefulness was inferred rather than declared.
+  const slug = collection.replace(/[^a-z0-9]+/gi, '[- ]?');
+  const named = new RegExp(`@cleanup:${slug}\\b|empty ${slug}\\b`, 'i');
+  const generic = /@isolate\b|empty state\b|fresh (?:browser )?context|new context|own fresh|{{\$timestamp}}/i;
+  return !named.test(featureText) && !generic.test(featureText);
 }
 
 /**
@@ -64,18 +75,50 @@ export function serialCascadeRisk(featureText: string, scenarioCount: number): n
   return scenarioCount;
 }
 
+/**
+ * Does a scenario OPEN ON the screen this route names? The route gives a URL slug
+ * (`basic-info`, `register`); the feature names screens by human label (`[Basic Info]`,
+ * `[Registration]`). A raw substring test fails on BOTH shapes of that mismatch — and
+ * did, in the field: `"registration".includes("register")` is FALSE ("registration" is
+ * regist+ration), and `"basic info".includes("basic-info")` is false on the separator.
+ * Every `Given User is on [Registration] page` was therefore invisible, so the sensor
+ * reported "only a page-nav assertion" for routes the suite genuinely operates on.
+ *
+ * Compare normalized (alphanumeric-only, lowercase): containment either way, or a shared
+ * prefix long enough to be the same word family (≥5 chars AND ≥60% of the shorter form) —
+ * which pairs register/registration and basic-info/"Basic Info", while keeping
+ * login/logout apart (shared prefix "log" is 3).
+ */
+const norm = (s: string): string => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+export function sameScreenName(slug: string, label: string): boolean {
+  const a = norm(slug), b = norm(label);
+  if (!a || !b) return false;
+  if (a.includes(b) || b.includes(a)) return true;
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  return i >= 5 && i / Math.min(a.length, b.length) >= 0.6;
+}
+
 export function downstreamScope(specText: string, scenarios: ScenarioInfo[]): DownstreamResult {
   const routes = downstreamRoutes(specText);
   const underCovered: { route: string; slug: string }[] = [];
   for (const route of routes) {
     const slug = (route.split('/').filter(Boolean).pop() || route).toLowerCase();
-    const refs = scenarios.filter((s) => s.haystack.includes(slug) || s.haystack.includes(route.toLowerCase()));
+    // Referenced when the route/slug appears literally, OR when any `[Ref]` in the suite
+    // names the same screen under its human label (register ↔ [Registration]).
+    const labelsOf = (s: ScenarioInfo): string[] =>
+      [...s.haystack.matchAll(/\[([^\]]+)\]/g)].map((m) => m[1].split(':')[0]);
+    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
     // 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.
-    const opensOn = new RegExp(`\\bis on \\[[^\\]]*${slug}`, 'i');
-    const contentCovered = refs.some((s) => opensOn.test(s.haystack));
+    const contentCovered = refs.some((s) =>
+      [...s.haystack.matchAll(/\bis on \[([^\]]+)\]/g)]
+        .some((m) => sameScreenName(slug, m[1].split(':')[0])));
     if (!contentCovered) underCovered.push({ route, slug });
   }
   return { downstreamRoutes: routes, underCovered };

package/src/harness/sensors.ts

@@ -40,6 +40,11 @@ const PHASE_BUCKETS: Record<string, string> = {
   HP: 'business-core',          // happy path = the business goal itself
   ER: 'validation-security',    // error recovery (validation must not trap the journey)
   EH: 'validation-security',    // guards & leakage (direct access, back, refresh)
+  // Use-case vocabulary (ISTQB/UC primer): one Basic Flow, N Alternate, N Exception.
+  // Alternate is a designed-for branch (not an error) → behaviour; Exception is blocked → guard side.
+  BF: 'business-core',
+  AF: 'behavior',
+  EF: 'validation-security',
 };
 
 /** Classify a VP category into a balance bucket by keyword containment + precedence (H1). */
@@ -47,7 +52,9 @@ export function bucketForCategory(category: string | undefined): string {
   const cat = (category || '').toUpperCase();
   if (!cat) return 'other';
   for (const seg of cat.split('-')) {
-    if (PHASE_BUCKETS[seg]) return PHASE_BUCKETS[seg];
+    // A flow id numbers its branch (AF02, EF11) — the phase is the letter part.
+    const phase = seg.replace(/\d+$/, '');
+    if (PHASE_BUCKETS[phase]) return PHASE_BUCKETS[phase];
   }
   for (const [bucket, kws] of BUCKET_ORDER) {
     if (kws.some((k) => cat.includes(k))) return bucket;
@@ -498,8 +505,17 @@ export interface TraceResult {
   note: string;
 }
 
+/**
+ * A viewpoint id without its family prefix. The use-case framework numbers flows and the
+ * two prefixes in circulation mean the same thing: a viewpoint declared `VP-BF` is the same
+ * family as a scenario coded `FL-BF-001` (and vice versa). Matching on the raw string made
+ * a correctly-traced flow suite read as 15% traceable (#592).
+ */
+const unprefixed = (id: string): string => id.replace(/^(?:VP|FL)-/i, '').toUpperCase();
+
 export function traceability(scenarios: ScenarioInfo[], viewpoints: ViewpointEntry[]): TraceResult {
   const overviewIds = new Set(viewpoints.map((v) => v.id.toUpperCase()));
+  const overviewBare = new Set(viewpoints.map((v) => unprefixed(v.id)));
   // A scenario carries an ID if it has a project-scheme leading ID (vpId) or a VP-CAT code.
   const withCode = scenarios.filter((s) => s.vpId || s.vpCode);
   // Maps to overview if the scenario's ID, its sequence-stripped prefix, or its VP-CAT code
@@ -507,6 +523,12 @@ export function traceability(scenarios: ScenarioInfo[], viewpoints: ViewpointEnt
   const mapped = withCode.filter((s) => {
     const id = (s.vpId || s.vpCode || '').toUpperCase();
     if (overviewIds.has(id) || overviewIds.has(idPrefix(id))) return true;
+    // Prefix-agnostic within the VP-/FL- family, and phase-family aware: FL-EF01-001 traces
+    // to a declared VP-EF (the branch number is part of the flow id, not of the family).
+    const bare = unprefixed(id), barePrefix = unprefixed(idPrefix(id));
+    if (overviewBare.has(bare) || overviewBare.has(barePrefix)) return true;
+    if ([...overviewBare].some((ob) => bare.startsWith(ob) || barePrefix.startsWith(ob) ||
+        bare.replace(/\d+$/, '').startsWith(ob.replace(/\d+$/, '')) && ob.length >= 2)) return true;
     return [...overviewIds].some((oid) => id.startsWith(oid) || oid.startsWith(idPrefix(id)) || (!!s.category && oid.includes(s.category)));
   });
   return {
@@ -621,7 +643,11 @@ const CLAIM_RULES: ClaimRule[] = [
     // "double-click does not create two orders" — not a per-feature keyword.
     claim: 'no-side-effect/no-duplicate',
     title: /(?=.*\b(submit|sen[dt]|resend|resubmit|re-?fire|re-?issue|re-?post|repost|create|charge|order|payment|\bpay\b|email|request|\botp\b|insert|register|book|duplicate|double[- ]?submit|again|twice)\b)(?=.*(\bno\b|\bnot\b|n['’]t\b|\bnever\b|\bwithout\b|\bcannot\b|prevent|block|avoid|reject|disabl|\bdeny\b|denies|\bkhông\b|\bchưa\b))/i,
-    proof: /\bcount\b|ok_count|status_counts|row with \{\{|table with|tohavecount|is hidden|are hidden|not complete|no longer/,
+    // `is disabled` counts: when the spec's own mechanism against a repeat is "the control
+    // is disabled immediately" (FR-014-style), asserting the disabled state IS the contrast —
+    // the second activation cannot occur. Without it the canonical double-submit proof shape
+    // was unrecognised (#592).
+    proof: /\bcount\b|ok_count|status_counts|row with \{\{|table with|tohavecount|is hidden|are hidden|is disabled|are disabled|not complete|no longer/,
     need: 'a record/request-count proof (count stays at one, e.g. `User see [Table] row with {{count}}`, an API `{{name.ok_count}}` invariant, or a `@query` DB count) or @manual with a request-count oracle',
     hint: 'a "does-not-happen / does-not-repeat" claim about a state-changing action is NOT proven by a terminal `see [...] page` — that page is identical whether or not the action (re-)fired. Prove the side-effect count is unchanged, or mark @manual with a setup→action→assert-no-duplicate oracle.',
     severity: 'fail',
@@ -728,9 +754,23 @@ const CATEGORY_SIGNALS: { cat: string; re: RegExp }[] = [
   { cat: 'LIST', re: /\b(product (list|grid)|featured product|product card|each (featured )?card|every (featured )?card)\b/ },
   { cat: 'NAV', re: /\b(navigates?|returns the user|redirect\w*|logo returns|menu navigates)\b/ },
   { cat: 'VAL', re: /\b(valid email|invalid\b|without (a |an )?@|without a domain|empty (email|input|field)|validation|required field)\b/ },
-  { cat: 'SEC', re: /\b(xss|sql|injection|payload|without authentication|unauthenticated|\binert\b|tamper\w*|malformed|url parameter|query param\w*|falls? back|gracefull?y|without a crash|not[- ]found|\b404\b|special character|abuse)\b/ },
+  // An access GUARD is security even when its only observable is a redirect: "direct access
+// … without a valid context redirects to X" used to match NAV (`redirect\w*`) and nothing in
+// SEC, so the linter told QA to re-tag genuine auth-gate tests as navigation — diluting the
+// visibility of the security suite (QA field report, 3.2.23). The guard vocabulary below is
+// what makes the INTENT matchable, and GUARD_INTENT then wins over a mere observable.
+  { cat: 'SEC', re: /\b(xss|sql|injection|payload|without authentication|unauthenticated|without an? (?:authenticated|valid|active) \w+|direct(?:ly)? access\w*|deep[- ]link\w*|auth[- ]?guard|not skippable|without having (?:completed|submitted|logged)|remains? unauthenticated|\binert\b|tamper\w*|malformed|url parameter|query param\w*|falls? back|gracefull?y|without a crash|not[- ]found|\b404\b|special character|abuse)\b/ },
 ];
 
+/**
+ * Categories whose signal describes the test's INTENT/risk rather than the observable action.
+ * When one of these matches, a competing observable-only category (NAV: "redirects", "navigates")
+ * must not out-vote it — the redirect is HOW the guard shows itself, not what the test is about.
+ */
+const INTENT_OVER_OBSERVABLE: Record<string, Set<string>> = {
+  SEC: new Set(['NAV']),
+};
+
 export function taxonomyLint(scenarios: ScenarioInfo[]): TaxonomyResult {
   const mislabeled: TaxonomyFinding[] = [];
   let checked = 0;
@@ -741,7 +781,10 @@ export function taxonomyLint(scenarios: ScenarioInfo[]): TaxonomyResult {
     const title = s.name.toLowerCase();
     const matched = [...new Set(CATEGORY_SIGNALS.filter((c) => c.re.test(title)).map((c) => c.cat))];
     if (matched.includes(cat)) continue;             // title supports its own category → fine
-    const others = matched.filter((c) => c !== cat);
+    // The declared category may be an INTENT category whose signal this title spells
+    // differently; never "correct" it toward a category that only names the observable.
+    const suppressed = INTENT_OVER_OBSERVABLE[cat];
+    const others = matched.filter((c) => c !== cat && !(suppressed && suppressed.has(c)));
     if (others.length === 1) {                        // unambiguous mismatch
       const sig = CATEGORY_SIGNALS.find((c) => c.cat === others[0])!;
       const m = title.match(sig.re);

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 };
+}