@sun-asterisk/sungen 3.2.21 → 3.2.22-beta.1

package/src/generators/test-generator/patterns/index.ts

@@ -73,34 +73,40 @@ export class PatternRegistry {
    * Prefers resolver (returns template data) over generator (renders directly).
    */
   generateStep(step: ParsedStep, context: PatternContext): MappedStep | null {
-    const pattern = this.findPattern(step);
-    if (!pattern) {
-      return null;
-    }
-
-    // Prefer resolver (framework-agnostic) over generator (legacy)
-    if (pattern.resolver) {
-      const resolved = pattern.resolver(step, context);
-
-      // Auto-inject parent scoping if step has parentRef
-      // Skip for table-* patterns — they resolve the table name internally from step text
-      if (step.parentRef && step.parentType && !pattern.name.startsWith('table-')) {
-        resolved.data.parentLocator = PatternRegistry.resolveParentLocator(
-          step.parentRef, step.parentType, context
-        );
+    // Matchers see only the STEP; some decisions need context (a resolver reading the
+    // test-data value, e.g. row-count's numeric check). A resolver may therefore return
+    // null to say "not mine after all" — the search continues with the next matching
+    // pattern in priority order instead of crashing or silently dropping the step.
+    const matchStep: ParsedStep = { ...step, text: maskRefsForMatching(step.text) };
+    for (const pattern of this.patterns) {
+      if (!this.matchesPattern(matchStep, pattern.matcher)) continue;
+
+      // Prefer resolver (framework-agnostic) over generator (legacy)
+      if (pattern.resolver) {
+        const resolved = pattern.resolver(step, context);
+        if (!resolved) continue; // resolver declined — fall through
+
+        // Auto-inject parent scoping if step has parentRef
+        // Skip for table-* patterns — they resolve the table name internally from step text
+        if (step.parentRef && step.parentType && !pattern.name.startsWith('table-')) {
+          resolved.data.parentLocator = PatternRegistry.resolveParentLocator(
+            step.parentRef, step.parentType, context
+          );
+        }
+
+        const code = context.templateEngine.renderStep(resolved.templateName, resolved.data);
+        return {
+          code,
+          comment: resolved.comment,
+        };
       }
 
-      const code = context.templateEngine.renderStep(resolved.templateName, resolved.data);
-      return {
-        code,
-        comment: resolved.comment,
-      };
-    }
+      if (pattern.generator) {
+        return pattern.generator(step, context);
+      }
 
-    if (pattern.generator) {
-      return pattern.generator(step, context);
+      return null;
     }
-
     return null;
   }
 

package/src/generators/test-generator/step-mapper.ts

@@ -175,6 +175,28 @@ export class StepMapper {
       this.lastPrimaryKeyword = keyword;
     }
 
+    // SG-W015 — `see [X] card with {{n}}` where n is a bare number compiles to a TEXT
+    // assertion (toHaveText('3')), not a count. An author reaching for "3 cards are shown"
+    // gets an assertion that can only pass if the card's TEXT is the digit — a wrong test
+    // with no error. Count semantics live on row/table ("see [T] table with {{n}}",
+    // "see [Ref] row with {{n}}") and lists ("should have count"); on the container types
+    // below, a bare-number text expectation is almost never what the author meant. A text
+    // element asserting a numeric readout ("[Row Quantity] text with 4") stays silent.
+    const COUNT_MISREAD_TYPES = new Set(['card', 'item', 'items', 'cards', 'option', 'options']);
+    if (this.diagnostics && step.dataRef && step.selectorRef &&
+        COUNT_MISREAD_TYPES.has((step.elementType || '').toLowerCase()) &&
+        /\bsees?\s+\[/.test(step.text) && /\bwith\b/.test(step.text)) {
+      // peekBaseValue reads the literal from test-data even in runtime-data mode,
+      // where resolveData returns an opaque marker (never numeric-looking).
+      let resolvedValue: string | undefined;
+      try { resolvedValue = this.dataResolver.peekBaseValue(step.dataRef, this.featureName); } catch { /* unresolved at compile time → cannot judge */ }
+      if (resolvedValue !== undefined && /^\d+$/.test(resolvedValue.trim())) {
+        this.diagnostics.add('SG-W015',
+          `\`see [${step.selectorRef}] ${step.elementType} with {{${step.dataRef}}}\` compiles to a TEXT assertion toHaveText('${resolvedValue.trim()}'), NOT a count of ${step.elementType}s. For a count use \`see [Ref] row with {{n}}\` / \`see [T] table with {{n}}\` (or a list "should have count"); if '${resolvedValue.trim()}' really is the ${step.elementType}'s text, assert it on a text/label element instead`,
+          { feature: this.featureName, step: step.text });
+      }
+    }
+
     // SG-W007 — a two-step-form browser-alert handler (`click [OK] alert`) written AFTER
     // an action step registers its page.once('dialog') listener too late: a dialog
     // triggered by the earlier action auto-dismisses with no error (issue #472).

package/src/harness/audit.ts

@@ -10,10 +10,11 @@ import * as path from 'path';
 import * as fs from 'fs';
 import { loadUnitScenarios, readUnitFeatureText, parseViewpointOverview, ScenarioInfo, ViewpointEntry } from './parse';
 import { checkViewpointBaseline, ViewpointBaseline } from './viewpoint-baseline';
+import { flowQuality, statefulDepthFor, FlowQualityResult } from './flow-contract';
 import { featureFilesFor } from './unit-paths';
 import {
   loadCatalog, viewpointGate, assertionDepth, dataThemesFor, depthThresholdFor, coverageBalance, duplicateClusters, traceability, claimProof, taxonomyLint,
-  automatableManual, flowCoveredThemes, flowRegressionDepth, oracleStrength,
+  automatableManual, flowCoveredThemes, flowRegressionDepth, oracleStrength, declaredPageType,
   GateResult, DepthResult, BalanceResult, DuplicateResult, TraceResult, ClaimProofResult, TaxonomyResult, Catalog, AutomatableManualResult, FlowDepthResult, OracleStrengthResult,
 } from './sensors';
 import { loadFlowScenarios } from './flow-check';
@@ -48,6 +49,7 @@ export interface AuditReport {
   oracle: OracleStrengthResult; // H4 — facet-oracle strength (weak name-substring vs title/detail/API/DB)
   ledger: LedgerResult;         // atomic viewpoint-item coverage (per-bullet status)
   viewpointBaseline: ViewpointBaseline; // is the yardstick still the accepted one? (#557)
+  flowQuality?: FlowQualityResult;      // #569 — flow contract verification (flows only)
   calibration: {                // #8 — multi-axis score so a high overall can't hide a weak axis
     axes: Record<string, number>;
     weakest: { axis: string; value: number };
@@ -154,15 +156,28 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // back to the in-core functions if the capability provides none.
   // A capability gate may need project context (the API gate resolves endpoint methods from the
   // catalog) + the focus depth threshold (so it scores depth with the SAME bar as the UI gate).
-  const capGate = scoringCap?.gateProvider as
-    ((i: { scenarios: ScenarioInfo[]; viewpoints: ViewpointEntry[]; catalog: Catalog; focus: typeof intent.focus; cwd: string; screenName: string; threshold: number; businessCriticalMethods?: string[] }) => { gate: GateResult; depth: DepthResult }) | undefined;
-  const provided = capGate?.({ scenarios, viewpoints, catalog, focus: intent.focus, cwd: projectRootFromScreenDir(screenDir), screenName: catalogScreenName, threshold: depthThresholdFor(intent.focus), businessCriticalMethods: intent.businessCriticalMethods });
   // Is the declaration this suite is measured against still the one a human accepted?
   const viewpointBaseline = checkViewpointBaseline(
     projectRootFromScreenDir(screenDir), catalogScreenName, viewpointPath);
   const viewpointText = fs.existsSync(viewpointPath) ? readTextFile(viewpointPath) : '';
-  const gate = provided?.gate ?? viewpointGate(scenarios, viewpoints, catalog, platform === 'mobile', viewpointText);
-  const depth = provided?.depth ?? assertionDepth(scenarios, dataThemesFor(catalog, gate.pageType), intent.focus);
+  // #569 — a flow WITH a contract is measured against ITS declaration, not a screen's.
+  // Keyword page-type detection force-fit flows into screen checklists (a registration
+  // flow judged as a `form` screen scored coverage 0%), so for contract-holding flows the
+  // page-type machinery only applies when the project DECLARED a page type explicitly.
+  // The stripped catalog feeds the CAPABILITY gate too — driver-ui provides the gate on
+  // real projects, and handing it the unstripped catalog re-introduced the force-fit.
+  const isUiFlowUnit = /^flows\//.test(catalogScreenName);
+  const flowQ: FlowQualityResult = isUiFlowUnit
+    ? flowQuality(screenDir, scenarios)
+    : { hasContract: false, errors: [], outcomeProven: false, outcomeManualOnly: false, offGoal: [], offGoalRatio: 0, offGoalCategories: [], phases: [], phaseRatio: 1, handoffs: { total: 0, asserted: 0, ratio: 1 }, sit: [] };
+  const gateCatalog = (flowQ.hasContract && !declaredPageType(viewpointText, catalog))
+    ? { ...catalog, page_types: {} } as Catalog
+    : catalog;
+  const capGate = scoringCap?.gateProvider as
+    ((i: { scenarios: ScenarioInfo[]; viewpoints: ViewpointEntry[]; catalog: Catalog; focus: typeof intent.focus; cwd: string; screenName: string; threshold: number; businessCriticalMethods?: string[] }) => { gate: GateResult; depth: DepthResult }) | undefined;
+  const provided = capGate?.({ scenarios, viewpoints, catalog: gateCatalog, focus: intent.focus, cwd: projectRootFromScreenDir(screenDir), screenName: catalogScreenName, threshold: depthThresholdFor(intent.focus), businessCriticalMethods: intent.businessCriticalMethods });
+  const gate = provided?.gate ?? viewpointGate(scenarios, viewpoints, gateCatalog, platform === 'mobile', viewpointText);
+  const depth = provided?.depth ?? assertionDepth(scenarios, dataThemesFor(gateCatalog, gate.pageType), intent.focus);
 
   // TQ-4 — deferral-aware coverage credit: an inherently cross-screen theme (cart / detail /
   // filter correctness) belongs in a FLOW, not on the screen. When a flow deeply covers a screen
@@ -200,8 +215,15 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // collection, the regression dimensions (count/quantity proof · teardown · multi-source) cap the
   // businessDepth headroom: it can reach 1.0 only when all three are exercised, so a present-but-
   // shallow flow can't claim a perfect score (floor 0.5 — assertion depth still dominates).
-  const isUiFlow = /^flows\//.test(catalogScreenName);
-  const flowDepth = isUiFlow ? flowRegressionDepth(scenarios) : { stateful: false, countProof: false, teardown: false, multiSource: false, ratio: 1, missing: [] } as FlowDepthResult;
+  const isUiFlow = isUiFlowUnit;
+  let flowDepth = isUiFlow ? flowRegressionDepth(scenarios) : { stateful: false, countProof: false, teardown: false, multiSource: false, ratio: 1, missing: [] } as FlowDepthResult;
+  // Contract-declared statefulness generalizes the cart-hardcoded vocabulary: a flow that
+  // mutates ANY named collection (order, application, submission …) gets the same three
+  // regression dims. The legacy cart detection stays for contract-less flows (snapshots).
+  if (isUiFlow && !flowDepth.stateful && flowQ.contract?.stateful) {
+    const d = statefulDepthFor(flowQ.contract.stateful, scenarios);
+    flowDepth = { stateful: true, countProof: d.countProof, teardown: d.teardown, multiSource: d.multiSource, ratio: d.ratio, missing: d.missing };
+  }
   const FLOW_DEPTH_FLOOR = 0.5;
   // H4 — oracle strength: a weak facet oracle (name-substring "proves" category/brand membership)
   // caps businessDepth the same way (floor 0.5). A suite with no facet claim, or a strong oracle, is
@@ -211,10 +233,14 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
 
   // Sub-scores
   const coverage = gate.coverageRatio;
+  // #569 — handoff integrity: a flow's depth is also whether each cross-screen transition
+  // is followed by an assertion on the carried state (same floor discipline as the other caps).
+  const HANDOFF_FLOOR = 0.5;
   const businessDepth = Math.min(
     depth.bcDepthRatio,
     flowDepth.stateful ? FLOW_DEPTH_FLOOR + (1 - FLOW_DEPTH_FLOOR) * flowDepth.ratio : 1,
     oracle.weak.length ? ORACLE_FLOOR + (1 - ORACLE_FLOOR) * oracle.ratio : 1,
+    flowQ.hasContract && flowQ.handoffs.total > 0 ? HANDOFF_FLOOR + (1 - HANDOFF_FLOOR) * flowQ.handoffs.ratio : 1,
   );
   // When the taxonomy drifted (most scenarios unclassified), the balance axis is unreliable — cap it
   // at 0.5 instead of awarding a vacuous 1.0 so a stale taxonomy fails loudly, not silently (H1).
@@ -246,8 +272,15 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   //     what a create-test run did, silently dropping the performance viewpoint on
   //     the way. While the declaration is unconfirmed, neither axis is evidence.
   const viewpointMoved = viewpointBaseline.status === 'changed';
+  //  4. A flow with a contract is measured on ITS coverage: journey phases (HP/ER/EH
+  //     automated) — not a screen's page-type themes. Same weight, same criticality,
+  //     so a flow can finally EARN the coverage axis instead of always losing it to
+  //     PAGE-TYPE-UNDETERMINED (or worse, being judged against a form checklist).
+  const flowScored = flowQ.hasContract;
   const axisDefs: Array<{ key: string; value: number; weight: number; applicable: boolean; critical: boolean }> = [
-    { key: 'coverage', value: coverage, weight: 0.22, applicable: !!gate.pageType && gate.themesTotal > 0, critical: true },
+    flowScored
+      ? { key: 'flowCoverage', value: flowQ.phaseRatio, weight: 0.22, applicable: true, critical: true }
+      : { key: 'coverage', value: coverage, weight: 0.22, applicable: !!gate.pageType && gate.themesTotal > 0, critical: true },
     { key: 'specFR', value: specRatio, weight: 0.15, applicable: spec.hasSpec && spec.frTotal > 0, critical: true },
     { key: 'atomicLedger', value: ledger.ratio, weight: 0.13, applicable: ledger.hasViewpoint && ledger.total > 0 && !viewpointMoved, critical: true },
     { key: 'businessDepth', value: businessDepth, weight: 0.20, applicable: true, critical: true },
@@ -297,9 +330,49 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     ].filter(Boolean).join(', ');
     findings.push(`VIEWPOINT-BASELINE-CHANGED: test-viewpoint.md no longer declares what it did when this unit was last accepted — ${moved || 'the declared ids were reordered or replaced'}. atomicLedger + traceability measure the suite AGAINST this file, so they are excluded from the score until the change is confirmed: a generator that rewrites the declaration scores both 100% by construction, and a viewpoint dropped from the file stops being missing from anything. Review the diff (a removed id means that coverage is now unclaimed), then run \`sungen audit --screen ${screenName} --accept-viewpoint\`.`);
   }
-  if (gate.pageTypeSource === 'undetermined') {
+  // On a contract flow the page type is INTENTIONALLY not applied — the contract is the checklist.
+  if (gate.pageTypeSource === 'undetermined' && !flowScored) {
     findings.push(`PAGE-TYPE-UNDETERMINED: no page type fits this screen with enough confidence (best ${gate.pageTypeEvidence?.hits ?? 0} keyword hit(s)), so NO critical themes were demanded and the coverage axis is excluded from the score — declare it in test-viewpoint.md (\`page-type: <id>\`) to have the theme checklist applied.`);
   }
+  // ---- #569: flow-quality findings -----------------------------------------
+  if (isUiFlow && !flowQ.hasContract) {
+    const why = flowQ.errors.length ? ` (${flowQ.errors.join('; ')})` : '';
+    findings.push(`FLOW-CONTRACT-MISSING: this flow declares no contract${why} — without \`requirements/flow-contract.yaml\` (goal · trigger · outcome.screen · phases) the flow cannot be scored on ITS coverage (journey phases) and falls back to screen machinery. Author it with the boundary checklist: one business goal, a clear trigger, ONE observable outcome valuable to the actor, name = "Verb + outcome"; split anything that forms an independently valuable flow.`);
+  }
+  if (flowQ.hasContract) {
+    if (!flowQ.outcomeProven) {
+      findings.push(flowQ.outcomeManualOnly
+        ? `FLOW-OUTCOME-UNPROVEN: the goal "${flowQ.contract!.goal}" is covered only by @manual scenarios — the flow's own outcome (\`${flowQ.contract!.outcome.screen}\`) has no AUTOMATED data assertion, so a regression run cannot prove the journey still works. Automate the happy-path proof first; it is the reason this flow exists.`
+        : `FLOW-OUTCOME-UNPROVEN: no scenario asserts data on the outcome screen \`${flowQ.contract!.outcome.screen}\` — the flow never proves its own goal ("${flowQ.contract!.goal}"). Add the happy-path scenario that ends in the declared final assertion.`);
+    }
+    if (flowQ.offGoalRatio > 0.35) {
+      findings.push(`FLOW-SCOPE-CREEP: ${flowQ.offGoal.length}/${scenarios.length} scenarios never touch the outcome screen \`${flowQ.contract!.outcome.screen}\` and are not guards/error-recovery (categories: ${flowQ.offGoalCategories.join(', ')}) — evidence of a SECOND business goal in this flow. Split them into their own flow (one flow = one goal, one observable outcome).`);
+    }
+    for (const ph of flowQ.phases.filter((p) => !p.covered || !p.automated)) {
+      findings.push(`FLOW-PHASE-${ph.phase}-MISSING: journey phase ${ph.phase} (${ph.phase === 'HP' ? 'happy path proving the outcome' : ph.phase === 'ER' ? 'error recovery — validation must not trap the journey' : 'guards — direct access / back / refresh'}) is ${ph.covered ? 'covered only by @manual' : 'not covered'} → it does not count toward flowCoverage until automated.`);
+    }
+    // #580 P10 — the QA matrix keeps System INTEGRATION cases (external-system legs)
+    // separate, and holds their exit criteria open while they are mock-verified only.
+    for (const x of flowQ.sit.filter((v) => v.mockOnly).slice(0, 4)) {
+      findings.push(`SIT-MOCK-ONLY: "${x.name}" touches the external system "${x.external}" but is verified only against mocks — Pass (Mocked) says nothing about the real vendor behaviour. Re-verify on the real dependency before calling it Done (the delivery's External Dependency Tracking table holds the checklist).`);
+    }
+    // #580 P9 — a release-critical flow must carry its Final-Inspection selection.
+    if (flowQ.contract!.golden && !/@golden\b/i.test(featureText)) {
+      findings.push(`GOLDEN-MISSING: the contract declares \`golden: true\` (release-critical) but no scenario is tagged @golden — Final Inspection (\`sungen inspect\`) will have nothing to run for this flow. Tag the happy-path scenario(s) that prove the outcome.`);
+    }
+    if (flowQ.handoffs.total > 0 && flowQ.handoffs.ratio < 0.7) {
+      findings.push(`FLOW-HANDOFF-SHALLOW: only ${flowQ.handoffs.asserted}/${flowQ.handoffs.total} cross-screen transitions are followed by an assertion in the new screen — carried state (the thing a flow exists to verify) is unproven at the handoff. businessDepth is capped until asserted.`);
+    }
+  }
+  if (isUiFlow) {
+    // Flows defer more than screens, so an UNCODED @manual is costlier here: the capability
+    // planner cannot route it to the driver that would automate it (password-reset: 11/22
+    // manual, most of them M5-inbox — invisible while tagged bare).
+    const bareManual = (featureText.match(/@manual(?![:\w])/g) || []).length;
+    if (bareManual > 0) {
+      findings.push(`MANUAL-CODE-MISSING: ${bareManual} @manual tag(s) carry no reason code — tag @manual:M1..M9 (M5 = external dependency e.g. inbox, M3 = mock/network, M7 = environment) so the capability planner can route what a driver would automate.`);
+    }
+  }
   for (const c of flowCredits) {
     findings.push(`COVERED-VIA-FLOW: critical theme "${c.theme}" is not covered on this screen but is deeply covered by flow "${c.flow}" — cross-screen depth correctly owned by the flow, so it is credited (not a screen gap). Verify with \`sungen flow-check\`.`);
   }
@@ -318,7 +391,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     const tag = depth.verdict === 'fail' ? 'DEPTH-FAIL' : depth.verdict === 'warn' ? 'DEPTH-WARN' : 'DEPTH';
     findings.push(
       `${tag}: ${depth.businessCriticalShallow}/${depth.businessCriticalTotal} data-correctness scenarios assert only visibility ` +
-      `(ratio ${depth.bcDepthRatio.toFixed(2)} < threshold ${depth.threshold.toFixed(2)} for focus "${depth.focus}") → ` +
+      `(ratio ${depth.bcDepthRatio.toFixed(2)} ${depth.bcDepthRatio < depth.threshold ? '<' : '≥'} threshold ${depth.threshold.toFixed(2)} for focus "${depth.focus}"${depth.bcDepthRatio < depth.threshold ? '' : ' — the gate holds; these are the remaining deepen-targets'}) → ` +
       `add data assertions (\`... with {{value}}\`, \`see all ... contain {{v}}\`) or, if cross-screen, defer to a flow with @manual + reason.`,
     );
   }
@@ -376,6 +449,13 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     const shown = spec.inferredOnly.slice(0, 8).join(', ');
     findings.push(`SPEC-TRACE-IMPLICIT: ${spec.inferredOnly.length} requirement(s) are covered by keyword inference only (${shown}${spec.inferredOnly.length > 8 ? ', …' : ''}) — add \`@spec:<id>\` to the scenario that proves each so the trace survives edits and delivery can report it.`);
   }
+  // Safety net for the parser (#572): the feature CITES requirement ids the spec parser
+  // could not find a declaration for. Silence here would repeat the original failure —
+  // "nothing found" quietly excluding the specFR axis while the evidence sits in the file.
+  if (spec.hasSpec && spec.frTotal === 0 && /@spec:/i.test(featureText)) {
+    const cited = [...new Set([...featureText.matchAll(/@spec:([A-Za-z0-9.-]+)/g)].map((m) => m[1].toUpperCase()))];
+    findings.push(`SPEC-IDS-UNPARSED: the feature cites ${cited.length} requirement id(s) via @spec: (${cited.slice(0, 5).join(', ')}${cited.length > 5 ? ', …' : ''}) but requirements/spec.md yielded ZERO parseable requirement declarations — the spec likely declares ids in a scheme the parser cannot read. Declare each requirement on its own line as \`<ID>: <clause>\` (bullet/bold/backtick all fine; the id must end in a number) so the MUST-coverage gate and the specFR axis can run.`);
+  }
   if (taxonomyMismatch) {
     findings.push(`VP-TAXONOMY-MISMATCH: only ${(trace.mappedRatio * 100).toFixed(0)}% of scenarios use the viewpoint IDs declared in test-viewpoint.md — scenarios invented a generic VP-<CAT> scheme. Re-tag to the project's viewpoint IDs so the coverage matrix is accurate.`);
   }
@@ -429,6 +509,18 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   for (const d of ownership.duplicates.slice(0, 6)) {
     findings.push(`DUPLICATE-FLOW-OWNERSHIP: "${d.scenario}" has the same shape as a scenario in flow "${d.flow}" — keep one owner (screen-local vs flow); the other should only reference/set up.`);
   }
+  // #580 — the flow→screen half of the ownership rule (ISTQB system-test design:
+  // representative, not exhaustive). A flow's cases take ONE representative input per
+  // branch — one valid value on the main flow, one error value that triggers the
+  // exception flow. An EP/data-family cluster (≥3 same-shape scenarios differing only
+  // in data) inside a FLOW is the screen's validation matrix being re-run where it
+  // does not belong: the screen already proved the field rejects each class; the flow
+  // only has to prove the journey survives one of them. Advisory — never a gate.
+  if (isUiFlow) {
+    for (const c of duplicates.clusters.filter((x) => !x.sameDataLikely && x.scenarios.length >= 3).slice(0, 4)) {
+      findings.push(`FLOW-EXHAUSTIVE-INPUTS: ${c.scenarios.length} same-shape scenarios differ only in data (${c.scenarios.slice(0, 3).join(' | ')}${c.scenarios.length > 3 ? ' …' : ''}) — a system-test flow uses REPRESENTATIVE inputs (one valid + one that triggers the exception branch); the full EP/boundary matrix belongs to the owning screen (or a @cases dataset there). Keep one representative per branch here.`);
+    }
+  }
   for (const u of unsourced.slice(0, 6)) {
     findings.push(`UNSOURCEABLE-SCENARIO: "${u}" doesn't trace to any FR / viewpoint item — link it to a source, or tag it @exploration (not part of the official suite).`);
   }
@@ -485,6 +577,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     scenarioCount: scenarios.length,
     gate, depth, claim, taxonomy, balance, duplicates, trace, spec,
     taxonomyMismatch, downstream, manualOracle: manualOracleResult, automatableManual: autoManual, flowDepth, oracle, ledger, viewpointBaseline, calibration,
+    ...(isUiFlow ? { flowQuality: flowQ } : {}),
     score: {
       overall: Math.round(overall * 10) / 10,
       coverage: Math.round(coverage * 100) / 100,

package/src/harness/flow-contract.ts

@@ -0,0 +1,261 @@
+/**
+ * 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>;
+  /** External-system legs (owned by another team/vendor) — ISTQB System INTEGRATION Testing
+   *  scope (#580 P10). Scenarios touching these namespaces are classified SIT. */
+  external?: Array<{ name: string; owner?: string; screens: string[] }>;
+  /** This flow is release-critical: Final Inspection expects a @golden scenario here (P9). */
+  golden?: boolean;
+}
+
+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 };
+  /** ISTQB SIT classification (#580 P10): scenarios whose steps touch an external-system
+   *  namespace declared in the contract's `external:` block. */
+  sit: Array<{ name: string; external: string; mockOnly: boolean }>;
+}
+
+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,
+      external: Array.isArray(raw.external)
+        ? (raw.external as Array<Record<string, unknown>>)
+            .filter((e) => e && typeof e === 'object' && e.name)
+            .map((e) => ({
+              name: String(e.name),
+              owner: e.owner !== undefined ? String(e.owner) : undefined,
+              screens: Array.isArray(e.screens) ? (e.screens as unknown[]).map((x) => String(x).toLowerCase()) : [],
+            }))
+        : undefined,
+      golden: raw.golden === true,
+    },
+    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 }, sit: [],
+  };
+  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 };
+
+  // --- SIT classification (#580 P10): a scenario whose steps touch an external-system
+  // namespace belongs to the System INTEGRATION group the QA matrix keeps separate. When
+  // that scenario is also verified only against mocks, its pass says nothing about the
+  // real vendor behaviour — the exit criteria the QA doc holds open (Pass (Mocked)).
+  const MOCK_STEP = /\[[^\]]+\]\s+mock\s+(?:is\s+active|called)\b/i;
+  const sit: FlowQualityResult['sit'] = [];
+  for (const leg of contract.external ?? []) {
+    const legScreens = new Set(leg.screens);
+    for (const s of scenarios) {
+      if (!namespacesInOrder(s).some((ns) => legScreens.has(ns))) continue;
+      sit.push({ name: s.name.slice(0, 80), external: leg.name, mockOnly: MOCK_STEP.test(s.stepsText) });
+    }
+  }
+
+  return {
+    hasContract: true, contract, errors: [],
+    outcomeProven, outcomeManualOnly,
+    offGoal: offGoalScenarios.map((s) => s.name.slice(0, 80)),
+    offGoalRatio, offGoalCategories,
+    phases, phaseRatio, handoffs, sit,
+  };
+}
+
+/**
+ * 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 };
 }