@sun-asterisk/sungen 3.2.20-beta.1 → 3.2.20-beta.3

package/src/harness/flow-contract.ts

@@ -0,0 +1,229 @@
+/**
+ * Flow Contract — the declared boundary of a flow, and the sensors that verify
+ * the suite against it. (#569, docs/spec/sungen-flow-quality-spec.md)
+ *
+ * A flow is the SMALLEST complete business action chain: one clear trigger ending
+ * in ONE observable, valuable outcome. Nothing enforced that: `add-flow` asked only
+ * "which screens, in order?", so a real example mixed three business goals (cart,
+ * filter, product-detail) in one "flow", and the harness scored flows with screen
+ * machinery — a registration flow was judged against the `form` page-type checklist
+ * (coverage 0%), and every flow audit showed taxonomy=0% because flow phase ids
+ * (FL-HP-001) don't even parse as categories.
+ *
+ * The contract is a declaration the QA owns (AI proposes at add-flow; a filled
+ * contract is an INPUT to generation, never an output — same rule as
+ * test-viewpoint.md). These sensors are deterministic checks against it:
+ *
+ *   - outcome proof   — the flow proves its own goal with an automated data assertion
+ *   - scope creep     — scenarios that never touch the outcome are a second goal
+ *   - phase coverage  — HP / ER / EH journey phases, the flow's coverage axis
+ *   - handoff         — a cross-screen transition is followed by an assertion
+ *   - stateful depth  — generalizes the cart-hardcoded regression dims to any
+ *                       declared collection (order, application, submission …)
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
+import { ScenarioInfo } from './parse';
+import { readTextFile } from './read-text';
+
+export interface FlowContract {
+  goal: string;
+  actor?: string;
+  trigger?: string;
+  precondition?: string;
+  outcome: { screen: string; assertion?: string };
+  value?: 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 mutated collection (cart, order, application …) — enables regression dims. */
+  stateful?: string;
+  budgets?: Record<string, number>;
+}
+
+export interface FlowQualityResult {
+  hasContract: boolean;
+  contract?: FlowContract;
+  /** Parse/shape errors — a broken contract is reported, never silently ignored. */
+  errors: string[];
+  outcomeProven: boolean;
+  /** Manual-only proof: the goal is covered but not by automation. */
+  outcomeManualOnly: boolean;
+  /** Scenario names that never touch the outcome screen (guard/error phases excluded). */
+  offGoal: string[];
+  offGoalRatio: number;
+  /** Off-goal categories, for the split suggestion ("VP-FILTER-* looks like its own flow"). */
+  offGoalCategories: string[];
+  phases: { phase: string; covered: boolean; automated: boolean }[];
+  /** Covered-and-automated phases / declared phases (UI excluded) — the flow coverage axis. */
+  phaseRatio: number;
+  /** Cross-namespace transitions followed by an assertion / all transitions. */
+  handoffs: { total: number; asserted: number; ratio: number };
+}
+
+const DEFAULT_PHASES = ['HP', 'ER', 'EH'];
+
+export function flowContractPath(unitDir: string): string {
+  return path.join(unitDir, 'requirements', 'flow-contract.yaml');
+}
+
+/** Load + validate. Returns null when absent; a present-but-broken file returns errors. */
+export function loadFlowContract(unitDir: string): { contract: FlowContract | null; errors: string[] } {
+  const p = flowContractPath(unitDir);
+  if (!fs.existsSync(p)) return { contract: null, errors: [] };
+  let raw: Record<string, unknown>;
+  try {
+    raw = parseYaml(readTextFile(p)) as Record<string, unknown>;
+  } catch (e) {
+    return { contract: null, errors: [`flow-contract.yaml does not parse: ${(e as Error).message}`] };
+  }
+  if (!raw || typeof raw !== 'object') return { contract: null, errors: ['flow-contract.yaml is empty'] };
+  const errors: string[] = [];
+  if (!raw.goal || typeof raw.goal !== 'string') errors.push('missing `goal:` (Verb + outcome, e.g. "Place an order for a product added from home")');
+  const outcome = raw.outcome as { screen?: unknown; assertion?: unknown } | undefined;
+  if (!outcome || typeof outcome.screen !== 'string' || !outcome.screen.trim()) {
+    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;
+  return {
+    contract: {
+      goal: String(raw.goal),
+      actor: raw.actor !== undefined ? String(raw.actor) : undefined,
+      trigger: raw.trigger !== undefined ? String(raw.trigger) : undefined,
+      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,
+      phases,
+      stateful: raw.stateful !== undefined ? String(raw.stateful).toLowerCase() : undefined,
+      budgets: (raw.budgets && typeof raw.budgets === 'object') ? raw.budgets as Record<string, number> : undefined,
+    },
+    errors: [],
+  };
+}
+
+/** `[screen:element]` namespaces referenced by a scenario's steps, in step order. */
+function namespacesInOrder(s: ScenarioInfo): string[] {
+  const out: string[] = [];
+  for (const m of s.stepsText.matchAll(/\[([a-z0-9_.-]+):/g)) out.push(m[1]);
+  return out;
+}
+
+function touchesOutcome(s: ScenarioInfo, outcomeScreen: string): boolean {
+  return namespacesInOrder(s).includes(outcomeScreen);
+}
+
+/** 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();
+  for (const ph of declared) {
+    if (new RegExp(`(^|-)${ph}(-|$)`).test(id)) 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';
+  if (declared.includes('ER') && /\b(invalid|error|required|validation|malformed|blocked|then correct|recover)\b/.test(hay)) return 'ER';
+  if (declared.includes('HP') && s.hasDataAssertion) return 'HP';
+  return null;
+}
+
+/**
+ * Verify the suite against the contract. Deterministic; a flow without a contract
+ * returns hasContract:false and neutral values (the audit reports the checklist).
+ */
+export function flowQuality(unitDir: string, scenarios: ScenarioInfo[]): FlowQualityResult {
+  const { contract, errors } = loadFlowContract(unitDir);
+  const neutral: FlowQualityResult = {
+    hasContract: false, errors, outcomeProven: false, outcomeManualOnly: false,
+    offGoal: [], offGoalRatio: 0, offGoalCategories: [],
+    phases: [], phaseRatio: 1, handoffs: { total: 0, asserted: 0, ratio: 1 },
+  };
+  if (!contract) return neutral;
+
+  const outcomeScreen = contract.outcome.screen;
+
+  // --- Outcome proof: the flow proves its own goal, by automation -------------
+  const proofs = scenarios.filter((s) => touchesOutcome(s, outcomeScreen) && s.hasDataAssertion);
+  const outcomeProven = proofs.some((s) => !s.manual);
+  const outcomeManualOnly = !outcomeProven && proofs.length > 0;
+
+  // --- 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 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
+  });
+  const offGoalRatio = scenarios.length ? offGoalScenarios.length / scenarios.length : 0;
+  const offGoalCategories = Array.from(new Set(
+    offGoalScenarios.map((s) => s.category ?? s.vpId?.replace(/-\d+.*$/, '') ?? '?')));
+
+  // --- Phase coverage: the flow's coverage axis (UI never demanded) -----------
+  const demanded = declaredPhases.filter((p) => p !== 'UI');
+  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;
+    return {
+      phase,
+      covered: relevant.length > 0,
+      automated: relevant.some((s) => !s.manual),
+    };
+  });
+  const phaseRatio = demanded.length
+    ? phases.filter((p) => p.covered && p.automated).length / demanded.length
+    : 1;
+
+  // --- 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
+  // flagged two legitimate shapes: a guard that asserts the REDIRECT target
+  // ("go to [Checkout] → see [Home] page"), and a passthrough click en route
+  // ("click [Cart:Checkout]" asserting on the next screen). What the sensor
+  // actually guards against is a flow that clicks through screens and ends blind.
+  let total = 0; let asserted = 0;
+  for (const s of scenarios) {
+    if (s.manual) continue;
+    const steps = s.steps ?? [];
+    let current: string | null = null;
+    for (let i = 0; i < steps.length; i++) {
+      const ns = (steps[i].text.match(/\[([A-Za-z0-9_.-]+):/) || [])[1]?.toLowerCase() ?? null;
+      if (!ns) continue;
+      if (current !== null && ns !== current) {
+        total++;
+        if (steps.slice(i).some((st) => st.bucket === 'then')) asserted++;
+      }
+      current = ns;
+    }
+  }
+  const handoffs = { total, asserted, ratio: total ? asserted / total : 1 };
+
+  return {
+    hasContract: true, contract, errors: [],
+    outcomeProven, outcomeManualOnly,
+    offGoal: offGoalScenarios.map((s) => s.name.slice(0, 80)),
+    offGoalRatio, offGoalCategories,
+    phases, phaseRatio, handoffs,
+  };
+}
+
+/**
+ * Generalized stateful regression depth: the contract names the mutated collection,
+ * so the three dims (count-proof · teardown · multi-source) stop being cart-only.
+ */
+export function statefulDepthFor(collection: string, scenarios: ScenarioInfo[]): { countProof: boolean; teardown: boolean; multiSource: boolean; missing: string[]; ratio: number } {
+  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 };
+}

package/src/harness/flow-plan.ts

@@ -71,6 +71,9 @@ export interface FlowPlan {
   legs: LegPlan[];
   byReason: Record<string, number>;
   capabilityManual: number;
+  /** @manual whose reason is "cross-screen → automate via flow" (class XS) — inside a flow this
+   *  usually means the scenario should simply BE automated here. (#569) */
+  crossScreenManual: number;
   judgmentManual: number;
   contracts: Contract[];
   readiness: 'ready' | 'not-ready';
@@ -87,14 +90,18 @@ export function buildFlowPlan(cwd: string, flow: string): FlowPlan {
   // Legs = distinct screen namespaces.
   const legMap = new Map<string, { scenarios: Set<string>; refs: Set<string>; automated: boolean }>();
   const byReason: Record<string, number> = {};
-  let capabilityManual = 0, judgmentManual = 0;
+  let capabilityManual = 0, judgmentManual = 0, crossScreenManual = 0;
 
   for (const sc of scenarios) {
     if (sc.manual) {
       const { code } = inferReasonCode(sc.tags, sc.reason);
       byReason[code] = (byReason[code] || 0) + 1;
       const cls = MANUAL_REASONS[code]?.cls;
-      if (cls === 'capability') capabilityManual++; else if (cls === 'keep') judgmentManual++;
+      // XS ("cross-screen → automate via flow") is a THIRD class; it used to be silently
+      // dropped from both counters, understating the plan's manual load. (#569)
+      if (cls === 'capability') capabilityManual++;
+      else if (cls === 'keep') judgmentManual++;
+      else if (cls === 'flow') crossScreenManual++;
     }
     for (const r of sc.refs) {
       const leg = r.screen.toLowerCase();
@@ -133,5 +140,5 @@ export function buildFlowPlan(cwd: string, flow: string): FlowPlan {
   }
   if (readiness === 'ready') plan.unshift('Selectors present for every automated leg — ready to compile + run.');
 
-  return { flow, total: scenarios.length, legs, byReason, capabilityManual, judgmentManual, contracts, readiness, missingLegs, plan };
+  return { flow, total: scenarios.length, legs, byReason, capabilityManual, judgmentManual, crossScreenManual, contracts, readiness, missingLegs, plan };
 }

package/src/harness/parse.ts

@@ -38,6 +38,8 @@ export interface ScenarioInfo {
   requiresCaps?: string[];    // @requires:<cap> — automation-ready but needs an opt-in driver (TQ-11)
   deferredToFlow?: boolean;   // @deferred:flow — owned by a flow, not automated on this screen (H6)
   ownedByFlow?: string;       // @owned-by:<flow> — the flow that owns this deferred scenario (H6)
+  /** Ordered steps with their resolved bucket (And/But inherit) — flow handoff analysis (#569). */
+  steps?: Array<{ bucket: 'given' | 'when' | 'then'; text: string }>;
 }
 
 /** Format-tolerant: is this token an ID (project's scheme), not a prose word?
@@ -91,6 +93,29 @@ export function parseViewpointOverview(filePath: string): ViewpointEntry[] {
     }
   }
 
+  // 1b) Flow-style declarations (#569). Flow viewpoint files commonly declare per-item
+  // ids at the END of a bullet ("… → **FL-HP-001**") under phase section headers
+  // ("## FL-HP — Happy Path"). Neither matched the table/group passes, so every flow
+  // audit collapsed to taxonomy=0% / traceability n-a — scenarios correctly tagged
+  // FL-HP-001 were reported as unmapped. Both forms are additive here.
+  for (const raw of lines) {
+    const line = raw.trim();
+    const section = line.match(/^##\s+([A-Z]{2,}(?:-[A-Z0-9]{2,})*)\s+[—–-]\s*(.*)$/);
+    if (section && isViewpointId(section[1] + '-0')) {
+      const id = section[1].toUpperCase();
+      if (!entries.has(id)) entries.set(id, { id, priority: 'Unknown', reason: section[2] ?? '' });
+    }
+    if (/^[-*+]\s/.test(line)) {
+      const arrow = line.match(/(?:→|->)\s*\*{0,2}([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d+[a-zA-Z]?)\*{0,2}\s*$/);
+      if (arrow) {
+        const id = arrow[1].toUpperCase();
+        if (!entries.has(id)) {
+          entries.set(id, { id, priority: 'Unknown', reason: line.replace(/\s*(?:→|->).*$/, '').replace(/^[-*+]\s+/, '') });
+        }
+      }
+    }
+  }
+
   // 2) Viewpoint Grouping: ### Required / ### Recommended / ### Optional → bullet list
   let group: ViewpointEntry['group'] | undefined;
   for (const raw of lines) {
@@ -144,7 +169,9 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
   // Category is everything between `VP-` and the final `-<sequence>` — INCLUDING hyphens, so
   // compound categories (VP-LIST-DISPLAY-01, VP-ADD-TO-CART-03, VP-PRODUCT-DISCOVERY-02) parse,
   // not just single-word ones. A single-word category (VP-CART-001) still works. (H1)
-  const codeMatch = sc.name.match(/\bVP-([A-Z]+(?:-[A-Z]+)*)-\d+/i);
+  // 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);
   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).
@@ -158,12 +185,14 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
   const skeletonParts: string[] = [];
   const textParts: string[] = [sc.name];
   const stepTextParts: string[] = [];
+  const orderedSteps: Array<{ bucket: 'given' | 'when' | 'then'; text: string }> = [];
 
   for (const step of sc.steps as ParsedStep[]) {
     const kw = step.keyword.trim();
     if (kw === 'Given' || kw === 'When' || kw === 'Then') last = kw;
     textParts.push(step.text);
     stepTextParts.push(step.text);
+    orderedSteps.push({ bucket: (kw === 'And' || kw === 'But' ? last : kw).toLowerCase() as 'given' | 'when' | 'then', text: step.text });
     // normalized skeleton: keep [refs] (distinct targets = distinct tests),
     // but neutralize {{vars}} and quoted values so EP/data families collapse.
     const skel = step.text
@@ -199,6 +228,7 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
     stepSkeleton: skeletonParts.join(' | '),
     haystack: textParts.join(' ').toLowerCase(),
     stepsText: stepTextParts.join(' ').toLowerCase(),
+    steps: orderedSteps,
     vpId,
     casesDataset,
     queryRefs: queryRefs.size ? [...queryRefs] : undefined,

package/src/harness/perf.ts

@@ -0,0 +1,112 @@
+/**
+ * Performance budgets — config + percentile math + the per-unit verdict. (#569)
+ *
+ * A flow's regression value includes "still fast enough": after a lib/framework
+ * upgrade the main journeys must not only pass but hold their response-time
+ * budget. Sungen had no perf concept at all — the Playwright JSON parser even
+ * dropped the `duration` field Playwright already emits on every result.
+ *
+ * Scope discipline:
+ *   - This is config + measurement + report over runs sungen already makes.
+ *     Real load tests stay @manual:M8 → a dedicated tool.
+ *   - The AUDIT never reads it: the quality score is documented as a pure
+ *     function of the design artifacts ("reads no test-results, live page, or
+ *     clock"). Perf reports where runs are already read — `sungen delivery`
+ *     and the dashboard. Advisory: a blown budget never fails the design gate.
+ *
+ * Config: qa/perf.yaml
+ *   percentile: p75          # default p75 — "≥75% of runs meet the budget"
+ *   defaults:
+ *     scenario_ms: 30000     # whole-scenario wall clock (Playwright duration)
+ *     page_load_ms: 3000     # Phase B — needs per-transition runtime timing
+ *     transition_ms: 2000    # Phase B
+ *   units:
+ *     place-order: { scenario_ms: 20000 }
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
+import { readTextFile } from './read-text';
+
+export interface PerfConfig {
+  /** 0..100 — e.g. 75 for p75. */
+  percentile: number;
+  defaults: Record<string, number>;
+  units: Record<string, Record<string, number>>;
+}
+
+export interface PerfVerdict {
+  unit: string;
+  metric: string;            // 'scenario_ms' today; page_load_ms/transition_ms in Phase B
+  percentile: number;        // 75
+  budgetMs: number;
+  measuredMs: number;        // the pXX of the observed durations
+  samples: number;
+  pass: boolean;
+  /** Titles of the slowest offenders (only when failing), for the report. */
+  slowest: Array<{ title: string; ms: number }>;
+}
+
+export function perfConfigPath(projectRoot: string): string {
+  return path.join(projectRoot, 'qa', 'perf.yaml');
+}
+
+/** Absent file → null (perf reporting is opt-in; nothing changes until configured). */
+export function loadPerfConfig(projectRoot: string): PerfConfig | null {
+  const p = perfConfigPath(projectRoot);
+  if (!fs.existsSync(p)) return null;
+  let raw: Record<string, unknown>;
+  try { raw = parseYaml(readTextFile(p)) as Record<string, unknown>; } catch { return null; }
+  if (!raw || typeof raw !== 'object') return null;
+  const pctRaw = String(raw.percentile ?? 'p75').toLowerCase().replace(/^p/, '');
+  const percentile = Math.min(100, Math.max(1, Number(pctRaw) || 75));
+  const num = (o: unknown): Record<string, number> => {
+    const out: Record<string, number> = {};
+    if (o && typeof o === 'object') {
+      for (const [k, v] of Object.entries(o as Record<string, unknown>)) {
+        const n = Number(v);
+        if (Number.isFinite(n) && n > 0) out[k] = n;
+      }
+    }
+    return out;
+  };
+  const units: Record<string, Record<string, number>> = {};
+  if (raw.units && typeof raw.units === 'object') {
+    for (const [u, o] of Object.entries(raw.units as Record<string, unknown>)) units[u] = num(o);
+  }
+  return { percentile, defaults: num(raw.defaults), units };
+}
+
+/**
+ * Nearest-rank percentile (ceil), the standard "≥pXX of samples meet the budget"
+ * reading: p75 of [a…] is the value at ceil(0.75·n) in the sorted list. One
+ * sample → that sample. Deterministic, no interpolation.
+ */
+export function percentileOf(p: number, values: number[]): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const rank = Math.min(sorted.length, Math.max(1, Math.ceil((p / 100) * sorted.length)));
+  return sorted[rank - 1];
+}
+
+/** Budget for a metric on a unit: per-unit override, else defaults, else none. */
+export function budgetFor(config: PerfConfig, unit: string, metric: string): number | undefined {
+  return config.units[unit]?.[metric] ?? config.defaults[metric];
+}
+
+/**
+ * The scenario_ms verdict for one unit's run. `durations` = per-test wall-clock ms
+ * (a @cases scenario contributes one sample per row-test — each is a real run).
+ */
+export function perfVerdict(
+  config: PerfConfig,
+  unit: string,
+  samples: Array<{ title: string; ms: number }>,
+): PerfVerdict | null {
+  const budgetMs = budgetFor(config, unit, 'scenario_ms');
+  if (budgetMs === undefined || samples.length === 0) return null;
+  const measuredMs = percentileOf(config.percentile, samples.map((s) => s.ms));
+  const pass = measuredMs <= budgetMs;
+  const slowest = pass ? [] : [...samples].sort((a, b) => b.ms - a.ms).slice(0, 3);
+  return { unit, metric: 'scenario_ms', percentile: config.percentile, budgetMs, measuredMs, samples: samples.length, pass, slowest };
+}

package/src/harness/sensors.ts

@@ -33,10 +33,22 @@ const BUCKET_ORDER: Array<[string, string[]]> = [
 ];
 const BUCKETS: Record<string, string[]> = Object.fromEntries(BUCKET_ORDER);
 
+// Flow journey-phase categories (FL-HP-001, FL-ER-002 …). Matched on exact SEGMENTS,
+// never by containment — 'SHOP'.includes('HP') is true, which is exactly the kind of
+// false hit substring matching would produce for two-letter phase tokens. (#569)
+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)
+};
+
 /** Classify a VP category into a balance bucket by keyword containment + precedence (H1). */
 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];
+  }
   for (const [bucket, kws] of BUCKET_ORDER) {
     if (kws.some((k) => cat.includes(k))) return bucket;
   }
@@ -351,7 +363,7 @@ export function flowRegressionDepth(scenarios: ScenarioInfo[]): FlowDepthResult
   // 1. Count/quantity proof — a row count or item quantity, not just presence of a row.
   const countProof = any(/\b(quantity|qty|two (?:rows|lines|cart)|row count|count column|number of items|one[_ ]row|two[_ ]rows|qty[_ ])/i);
   // 2. Teardown — removes the item and verifies the empty/zero state (the inverse operation).
-  const teardown = any(/\b(remove|delete|clear)\b/i) && any(/\b(empty|no items|zero|removed|0 items)\b/i);
+  const teardown = any(/\b(remove|delete|clear)(?:s|d|ed|ing)?\b/i) && any(/\b(empty|emptied|no items|zero|removed|cleared|0 items)\b/i);
   // 3. Multi-source — the cart is fed from >1 source (the main list AND a recommended/related rail).
   const multiSource = any(/\b(recommended|related|you may also|suggest)\b/i) && addsToCart;
 

package/src/harness/spec-coverage.ts

@@ -66,10 +66,27 @@ export function parseSpecClauses(specPath: string): { frs: FrClause[]; valRows:
   if (!fs.existsSync(specPath)) return { frs: [], valRows: [] };
   const lines = readTextFile(specPath).split('\n');
 
+  // Requirement ids follow the PROJECT's scheme, not ours (#572): `**FR-1**:` is one
+  // convention among many — a real spec declared ~30 MUST clauses as `` `REQ-SRCH-001`: ``
+  // and the FR-locked pattern returned zero, so the MUST-coverage gate never ran and the
+  // specFR axis was excluded "for lack of evidence" that was sitting right there. Same
+  // silent-failure class as the CRLF parsers, same id-scheme-tolerance lesson as delivery.
+  //
+  // A declaration is: line-leading (optionally bulleted / bold / backticked) `<ID>:` where
+  // the id ends in a number. Table rows are EXCLUDED — traceability tables cite requirement
+  // ids without declaring them — and so are prefixes that are never requirements
+  // (test cases, viewpoints, known-defect records, data-factory checks, flows, delivery items).
+  const NON_REQUIREMENT_PREFIX = /^(TC|VP|KD|CHK|FL|DI)-/i;
   const frs: FrClause[] = [];
+  const seen = new Set<string>();
   for (const line of lines) {
-    const m = line.match(/\*\*FR-(\d+)\*\*\s*:\s*(.+)$/);
-    if (m) frs.push({ id: `FR-${m[1]}`, text: m[2].replace(/\*\*/g, '').trim(), modality: modalityOf(m[2]) });
+    if (/^\s*\|/.test(line)) continue;   // table row = citation, not declaration
+    const m = line.match(/^\s*(?:[-*+]\s+)?[*_`]*([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d+[a-zA-Z]?)[*_`]*\s*:\s*(.+)$/);
+    if (!m || NON_REQUIREMENT_PREFIX.test(m[1])) continue;
+    const id = m[1].toUpperCase();
+    if (seen.has(id)) continue;          // first declaration wins
+    seen.add(id);
+    frs.push({ id, text: m[2].replace(/\*\*/g, '').trim(), modality: modalityOf(m[2]) });
   }
 
   // Validation Rules table: a row carries a Constraint, a Trigger cell, and (often) a code.

package/src/orchestrator/templates/ai-src/commands/add-flow.md

@@ -86,15 +86,52 @@ qa/flows/${input:flow}/
     └── ui/                        # Screenshots, mockups
 ```
 
-### 1a. Identify the screens in the flow
+### 1a. Define the flow's BOUNDARY, then its screens
 
-Ask the user: "Which screens does this flow visit, in order? (e.g., login → dashboard → award-form → confirmation)"
+A flow is the **smallest complete business action chain**: one clear trigger ending in ONE
+observable, valuable outcome. Before asking for screens, walk this checklist with the user —
+if 1, 3 or 8 fails, propose SPLITTING into separate flows:
+
+1. Exactly **one business goal**? (cart correctness + category filtering = two flows)
+2. A clear **trigger** and precondition?
+3. **One observable final outcome**? (a final assertion you can write in one sentence)
+4. Is that outcome **valuable to the actor**? (an order placed, a password reset — not "a page rendered")
+5. Is **every step necessary** for that outcome?
+6. Are all steps at the **same business abstraction**?
+7. Are optional/error branches **phases of this goal** (ER/EH), not new goals?
+8. Does **no segment** form an independently valuable flow on its own?
+9. Can you write **a single clear final assertion**?
+10. Can you name it "**Verb + outcome**"? (`place-order`, `reset-password` — not `cart-and-filter`)
+
+Then ask: "Which screens does this flow visit, in order? (e.g., login → dashboard → award-form → confirmation)"
 
 Record the screen list — you will need it for:
 - Filling `spec.md` (Step 3)
 - Suggesting `[Screen:Element]` namespace prefixes
 - Capturing visuals per screen (Step 2)
 
+### 1b. Author the Flow Contract (`requirements/flow-contract.yaml`)
+
+Write the answers down as the flow's contract — `sungen audit` scores the flow **against it**
+(the `flowCoverage` axis: HP/ER/EH journey phases; `FLOW-OUTCOME-UNPROVEN` when no automated
+scenario asserts data on the outcome screen; `FLOW-SCOPE-CREEP` when scenarios never touch it):
+
+```yaml
+goal: "Place an order for a product added from home"   # Verb + outcome
+actor: user
+trigger: "Add a product to the cart from the home featured list"
+precondition: "A registered account; an empty cart"
+outcome:
+  screen: checkout            # the [Screen:...] namespace carrying the final proof
+  assertion: "The confirmation shows the order number and the paid total"
+value: "The customer has paid; the shop has a new order"
+phases: [HP, ER, EH]          # journey phases (default); add UI only if the flow owns UI states
+stateful: cart                # the mutated collection, if any — enables regression-depth dims
+```
+
+**A filled contract is an INPUT to generation — never an output.** Like `test-viewpoint.md`,
+generation must not rewrite it to match what was generated; disagree → propose the diff and ask.
+
 ### 2. Capture visual source
 
 **Mobile path** (`platform: mobile`):
@@ -187,7 +224,8 @@ If user picks `/sungen:create-test`, **you MUST use the Skill tool** to invoke i
 - Test data namespaced by phase: `login.email`, `submission.nominee`
 - `@flow` tag required at feature level
 - `Background:` should only contain the starting navigation — the URL path (web) or the `--reach` nav recipe (mobile)
-- Each scenario = one phase of the journey
+- Each scenario = one phase of the journey; ids are `FL-<PHASE>-NNN` (`HP`/`ER`/`EH`, optional `UI`)
+- One flow = ONE business goal with ONE observable outcome (`requirements/flow-contract.yaml`) — a segment with its own value is its own flow
 {{#cap parallel-subagents}}
 - Mobile flows are tagged `@platform:mobile` and run via `/sungen:run-test <flow>` (WebdriverIO, not Playwright)
 {{/cap}}