@aperant/framework 0.11.0 → 0.12.1

package/src/cli/gate/gates/verify-approved.mjs

@@ -4,10 +4,14 @@
  *
  * Requires {task_dir}/qa_signoff.json to exist, parse, and carry
  * verdict === "approved" (BUG-013: normalized via parseQaSignoff — case
- * and underscore/hyphen variants collapse to canonical). BUG-012: also
- * accepts `approved-with-notes` when config.qa.approved_with_notes_threshold
- * is set AND every dimension score meets the threshold (best-effort when
- * dimensions are missing or in an unknown shape).
+ * and underscore/hyphen variants collapse to canonical).
+ *
+ * v0.9.0 (verify-proof-v2-outcome-walker_27-05-26) — the legacy
+ * `approved-with-notes` acceptance branch is REMOVED. `verify-approved`
+ * only accepts a verdict of exactly `approved`. Tasks whose verify-proof
+ * run returned `needs_human` MUST re-run verify-proof with the missing
+ * transport installed; tasks whose run returned `rejected` MUST fix the
+ * code. There is no middle band.
  *
  * Accepts both `verdict` (newer) and `status` (older) field names — that
  * normalization is delegated to parseQaSignoff.
@@ -18,39 +22,9 @@ import { join } from 'node:path'
 import { parseQaSignoff } from '../../consistency/parse-qa.mjs'
 import { registerGate } from '../registry.mjs'
 
-/**
- * Extract dimension scores from the qa_signoff.json shape. We've seen two
- * shapes in the wild:
- *   - Array: `dimensions: [{name: 'security', score: 0.9}, ...]`
- *   - Object: `dimensions: {security: 0.9, performance: 0.85}` OR
- *     `dimensions: {security: {score: 0.9}, ...}`
- * Returns an array of numeric scores, or null when no recognizable shape
- * is present (best-effort accept per brief).
- */
-function extractDimensionScores(doc) {
-	const dims = doc.dimensions ?? doc.qa?.dimensions ?? null
-	if (!dims) return null
-	if (Array.isArray(dims)) {
-		const scores = dims
-			.map((d) => (typeof d?.score === 'number' ? d.score : null))
-			.filter((s) => s !== null)
-		return scores.length > 0 ? scores : null
-	}
-	if (typeof dims === 'object') {
-		const scores = []
-		for (const v of Object.values(dims)) {
-			if (typeof v === 'number') scores.push(v)
-			else if (typeof v?.score === 'number') scores.push(v.score)
-		}
-		return scores.length > 0 ? scores : null
-	}
-	return null
-}
-
 const gate = {
 	id: 'verify-approved',
-	description:
-		'qa_signoff.json exists with verdict === "approved" (or "approved-with-notes" when configured)',
+	description: 'qa_signoff.json exists with verdict === "approved" (v0.9.0+ two-gate verdict)',
 	severity: 'blocking',
 	skills: ['ship'],
 	applies_to_profile: (ctx) => ctx.profile === 'full-pipeline',
@@ -77,65 +51,32 @@ const gate = {
 
 		// BUG-013: route through parseQaSignoff so the verdict is
 		// case-insensitive AND tolerates `_↔-` (so 'APPROVED', 'Approved',
-		// ' approved ', 'APPROVED_WITH_NOTES' all behave canonically). The
-		// pre-fix gate compared the raw string against `'approved'` which
-		// false-rejected every legitimate variant.
-		const { verdict } = parseQaSignoff(doc)
-
-		if (verdict === 'approved') {
+		// ' approved ', 'APPROVED_WITH_NOTES' all behave canonically).
+		// v0.9.0: parseQaSignoff THROWS on legacy approved_with_notes —
+		// surface that as a gate fail with the migration message verbatim.
+		let parsed
+		try {
+			parsed = parseQaSignoff(doc)
+		} catch (err) {
 			return {
-				status: 'pass',
-				reason: 'qa_signoff.json verdict normalized to "approved"',
+				status: 'fail',
+				reason: `qa_signoff.json carries a legacy verdict that requires migration: ${err.message}`,
 				inputs,
 			}
 		}
+		const { verdict } = parsed
 
-		// BUG-012: accept `approved-with-notes` when the project has opted
-		// in via config.qa.approved_with_notes_threshold. The threshold is
-		// the minimum per-dimension score required. Best-effort: when
-		// dimensions are missing / in an unknown shape we still accept and
-		// log, rather than hard-failing, so projects that haven't started
-		// scoring dimensions yet aren't blocked.
-		if (verdict === 'approved-with-notes') {
-			const threshold = ctx.config?.qa?.approved_with_notes_threshold
-			if (typeof threshold !== 'number') {
-				return {
-					status: 'fail',
-					reason:
-						'qa_signoff.json verdict is "approved-with-notes" but config.qa.approved_with_notes_threshold is not set',
-					evidence: { verdict, threshold: threshold ?? null },
-					inputs,
-				}
-			}
-			const scores = extractDimensionScores(doc)
-			if (scores === null) {
-				return {
-					status: 'pass',
-					reason: `qa_signoff.json verdict is "approved-with-notes" and threshold ${threshold} is enabled; dimensions missing or unknown-shape — accepting best-effort`,
-					evidence: { verdict, threshold, dimensions_present: false },
-					inputs,
-				}
-			}
-			const failing = scores.filter((s) => s < threshold)
-			if (failing.length > 0) {
-				return {
-					status: 'fail',
-					reason: `qa_signoff.json verdict is "approved-with-notes" but ${failing.length}/${scores.length} dimension score(s) below threshold ${threshold}`,
-					evidence: { verdict, threshold, scores, failing },
-					inputs,
-				}
-			}
+		if (verdict === 'approved') {
 			return {
 				status: 'pass',
-				reason: `qa_signoff.json verdict is "approved-with-notes" and all ${scores.length} dimension score(s) meet threshold ${threshold}`,
-				evidence: { verdict, threshold, scores },
+				reason: 'qa_signoff.json verdict normalized to "approved"',
 				inputs,
 			}
 		}
 
 		return {
 			status: 'fail',
-			reason: `qa_signoff.json verdict is "${verdict}" (expected "approved" or "approved-with-notes" with threshold)`,
+			reason: `qa_signoff.json verdict is "${verdict}" (expected "approved"; v0.9.0 enum is {approved, rejected, needs_human})`,
 			evidence: { verdict },
 			inputs,
 		}

package/src/cli/install/mcp-server-specs.mjs

@@ -61,6 +61,17 @@ export const PROVISION_SPECS = {
 		args: ['./scripts/tauri-mcp.sh'],
 		requiresLauncherScript: true,
 	},
+	'mobile-mcp': {
+		kind: 'mcp-server',
+		// Unified iOS + Android UI-driving server (Apache-2.0). Pure npm —
+		// the iOS/Android SYSTEM prereqs (idb-companion / adb / Xcode /
+		// Android SDK) are validated by the mobile driver's preflight, NOT
+		// installed here (decision D-09). Matches the driver manifest's
+		// transport.mcp_server_id = "mobile-mcp".
+		command: 'npx',
+		args: ['-y', '@mobilenext/mobile-mcp@latest'],
+		env: {},
+	},
 	// kind 'skill'
 	'agent-browser': {
 		kind: 'skill',
@@ -79,14 +90,15 @@ export const PROVISION_SPECS = {
  * triggers. A multi-surface monorepo (e.g. electron + nextjs) returns
  * multiple ids.
  *
- *   is_electron                          → ['electron']
- *   is_tauri                             → ['tauri']
- *   is_web_frontend|is_nextjs|is_nuxt    → ['agent-browser']
+ *   is_electron                                       → ['electron']
+ *   is_tauri                                          → ['tauri']
+ *   is_web_frontend|is_nextjs|is_nuxt                 → ['agent-browser']
+ *   is_ios_native|is_android_native|is_expo|is_react_native → ['mobile-mcp']
  *
  * Accepts a partial capability record — only the flags it reads need be
  * present (the rest default to absent/false).
  *
- * @param {Partial<import('../util/runtime-capabilities.mjs').RuntimeCapabilities>} runtimeCaps
+ * @param {Partial<import('../util/runtime-capabilities.mjs').RuntimeCapabilities> | null | undefined} runtimeCaps
  * @returns {string[]}
  */
 export function capabilityToProvisionIds(runtimeCaps) {
@@ -97,5 +109,13 @@ export function capabilityToProvisionIds(runtimeCaps) {
 	if (runtimeCaps.is_web_frontend || runtimeCaps.is_nextjs || runtimeCaps.is_nuxt) {
 		ids.push('agent-browser')
 	}
+	if (
+		runtimeCaps.is_ios_native ||
+		runtimeCaps.is_android_native ||
+		runtimeCaps.is_expo ||
+		runtimeCaps.is_react_native
+	) {
+		ids.push('mobile-mcp')
+	}
 	return ids
 }

package/src/cli/roadmap/backend-adapter.mjs

@@ -0,0 +1,231 @@
+/**
+ * Task 26-05-26 subtask 2.4 — roadmap.backend dispatch adapter.
+ *
+ * Reads `.aperant/config.json :: roadmap.backend` and either delegates
+ * the subcommand to the Aperant Cloud MCP server (`'cloud-mcp'`) or
+ * returns a `{ delegated: false }` envelope so the calling subcommand
+ * proceeds with the existing markdown-canonical file-write path.
+ *
+ * Fast Path Guarantee: a missing `roadmap` block, a missing
+ * `roadmap.backend` key, or `backend: 'markdown'` ALL return
+ * `{ backend: 'markdown', delegated: false }` byte-identically — OSS
+ * framework users with zero cloud config see no behaviour change.
+ *
+ * Token resolution mirrors convex-mirror.mjs (token-source order ID-07):
+ *   1. process.env.MCP_ROADMAP_TOKEN
+ *   2. .aperant/team.json :: roadmapMcpToken
+ *
+ * Tool registration on the server side lands in subtask 2.3
+ * (apps/web/src/app/api/mcp/_lib/tools.ts). Until 2.3 ships, the
+ * adapter will issue the MCP call against whatever endpoint the user
+ * configured; a 404 / "unknown tool" response surfaces as a delegated
+ * error envelope rather than silently falling back to markdown.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Load `.aperant/config.json` defensively. Returns `{}` for any read
+ * or parse failure so callers never throw — the Fast Path branch must
+ * hit even when the config file is missing or malformed.
+ *
+ * @param {string} projectDir
+ * @returns {Record<string, unknown>}
+ */
+function loadConfig(projectDir) {
+	const p = join(projectDir, '.aperant', 'config.json')
+	if (!existsSync(p)) return {}
+	try {
+		const parsed = JSON.parse(readFileSync(p, 'utf-8'))
+		return parsed && typeof parsed === 'object' ? parsed : {}
+	} catch {
+		return {}
+	}
+}
+
+/**
+ * Resolve the cloud-mcp bearer token via the documented order. Returns
+ * `null` when neither source has a non-empty string.
+ *
+ * @param {string} projectDir
+ * @returns {string | null}
+ */
+function resolveToken(projectDir) {
+	const env = process.env.MCP_ROADMAP_TOKEN
+	if (typeof env === 'string' && env.length > 0) return env
+	const teamPath = join(projectDir, '.aperant', 'team.json')
+	if (!existsSync(teamPath)) return null
+	try {
+		const parsed = JSON.parse(readFileSync(teamPath, 'utf-8'))
+		if (typeof parsed.roadmapMcpToken === 'string' && parsed.roadmapMcpToken.length > 0) {
+			return parsed.roadmapMcpToken
+		}
+	} catch {
+		// Bad JSON — fall through to null
+	}
+	return null
+}
+
+/**
+ * Map a CLI subcommand to the MCP tool name registered in subtask 2.3.
+ * Read-side subcommands are intentionally absent — Phase 2 keeps reads
+ * markdown-only (cloud-mcp render is a Phase 3 follow-up per the plan).
+ *
+ * @param {string} subcommand
+ * @returns {string | null}
+ */
+function toolNameFor(subcommand) {
+	switch (subcommand) {
+		case 'add-milestone':
+			return 'roadmap.hierarchy.milestones.create'
+		case 'add-phase':
+			return 'roadmap.hierarchy.phases.create'
+		case 'set-phase-status':
+			return 'roadmap.hierarchy.phases.update'
+		case 'delete-phase':
+			return 'roadmap.hierarchy.phases.remove'
+		case 'delete-milestone':
+			return 'roadmap.hierarchy.milestones.remove'
+		default:
+			return null
+	}
+}
+
+/**
+ * Dispatch a roadmap write subcommand through the configured backend.
+ *
+ * Return shapes:
+ *   - markdown (default) → `{ backend: 'markdown', delegated: false }`
+ *     The caller proceeds with the existing markdown file-write path.
+ *   - cloud-mcp success  → `{ backend: 'cloud-mcp', delegated: true,
+ *                             result: <MCP response JSON> }`
+ *   - cloud-mcp error    → `{ backend: 'cloud-mcp', delegated: true,
+ *                             error: '<msg>', code?: <http>, status: 'error' }`
+ *
+ * The `error` branch is still `delegated: true` because the caller MUST
+ * NOT silently fall through to the markdown path when the user has
+ * opted into cloud-mcp — that would lose writes the user expected to
+ * land in Convex.
+ *
+ * @param {string} projectDir
+ * @param {string} subcommand
+ * @param {Record<string, unknown>} args
+ * @param {{ fetchImpl?: typeof fetch }} [opts]
+ * @returns {Promise<
+ *   | { backend: 'markdown', delegated: false }
+ *   | { backend: 'cloud-mcp', delegated: true, result: unknown }
+ *   | { backend: 'cloud-mcp', delegated: true, status: 'error', error: string, code?: number }
+ * >}
+ */
+export async function dispatchRoadmapWrite(projectDir, subcommand, args, opts = {}) {
+	const config = loadConfig(projectDir)
+	const roadmapBlock = config.roadmap && typeof config.roadmap === 'object' ? config.roadmap : null
+	const backend =
+		roadmapBlock && typeof roadmapBlock.backend === 'string' ? roadmapBlock.backend : 'markdown'
+
+	if (backend !== 'cloud-mcp') {
+		return { backend: 'markdown', delegated: false }
+	}
+
+	const cloudMcp =
+		roadmapBlock && typeof roadmapBlock.cloudMcp === 'object' && roadmapBlock.cloudMcp !== null
+			? roadmapBlock.cloudMcp
+			: {}
+	const teamSlug = typeof cloudMcp.teamSlug === 'string' ? cloudMcp.teamSlug : null
+	if (!teamSlug || teamSlug.length === 0) {
+		return {
+			backend: 'cloud-mcp',
+			delegated: true,
+			status: 'error',
+			error: 'roadmap.cloudMcp.teamSlug required when roadmap.backend=cloud-mcp',
+		}
+	}
+
+	const tool = toolNameFor(subcommand)
+	if (!tool) {
+		return {
+			backend: 'cloud-mcp',
+			delegated: true,
+			status: 'error',
+			error: `cloud-mcp backend does not handle subcommand "${subcommand}" (read-side stays markdown in Phase 2)`,
+		}
+	}
+
+	const token = resolveToken(projectDir)
+	if (!token) {
+		return {
+			backend: 'cloud-mcp',
+			delegated: true,
+			status: 'error',
+			error: 'No roadmap MCP token (set MCP_ROADMAP_TOKEN or .aperant/team.json::roadmapMcpToken)',
+		}
+	}
+
+	const baseUrl = (
+		typeof cloudMcp.mcpServerUrl === 'string' && cloudMcp.mcpServerUrl.length > 0
+			? cloudMcp.mcpServerUrl
+			: process.env.APERANT_BASE_URL || 'https://app.aperant.com'
+	).replace(/\/$/, '')
+	const url = `${baseUrl}/api/mcp/${encodeURIComponent(teamSlug)}`
+
+	// Streamable HTTP MCP body — tools/call envelope per the existing
+	// server-factory contract. The wire format mirrors what the
+	// MCP SDK clients send; the Aperant route handler dispatches on
+	// `params.name` to the matching tool registered in subtask 2.3.
+	const body = {
+		jsonrpc: '2.0',
+		id: 1,
+		method: 'tools/call',
+		params: {
+			name: tool,
+			arguments: args,
+		},
+	}
+
+	const f = opts.fetchImpl ?? fetch
+	let res
+	try {
+		res = await f(url, {
+			method: 'POST',
+			headers: {
+				Authorization: `Bearer ${token}`,
+				'Content-Type': 'application/json',
+				Accept: 'application/json, text/event-stream',
+			},
+			body: JSON.stringify(body),
+		})
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e)
+		return {
+			backend: 'cloud-mcp',
+			delegated: true,
+			status: 'error',
+			error: `network: ${msg}`,
+		}
+	}
+
+	if (res.status >= 400) {
+		let detail = ''
+		try {
+			detail = await res.text()
+		} catch {
+			// ignore body-read failures
+		}
+		return {
+			backend: 'cloud-mcp',
+			delegated: true,
+			status: 'error',
+			code: res.status,
+			error: detail || `http ${res.status}`,
+		}
+	}
+
+	let parsed
+	try {
+		parsed = await res.json()
+	} catch {
+		parsed = null
+	}
+	return { backend: 'cloud-mcp', delegated: true, result: parsed }
+}

package/src/cli/util/runtime-capabilities.mjs

@@ -21,6 +21,14 @@
  * whose monorepo lives elsewhere (e.g. `packages/apps/*`) pass a
  * custom `monorepo_globs`. Setting `monorepo_globs: []` disables the
  * walk entirely (root-only escape hatch).
+ *
+ * Mobile verify-proof surface — `loadRuntimeCapabilities` ALSO detects
+ * pure-native iOS/Android projects (Swift `*.xcodeproj` / Kotlin
+ * `build.gradle`) that carry no JS deps, via a shallow fs check on the
+ * root + each monorepo dir (`detectNativeProject`). The pure
+ * `detectFromPackageJson` is intentionally NOT given fs access — native
+ * detection lives ONLY in the fs-walking `loadRuntimeCapabilities` so the
+ * pure-function contract holds (decision D-06).
  */
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
@@ -35,6 +43,10 @@ import { join, resolve } from 'node:path'
  * @property {boolean} is_web_frontend
  * @property {boolean} is_expo
  * @property {boolean} is_react_native
+ * @property {boolean} [is_ios_native]   — optional: always populated by the
+ *   detector, but optional in the type so partial capability records built by
+ *   other consumers (and pre-existing test fixtures) stay valid.
+ * @property {boolean} [is_android_native]
  * @property {boolean} has_node
  */
 
@@ -48,6 +60,8 @@ function emptyCapabilities() {
 		is_web_frontend: false,
 		is_expo: false,
 		is_react_native: false,
+		is_ios_native: false,
+		is_android_native: false,
 		has_node: false,
 	}
 }
@@ -134,6 +148,8 @@ export function loadRuntimeCapabilities(projectDir, opts) {
 			/* fall through with empty caps */
 		}
 	}
+	// Fold in pure-native detection on the root (covers a JS-less iOS/Android app).
+	rootCaps = orMergeCapabilities(rootCaps, detectNativeProject(root))
 
 	// Default to the canonical Aperant monorepo layout. Passing `[]`
 	// disables the walk entirely (root-only escape hatch per spec ID-05).
@@ -144,6 +160,9 @@ export function loadRuntimeCapabilities(projectDir, opts) {
 	for (const glob of globs) {
 		const matches = expandSimpleGlob(root, glob)
 		for (const dir of matches) {
+			// Native detection runs regardless of package.json — a pure-native
+			// iOS/Android app in apps/* may carry no package.json at all.
+			merged = orMergeCapabilities(merged, detectNativeProject(dir))
 			const childPkgPath = join(dir, 'package.json')
 			if (!existsSync(childPkgPath)) continue
 			try {
@@ -211,6 +230,54 @@ function orMergeCapabilities(a, b) {
 		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,
+		is_ios_native: a.is_ios_native || b.is_ios_native,
+		is_android_native: a.is_android_native || b.is_android_native,
 		has_node: a.has_node || b.has_node,
 	}
 }
+
+/**
+ * Shallow fs detection of a pure-native mobile project — a Swift/ObjC iOS
+ * app (`*.xcodeproj` / `*.xcworkspace`) or a Kotlin/Java Android app
+ * (`build.gradle[.kts]` / `settings.gradle[.kts]`). Checks `dir` itself and
+ * the conventional `ios/` + `android/` subdirs (the React Native / Expo
+ * prebuild layout). Returns a full capability record so it OR-merges with
+ * the package.json-derived caps.
+ *
+ * This is the ONLY fs-touching detection — `detectFromPackageJson` stays
+ * pure (D-06). Fails closed (treats unreadable dirs as absent).
+ *
+ * @param {string} dir
+ * @returns {RuntimeCapabilities}
+ */
+function detectNativeProject(dir) {
+	const caps = emptyCapabilities()
+	if (dirHasXcodeProject(dir) || dirHasXcodeProject(join(dir, 'ios'))) {
+		caps.is_ios_native = true
+	}
+	if (dirHasGradle(dir) || dirHasGradle(join(dir, 'android'))) {
+		caps.is_android_native = true
+	}
+	return caps
+}
+
+/** True when `dir` directly contains a `*.xcodeproj` or `*.xcworkspace`. */
+function dirHasXcodeProject(dir) {
+	if (!existsSync(dir)) return false
+	try {
+		return readdirSync(dir).some((n) => n.endsWith('.xcodeproj') || n.endsWith('.xcworkspace'))
+	} catch {
+		return false
+	}
+}
+
+/** True when `dir` directly contains a Gradle build/settings file. */
+function dirHasGradle(dir) {
+	if (!existsSync(dir)) return false
+	return (
+		existsSync(join(dir, 'build.gradle')) ||
+		existsSync(join(dir, 'build.gradle.kts')) ||
+		existsSync(join(dir, 'settings.gradle')) ||
+		existsSync(join(dir, 'settings.gradle.kts'))
+	)
+}

package/src/cli/verify-proof/manifest-validator.mjs

@@ -172,6 +172,21 @@ function validateNode(value, schema, path, errors) {
 				}
 			}
 		}
+		// additionalProperties: false — reject any key not declared in `properties`.
+		if (
+			schema.additionalProperties === false &&
+			schema.properties &&
+			typeof schema.properties === 'object'
+		) {
+			for (const key of Object.keys(obj)) {
+				if (!(key in schema.properties)) {
+					errors.push({
+						path: `${path}/${key}`,
+						message: `additional property "${key}" is not allowed`,
+					})
+				}
+			}
+		}
 	}
 
 	// array validation

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

@@ -124,6 +124,8 @@ function matchesRuntime(manifest, runtime) {
 		if (stripped === 'nuxt' && runtime.is_nuxt) return true
 		if (stripped === 'expo' && runtime.is_expo) return true
 		if (stripped === 'react-native' && runtime.is_react_native) return true
+		if (stripped === 'ios' && runtime.is_ios_native) return true
+		if (stripped === 'android' && runtime.is_android_native) return true
 		if (stripped === 'node' && runtime.has_node) return true
 		if (stripped === 'cli' && runtime.has_node) return true
 		if (stripped === 'api' && runtime.has_node) return true
@@ -246,12 +248,15 @@ export function resolveDriver(opts) {
  * 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`.
+ * Closed surface set: `electron | web | cli | api | mobile | electron+web`.
  * `electron+web` is NOT a single flag — it's a cross-surface tag the
- * workflow runner expands into two single-surface dispatches.
+ * workflow runner expands into two single-surface dispatches. `mobile`
+ * maps to the synthetic `is_mobile` marker, which `maskRuntimeForSurface`
+ * expands to the four real mobile flags (the unified mobile-mcp driver
+ * targets ios/android/expo/react-native — decision D-08).
  *
- * @param {('electron'|'web'|'cli'|'api')} surface
- * @returns {('is_electron'|'is_web_frontend'|'has_node')}
+ * @param {('electron'|'web'|'cli'|'api'|'mobile')} surface
+ * @returns {('is_electron'|'is_web_frontend'|'has_node'|'is_mobile')}
  */
 export function surfaceToRequiredFlag(surface) {
 	switch (surface) {
@@ -262,6 +267,8 @@ export function surfaceToRequiredFlag(surface) {
 		case 'cli':
 		case 'api':
 			return 'has_node'
+		case 'mobile':
+			return 'is_mobile'
 		default:
 			throw new Error(`surfaceToRequiredFlag: unknown surface "${surface}"`)
 	}
@@ -292,7 +299,7 @@ export function surfaceToRequiredFlag(surface) {
  * @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 {Array<{id: string, surface: 'electron'|'web'|'cli'|'api'|'mobile'|'electron+web'}>} opts.outcomes
  * @param {string[]} [opts.override]
  * @param {string[]} [opts.required_stability]
  * @param {string[]} [opts.required_capabilities] — defaults to ['screenshot']
@@ -314,7 +321,9 @@ export function resolveDriversForOutcomes(opts) {
 			outcome.surface === 'electron+web' ? ['electron', 'web'] : [outcome.surface]
 
 		for (const surface of surfacesToDispatch) {
-			const flag = surfaceToRequiredFlag(/** @type {'electron'|'web'|'cli'|'api'} */ (surface))
+			const flag = surfaceToRequiredFlag(
+				/** @type {'electron'|'web'|'cli'|'api'|'mobile'} */ (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
@@ -347,7 +356,7 @@ export function resolveDriversForOutcomes(opts) {
  * single surface during per-outcome dispatch.
  *
  * @param {RuntimeCapabilities} runtime
- * @param {string} flag — one of: is_electron | is_web_frontend | has_node
+ * @param {string} flag — one of: is_electron | is_web_frontend | has_node | is_mobile
  * @returns {RuntimeCapabilities}
  */
 function maskRuntimeForSurface(runtime, flag) {
@@ -360,6 +369,8 @@ function maskRuntimeForSurface(runtime, flag) {
 		is_web_frontend: false,
 		is_expo: false,
 		is_react_native: false,
+		is_ios_native: false,
+		is_android_native: false,
 		has_node: false,
 	}
 	// Only flip the surface's flag on if the project actually carries it
@@ -373,5 +384,14 @@ function maskRuntimeForSurface(runtime, flag) {
 		masked.is_nuxt = runtime.is_nuxt
 	}
 	if (flag === 'has_node') masked.has_node = runtime.has_node
+	// `is_mobile` is a synthetic surface marker — expand it to the four real
+	// mobile flags so the unified mobile-mcp driver (targets ios/android/
+	// expo/react-native) matches whichever the project actually carries.
+	if (flag === 'is_mobile') {
+		masked.is_ios_native = runtime.is_ios_native
+		masked.is_android_native = runtime.is_android_native
+		masked.is_expo = runtime.is_expo
+		masked.is_react_native = runtime.is_react_native
+	}
 	return masked
 }