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

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

@@ -603,24 +603,67 @@ error:
 
 ## Flow Test Generation
 
+> **Terminology**: many QA teams call this level **System Test** (ISTQB: verify the fully
+> integrated system against its specified requirements, designed around business
+> processes/use cases). In sungen a *flow* is that system-test suite run through the real UI;
+> its automation then serves as the regression suite on later runs. The names are
+> interchangeable in conversation; the artifacts stay `qa/flows/<name>/`.
+
+**Representative, not exhaustive (ISTQB system-test design rule).** A flow case takes ONE
+representative input per branch — one valid value for the main flow, one error value that
+triggers the exception branch and proves the journey recovers. The full equivalence/boundary
+matrix belongs to the OWNING SCREEN (as `@cases` there), never re-run inside the flow: if the
+screen already proved "the field rejects negatives", the flow only proves "the journey survives
+one rejected input". `sungen audit` reports `FLOW-EXHAUSTIVE-INPUTS` when ≥3 same-shape flow
+scenarios differ only in data. **Mocked dependencies**: a flow scenario using `@mock` is
+delivered as *Pass (Mocked)* — verified handling logic, not the real dependency; the delivery's
+External Dependency Tracking table lists it until re-verified real.
+
+**Release selection & external legs**: when the contract declares `golden: true`, tag the
+happy-path scenario(s) that prove the outcome with **`@golden`** — that is the set
+`sungen inspect` (Final Inspection, Go/No-Go) runs before a release; `GOLDEN-MISSING` fires
+until it exists, and a @golden scenario that passes only against mocks BLOCKS the release.
+When the contract declares `external:` legs (another team/vendor's system), scenarios touching
+those namespaces are the **System INTEGRATION** group — keep their oracles about the boundary
+(contract/format/handoff), and expect `SIT-MOCK-ONLY` until they are re-verified real.
+
+
 > **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 +673,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.21",
+  "version": "3.2.22-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.21",
-    "@sungen/driver-ui": "3.2.21",
+    "@sungen/driver-data-factory": "3.2.22-beta.1",
+    "@sungen/driver-ui": "3.2.22-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

@@ -100,7 +100,7 @@ function listFeatureTargets(cwd: string, screen: string, kind: UnitKind): Delive
     .sort((a, b) => a.featureBaseName.localeCompare(b.featureBaseName));
 }
 
-function listAllTargets(cwd: string): DeliveryTarget[] {
+export function listAllTargets(cwd: string): DeliveryTarget[] {
   const targets: DeliveryTarget[] = [];
   const scan = (kind: UnitKind, skip: (n: string) => boolean = () => false) => {
     const root = path.join(cwd, 'qa', qaParent(kind));
@@ -629,7 +629,7 @@ async function exportTarget(
 // Matrix export (Delivery v2 — the default; --legacy keeps the classic workbook)
 // ----------------------------------------------------------------------------
 
-function matrixPathsFor(cwd: string, target: DeliveryTarget): MatrixTargetPaths {
+export function matrixPathsFor(cwd: string, target: DeliveryTarget): MatrixTargetPaths {
   const base = qaDir(cwd, target);
   const genBase = generatedDir(cwd, target);
   return {
@@ -690,6 +690,18 @@ 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}`);
+  {
+    const mocked = model.items.flatMap((it) => it.variants.filter((v) => v.mocked));
+    if (mocked.length > 0) {
+      log(`  ${COLOR.yellow}MOCKED${COLOR.reset}: ${mocked.length} variant(s) verified against mocks (${mocked.slice(0, 4).map((v) => v.ref).join(', ')}${mocked.length > 4 ? ', …' : ''}) — Pass (Mocked) ≠ Pass (Real); see the External Dependency Tracking block on the Coverage sheet.`);
+    }
+  }
+  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/inspect.ts

@@ -0,0 +1,128 @@
+/**
+ * `sungen inspect` — Final Inspection: the deterministic Go/No-Go view. (#580 P9)
+ *
+ * The QA practice this implements: ONCE per release, run only the release-critical
+ * (@golden) journeys on the real environment with real (masked) data, on FROZEN code,
+ * and answer one question — is this build safe to release? Not a place to find new
+ * bugs; a place to refuse a release that is not proven.
+ *
+ * Every ingredient already exists, this command only reads them:
+ *   - selection   : @golden scenarios (tags pass through to Playwright — `--grep @golden`)
+ *   - results     : the units' Playwright JSON runs (same source delivery reads)
+ *   - freeze      : the approved delivery map's fingerprints — Gate E drift = not frozen
+ *   - honesty     : a @golden variant verified against MOCKS blocks GO — Pass (Mocked)
+ *                   says nothing about the real dependency (External Dependency Tracking)
+ *   - perf        : the qa/perf.yaml verdict, when configured
+ *
+ * Exit code 0 = GO, 2 = NO-GO — CI-usable as a release gate.
+ */
+import { Command } from 'commander';
+import * as fs from 'fs';
+import { listAllTargets, matrixPathsFor } from './delivery';
+import { loadMatrixModel } from '../../exporters/matrix/export';
+
+export interface UnitInspection {
+  unit: string;
+  approved: boolean;
+  frozen: boolean;              // no Gate E drift against the approved fingerprints
+  goldenTotal: number;
+  goldenPassed: number;
+  goldenFailed: number;
+  goldenPending: number;        // golden variants with no run result yet
+  goldenMocked: number;         // golden variants verified only against mocks
+  perfPass: boolean | null;     // null = no budget configured / no samples
+  reasons: string[];            // what blocks GO for this unit (empty = clean)
+}
+
+export interface ProjectInspection {
+  units: UnitInspection[];
+  goldenTotal: number;
+  verdict: 'GO' | 'NO-GO';
+  reasons: string[];
+}
+
+/** Pure aggregation over the delivery models — testable without the CLI. */
+export function inspectProject(cwd: string): ProjectInspection {
+  const units: UnitInspection[] = [];
+  for (const target of listAllTargets(cwd)) {
+    const paths = matrixPathsFor(cwd, target);
+    if (!fs.existsSync(paths.mapFile)) continue;   // no delivery map → not a delivered unit
+    const { model } = loadMatrixModel(paths);
+    if (!model) continue;                          // structural map errors surface in delivery
+
+    const variants = model.items.flatMap((it) => it.variants);
+    const golden = variants.filter((v) => v.golden);
+    if (golden.length === 0) continue;             // Final Inspection reads only the golden set
+
+    const passed = golden.filter((v) => v.result?.status === 'passed');
+    const failed = golden.filter((v) => v.result && ['failed', 'timedOut', 'interrupted'].includes(v.result.status));
+    const pending = golden.filter((v) => !v.result);
+    const mocked = golden.filter((v) => v.mocked);
+    const approved = model.manifest.approvalState === 'approved';
+    const frozen = !model.findings.some((f) => f.gate === 'E');
+    const perfPass = model.perf ? model.perf.pass : null;
+
+    const reasons: string[] = [];
+    if (!approved) reasons.push('delivery map not approved');
+    if (!frozen) reasons.push('sources drifted since approval (not frozen — Gate E)');
+    if (failed.length) reasons.push(`${failed.length} golden variant(s) FAILED`);
+    if (pending.length) reasons.push(`${pending.length} golden variant(s) have no run result`);
+    if (mocked.length) reasons.push(`${mocked.length} golden variant(s) are mock-verified — Pass (Mocked) cannot release`);
+    if (perfPass === false) reasons.push('performance budget OVER (qa/perf.yaml)');
+
+    units.push({
+      unit: paths.label ?? target.name,
+      approved, frozen,
+      goldenTotal: golden.length,
+      goldenPassed: passed.length,
+      goldenFailed: failed.length,
+      goldenPending: pending.length,
+      goldenMocked: mocked.length,
+      perfPass,
+      reasons,
+    });
+  }
+
+  const goldenTotal = units.reduce((n, u) => n + u.goldenTotal, 0);
+  const reasons = units.flatMap((u) => u.reasons.map((r) => `${u.unit}: ${r}`));
+  if (goldenTotal === 0) reasons.push('no @golden scenario anywhere — nothing proves the release (tag the release-critical journeys)');
+  return { units, goldenTotal, verdict: reasons.length === 0 ? 'GO' : 'NO-GO', reasons };
+}
+
+export function registerInspectCommand(program: Command): void {
+  program
+    .command('inspect')
+    .description('Final Inspection: Go/No-Go over the @golden set — results, freeze, mocks, perf (exit 2 = NO-GO)')
+    .option('--json', 'Output the raw JSON report')
+    .action((options) => {
+      try {
+        const report = inspectProject(process.cwd());
+        if (options.json) {
+          console.log(JSON.stringify(report, null, 2));
+        } else {
+          const L = console.log;
+          L('');
+          L(`━━━ Final Inspection — ${report.goldenTotal} @golden variant(s) across ${report.units.length} unit(s) ━━━`);
+          L('');
+          for (const u of report.units) {
+            const ok = u.reasons.length === 0;
+            L(`  ${ok ? '✓' : '✗'} ${u.unit} — golden ${u.goldenPassed}/${u.goldenTotal} passed` +
+              `${u.goldenMocked ? ` · ${u.goldenMocked} mocked` : ''}` +
+              `${u.perfPass === null ? '' : u.perfPass ? ' · perf PASS' : ' · perf OVER'}` +
+              ` · ${u.approved ? 'approved' : 'NOT approved'} · ${u.frozen ? 'frozen' : 'DRIFTED'}`);
+            for (const r of u.reasons) L(`      • ${r}`);
+          }
+          L('');
+          L(`  Verdict: ${report.verdict === 'GO' ? '✅ GO' : '⛔ NO-GO'}`);
+          for (const r of report.units.length === 0 ? report.reasons : (report.verdict === 'NO-GO' ? report.reasons.slice(0, 12) : [])) {
+            L(`      • ${r}`);
+          }
+          L('');
+        }
+        if (report.verdict !== 'GO') process.exitCode = 2;
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

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/cli/index.ts

@@ -15,6 +15,7 @@ import { registerFigmaCommand } from './commands/figma';
 import { registerAddFlowCommand } from './commands/add-flow';
 import { registerDashboardCommand } from './commands/dashboard';
 import { registerAuditCommand } from './commands/audit';
+import { registerInspectCommand } from './commands/inspect';
 import { registerDepthLintCommand } from './commands/depth-lint';
 import { registerJourneyCommand } from './commands/journey';
 import { registerGateCommand } from './commands/gate';
@@ -63,6 +64,7 @@ async function main() {
   registerAddFlowCommand(program);
   registerDashboardCommand(program);
   registerAuditCommand(program);
+  registerInspectCommand(program);
   registerDepthLintCommand(program);
   registerJourneyCommand(program);
   registerGateCommand(program);

package/src/exporters/matrix/build.ts

@@ -32,6 +32,8 @@ import {
   MAX_VARIANTS_PER_ITEM,
 } from './types';
 import { runGates } from './gates';
+import { capabilityRegistry } from '../../capabilities/registry';
+import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 
 // ---------------------------------------------------------------------------
 // Variant derivation
@@ -42,6 +44,27 @@ function normalizeShape(text: string): string {
   return text.replace(/\{\{[^}]*\}\}/g, '{{*}}').replace(/\s+/g, ' ').trim();
 }
 
+/**
+ * Is this scenario verified against MOCKED responses, and against which named deps? (#580)
+ * The mock capability owns its grammar: prefer the registry's `annotations` + `detectsStep`
+ * (driver-mock exports isMockStep — install AND call-count forms); fall back to literal
+ * twins of that grammar when the driver is not installed on this machine.
+ */
+export function detectMocked(tags: string[], stepTexts: string[]): { mocked: boolean; mockDeps: string[] } {
+  discoverAndRegisterCapabilities();
+  const cap = capabilityRegistry.get('mock');
+  const tagForms = cap?.annotations ?? ['@mock', '@network'];
+  const tagged = tags.some((t) => tagForms.some((a) => t === a || t.startsWith(`${a}:`)));
+  const isMockStep = cap?.detectsStep ?? ((t: string) =>
+    /\[[^\]]+\]\s+mock\s+is\s+active\b/i.test(t) ||
+    /\[[^\]]+\]\s+mock\s+called\s+(?:\{\{[^}]+\}\}|\d+)\s+times?\b/i.test(t));
+  const mockDeps = Array.from(new Set(stepTexts
+    .filter((t) => isMockStep(t))
+    .map((t) => (t.match(/\[([^\]]+)\]\s+mock\b/i) || [])[1])
+    .filter((x): x is string => Boolean(x))));
+  return { mocked: tagged || mockDeps.length > 0, mockDeps };
+}
+
 function deriveLayers(tags: string[]): MatrixLayer[] {
   const layers = new Set<MatrixLayer>(['ui']);
   if (tags.some((t) => t === '@api' || t.startsWith('@api:') || t === '@requires:api')) layers.add('api');
@@ -178,12 +201,29 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
       ...(apiCallsAreTrigger ? [] : apiRequestLines),
     ]));
 
+    // Mocked-run detection (#580): a pass against a scripted response must never read as a
+    // pass against the real dependency. The GRAMMAR authority is the mock capability itself
+    // (driver-mock declares `annotations` and exports `detectsStep`) — consult it instead of
+    // re-writing its regexes here, so new tag/step forms are picked up automatically. The
+    // literal fallback keeps delivery honest on machines WITHOUT the driver installed
+    // (delivery reads only feature text + results, it never compiles). Background steps are
+    // scanned too — a Background install mocks every scenario in the feature, and the
+    // driver's own spec warns that per-scenario tracking misses them.
+    const scenarioStepTexts = [
+      ...inputs.feature.backgroundOrderedSteps.map((st) => st.text),
+      ...m.feature.orderedSteps.map((st) => st.text),
+    ];
+    const { mocked, mockDeps } = detectMocked(tags, scenarioStepTexts);
+
     const base = {
       vpId,
       vpCategory,
       priority: extractPriority(tags),
       mode: mode as 'auto' | 'manual',
       manualReason: manualReason(tags),
+      mocked,
+      ...(mockDeps.length ? { mockDeps } : {}),
+      golden: tags.includes('@golden'),
       layers: deriveLayers(tags),
       traces: tags.filter((t) => t.startsWith('@spec:')).map((t) => t.slice('@spec:'.length)),
       runtimeVars: [...runtimeVars],

package/src/exporters/matrix/export.ts

@@ -17,6 +17,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';
@@ -89,6 +90,16 @@ export function loadMatrixModel(paths: MatrixTargetPaths): MatrixLoadResult {
     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: [] };
 }
 

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

@@ -224,7 +224,7 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
         // parent's steps + these read as one continuous procedure.
         numbered(item.triggerDeltas[v.ref] ?? [], item.trigger.length + 1),
         expectedWithVerification(v.oracle, v.verification),
-        v.mode === 'manual' ? `Manual${v.manualReason ? ` (${v.manualReason})` : ''}` : 'Auto',
+        v.mode === 'manual' ? `Manual${v.manualReason ? ` (${v.manualReason})` : ''}` : (v.mocked ? 'Auto · Mocked' : 'Auto'),
         v.traces.join(', '),
         variantState(v),
         isoDate(v.result?.startTime),
@@ -315,6 +315,50 @@ 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;
+  }
+
+  // --- External Dependency Tracking (#580, ISTQB system-test practice): every case that
+  // ran against a MOCK is listed centrally. Its Result stays in the canonical vocabulary
+  // (the roll-up formulas depend on it); THIS table is where "Pass (Mocked) ≠ Pass (Real)"
+  // is visible — a case verified only against mocks is not Done until re-verified real.
+  {
+    const mockedVars = model.items.flatMap((it) => it.variants.filter((v) => v.mocked).map((v) => ({ it, v })));
+    if (mockedVars.length > 0) {
+      dataCell(ws.getRow(rowIdx).getCell(2), 'External Dependency Tracking — mock-verified cases (Pass here = Pass (Mocked), not Pass (Real))', { bold: true });
+      rowIdx++;
+      const hd = ws.getRow(rowIdx);
+      dataCell(hd.getCell(2), 'Variant');
+      dataCell(hd.getCell(3), 'Mocked dependency');
+      dataCell(hd.getCell(4), 'Delivery item');
+      dataCell(hd.getCell(5), 'Result');
+      dataCell(hd.getCell(8), 'Real-environment re-verify');
+      rowIdx++;
+      for (const { it, v } of mockedVars) {
+        const r = ws.getRow(rowIdx);
+        dataCell(r.getCell(2), v.ref);
+        dataCell(r.getCell(3), (v.mockDeps ?? []).join(', ') || '(scenario-level @mock)');
+        dataCell(r.getCell(4), it.id);
+        dataCell(r.getCell(5), variantState(v));
+        dataCell(r.getCell(8), '');
+        rowIdx++;
+      }
+      rowIdx++;
+    }
+  }
+
   // --- 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

@@ -92,6 +92,14 @@ export interface CoverageVariant {
   /** 'auto' | 'manual'; manual keeps its @manual:Mx reason. */
   mode: 'auto' | 'manual';
   manualReason?: string;
+  /** The scenario runs against MOCKED network responses (@mock / `[x] mock is active`) —
+   *  a pass verifies the handling logic, not the real dependency (Pass (Mocked) ≠ Pass (Real),
+   *  #580: ISTQB external-dependency tracking). */
+  mocked?: boolean;
+  /** Named mocked dependencies (`[name] mock is active` refs), for the tracking table. */
+  mockDeps?: string[];
+  /** Release-critical: tagged @golden — the Final Inspection set (`sungen inspect`, #580 P9). */
+  golden?: boolean;
   layers: MatrixLayer[];
   /** @spec:* requirement traces. */
   traces: string[];
@@ -225,6 +233,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;