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

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

@@ -605,22 +605,40 @@ error:
 
 > **Auto-detect**: if path is `qa/flows/<name>/` → use this section. Skip Steps 1–4 above.
 
+**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`).
+
 | Aspect | Screen | Flow |
 |---|---|---|
-| Section focus | UI patterns per section | Journey phases across screens |
+| Section focus | UI patterns per section | Journey phases toward ONE declared outcome |
 | Selector format | `[Element]` | `[Screen:Element]` (namespaced) |
 | Test data keys | `{{variable}}` | `{{phase.variable}}` |
 | Feature tag | `@auto` / `@smoke` etc. | `@flow` (required) |
-| Viewpoints | VP-UI/VAL/LOGIC/SEC per section | VP-LOGIC (transitions), VP-SEC (auth persistence), VP-VAL (cross-screen data) |
+| Scenario ids | `VP-<CATEGORY>-NNN` | `FL-<PHASE>-NNN` — phases: `HP` (happy path), `ER` (error recovery), `EH` (guards), `UI` (journey UI states, optional) |
 
-**Scenarios to generate:**
+**Scenarios to generate — every phase demanded by the contract, automated:**
 
-| Category | What to test |
-|---|---|
-| Happy path | Complete flow end-to-end with valid data |
-| Auth persistence | Auth state maintained across screen transitions |
-| Error recovery | Invalid input mid-flow → fix → continue |
-| Cross-screen data | Data entered on screen A visible on screen B |
+| Phase | What to test | Scoring |
+|---|---|---|
+| `FL-HP` happy path | The complete journey ending in the contract's `outcome.assertion` — an AUTOMATED **data** assertion on `outcome.screen` (an order number, a summed total — not just "page visible"). This scenario is WHY the flow exists: it is the regression proof after a lib/framework upgrade. | uncovered → `flowCoverage` drops + `FLOW-OUTCOME-UNPROVEN` |
+| `FL-ER` error recovery | Invalid input mid-flow → error shown → fix → the journey still completes. Validation must not trap the journey. | uncovered → `flowCoverage` drops |
+| `FL-EH` guards | Direct URL access without the precondition · browser back · refresh · expired context — each ends in a safe observable state. | uncovered → `flowCoverage` drops |
+| 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`) |
+
+**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).
+Auth persistence across transitions is part of `EH` unless the project declares it its own phase.
+
+**Manual in flows**: always `@manual:Mx` with the reason code — bare `@manual` is flagged
+(`MANUAL-CODE-MISSING`) because the capability planner cannot route it. Typical flow deferrals:
+inbox/mail oracle → `M5`, network-request count → `M3`, context expiry control → `M7`. A
+cross-screen scenario inside the flow's own goal is NOT manual — automate it here.
 
 ```gherkin
 @flow @auth:user
@@ -630,19 +648,20 @@ Feature: Award Submission Flow
     Given User is on [Login] page
 
   @high
-  Scenario: User logs in successfully
+  Scenario: FL-HP-001 A signed-in user's nomination is submitted and confirmed
     When User fill [Login:Email] field with {{login.email}}
     And User fill [Login:Password] field with {{login.password}}
     And User click [Login:Submit] button
     Then User see [Dashboard] page
-
-  @high
-  Scenario: User submits nomination
     When User click [Dashboard:Awards] link
-    Then User see [Awards] page
-    When User fill [Awards:Nominee] field with {{submission.nominee}}
+    And User fill [Awards:Nominee] field with {{submission.nominee}}
     And User click [Awards:Submit] button
-    Then User see {{success_message}} message
+    Then User see [Awards:Success Message] text with {{success_message}}
+
+  @high
+  Scenario: FL-EH-001 Direct access to the award form without login redirects to login
+    When User go to [Awards] page
+    Then User see [Login] page
 ```
 
 ```yaml

package/dist/orchestrator/templates/qa-context.md

@@ -45,8 +45,21 @@ Example:
 
 ## Testing Strategy
 
+Machine-readable intent — `sungen audit` reads these keys (Intent Profile). Values here are
+live even when the surrounding text changes; an invalid value silently falls back to the default.
+
+focus: functional
+<!-- focus: functional | e-commerce | security | smoke — drives the audit's depth threshold -->
+
+risk_tier: normal
+<!-- risk_tier: high | normal | low -->
+
+To silence driver suggestions in audit findings, add a line: capability_suggestions with value off.
+
 **Focus areas** — what to cover thoroughly:
-<!-- List from: functional, security, ui, accessibility, performance -->
+<!-- Prose for humans; the parseable value is the `focus:` key above.
+     Response-time budgets are NOT a focus value — declare them in qa/perf.yaml
+     (percentile + scenario_ms budgets; reported by `sungen delivery`). -->
 <!-- Example: functional, security -->
 
 **Mandatory coverage:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.20-beta.1",
+  "version": "3.2.20-beta.2",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -39,8 +39,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.2.20-beta.1",
-    "@sungen/driver-ui": "3.2.20-beta.1",
+    "@sungen/driver-data-factory": "3.2.20-beta.2",
+    "@sungen/driver-ui": "3.2.20-beta.2",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

package/src/cli/commands/audit.ts

@@ -40,6 +40,14 @@ function render(r: AuditReport): void {
   if (r.gate.gaps.length) for (const g of r.gate.gaps) L(`      ✗ ${g.status === 'shallow' ? 'SHALLOW' : 'MISSING'}: ${g.theme}`);
   else L('      ✓ all critical themes covered (with data assertions)');
   L('');
+  if (r.flowQuality?.hasContract) {
+    const fq = r.flowQuality;
+    L(`  ①F Flow contract — goal: ${fq.contract!.goal}`);
+    L(`      outcome [${fq.contract!.outcome.screen}]: ${fq.outcomeProven ? '✓ proven (automated data assertion)' : fq.outcomeManualOnly ? '⚠ manual-only' : '✗ UNPROVEN'}`);
+    L(`      phases: ${fq.phases.map((p) => `${p.phase}=${p.covered ? (p.automated ? '✓' : 'manual') : '✗'}`).join('  ')}  → flowCoverage ${(fq.phaseRatio * 100).toFixed(0)}%`);
+    L(`      handoffs asserted: ${fq.handoffs.asserted}/${fq.handoffs.total}${fq.offGoal.length ? `   ⚠ off-goal scenarios: ${fq.offGoal.length} (${fq.offGoalCategories.join(', ')})` : ''}`);
+    L('');
+  }
   L(`  ② Assertion depth — ${r.depth.businessCriticalShallow}/${r.depth.businessCriticalTotal} business-critical scenarios are shallow (visibility/nav only)`);
   for (const s of r.depth.shallowBusinessCritical.slice(0, 8)) L(`      ⚠ ${s.category}: ${s.name}`);
   if (r.depth.shallowBusinessCritical.length > 8) L(`      … +${r.depth.shallowBusinessCritical.length - 8} more`);

package/src/cli/commands/delivery.ts

@@ -688,6 +688,12 @@ async function exportMatrixTarget(
   }
 
   log(`${COLOR.bold}${paths.label}${COLOR.reset} — ${model.manifest.itemCount} delivery item(s), ${model.manifest.variantCount} coverage variant(s), state: ${model.manifest.approvalState}`);
+  if (model.perf) {
+    const p = model.perf;
+    const tone = p.pass ? COLOR.green : COLOR.yellow;
+    log(`  ${tone}PERF ${p.pass ? 'PASS' : 'OVER BUDGET'}${COLOR.reset}: p${p.percentile} ${p.metric.replace('_ms', '')} ${p.measuredMs}ms ${p.pass ? '≤' : '>'} budget ${p.budgetMs}ms (${p.samples} run${p.samples === 1 ? '' : 's'})`);
+    for (const s of p.slowest) log(`    ${COLOR.yellow}slowest:${COLOR.reset} ${s.ms}ms — ${s.title.slice(0, 90)}`);
+  }
   printFindings(model.findings);
 
   if (opts.check) {

package/src/exporters/matrix/export.ts

@@ -16,6 +16,7 @@ import { mergeFeatureAndSpec } from '../scenario-merger';
 import { getPackageVersion } from '../package-info';
 import { writeCsv } from '../csv-exporter';
 import { writeXlsx } from '../xlsx-exporter';
+import { loadPerfConfig, perfVerdict } from '../../harness/perf';
 import { loadDeliveryMap, writeDeliveryMap } from './map-loader';
 import { mapContentFingerprint } from './fingerprint';
 import { buildMatrix, deriveVariants } from './build';
@@ -75,6 +76,16 @@ export function loadMatrixModel(paths: MatrixTargetPaths): MatrixLoadResult {
     transformerVersion: getPackageVersion(),
     specText: readSpecText(paths),
   });
+  // Perf verdict (#569): budgets are config (qa/perf.yaml), samples are the run's
+  // per-test durations. Advisory — reported here because delivery is where runs
+  // are read; the audit's score stays a pure function of the design artifacts.
+  const perfConfig = loadPerfConfig(paths.cwd);
+  if (perfConfig && results) {
+    const samples = [...results.values()]
+      .filter((r) => (r.status === 'passed' || r.status === 'failed' || r.status === 'timedOut') && typeof r.duration === 'number')
+      .map((r) => ({ title: r.testTitle, ms: r.duration as number }));
+    model.perf = perfVerdict(perfConfig, paths.unit, samples);
+  }
   return { model, map, mapErrors: [] };
 }
 

package/src/exporters/matrix/render-xlsx.ts

@@ -315,6 +315,21 @@ function addCoverageSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersio
 
   let rowIdx = 7;
 
+  // --- Performance budget (#569) — advisory: config (qa/perf.yaml) vs measured runs.
+  if (model.perf) {
+    const p = model.perf;
+    dataCell(ws.getRow(rowIdx).getCell(2), 'Performance budget', { bold: true });
+    rowIdx++;
+    const r = ws.getRow(rowIdx);
+    dataCell(r.getCell(2), `p${p.percentile} ${p.metric.replace('_ms', ' time')}`);
+    dataCell(r.getCell(3), p.pass ? 'PASS' : 'OVER BUDGET', { bold: true });
+    dataCell(r.getCell(4), `measured ${p.measuredMs}ms`);
+    dataCell(r.getCell(5), `budget ${p.budgetMs}ms`);
+    dataCell(r.getCell(6), `${p.samples} runs`);
+    if (!p.pass && p.slowest.length) dataCell(r.getCell(8), `slowest: ${p.slowest.map((x) => `${x.ms}ms ${x.title.slice(0, 40)}`).join(' · ')}`);
+    rowIdx += 2;
+  }
+
   // --- Requirement coverage (review §6): every requirement id gets ONE explicit status.
   if (model.requirements.length > 0) {
     dataCell(ws.getRow(rowIdx).getCell(2), 'Requirement coverage — every id has an explicit status', { bold: true });

package/src/exporters/matrix/types.ts

@@ -220,6 +220,8 @@ export interface MatrixModel {
   requirements: RequirementCoverage[];
   findings: MatrixFinding[];
   manifest: MatrixManifest;
+  /** Perf verdict (#569) — present when qa/perf.yaml sets a budget AND the run produced durations. */
+  perf?: import('../../harness/perf').PerfVerdict | null;
 }
 
 /** Complexity warning threshold (rules draft Gate I; raised for compact grouping) — echoed in the manifest. */

package/src/exporters/playwright-report-parser.ts

@@ -54,6 +54,7 @@ interface PlaywrightSpec {
     projectId?: string;
     results?: Array<{
       status?: string;           // 'passed' | 'failed' | 'timedOut' | 'skipped' | 'interrupted'
+      duration?: number;         // ms — Playwright emits this on every result (#569 perf budgets)
       startTime?: string;
       error?: { message?: string; stack?: string };
       attachments?: Array<{ name?: string; path?: string; contentType?: string }>;
@@ -120,6 +121,7 @@ export function loadPlaywrightReport(reportPath: string): Map<string, Playwright
     result.set(stripped, {
       testTitle: stripped,
       status,
+      duration: typeof res?.duration === 'number' ? res.duration : undefined,
       startTime: res?.startTime,
       error: errorMsg,
       tracePath: trace,

package/src/exporters/types.ts

@@ -121,6 +121,8 @@ export interface SpecFileData {
 export interface PlaywrightResult {
   testTitle: string;
   status: 'passed' | 'failed' | 'skipped' | 'timedOut' | 'interrupted' | 'unknown';
+  /** Wall-clock run time in ms (from Playwright's results[].duration) — perf budgets (#569). */
+  duration?: number;
   startTime?: string;
   error?: string;
   tracePath?: string;

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 } };
+  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,40 @@ 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.`);
+    }
+    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\`.`);
   }
@@ -485,6 +549,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,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 };
+}