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

package/dist/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}}

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

@@ -6,6 +6,16 @@ order: 20
 claude-tools: "Read, Grep, Bash, Glob, Write, AskUserQuestion, Skill, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot"
 copilot-tools: "[vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']"
 codex-trigger: "Run when the user asks to CREATE, generate, write, or author test cases / a .feature file for a screen or flow. Step 2 (after add-screen/add-flow, before run-test). Do NOT use for executing, running, or compiling existing tests."
+---
+## ⛔ HARD RULE — the run's LAST action is the next-step hand-back
+
+A create-test run is NOT finished when the files are written or the audit prints. The final
+action of EVERY run — success, partial, or aborted — is the next-step hand-back
+({{#cap parallel-subagents}}an `AskUserQuestion` offering the next actions{{/cap}}{{^cap parallel-subagents}}a numbered list of next-action choices{{/cap}};
+see "Finish — always hand the next step back" at the end of this file). Ending with a prose
+summary and no choices is a broken run: the operator is left guessing. This holds no matter
+how long the generation/repair loop ran.
+
 ---
 {{#cap parallel-subagents}}
 ## ⛔ HARD RULE — No Figma MCP when PAT data exists

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",
+  "version": "3.2.21-beta.1",
   "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",
-    "@sungen/driver-ui": "3.2.20",
+    "@sungen/driver-data-factory": "3.2.21-beta.1",
+    "@sungen/driver-ui": "3.2.21-beta.1",
     "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

@@ -635,6 +635,8 @@ function matrixPathsFor(cwd: string, target: DeliveryTarget): MatrixTargetPaths
   return {
     cwd,
     unit: target.featureBaseName,
+    kind: target.kind,
+    area: target.screen,
     label: target.isFlow ? `flow/${target.featureBaseName}` : target.featureBaseName,
     featureFile: path.join(base, 'features', `${target.featureBaseName}.feature`),
     testDataFile: resolveTestDataPathForTarget(cwd, target),
@@ -688,6 +690,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/cli/commands/trace.ts

@@ -55,6 +55,15 @@ export function registerTraceCommand(program: Command): void {
         for (const line of r.mermaid.split('\n')) L('  ' + line);
         L('  ```');
         L('');
+        // ⑥ Deterministic next-step hand-back. The AI commands are INSTRUCTED to close
+        // every run by offering next actions, but a long generation run can end without
+        // it — leaving the operator guessing. Printing the choices here makes the
+        // hand-back survive the AI forgetting: trace is the converge step's last call.
+        L('  ⑥ NEXT STEPS');
+        L(`     → /sungen:run-test ${name}     (generate selectors, compile, run, auto-fix)`);
+        L(`     → /sungen:create-test ${name}  (extend coverage / next tier)`);
+        L(`     → /sungen:delivery ${name}     (export the Test Case & Coverage Matrix)`);
+        L('');
       } catch (error) {
         console.error('Error:', error instanceof Error ? error.message : error);
         process.exit(1);

package/src/exporters/api-testcase-formatter.ts

@@ -74,26 +74,7 @@ export function formatApiRequest(
   const calls = parseApiCalls(tags).filter((c) => catalog[c.name]);
   if (calls.length === 0) return '';
 
-  const blocks = calls.map((call) => {
-    const entry = catalog[call.name];
-    const resolve = (raw: string): string => localize(bindParams(raw, call.args));
-    // Coerce method/path — loadApiCatalog is a raw passthrough, so a malformed entry
-    // (numeric method/path) must degrade gracefully, not crash the unit's export.
-    const method = String(entry.method ?? '').toUpperCase() || '—';
-    const api = entry.path ? resolve(String(entry.path)) : '—';
-    const header = formatHeaders(entry, call.args, localize);
-    const lines = [`Method: ${method}`, `API: ${api}`, `Header: ${header}`];
-    // A file upload carries its parts in `files:` / `bodyFile:`, NOT `body:` — render them so the
-    // delivery Steps reflect the actual request (without this, fields like `gift_image` vanished from
-    // the export even though the compiled .spec.ts sent them).
-    const filesStr = formatFiles(entry.files, call.args, localize);
-    const bodyFileStr = formatBodyFile(entry.bodyFile, call.args, localize);
-    // Body is scalar fields; a pure file upload may have none → still show `Body: —` for a stable shape.
-    lines.push(`Body: ${formatBody(entry.body, call.args, localize)}`);
-    if (filesStr) lines.push(`Files: ${filesStr}`);
-    if (bodyFileStr) lines.push(`Body file: ${bodyFileStr}`);
-    return lines.join('\n');
-  });
+  const blocks = calls.map((call) => callBlockLines(call, catalog[call.name], localize).join('\n'));
 
   if (blocks.length === 1) return blocks[0];
   // Multiple endpoints (flow) — number them so the call order is explicit.
@@ -102,6 +83,51 @@ export function formatApiRequest(
     .join('\n');
 }
 
+/** Render one invoked endpoint as its Method / API / Header / Body block lines. */
+function callBlockLines(call: ApiCall, entry: ApiCatalogEntry, localize: (text: string) => string): string[] {
+  const resolve = (raw: string): string => localize(bindParams(raw, call.args));
+  // Coerce method/path — loadApiCatalog is a raw passthrough, so a malformed entry
+  // (numeric method/path) must degrade gracefully, not crash the unit's export.
+  const method = String(entry.method ?? '').toUpperCase() || '—';
+  const api = entry.path ? resolve(String(entry.path)) : '—';
+  const header = formatHeaders(entry, call.args, localize);
+  const lines = [`Method: ${method}`, `API: ${api}`, `Header: ${header}`];
+  // A file upload carries its parts in `files:` / `bodyFile:`, NOT `body:` — render them so the
+  // delivery Steps reflect the actual request (without this, fields like `gift_image` vanished from
+  // the export even though the compiled .spec.ts sent them).
+  const filesStr = formatFiles(entry.files, call.args, localize);
+  const bodyFileStr = formatBodyFile(entry.bodyFile, call.args, localize);
+  // Body is scalar fields; a pure file upload may have none → still show `Body: —` for a stable shape.
+  lines.push(`Body: ${formatBody(entry.body, call.args, localize)}`);
+  if (filesStr) lines.push(`Files: ${filesStr}`);
+  if (bodyFileStr) lines.push(`Body file: ${bodyFileStr}`);
+  return lines;
+}
+
+/**
+ * Matrix-cell view of the ordered `@api:` chain: ONE string per call — the full
+ * request block for cataloged endpoints, a name-only line otherwise (a call must
+ * never silently vanish from the deliverable). Blocks are numbered when the chain
+ * has more than one call — same style as formatApiRequest — which also keeps a
+ * deliberately repeated call distinct through the matrix's precondition Set-dedup.
+ */
+export function formatApiCallLines(
+  calls: ApiCall[],
+  catalog: Record<string, ApiCatalogEntry>,
+  localize: (text: string) => string,
+): string[] {
+  const blocks = calls.map((call) => {
+    const entry = catalog[call.name];
+    if (!entry) {
+      const args = Object.entries(call.args).map(([k, v]) => `${k}=${v}`).join(', ');
+      return [`Call API ${call.name}${args ? ` (${args})` : ''}.`];
+    }
+    return callBlockLines(call, entry, localize);
+  });
+  if (blocks.length === 1) return [blocks[0].join('\n')];
+  return blocks.map((b, i) => b.map((l, j) => (j === 0 ? `${i + 1}. ${l}` : `   ${l}`)).join('\n'));
+}
+
 /**
  * Rewrite an API scenario's `Then` assertions into readable Status / Response lines.
  * Raw assertions reference the runtime response object

package/src/exporters/matrix/build.ts

@@ -5,7 +5,8 @@
  * is structural: there is no independent parent result input).
  */
 
-import { FeatureMetadata, PlaywrightResult } from '../types';
+import { ApiCatalogEntry, FeatureMetadata, PlaywrightResult } from '../types';
+import { formatApiCallLines, parseApiCalls } from '../api-testcase-formatter';
 import { bucketTexts } from './step-buckets';
 import { MergedScenario } from '../scenario-merger';
 import {
@@ -95,6 +96,8 @@ export interface BuildInputs {
   transformerVersion: string;
   /** requirements/spec.md content — source of the requirement-id inventory (FR/TR/NFR). */
   specText?: string;
+  /** apis.yaml endpoint catalog (api units) — renders `@api:` calls as request blocks. */
+  apiCatalog?: Record<string, ApiCatalogEntry>;
 }
 
 /**
@@ -102,11 +105,12 @@ export interface BuildInputs {
  * `@cases` dataset row). Exported separately so the gates + the map-proposal
  * support tooling see the same universe the builder does.
  */
-export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' | 'testData' | 'results'>): CoverageVariant[] {
+export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' | 'testData' | 'results' | 'apiCatalog'>): CoverageVariant[] {
   const { merged, results } = inputs;
   // Test-data values may cross-reference other keys (email_padded: " {{valid_email}} ") —
   // resolve one level so display cells never leak a template token (review B-04).
   const testData = resolveCrossRefs(inputs.testData);
+  const apiCatalog = inputs.apiCatalog ?? {};
   const variants: CoverageVariant[] = [];
 
   for (const m of merged) {
@@ -141,11 +145,27 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
       tags,
     );
 
+    // `@api:<name>(args)` invocations — the runtime's precondition codegen (driver-api):
+    // each call sends its catalog request BEFORE the scenario's own steps and binds
+    // {{<name>.*}}. Cell placement follows what the tester actually does:
+    //  - pure api scenario (no When steps): the calls ARE the procedure → trigger,
+    //    rendered as Method/API/Header/Body blocks (the legacy Steps-cell language) —
+    //    the page-load fallback would misdescribe an HTTP request;
+    //  - hybrid (@api + own When steps): the calls are setup → precondition.
+    // Blocks keep raw `{{var}}` tokens here; renderCells' sub resolves them per data
+    // context (so @cases rows render their own arg values).
+    const apiCalls = parseApiCalls(tags);
+    const apiCallsAreTrigger = apiCalls.length > 0 && rawTrigger.length === 0;
+    const apiRequestLines = apiCalls.length > 0 ? formatApiCallLines(apiCalls, apiCatalog, (s) => s) : [];
+    // Shape entry per call: endpoint identity + arg KEYS (values are data, not shape).
+    const apiCallShapes = apiCalls.map((c) => `api:${c.name}(${Object.keys(c.args).join(',')})`);
+
     const preconditionProfile = [
       authRole ?? '-',
       m.feature.extendsName ?? '-',
       ...bucketTexts(m.feature.orderedSteps, 'given').map(normalizeShape),
       ...(manual?.preconditions ?? []).map(normalizeShape),
+      ...(apiCallsAreTrigger ? [] : apiCallShapes),
     ].join(' | ');
     // Display precondition = auth state + Background Given (shared start state) +
     // the scenario's own Given steps + manual Setup lines — deduplicated (a manual
@@ -155,6 +175,7 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
       ...bucketTexts(inputs.feature.backgroundOrderedSteps, 'given').map(renderPrecondition),
       ...bucketTexts(m.feature.orderedSteps, 'given').map(renderPrecondition),
       ...(manual?.preconditions ?? []).map((t) => renderSetupInstruction(t)),
+      ...(apiCallsAreTrigger ? [] : apiRequestLines),
     ]));
 
     const base = {
@@ -166,7 +187,8 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
       layers: deriveLayers(tags),
       traces: tags.filter((t) => t.startsWith('@spec:')).map((t) => t.slice('@spec:'.length)),
       runtimeVars: [...runtimeVars],
-      triggerShape: rawTrigger.map(normalizeShape),
+      apiCalls: apiCalls.length,
+      triggerShape: [...rawTrigger.map(normalizeShape), ...(apiCallsAreTrigger ? apiCallShapes : [])],
       oracleShape: rawOracle.map(normalizeShape),
       preconditionProfile,
       precondition,
@@ -196,7 +218,11 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
         });
         return { trigger, oracle, precondition: preconditionOut, verification: verificationOut };
       }
-      const trigger = rawTrigger.map((s) => renderAction(sub(s)));
+      // A pure api scenario's procedure is its request blocks (not renderAction —
+      // Method/API/Header/Body lines are already reader-facing, not step DSL).
+      const trigger = apiCallsAreTrigger
+        ? apiRequestLines.map(sub)
+        : rawTrigger.map((s) => renderAction(sub(s)));
       const oracle = rawOracle.map((s) => renderExpected(sub(s)));
       return {
         // A pure-render check (Given + Then only) is checked on page load — say so

package/src/exporters/matrix/export.ts

@@ -8,6 +8,7 @@
  */
 
 import * as fs from 'fs';
+import { loadApiCatalog } from '../api-catalog-loader';
 import { parseFeatureMetadata } from '../feature-parser';
 import { parseSpecFile } from '../spec-parser';
 import { loadTestData } from '../test-data-resolver';
@@ -16,17 +17,25 @@ 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';
 import { renderMatrixXlsx } from './render-xlsx';
 import { renderMatrixCsv } from './render-csv';
 import { DeliveryMap, MatrixFinding, MatrixModel } from './types';
+import { ApiCatalogEntry } from '../types';
 
 export interface MatrixTargetPaths {
   cwd: string;
   /** Feature basename — names the deliverable files. */
   unit: string;
+  /** Unit kind — 'api' loads the endpoint catalog so cells render request blocks.
+   *  Optional for back-compat: absent means non-api (no catalog). */
+  kind?: 'screen' | 'flow' | 'api';
+  /** Area/screen directory name (differs from `unit` for sub-features) — keys the
+   *  unit-level apis.yaml path. Defaults to `unit`. */
+  area?: string;
   /** Display label (flow/… prefix for flows). */
   label: string;
   featureFile: string;
@@ -44,6 +53,11 @@ function readSpecText(paths: MatrixTargetPaths): string {
     : '';
 }
 
+/** apis.yaml endpoint catalog for an api unit ({} for screen/flow — loader no-ops). */
+function catalogFor(paths: MatrixTargetPaths): Record<string, ApiCatalogEntry> {
+  return loadApiCatalog(paths.cwd, paths.kind ?? 'screen', paths.area ?? paths.unit);
+}
+
 export interface MatrixLoadResult {
   model?: MatrixModel;
   map?: DeliveryMap;
@@ -74,7 +88,18 @@ export function loadMatrixModel(paths: MatrixTargetPaths): MatrixLoadResult {
     map,
     transformerVersion: getPackageVersion(),
     specText: readSpecText(paths),
+    apiCatalog: catalogFor(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: [] };
 }
 
@@ -95,15 +120,17 @@ export function approveMatrix(paths: MatrixTargetPaths, groupIds?: string[]): {
   const merged = mergeFeatureAndSpec(feature, spec);
   const testData = fs.existsSync(paths.testDataFile) ? loadTestData(paths.testDataFile, process.env.SUNGEN_ENV ?? null) : null;
 
+  const apiCatalog = catalogFor(paths);
   const model = buildMatrix({
     unit: paths.unit, feature, merged, testData, results: null, map,
     transformerVersion: getPackageVersion(),
     specText: readSpecText(paths),
+    apiCatalog,
   });
   const blocking = model.findings.filter((f) => f.severity === 'error');
   if (blocking.length > 0) return { findings: blocking, approved: [] };
 
-  const variants = deriveVariants({ feature, merged, testData, results: null });
+  const variants = deriveVariants({ feature, merged, testData, results: null, apiCatalog });
   const byRef = new Map(variants.map((v) => [v.ref, v] as const));
   const byVp = new Map<string, typeof variants>();
   for (const v of variants) {

package/src/exporters/matrix/gates.ts

@@ -248,7 +248,13 @@ function gateDExecutability(ctx: GateContext, findings: MatrixFinding[]): void {
   for (const g of map.groups) {
     const vs = g.variants.flatMap((ref) => expandMapRef(ref, variantsByVp));
     for (const v of vs) {
-      const hasPrecondition = v.precondition.length > 0 || bucketTexts(feature.backgroundOrderedSteps, 'given').length > 0;
+      // An api-first variant (`@api:` calls, no UI steps) legitimately has no UI start
+      // state — the request blocks in its trigger (Method/API/Header/Body) carry
+      // everything a tester needs. Demanding a Background/Given here blocked 100% of
+      // api-first units (field report 3.2.19).
+      const hasPrecondition = v.precondition.length > 0
+        || bucketTexts(feature.backgroundOrderedSteps, 'given').length > 0
+        || v.apiCalls > 0;
       if (!hasPrecondition) {
         findings.push({
           gate: 'D', severity: 'error', ref: v.ref,

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

@@ -98,6 +98,11 @@ export interface CoverageVariant {
   /** Variables this scenario produces at RUN TIME (`remember … as {{v}}`, capability
    *  bindings) — they never exist in test-data, so Gate D must not demand them. */
   runtimeVars: string[];
+  /** Count of `@api:<name>` invocations. An api-first variant's start state lives in
+   *  its request blocks (Method/API/Header/Body), so Gate D's precondition demand is
+   *  waived when this is > 0 — requiring a Background/Given blocked EVERY api-first
+   *  unit (field report 3.2.19). */
+  apiCalls: number;
   /** Condition summary: differentiating dimension shown on the sub-row. */
   condition: string;
   /** Resolved data pairs (test-data values / dataset-row columns), `key: value` lines. */
@@ -220,6 +225,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/generators/test-generator/diagnostics.ts

@@ -35,12 +35,17 @@
  *             nothing for the query half to assert, so the step checks the PATH only. Not an
  *             error (the value may legitimately vary per environment), but the step asserts
  *             strictly less than it appears to
+ *   SG-W015 — `see [X] card/item with {{n}}` where the value is a bare number: this 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. Count semantics exist on row/table ("see [T] table with {{n}}",
+ *             "see [Ref] row with {{n}}") and lists ("should have count") only
  *
  * Diagnostics never block generation by themselves; `sungen generate --strict`
  * turns any collected diagnostic into a non-zero exit.
  */
 
-export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012' | 'SG-W013' | 'SG-W014';
+export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012' | 'SG-W013' | 'SG-W014' | 'SG-W015';
 
 export interface Diagnostic {
   code: DiagnosticCode;