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

package/src/harness/flow-contract.ts

@@ -34,6 +34,12 @@ 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[];
@@ -72,6 +78,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,6 +114,8 @@ 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,
       stateful: raw.stateful !== undefined ? String(raw.stateful).toLowerCase() : undefined,
       budgets: (raw.budgets && typeof raw.budgets === 'object') ? raw.budgets as Record<string, number> : undefined,
@@ -138,8 +149,12 @@ function touchesOutcome(s: ScenarioInfo, outcomeScreen: string): boolean {
  *  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';
@@ -171,10 +186,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 +201,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 +265,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 +314,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/viewpoint-ledger.ts

@@ -23,6 +23,19 @@ export interface LedgerResult {
 }
 
 const ID_RE = /\b([A-Z]{1,5}\d{0,2}(?:[.\-][A-Za-z0-9]+)*-?\d{0,3})\b/; // VP0.Title, VP7-002, MS-HP-001, TV-01
+
+/**
+ * Lines that DECLARE something about the checklist rather than being a checklist item —
+ * atomizing them manufactures gaps that can never be closed (QA field report: 4 of 6
+ * "missing items" were a `qa/bug-reports` placeholder plus three Priority-Viewpoints
+ * rows whose third cell is the PROSE REASON for a priority, not a claim to test).
+ */
+// "None on file yet …", "N/A", "TBD", "Do not invent …" — an explicit statement that there
+// is nothing here. A gap report built from these tells the author to test the absence.
+const PLACEHOLDER_ITEM = /^(none\b|n\/a\b|tbd\b|no known\b|nothing\b|do not invent\b|-+$)/i;
+/** A priority-DECLARATION row: `| VP-LOGIC | High | <reason prose> |`. The category id and its
+ *  priority are consumed by the traceability + balance axes; the reason is rationale. */
+const PRIORITY_ROW = /^(?:VP|FL)[A-Z0-9._-]*\s+—\s+(?:critical|high|medium|normal|low|deferred)\b/i;
 const GENERIC = new Set(['display', 'shown', 'value', 'field', 'input', 'page', 'screen', 'button', 'link', 'text', 'check', 'verify', 'should', 'with', 'when', 'then', 'user', 'this', 'that', 'each', 'item', 'items']);
 
 /** Extract atomic checklist items from a viewpoint file (format-tolerant). */
@@ -42,11 +55,13 @@ export function parseViewpointItems(viewpointPath: string): { id?: string; text:
     else if (line.startsWith('|')) {                       // table data row
       if (/^\|[\s|:-]+\|?$/.test(line)) continue;           // separator
       const cells = line.split('|').map((c) => c.trim()).filter(Boolean);
-      if (/^(vp|id|viewpoint|priority|reason|no\.?|category|item|trigger|#|pattern|applicable|notes|field|constraint|code|description|status)$/i.test(cells[0] || '')) continue; // header
+      if (/^(vp|id|viewpoint|priority|reason|no\.?|category|item|trigger|#|pattern|applicable|notes|field|constraint|code|description|status|step|flow|ref|level|question|screen|actor|branches from|own steps|component|thành phần|trường|bước)$/i.test(cells[0] || '')) continue; // header
       text = cells.join(' — ');
     } else continue;
     text = text.replace(/[*`]/g, '').trim();
     if (!text) continue;
+    if (PLACEHOLDER_ITEM.test(text)) continue;   // "None on file yet" is not a claim
+    if (PRIORITY_ROW.test(text)) continue;       // priority declaration, not a checklist item
     const idM = text.match(ID_RE);
     const id = idM && /\d/.test(idM[1]) ? idM[1] : undefined; // require a digit so prose words aren't IDs
     const words = (text.toLowerCase().match(/[a-z][a-z-]{3,}/g) || []).filter((w) => !GENERIC.has(w));

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

@@ -30,6 +30,23 @@ If `spec_figma.md` exists OR the user provides a Figma URL for the PAT flow:
 **Input**: Screen or flow name (e.g., `/sungen-create-test admin-users`).
 {{/cap}}
 
+## ⛔ HARD RULE — in flow mode, AUTHOR the flow contract before generating
+
+If `requirements/flow-contract.yaml` is missing, **write it first** — never cite a contract you
+did not create, and never generate scenarios without one. Without it the flow is scored as a
+generic screen (page-type themes that do not fit a journey), and the audit reports
+`FLOW-CONTRACT-MISSING`.
+
+It needs the use-case declaration ONCE — actor · trigger · goal · precondition · `outcome` —
+plus **both** postconditions: `successGuarantee` (true when the goal is reached) and
+`minimalGuarantee` (what must still hold when the journey FAILS). Exception flows assert against
+the second one; with no `minimalGuarantee` they can only prove "an error appeared"
+(`FLOW-GUARANTEE-MISSING`). Then declare `phases:` — `[BF, AF, EF]` for a use-case decomposition
+(the first phase is the Basic Flow) — and enumerate flows with the step × risk matrix in the
+`sungen-tc-generation` skill.
+
+---
+
 ## Platform detection (do this FIRST)
 
 Read `qa/capabilities.yaml` and check the `platform` field — **and the verification scope** (`verification:` if set, else derived from `enabled`: `ui` always; `api`/`db` only if that driver is on). This is the project's recorded **test type**: an **E2E/UI-only** project (no `api`/`db`) must NOT get `@api`/`@query`/`@requires:api|db` verification unless the test-viewpoint explicitly asks for it — keep oracles UI-observable, and cap any in-scope API/DB-in-E2E verification at the **≤20% band** (see `sungen-tc-generation` → "Respect the project's verification scope"). `sungen audit` flags `VERIFICATION-OUT-OF-SCOPE`.

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

@@ -636,10 +636,21 @@ those namespaces are the **System INTEGRATION** group — keep their oracles abo
 
 **Read `requirements/flow-contract.yaml` FIRST — it is the flow's boundary and the yardstick
 `sungen audit` scores the flow against** (`flowCoverage` axis = journey phases HP/ER/EH automated;
-`FLOW-OUTCOME-UNPROVEN`; `FLOW-SCOPE-CREEP`). No contract yet → author it with the user via the
-boundary checklist in `add-flow` (one business goal · clear trigger · ONE observable outcome
-valuable to the actor · name = "Verb + outcome"), THEN generate. **A filled contract is an INPUT —
-never rewrite it to match your output** (same rule as `test-viewpoint.md`).
+`FLOW-OUTCOME-UNPROVEN`; `FLOW-SCOPE-CREEP`). **A filled contract is an INPUT — never rewrite it
+to match your output** (same rule as `test-viewpoint.md`).
+
+> **HARD RULE — the contract must be AUTHORED, never merely cited.** If
+> `requirements/flow-contract.yaml` is absent, WRITE it (with the user, via the boundary checklist
+> in `add-flow`: one business goal · clear trigger · ONE observable outcome valuable to the actor ·
+> name = "Verb + outcome") **before** generating scenarios. Citing a contract you did not create
+> leaves the flow scored as a generic screen — `flowCoverage` never applies, `coverage` falls back
+> to page-type themes that do not fit a journey, and the audit reports `FLOW-CONTRACT-MISSING`.
+> A contract also needs **both** guarantees, not just the happy one:
+>
+> - `successGuarantee` — everything true once the goal IS reached (what the Basic Flow proves).
+> - `minimalGuarantee` — what must still hold when the journey **FAILS** (no duplicate record, no
+>   mail on a rejected submit, no half-written state). Without it an Exception Flow has nothing to
+>   assert against beyond "an error appeared", and `FLOW-GUARANTEE-MISSING` is reported.
 
 | Aspect | Screen | Flow |
 |---|---|---|
@@ -647,7 +658,7 @@ never rewrite it to match your output** (same rule as `test-viewpoint.md`).
 | Selector format | `[Element]` | `[Screen:Element]` (namespaced) |
 | Test data keys | `{{variable}}` | `{{phase.variable}}` |
 | Feature tag | `@auto` / `@smoke` etc. | `@flow` (required) |
-| Scenario ids | `VP-<CATEGORY>-NNN` | `FL-<PHASE>-NNN` — phases: `HP` (happy path), `ER` (error recovery), `EH` (guards), `UI` (journey UI states, optional) |
+| Scenario ids | `VP-<CATEGORY>-NNN` | `FL-<PHASE>-NNN` — use-case phases `BF`/`AF0n`/`EF0n` (see below), or the flat `HP` (happy path) / `ER` (error recovery) / `EH` (guards) / `UI` for a short single-outcome flow |
 
 **Scenarios to generate — every phase demanded by the contract, automated:**
 
@@ -659,6 +670,52 @@ never rewrite it to match your output** (same rule as `test-viewpoint.md`).
 | Cross-screen handoff | After every screen transition, assert the CARRIED state on the new screen (the added product's name in the cart, the email echoed on the sent screen). | blind tails cap `businessDepth` (`FLOW-HANDOFF-SHALLOW`) |
 | Stateful regression (when `stateful:` declared) | Count/quantity proof · teardown (remove → empty) · multi-source add. | missing dims cap `businessDepth` (`FLOW-DEPTH`) |
 
+### Use-case decomposition — how a flow becomes 15 scenarios instead of 3
+
+`HP`/`ER`/`EH` are phase *buckets*; they do not tell you how many flows a use case HAS. The
+use-case framework does, and it is the default decomposition for a multi-screen journey:
+
+**1 Use Case = 1 Basic Flow + N Alternate Flows + N Exception Flows.**
+
+| Phase | Meaning | Test |
+|---|---|---|
+| `BF` Basic Flow | **Exactly one.** The path where nothing goes wrong, end to end. | Reaches `outcome.assertion` and satisfies `successGuarantee`. |
+| `AF` Alternate Flow | A **designed-for branch** — the user does something else legitimate. NOT an error. | Its own outcome: either re-enters the BF at a named step, or ends elsewhere on purpose. |
+| `EF` Exception Flow | **Blocked.** The goal is not reached. | Asserts `minimalGuarantee` — what must STILL be true now that this failed. |
+
+`AF` is the bucket most generators skip entirely, and it is where the interesting bugs live
+(going back and finding the form re-hydrated, two tabs, an escape hatch out of the journey).
+Use `FL-BF-NNN` / `FL-AF0n-NNN` / `FL-EF0n-NNN` ids — `sungen audit` buckets them (BF→business
+core, AF→behaviour, EF→validation/security) and traces them to the viewpoint's `FL-BF`/`FL-AF`/
+`FL-EF` priority rows. Declare `phases: [BF, AF, EF]` in the contract; the FIRST phase is the
+Basic Flow and is the one that must reach `outcome`.
+
+**Declare once, then declare only the differences.** Actor · Trigger · Goal · Precondition ·
+`successGuarantee` · `minimalGuarantee` are use-case-level: they live in `flow-contract.yaml`
+and are never repeated per flow. Each flow in `test-viewpoint.md` then states only three things:
+**where it branches from · its own steps · its own outcome.** Repeating the precondition in
+fifteen rows is noise; the branch point is the information.
+
+**Enumerate flows with the step × risk matrix.** Walk every BF step and ask each column. A hit
+with a basis in the spec becomes a flow; a hit with no basis becomes an **open question** — never
+an invented behaviour:
+
+| Risk family | The question at this step |
+|---|---|
+| Double submit | Is the control tapped twice guarded? One request, one record? (Spec silent → open question, not an assumed guard.) |
+| Client-side buffer | Is state held client-side between this step and the next? Then test **both** directions — it survives a legitimate back, and it is **LOST** on reload. A suite proving only the surviving side has tested half the mechanism (`CONTINUITY-ONE-SIDED`). |
+| Concurrency | Two tabs / two devices at this step — whose state wins? |
+| Server error | This step's submit fails server-side: what is kept, what is retryable, is anything half-written? |
+| Abandonment / TTL | The user stops here. Does the partial state lapse, expire, or linger forever? |
+| Direct access | This step's URL opened cold, without the preceding state → refused, and the screen never renders. |
+| Auth transition | Where exactly does the session begin? Before that point the actor is unauthenticated — prove it. |
+| Escape hatch | Is there a documented way OUT of the journey here (back to top, cancel)? That is an `AF`, and its outcome is "goal deliberately not reached". |
+
+**Do NOT re-derive field validation.** Per-field equivalence and boundary values belong to the
+OWNING SCREEN's suite. A flow takes representative inputs (see the system-test rule above). State
+that exclusion in the viewpoint's Design Decisions — and if the screen suite does not exist, that
+is a gap to REPORT, not to quietly absorb.
+
 **Boundary discipline while generating:** every scenario must serve the contract's goal. A scenario
 that never touches `outcome.screen` and is not a guard (`EH`) or error-recovery (`ER`) belongs in a
 DIFFERENT flow — propose the split instead of writing it here (`FLOW-SCOPE-CREEP` will flag it).

package/src/orchestrator/templates/ai-src/skills/sungen-viewpoint/group-e-identity.md

@@ -107,7 +107,7 @@ See `SKILL.md` for the 4 Viewpoints, Shared Checks, and Security Tag Rules.
 
 **[VP-VAL] Edge cases**
 
-- [@normal] Register with a sub-address email (user+tag@gmail.com) → treated as a unique email, creation succeeds
+- [@normal] Register with a sub-address email (user+tag@sun-asterisk.com) → treated as a unique email, creation succeeds
 - [@low] Browser autofill fills the fields → the form receives the correct values, no conflict with a custom input component
 
 ---

package/src/orchestrator/test-data-guide.ts

@@ -50,6 +50,14 @@ payload \`<script>alert(1)</script>\`; the exact expected error message from the
 **Self-check:** *"If I swapped this for another value of the same kind, would the
 test still mean the same thing?"* → yes = INVENTED.
 
+**Email domains — never a live mailbox provider.** An invented address still gets
+mail sent to it: a registration or password-reset test submits it and the system
+dispatches for real. \`@gmail.com\`, \`@yahoo.com\`, \`@outlook.com\` and friends all
+resolve, so that mail reaches whoever owns the address — a stranger, or someone's
+personal account. Use the project domain \`@sun-asterisk.com\`, or \`@example.com\`
+(RFC 2606 — reserved, guaranteed never to deliver). Make each run unique with
+\`{{$timestamp}}\` in the local part: \`"signup+{{\$timestamp}}@sun-asterisk.com"\`.
+
 ## 2) ENV-BOUND — real records of the test environment (not secret)
 
 **What it is:** the value must EXIST in the environment for the test to work — a