@aperant/framework 0.8.4 → 0.8.7

package/src/cli/verify-proof/resolver.mjs

@@ -16,12 +16,24 @@
  *
  * Ties are broken by the next dimension; if every dimension is equal the
  * driver with the lexicographically smaller driverId wins (deterministic).
+ *
+ * v0.8.6 — `resolveDriversForOutcomes(opts)` adds per-outcome driver
+ * dispatch for cross-surface specs (per spec §ID-03). It accepts the
+ * positional `outcomes[]` produced by `parseUserOutcomes` and returns
+ * `Array<{outcome_id, surface, driver}>` — one entry per
+ * (outcome, surface) pair. For `[electron+web]` outcomes it emits TWO
+ * entries with the same outcome_id and different drivers. The
+ * outcome_id field is passed through verbatim from parser → resolver
+ * → workflow runner with no name rewriting (the positional-ID
+ * contract).
+ *
+ * Existing `resolveDriver()` and `scoreDriver()` exports are unchanged.
  */
 
-import { UnsatisfiedRequiredCapabilityError } from '@aperant/driver-sdk'
+import { UnsatisfiedRequiredCapabilityError } from '@aperant/framework/driver-sdk'
 
 /**
- * @typedef {import('@aperant/driver-sdk').DriverManifest} DriverManifest
+ * @typedef {import('@aperant/framework/driver-sdk').DriverManifest} DriverManifest
  * @typedef {import('./runtime-detect.mjs').RuntimeCapabilities} RuntimeCapabilities
  */
 
@@ -131,8 +143,29 @@ export function resolveDriver(opts) {
 		stableOnly.push(d)
 	}
 
-	// Score every survivor against required capabilities.
-	const scored = stableOnly.map((m) => ({ manifest: m, ...scoreDriver(m, runtime, required) }))
+	// Override is hard precedence (per opts.override docstring "explicit
+	// driverId precedence"): when set, try override-listed drivers in
+	// override order — the first one that satisfies every required
+	// capability wins, regardless of compatibility/priority/stability
+	// ranking. Non-matching override entries land in fallback. Only when
+	// every override entry misses a required cap do we fall through to
+	// score-based pick on the remaining drivers.
+	const overrideListed = stableOnly.filter((m) => overrideSet.has(m.driverId))
+	for (const candidate of overrideListed) {
+		const caps = new Set(candidate.capabilities ?? [])
+		const missing = required.filter((c) => !caps.has(c))
+		if (missing.length === 0) {
+			return { selected: candidate, fallback_attempts: fallback }
+		}
+		fallback.push({
+			driver_id: candidate.driverId,
+			reason: `override-listed but missing required capabilities: ${missing.join(', ')}`,
+		})
+	}
+
+	// Score every non-override survivor against required capabilities.
+	const nonOverride = stableOnly.filter((m) => !overrideSet.has(m.driverId))
+	const scored = nonOverride.map((m) => ({ manifest: m, ...scoreDriver(m, runtime, required) }))
 
 	// Sort highest-first, tie-break on driverId for determinism.
 	scored.sort((a, b) => {
@@ -161,3 +194,137 @@ export function resolveDriver(opts) {
 		fallback,
 	)
 }
+
+/**
+ * Map a User Outcomes surface tag to the runtime-capability flag a driver
+ * must carry (via `matchesRuntime`) to be eligible for that surface.
+ *
+ * Closed surface set: `electron | web | cli | api | electron+web`.
+ * `electron+web` is NOT a single flag — it's a cross-surface tag the
+ * workflow runner expands into two single-surface dispatches.
+ *
+ * @param {('electron'|'web'|'cli'|'api')} surface
+ * @returns {('is_electron'|'is_web_frontend'|'has_node')}
+ */
+export function surfaceToRequiredFlag(surface) {
+	switch (surface) {
+		case 'electron':
+			return 'is_electron'
+		case 'web':
+			return 'is_web_frontend'
+		case 'cli':
+		case 'api':
+			return 'has_node'
+		default:
+			throw new Error(`surfaceToRequiredFlag: unknown surface "${surface}"`)
+	}
+}
+
+/**
+ * Resolve a driver per outcome surface tag, NOT per verify-proof run
+ * (per spec §ID-03). For each input outcome the function returns one
+ * `{outcome_id, surface, driver}` entry; for `[electron+web]` outcomes
+ * it returns TWO entries (electron + web) sharing the same outcome_id.
+ *
+ * The `outcome_id` field on each returned entry is the positional ID
+ * produced by `parseUserOutcomes` (e.g. `O1`, `O2`). The resolver does
+ * NOT rewrite or regenerate IDs — they pass through verbatim so the
+ * workflow runner can correlate proof artifacts to spec lines.
+ *
+ * Each per-surface dispatch synthesizes a runtime-capabilities view
+ * that ONLY claims the surface's required flag (e.g. `is_electron`
+ * alone for an electron-surface outcome, even when the project also
+ * carries `is_web_frontend`). This forces the existing scoring to
+ * pick the per-surface driver — without it, a project with BOTH
+ * electron AND web capabilities would always select the highest-
+ * priority bundled driver (currently `browser`) for every outcome.
+ *
+ * Delegates to the existing `resolveDriver()` for the actual scoring
+ * — the scoring code stays in one place.
+ *
+ * @param {Object} opts
+ * @param {DriverManifest[]} opts.drivers
+ * @param {RuntimeCapabilities} opts.runtime
+ * @param {Array<{id: string, surface: 'electron'|'web'|'cli'|'api'|'electron+web'}>} opts.outcomes
+ * @param {string[]} [opts.override]
+ * @param {string[]} [opts.required_stability]
+ * @param {string[]} [opts.required_capabilities] — defaults to ['screenshot']
+ * @returns {Array<{outcome_id: string, surface: string, driver: DriverManifest, fallback_attempts: Array<{driver_id: string, reason: string}>}>}
+ */
+export function resolveDriversForOutcomes(opts) {
+	const drivers = opts.drivers ?? []
+	const runtime = opts.runtime
+	const outcomes = opts.outcomes ?? []
+	const required = opts.required_capabilities ?? ['screenshot']
+	const override = opts.override
+	const stability = opts.required_stability
+
+	/** @type {Array<{outcome_id: string, surface: string, driver: DriverManifest, fallback_attempts: Array<{driver_id: string, reason: string}>}>} */
+	const results = []
+
+	for (const outcome of outcomes) {
+		const surfacesToDispatch =
+			outcome.surface === 'electron+web' ? ['electron', 'web'] : [outcome.surface]
+
+		for (const surface of surfacesToDispatch) {
+			const flag = surfaceToRequiredFlag(/** @type {'electron'|'web'|'cli'|'api'} */ (surface))
+			// Synthesize a per-surface runtime view: only the surface's
+			// required flag is on; every other flag is masked off so the
+			// scoring prefers per-surface drivers (otherwise, on a
+			// multi-runtime project, the highest-priority bundled driver
+			// always wins). `has_node` stays on for cli/api since multiple
+			// drivers may target node.
+			const surfaceRuntime = maskRuntimeForSurface(runtime, flag)
+			const resolved = resolveDriver({
+				drivers,
+				runtime: surfaceRuntime,
+				required_capabilities: required,
+				...(override ? { override } : {}),
+				...(stability ? { required_stability: stability } : {}),
+			})
+			results.push({
+				outcome_id: outcome.id,
+				surface,
+				driver: resolved.selected,
+				fallback_attempts: resolved.fallback_attempts,
+			})
+		}
+	}
+
+	return results
+}
+
+/**
+ * Return a copy of `runtime` with every flag false EXCEPT the one named
+ * by `flag`. Used to scope the resolver's compatibility check to a
+ * single surface during per-outcome dispatch.
+ *
+ * @param {RuntimeCapabilities} runtime
+ * @param {string} flag — one of: is_electron | is_web_frontend | has_node
+ * @returns {RuntimeCapabilities}
+ */
+function maskRuntimeForSurface(runtime, flag) {
+	/** @type {RuntimeCapabilities} */
+	const masked = {
+		is_electron: false,
+		is_tauri: false,
+		is_nextjs: false,
+		is_nuxt: false,
+		is_web_frontend: false,
+		is_expo: false,
+		is_react_native: false,
+		has_node: false,
+	}
+	// Only flip the surface's flag on if the project actually carries it
+	// (otherwise the resolver should genuinely fail — fail-closed).
+	if (flag === 'is_electron' && runtime.is_electron) masked.is_electron = true
+	if (flag === 'is_web_frontend' && runtime.is_web_frontend) {
+		masked.is_web_frontend = true
+		// Carry the framework hint too (Next.js / Nuxt) so drivers that
+		// target browser via those frameworks still match.
+		masked.is_nextjs = runtime.is_nextjs
+		masked.is_nuxt = runtime.is_nuxt
+	}
+	if (flag === 'has_node') masked.has_node = runtime.has_node
+	return masked
+}

package/src/cli/verify-proof/runtime-detect.mjs

@@ -8,9 +8,17 @@
  *
  * Pattern: pure data in → pure data out. No filesystem walking, no exec.
  * Use loadRuntimeCapabilities(projectDir) for the cwd-rooted variant.
+ *
+ * v0.8.6 — `loadRuntimeCapabilities` now ALSO walks `apps/*` by default
+ * (configurable via the second arg `{monorepo_globs}`) and OR-merges
+ * each match's `package.json` capabilities with the root. The default
+ * `['apps/*']` matches the canonical Aperant monorepo layout; adopters
+ * whose monorepo lives elsewhere (e.g. `packages/apps/*`) pass a
+ * custom `monorepo_globs`. Setting `monorepo_globs: []` disables the
+ * walk entirely (root-only escape hatch).
  */
 
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 
 /**
@@ -103,20 +111,101 @@ export function detectFromPackageJson(packageJson) {
 
 /**
  * Load and detect capabilities from a project directory's package.json.
- * Returns empty capabilities if no package.json exists (malformed or
- * missing — both cases fall through to "nothing detected").
+ * v0.8.6 — also walks `monorepo_globs` (default `['apps/*']`) and
+ * OR-merges each match's capabilities with the root.
  *
  * @param {string} projectDir
+ * @param {{monorepo_globs?: string[]}} [opts]
  * @returns {RuntimeCapabilities}
  */
-export function loadRuntimeCapabilities(projectDir) {
-	const pkgPath = join(resolve(projectDir), 'package.json')
-	if (!existsSync(pkgPath)) return emptyCapabilities()
-	let parsed
+export function loadRuntimeCapabilities(projectDir, opts) {
+	const root = resolve(projectDir)
+	const rootPkgPath = join(root, 'package.json')
+	let rootCaps = emptyCapabilities()
+	if (existsSync(rootPkgPath)) {
+		try {
+			rootCaps = detectFromPackageJson(JSON.parse(readFileSync(rootPkgPath, 'utf-8')))
+		} catch {
+			/* fall through with empty caps */
+		}
+	}
+
+	// Default to the canonical Aperant monorepo layout. Passing `[]`
+	// disables the walk entirely (root-only escape hatch per spec ID-05).
+	const globs = opts && Array.isArray(opts.monorepo_globs) ? opts.monorepo_globs : ['apps/*']
+	if (globs.length === 0) return rootCaps
+
+	let merged = rootCaps
+	for (const glob of globs) {
+		const matches = expandSimpleGlob(root, glob)
+		for (const dir of matches) {
+			const childPkgPath = join(dir, 'package.json')
+			if (!existsSync(childPkgPath)) continue
+			try {
+				const childCaps = detectFromPackageJson(JSON.parse(readFileSync(childPkgPath, 'utf-8')))
+				merged = orMergeCapabilities(merged, childCaps)
+			} catch {
+				/* skip malformed package.json */
+			}
+		}
+	}
+	return merged
+}
+
+/**
+ * Expand a simple `prefix/*` glob against the root. Supports ONLY the
+ * `<dir>/*` shape (matches each direct subdirectory of `<dir>`). Other
+ * glob syntax is intentionally rejected — v1 keeps the dep surface
+ * small. Fails closed on malformed patterns (returns []).
+ *
+ * @param {string} root
+ * @param {string} glob
+ * @returns {string[]}
+ */
+function expandSimpleGlob(root, glob) {
+	if (typeof glob !== 'string' || !glob.endsWith('/*')) return []
+	const prefix = glob.slice(0, -2)
+	if (prefix.length === 0 || prefix.includes('*')) return []
+	const dir = join(root, prefix)
+	if (!existsSync(dir)) return []
+	let entries
 	try {
-		parsed = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+		entries = readdirSync(dir)
 	} catch {
-		return emptyCapabilities()
+		return []
+	}
+	const matches = []
+	for (const name of entries) {
+		const sub = join(dir, name)
+		try {
+			if (statSync(sub).isDirectory()) matches.push(sub)
+		} catch {
+			/* skip unreadable entries */
+		}
+	}
+	return matches
+}
+
+/**
+ * Boolean OR-merge of two capability records. Any flag true in either
+ * input is true in the output. The "Electron wins over web" rule from
+ * `detectFromPackageJson` is preserved when this is called repeatedly —
+ * each child's flags are honest about that child's own shape, and the
+ * OR-merge just unions them.
+ *
+ * @param {RuntimeCapabilities} a
+ * @param {RuntimeCapabilities} b
+ * @returns {RuntimeCapabilities}
+ */
+function orMergeCapabilities(a, b) {
+	return {
+		is_electron: a.is_electron || b.is_electron,
+		is_tauri: a.is_tauri || b.is_tauri,
+		is_nextjs: a.is_nextjs || b.is_nextjs,
+		is_nuxt: a.is_nuxt || b.is_nuxt,
+		is_web_frontend: a.is_web_frontend || b.is_web_frontend,
+		is_expo: a.is_expo || b.is_expo,
+		is_react_native: a.is_react_native || b.is_react_native,
+		has_node: a.has_node || b.has_node,
 	}
-	return detectFromPackageJson(parsed)
 }

package/src/cli/verify-proof/trust.mjs

@@ -23,7 +23,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 
 /**
- * @typedef {import('@aperant/driver-sdk').DriverManifest} DriverManifest
+ * @typedef {import('@aperant/framework/driver-sdk').DriverManifest} DriverManifest
  */
 
 const TOFU_PATH = '.aperant/driver-tofu.json'

package/templates/proof-verification.md

@@ -53,7 +53,13 @@ JSON schema reference for `.aperant/proof/{app}/{date}/{run}/verification.json`
     "tested_count": 0,
     "skipped_count": 0,
     "percent": 0,
-    "gate_result": "pass | warn | block"
+    "gate_result": "pass | warn | block",
+    "by_surface": {
+      "electron": { "tested": 0, "total": 0 },
+      "web": { "tested": 0, "total": 0 },
+      "cli": { "tested": 0, "total": 0 },
+      "api": { "tested": 0, "total": 0 }
+    }
   },
 
   "tests": [
@@ -61,14 +67,33 @@ JSON schema reference for `.aperant/proof/{app}/{date}/{run}/verification.json`
       "id": "TEST-01",
       "registry_id": "terminals-grid-auto-tile",
       "name": "Three Terminal Grid Auto-Tile",
+      "outcome_id": "O3",
+      "surface": "electron",
+      "transport": "mcp",
       "precondition": "2 terminals active",
       "action": "Press Cmd+T",
       "expected": "Grid reflows to 2+1 layout",
       "actual": "Grid correctly tiled to 2+1",
-      "evidence": "screenshots/03-grid.png",
+      "evidence": "electron/screenshots/03-grid.png",
       "analysis": "Screenshot shows three terminal panes. Top row has 2 equal-width panes, bottom row has 1 centered pane. Grid lines are clean, no overlap or gap artifacts. Each pane shows an active shell prompt with correct path.",
       "result": "pass | fail | blocked | skip",
       "severity": null
+    },
+    {
+      "id": "TEST-02",
+      "registry_id": "settings-theme-picker",
+      "name": "Theme picker — cross-surface",
+      "outcome_id": "O5",
+      "surface": "web",
+      "transport": "skill",
+      "precondition": "App loaded in web shell",
+      "action": "Click 'Dark mode' in the theme picker",
+      "expected": "Background flips to dark; persists across reload",
+      "actual": "Dark mode applied, persisted across reload",
+      "evidence": "web/screenshots/05-dark-mode.png",
+      "analysis": "Screenshot shows app body with #111 background, all text legible on dark surface. After reload, dark mode is still active — localStorage entry confirmed.",
+      "result": "pass",
+      "severity": null
     }
   ],
 
@@ -175,6 +200,7 @@ Each check has `status` (pass/fail) and `output` (captured terminal output). The
 | `skipped_count` | number | Number of entries in the skipped array |
 | `percent` | number | `tested_count / registered_count * 100` |
 | `gate_result` | string | `block` if < 50%, `warn` if < 80%, `pass` if >= 80% |
+| `by_surface` | object | v0.8.6 — per-surface rollup. Each surface key (`electron`, `web`, `cli`, `api`) maps to `{tested, total}` so reviewers can tell which surface fell short. |
 
 ### tests
 Each test entry tracks one sub-feature verification. Fields:
@@ -184,11 +210,14 @@ Each test entry tracks one sub-feature verification. Fields:
 | `id` | string | IMMUTABLE | Sequential ID: TEST-01, TEST-02, etc. |
 | `registry_id` | string | IMMUTABLE | Must match a sub-feature `id` from `.aperant/features/{area}.json` |
 | `name` | string | IMMUTABLE | Human-readable test name |
+| `outcome_id` | string | IMMUTABLE | v0.8.6 — positional ID from `## User Outcomes` (e.g. `O1`, `O2`). Synthesized by `parseUserOutcomes`; passed through verbatim by `resolveDriversForOutcomes`. Optional for legacy specs without `## User Outcomes`. |
+| `surface` | string | IMMUTABLE | v0.8.6 — one of `electron | web | cli | api`. Drives the per-surface screenshot path and the `coverage.by_surface` rollup. Cross-surface outcomes (`[electron+web]`) produce TWO test entries with the same `outcome_id` and different `surface` values. |
+| `transport` | string | OVERWRITE | v0.8.6 — `skill | mcp | binary | http`. Populated by the workflow runner from the dispatcher's directive (per Step 7a of `workflows/verify-proof.md`). For browser-driver web outcomes on Skill-capable hosts the value is `"skill"`; on legacy MCP hosts it falls back to `"mcp"`. |
 | `precondition` | string | IMMUTABLE | What must be true before testing |
 | `action` | string | IMMUTABLE | Specific action to perform |
 | `expected` | string | IMMUTABLE | Specific observable result expected |
 | `actual` | string | OVERWRITE | What actually happened (filled after testing) |
-| `evidence` | string | OVERWRITE | Screenshot filename or video timestamp |
+| `evidence` | string | OVERWRITE | Screenshot filename or video timestamp. v0.8.6 — paths are PER-SURFACE: `{surface}/screenshots/{outcome-id}.png`. |
 | `analysis` | string | OVERWRITE | Adversarial analysis of evidence — describe what you SEE, not what you expect |
 | `result` | string | OVERWRITE | `pass`, `fail`, `blocked`, or `skip` |
 | `severity` | string/null | OVERWRITE | `blocker`, `major`, `minor`, `cosmetic`, or `null` if pass |

package/workflows/verify-proof.md

@@ -43,13 +43,25 @@ cat implementation_plan.json 2>/dev/null
 cat testable_features.json 2>/dev/null
 ```
 
-Generate run ID and create proof directory:
+Generate run ID and create proof directory. v0.8.6 — when the spec
+carries `## User Outcomes` with cross-surface tags (e.g.
+`[electron+web]`), proof artifacts MUST land under PER-SURFACE
+subdirectories so reviewers can tell at a glance which surface failed.
+Set up the path template here:
+
 ```bash
 RUN_ID="$(date +%H%M%S)"
 APP_NAME=$(node -e "try{console.log(JSON.parse(require('fs').readFileSync('package.json','utf8')).name)}catch{console.log('app')}" 2>/dev/null)
 PROOF_DIR=".aperant/proof/${APP_NAME}/$(date +%Y%m%d)/${RUN_ID}"
-mkdir -p "${PROOF_DIR}/screenshots"
+# Per-surface screenshot path template — Step 7c populates ${surface}
+# from the per-outcome resolver dispatch:
+#   ${PROOF_DIR}/${surface}/screenshots/${outcome-id}.png
+mkdir -p "${PROOF_DIR}"
 ```
+
+Sub-directories under `${PROOF_DIR}/${surface}/screenshots/` are
+created lazily in Step 7c when the workflow runner takes the first
+screenshot for that surface.
 </step>
 
 <step name="pre_check">
@@ -83,6 +95,18 @@ If no driver satisfies a REQUIRED capability, the resolver throws
 `unsatisfied_required_capability` — fail-closed, NOT a silent
 `blocked_by_platform` skip (per ID-02).
 
+**v0.8.6 — per-outcome dispatch.** When the spec carries
+`## User Outcomes`, the workflow runner picks a driver PER OUTCOME
+SURFACE via `resolveDriversForOutcomes()` instead of a single
+per-run driver pick. Each outcome's `[surface]` tag maps to the
+runtime-capability flag a driver must carry; `[electron+web]`
+outcomes dispatch to TWO drivers (one per surface) sharing the same
+`outcome_id`. The legacy `apt-tools detect-runtime .` call above
+still works for the per-run "what driver would be picked?" preview
+— it answers the OLD question. For the new per-outcome question,
+the workflow runner imports `resolveDriversForOutcomes` directly
+from the resolver module in Step 7c.
+
 ### 2b. Probe optional evidence-capture tools
 
 ```bash
@@ -142,6 +166,16 @@ If no feature registry exists:
 - Suggest: "No feature registry found. Consider running `/apt:scan {area}` first for exhaustive coverage."
 - Proceed with manual discovery below, but warn that coverage may be incomplete
 
+**v0.8.6 — read `## User Outcomes` from spec.md FIRST when present.**
+The PRD-shaped spec.md (STANDARD/DEEP tracks) ships a
+`## User Outcomes` section that is the verify-proof input contract:
+`**Epic:**` headline + N atomic outcomes tagged by `[surface]`. When
+present, each outcome maps 1:1 to a test entry — the workflow runner
+does NOT have to invent test units from the feature registry. Fall
+back to the feature-registry-based discovery below ONLY when the spec
+lacks `## User Outcomes` (the v0.8.x warn-not-block migration window
+per spec ID-06; the section becomes a hard block in v0.9.0).
+
 ### 4b. Read the source code
 
 You MUST read the actual source code for the features under test. Do not guess.
@@ -278,19 +312,49 @@ a local binary, or a built-in HTTP request). Workflow prose names ONLY
 IDL verbs per ID-01 — concrete tool names live in
 `packages/framework/drivers/<driver>/driver.mjs`.
 
+**v0.8.6 — transport dispatch directive (MUST honor).** When
+`driver.transport.skill_id` is set AND the host CLI exposes the
+Skill tool AND the outcome surface is `web`, the workflow runner
+MUST invoke `Skill({skill: driver.transport.skill_id, args: ...})`
+(passing the IDL verb args) and MUST record `transport: "skill"` on
+the resulting test entry in verification.json. When the host CLI
+does NOT expose the Skill tool, fall back to the MCP transport via
+the existing puppeteer MCP server and record `transport: "mcp"`.
+The driver's `chooseTransport({has_skill_tool})` helper computes
+the choice; the workflow runner is the site that knows
+`has_skill_tool`. This directive is LLM-honored (the v1 verify-proof
+runner is the host LLM following this workflow as prose); a
+text-level grep guard (TD-08) pins the `MUST` language so future
+edits cannot silently soften it to `SHOULD`.
+
 ### 7b. Wait for Result
 Wait for the action to complete. If it involves loading, wait for the load.
 Add a short delay (1-2 seconds) so the CDP capture also captures this state.
 
 ### 7c. Capture Evidence
-Take a screenshot AFTER the action completes:
+Take a screenshot AFTER the action completes. v0.8.6 — screenshots
+land under PER-SURFACE subdirectories, with the per-outcome driver
+returned by `resolveDriversForOutcomes()`:
+
 ```
-driver.screenshot({
-  target: { kind: "css", value: "body" },
-  output_path: "${PROOF_DIR}/screenshots/{feature-id}-test-{n}.png"
-})
+// Pick a driver per outcome surface (NOT per run). `entries[]` is
+// the resolver's per-(outcome, surface) dispatch — for an
+// [electron+web] outcome you get TWO entries sharing outcome_id
+// and you loop both, capturing one screenshot per surface.
+for (const entry of entries) {
+  await entry.driver.screenshot({
+    target: { kind: "css", value: "body" },
+    output_path: `${PROOF_DIR}/${entry.surface}/screenshots/${outcome.id}.png`
+  })
+}
 ```
 
+Single-surface outcomes (`[electron]`, `[web]`, `[cli]`, `[api]`)
+produce one screenshot under `${PROOF_DIR}/${surface}/screenshots/`;
+cross-surface (`[electron+web]`) produces two — one per surface tree
+— with both test entries in `verification.json:tests[]` carrying the
+same `id` but distinct `surface` and `evidence` fields.
+
 ### 7d. Analyze Evidence
 **MANDATORY and CRITICAL.** Every screenshot must be analyzed in detail.
 
@@ -313,18 +377,23 @@ apt-proof-video analyze "${PROOF_DIR}/screenshots/{feature-id}-test-{n}.png" \
 ```
 
 ### 7e. Record Result to verification.json
-After each test, update the test entry in verification.json `tests` array:
+After each test, update the test entry in verification.json `tests` array.
+v0.8.6 adds `surface` and `transport` fields per test entry — the workflow
+runner populates them from the per-outcome dispatch directive:
 
 ```json
 {
   "id": "TEST-01",
   "registry_id": "terminals-grid-auto-tile",
   "name": "Three Terminal Grid Auto-Tile",
+  "outcome_id": "O3",
+  "surface": "electron",
+  "transport": "mcp",
   "precondition": "2 terminals active",
   "action": "Press Cmd+T",
   "expected": "Grid reflows to 2+1 layout",
   "actual": "Grid correctly tiled",
-  "evidence": "screenshots/03-grid.png",
+  "evidence": "electron/screenshots/03-grid.png",
   "analysis": "Detailed adversarial analysis of what is actually visible in the screenshot...",
   "result": "pass",
   "severity": null