@aperant/framework 0.11.0 → 0.12.0

package/src/cli/verify-proof/sandbox/recipe-diff.mjs

@@ -0,0 +1,208 @@
+/**
+ * recipe-diff.mjs — read-only Markdown diff generator for a recipe.
+ *
+ * Loads the recipe, walks `changes[]`, and emits a Markdown report
+ * enumerating every proposed write WITH `--- before` / `+++ after`
+ * blocks. The generator is pure read — it never writes to the adopter's
+ * tree (ID-02). The companion `apply-recipe` command is the only
+ * writer.
+ *
+ * Public contract:
+ *   generateRecipeDiff({projectDir, recipeId, recipes}) → {
+ *     format: 'markdown',
+ *     body: string,
+ *     changes: [{path, kind, summary}],
+ *     envelope: {status, recipe_version, compatible}
+ *   }
+ *
+ * The Markdown is user-facing and load-bearing — drift = golden-snapshot
+ * test failure by design (subtask 2.1 / TD-03).
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+/**
+ * Defense-in-depth path-under-root check. Returns the validated absolute
+ * path or null when the candidate escapes the root. The diff generator
+ * surfaces a "template not found" envelope rather than throwing (read-
+ * only generator stays non-fatal).
+ *
+ * @param {string} rootAbs
+ * @param {string} relPath
+ * @returns {string|null}
+ */
+function safeJoinUnderRoot(rootAbs, relPath) {
+	if (typeof relPath !== 'string' || relPath.length === 0) return null
+	if (isAbsolute(relPath)) return null
+	const candidate = resolve(rootAbs, relPath)
+	const rel = relative(rootAbs, candidate)
+	if (rel.startsWith('..') || isAbsolute(rel)) return null
+	return candidate
+}
+
+/**
+ * @param {{projectDir: string, recipeId: string, recipes: object[]}} args
+ * @returns {{
+ *   format: 'markdown',
+ *   body: string,
+ *   changes: Array<{path: string, kind: string, summary: string}>,
+ *   envelope: {status: 'ok'|'error', recipe_version: string|null, compatible: boolean}
+ * }}
+ */
+export function generateRecipeDiff({ projectDir, recipeId, recipes }) {
+	const recipe = (recipes ?? []).find((r) => r && r.recipeId === recipeId)
+	if (!recipe) {
+		return {
+			format: 'markdown',
+			body: `# No recipe available\n\nrecipeId \`${recipeId}\` is not in the registered recipes list.\n`,
+			changes: [],
+			envelope: { status: 'error', recipe_version: null, compatible: false },
+		}
+	}
+
+	const adopterRoot = resolve(projectDir)
+	const changeRows = []
+	const sections = []
+
+	for (const change of recipe.changes ?? []) {
+		// Defense-in-depth: a malicious recipe could otherwise read
+		// arbitrary host files via `change.path: '../../etc/passwd'`. The
+		// diff generator is read-only but the read CONTENT lands in the
+		// emitted Markdown — refuse to enumerate paths outside root.
+		const targetAbs = safeJoinUnderRoot(adopterRoot, change.path)
+		if (targetAbs === null) {
+			sections.push(
+				`## ${change.path}\n\n_(rejected: change.path escapes project root — recipe defect)_\n`,
+			)
+			changeRows.push({
+				path: change.path,
+				kind: change.kind,
+				summary: 'rejected (path escapes root)',
+			})
+			continue
+		}
+		const exists = existsSync(targetAbs)
+		const before = exists ? safeReadFile(targetAbs) : ''
+		const after = renderAfter(change, recipe, adopterRoot)
+
+		const summary = renderChangeSummary(change, exists)
+		changeRows.push({ path: change.path, kind: change.kind, summary })
+
+		sections.push(renderChangeSection(change, before, after, exists))
+	}
+
+	const body = renderBody(recipe, sections)
+	return {
+		format: 'markdown',
+		body,
+		changes: changeRows,
+		envelope: {
+			status: 'ok',
+			recipe_version: recipe.recipeVersion ?? null,
+			compatible: true,
+		},
+	}
+}
+
+function renderBody(recipe, sections) {
+	const lines = []
+	lines.push(`# Recipe diff: ${recipe.name ?? recipe.recipeId}`)
+	lines.push('')
+	lines.push(
+		`**Recipe:** \`${recipe.recipeId}\` v${recipe.recipeVersion}  ` +
+			`(compatibleWithApplied: ${JSON.stringify(recipe.compatibleWithApplied ?? [])})`,
+	)
+	lines.push('')
+	lines.push(recipe.description ?? '')
+	lines.push('')
+	lines.push(`This recipe proposes **${(recipe.changes ?? []).length}** changes.`)
+	lines.push(
+		'No file is written until you run `apt-tools apply-recipe . --confirm` ' +
+			'and accept each change individually.',
+	)
+	lines.push('')
+	for (const section of sections) {
+		lines.push(section)
+		lines.push('')
+	}
+	return lines.join('\n').replace(/\n{3,}/g, '\n\n')
+}
+
+function renderChangeSummary(change, exists) {
+	const verb =
+		change.kind === 'file-create' ? 'create' : change.kind === 'json-merge' ? 'merge into' : 'edit'
+	const target = exists ? change.path : `${change.path} (new file)`
+	return `${verb} ${target}`
+}
+
+function renderChangeSection(change, before, after, exists) {
+	const lines = []
+	lines.push(`## ${change.path}`)
+	lines.push('')
+	lines.push(
+		`- kind: \`${change.kind}\``,
+		`- marker: \`${change.marker ?? '(none)'}\``,
+		`- target ${exists ? 'exists' : 'does not exist'} on disk`,
+	)
+	lines.push('')
+	lines.push('```diff')
+	const beforeBlock = before === '' ? '(empty / file does not exist)' : before
+	for (const line of beforeBlock.split('\n')) lines.push(`--- ${line}`)
+	lines.push('')
+	for (const line of after.split('\n')) lines.push(`+++ ${line}`)
+	lines.push('```')
+	return lines.join('\n')
+}
+
+/**
+ * Render the "after" content per change kind. For json-merge we stringify
+ * the patch payload; for text-insert / file-create we load the template
+ * from the recipe directory (when present).
+ */
+function renderAfter(change, recipe, adopterRoot) {
+	if (change.kind === 'json-merge') {
+		return JSON.stringify(change.after ?? {}, null, 2)
+	}
+	if (change.template) {
+		const tplPath = locateRecipeTemplate(recipe, change.template, adopterRoot)
+		if (tplPath && existsSync(tplPath)) {
+			return safeReadFile(tplPath)
+		}
+		return `(template not found on disk: ${change.template})`
+	}
+	if (typeof change.after === 'string') return change.after
+	return ''
+}
+
+/**
+ * Resolve a recipe template path relative to the framework's recipes/
+ * directory. The framework ships recipes at packages/framework/recipes/
+ * <id>/templates/. We compute the directory from this module's location
+ * so the resolver works regardless of cwd.
+ */
+function locateRecipeTemplate(recipe, templateName, _adopterRoot) {
+	// __dirname → packages/framework/src/cli/verify-proof/sandbox/
+	// → up four levels → packages/framework/
+	// Defense-in-depth: reject `../` escapes in templateName AND validate
+	// recipeId so a crafted id (e.g. '../../evil') cannot shift the anchor
+	// outside the framework root. discoverBundledRecipes() skips schema
+	// validation, so the ^[a-z][a-z0-9_-]*$ pattern may not have been enforced.
+	if (typeof recipe.recipeId !== 'string' || !/^[a-z][a-z0-9_-]*$/.test(recipe.recipeId)) {
+		return null
+	}
+	const frameworkRoot = resolve(__dirname, '..', '..', '..', '..')
+	const templatesRoot = join(frameworkRoot, 'recipes', recipe.recipeId, 'templates')
+	return safeJoinUnderRoot(templatesRoot, templateName)
+}
+
+function safeReadFile(path) {
+	try {
+		return readFileSync(path, 'utf-8')
+	} catch {
+		return ''
+	}
+}

package/src/cli/verify-proof/sandbox/sandbox-config.mjs

@@ -0,0 +1,82 @@
+/**
+ * sandbox-config.mjs — central loader for sandbox recipes + the
+ * adopter's verification.sandbox config block.
+ *
+ * Two responsibilities:
+ *
+ *   1. discoverBundledRecipes() — walk packages/framework/recipes/<id>/
+ *      and return every parseable recipe.json. Mirrors the bundled-
+ *      drivers discovery pattern in commands/detect-runtime.mjs.
+ *
+ *   2. readSandboxConfig(projectDir) — read .aperant/config.json's
+ *      verification.sandbox block (or null if absent). Pure read; no
+ *      merge with config.local.json — sandbox state is shared, not
+ *      per-device.
+ *
+ * Stays in src/cli/verify-proof/sandbox/ so consumers under that tree
+ * share one loader. The CLI commands (recipe-diff, apply-recipe,
+ * verify-sandbox) all import from here.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+/**
+ * Resolve the framework's recipes directory at runtime. Works whether
+ * the module is loaded from source (packages/framework/src/...) or from
+ * the installed dist (.aperant/deps/node_modules/@aperant/framework/...).
+ *
+ * @returns {string}
+ */
+export function resolveRecipesDir() {
+	// __dirname → packages/framework/src/cli/verify-proof/sandbox/
+	// → up four levels → packages/framework/
+	return resolve(__dirname, '..', '..', '..', '..', 'recipes')
+}
+
+/**
+ * Walk the recipes/ directory and return every recipe.json that parses.
+ * Each entry is the raw recipe object (NOT validated — callers can
+ * call validateManifest if they need schema guarantees).
+ *
+ * @returns {Array<object>}
+ */
+export function discoverBundledRecipes() {
+	const dir = resolveRecipesDir()
+	if (!existsSync(dir)) return []
+	const out = []
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue
+		const recipePath = join(dir, entry.name, 'recipe.json')
+		if (!existsSync(recipePath)) continue
+		try {
+			out.push(JSON.parse(readFileSync(recipePath, 'utf-8')))
+		} catch {
+			/* skip malformed recipes */
+		}
+	}
+	return out
+}
+
+/**
+ * Read .aperant/config.json's verification.sandbox block, or null when
+ * absent / unparseable. Pure read — no defaults injected.
+ *
+ * @param {string} projectDir
+ * @returns {object|null}
+ */
+export function readSandboxConfig(projectDir) {
+	const path = join(resolve(projectDir), '.aperant', 'config.json')
+	if (!existsSync(path)) return null
+	try {
+		const config = JSON.parse(readFileSync(path, 'utf-8'))
+		const v = config?.verification
+		if (v === null || typeof v !== 'object') return null
+		return v.sandbox ?? null
+	} catch {
+		return null
+	}
+}

package/src/cli/verify-proof/sandbox/sandbox-schema.json

@@ -0,0 +1,33 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://aperant.dev/schemas/verification-sandbox-v1.json",
+	"title": "Aperant verification.sandbox config block v1",
+	"description": "Structural contract for the optional verification.sandbox config block at .aperant/config.json. When this block is ABSENT every existing code path is byte-identical to today (Fast Path Guarantee, ID-07). When present, it records which recipe the adopter opted into and the audit metadata of the apply-recipe run that wrote it.",
+	"type": "object",
+	"required": ["enabled", "recipeId", "recipeVersion"],
+	"additionalProperties": false,
+	"properties": {
+		"enabled": {
+			"type": "boolean",
+			"description": "Master switch. False suppresses the parallel gate even when a recipe is applied — used to wind back without removing the recipe artifacts."
+		},
+		"recipeId": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9_-]*$",
+			"description": "Identifier of the recipe applied to this project (e.g. 'electron-libsql')."
+		},
+		"recipeVersion": {
+			"type": "string",
+			"description": "Semver of the recipe at apply time (e.g. '0.1.0'). Used by `apt-tools recipe-diff` to detect already-applied / incremental / incompatible cases via compatibleWithApplied[]."
+		},
+		"appliedAt": {
+			"type": "string",
+			"description": "ISO-8601 timestamp recorded at apply time. Optional — only written by apply-recipe."
+		},
+		"appliedHash": {
+			"type": "string",
+			"pattern": "^[a-f0-9]{64}$",
+			"description": "SHA-256 of the canonical recipe manifest contents at apply time. Optional — used to detect drift between the applied recipe and the on-disk recipe library."
+		}
+	}
+}

package/src/cli/verify-proof/sandbox/self-test.mjs

@@ -0,0 +1,265 @@
+/**
+ * self-test.mjs — two-instance concurrent self-test for parallel
+ * /apt:verify-proof.
+ *
+ * Spawns TWO instances of the recipe's launch command concurrently
+ * (Promise.all with B jittered 50-150 ms) against per-instance sandbox
+ * dirs. Asserts BOTH instances reach the recipe's `readiness.logPattern`
+ * within `readiness.timeoutMs` AND neither emits `SQLITE_BUSY` or
+ * `EADDRINUSE`/`bind` errors in stderr.
+ *
+ * The verdict envelope shape mirrors verify-proof v2's
+ * `verification.json :: meta.verdict`:
+ *   {verified: bool, verdict: 'approved'|'needs_human',
+ *    reason: null|'self_test_failed_sqlite_busy'|
+ *            'self_test_failed_port_conflict'|
+ *            'self_test_failed_app_init_timeout',
+ *    durationMs: number}
+ *
+ * Cross-platform via `node:child_process.spawn` (NO shell). win32 short-
+ * circuits at the verify-sandbox command layer (subtask 4.2) — this
+ * module assumes a POSIX-ish host.
+ *
+ * No state-file writing here (4.2's job). Pure functional contract so
+ * the integration tests can drive it via `vi.spyOn(child_process,
+ * 'spawn')`.
+ */
+
+import child_process from 'node:child_process'
+import { mkdirSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+/**
+ * @typedef {Object} SelfTestVerdict
+ * @property {boolean} verified
+ * @property {'approved'|'needs_human'} verdict
+ * @property {null|'self_test_failed_sqlite_busy'|'self_test_failed_port_conflict'|'self_test_failed_app_init_timeout'} reason
+ * @property {number} durationMs
+ * @property {{A: ChildOutcome, B: ChildOutcome}} children
+ */
+
+/**
+ * @typedef {Object} ChildOutcome
+ * @property {boolean} ready
+ * @property {string|null} failureReason
+ * @property {string} stderrTail
+ */
+
+/**
+ * @param {{projectDir: string, recipeId: string, recipes: object[]}} args
+ * @returns {Promise<SelfTestVerdict>}
+ */
+export async function runSelfTest({ projectDir, recipeId, recipes }) {
+	const recipe = (recipes ?? []).find((r) => r && r.recipeId === recipeId)
+	if (!recipe) {
+		throw new Error(`runSelfTest: recipe not found: ${recipeId}`)
+	}
+	const launch = recipe.launch
+	if (!launch?.binary) {
+		throw new Error(`runSelfTest: recipe ${recipeId} missing launch.{binary, args}`)
+	}
+	const readiness = recipe.readiness
+	if (!readiness || typeof readiness.logPattern !== 'string') {
+		throw new Error(`runSelfTest: recipe ${recipeId} missing readiness.logPattern`)
+	}
+	const timeoutMs = readiness.timeoutMs ?? 30000
+	const pid = process.pid
+	const sandboxRoot = join(tmpdir(), `aperant-sandbox-${pid}-${Date.now()}`)
+	const dirs = {
+		A: join(sandboxRoot, 'A'),
+		B: join(sandboxRoot, 'B'),
+	}
+	mkdirSync(dirs.A, { recursive: true })
+	mkdirSync(dirs.B, { recursive: true })
+
+	const startedAt = Date.now()
+	const jitter = 50 + Math.random() * 100
+
+	// Concurrency by construction: A starts immediately, B's start is
+	// awaited via a microtask + jitter delay. Promise.all races them.
+	const [outcomeA, outcomeB] = await Promise.all([
+		spawnInstance({ index: 'A', launch, readiness, timeoutMs, sandboxDir: dirs.A, projectDir }),
+		delay(jitter).then(() =>
+			spawnInstance({ index: 'B', launch, readiness, timeoutMs, sandboxDir: dirs.B, projectDir }),
+		),
+	])
+
+	const durationMs = Date.now() - startedAt
+	const verdict = decideVerdict(outcomeA, outcomeB)
+	return {
+		...verdict,
+		durationMs,
+		children: { A: outcomeA, B: outcomeB },
+	}
+}
+
+/**
+ * Race a readiness signal against the timeout, scanning stderr for the
+ * three known-bad patterns. Resolves to a ChildOutcome regardless of
+ * which arm wins. Always kills the child before resolving.
+ */
+function spawnInstance({ index: _index, launch, readiness, timeoutMs, sandboxDir, projectDir }) {
+	return new Promise((resolveOutcome) => {
+		const env = renderLaunchEnv(launch.envTemplate ?? {}, sandboxDir)
+		const child = child_process.spawn(launch.binary, launch.args ?? [], {
+			cwd: resolve(projectDir),
+			env: { ...process.env, ...env, SANDBOX_DIR: sandboxDir },
+			stdio: ['ignore', 'pipe', 'pipe'],
+		})
+
+		let resolved = false
+		let stderrBuf = ''
+		const stdoutBuf = []
+		const MAX_STDERR_BYTES = 4096
+
+		const finish = (outcome) => {
+			if (resolved) return
+			resolved = true
+			clearTimeout(timer)
+			try {
+				child.kill('SIGTERM')
+			} catch {
+				/* already gone */
+			}
+			// SIGKILL grace
+			setTimeout(() => {
+				try {
+					child.kill('SIGKILL')
+				} catch {
+					/* gone */
+				}
+			}, 5000).unref?.()
+			resolveOutcome(outcome)
+		}
+
+		// onStderrText: appends to stderrBuf and checks failure-reason patterns.
+		// Must NOT be called with stdout data — informational app logs that mention
+		// "SQLITE_BUSY" or "EADDRINUSE" must not trigger failure verdicts (LOG-001).
+		const onStderrText = (text) => {
+			stderrBuf = (stderrBuf + text).slice(-MAX_STDERR_BYTES)
+			if (/SQLITE_BUSY/i.test(text)) {
+				finish({
+					ready: false,
+					failureReason: 'self_test_failed_sqlite_busy',
+					stderrTail: stderrBuf.slice(-500),
+				})
+				return
+			}
+			if (/EADDRINUSE|bind\s+failed|address already in use|EACCES|EPERM/i.test(text)) {
+				finish({
+					ready: false,
+					failureReason: 'self_test_failed_port_conflict',
+					stderrTail: stderrBuf.slice(-500),
+				})
+				return
+			}
+		}
+
+		// onStdoutText: checks readiness signal only. Never touches stderrBuf and
+		// never triggers failure-reason heuristics — stdout is not an error stream.
+		const onStdoutText = (text) => {
+			if (text.includes(readiness.logPattern)) {
+				finish({ ready: true, failureReason: null, stderrTail: stderrBuf.slice(-500) })
+			}
+		}
+
+		child.stdout?.on?.('data', (chunk) => {
+			const text = String(chunk)
+			stdoutBuf.push(text)
+			onStdoutText(text)
+		})
+		child.stderr?.on?.('data', (chunk) => {
+			const text = String(chunk)
+			onStderrText(text)
+			// Readiness may also appear on stderr (some apps log to stderr only).
+			if (text.includes(readiness.logPattern)) {
+				finish({ ready: true, failureReason: null, stderrTail: stderrBuf.slice(-500) })
+			}
+		})
+		child.on?.('error', (err) => {
+			finish({
+				ready: false,
+				failureReason: 'self_test_failed_app_init_timeout',
+				stderrTail: String(err.message ?? err),
+			})
+		})
+		child.on?.('exit', () => {
+			if (!resolved) {
+				// Process exited before signalling readiness. Treat as init timeout
+				// unless the stderr already revealed a known bad pattern (handled
+				// above before exit).
+				finish({
+					ready: false,
+					failureReason: 'self_test_failed_app_init_timeout',
+					stderrTail: stderrBuf.slice(-500),
+				})
+			}
+		})
+
+		const timer = setTimeout(() => {
+			finish({
+				ready: false,
+				failureReason: 'self_test_failed_app_init_timeout',
+				stderrTail: stderrBuf.slice(-500),
+			})
+		}, timeoutMs)
+		// Don't keep the event loop alive on the timer.
+		timer.unref?.()
+	})
+}
+
+/**
+ * Combine two outcomes into the v2-shaped verdict envelope.
+ * Failure precedence: sqlite_busy > port_conflict > app_init_timeout.
+ *
+ * Every spawnInstance() resolution sets failureReason explicitly on the
+ * !ready path (the four finish() call sites cover SQLITE_BUSY, port
+ * conflict, app_init_timeout, and the child-error path which also maps
+ * to app_init_timeout). The priority loop therefore always finds a
+ * match; the unreachable fallthrough that used to live here was
+ * deleted per CLAUDE.md guideline 2 (no handling for impossible
+ * scenarios).
+ */
+function decideVerdict(a, b) {
+	if (a.ready && b.ready) {
+		return { verified: true, verdict: /** @type {const} */ ('approved'), reason: null }
+	}
+	const reasons = [a.failureReason, b.failureReason].filter(Boolean)
+	const priority = [
+		'self_test_failed_sqlite_busy',
+		'self_test_failed_port_conflict',
+		'self_test_failed_app_init_timeout',
+	]
+	for (const cand of priority) {
+		if (reasons.includes(cand)) {
+			return {
+				verified: false,
+				verdict: /** @type {const} */ ('needs_human'),
+				reason: /** @type {any} */ (cand),
+			}
+		}
+	}
+	throw new Error(
+		`self-test decideVerdict: unreachable — both outcomes failed without a known reason: ${JSON.stringify({ a, b })}`,
+	)
+}
+
+/**
+ * Substitute ${SANDBOX_DIR} placeholders in the recipe's envTemplate.
+ */
+function renderLaunchEnv(envTemplate, sandboxDir) {
+	const out = {}
+	for (const [k, v] of Object.entries(envTemplate)) {
+		// biome-ignore lint/suspicious/noTemplateCurlyInString: config template marker, not a typo
+		out[k] = typeof v === 'string' ? v.replaceAll('${SANDBOX_DIR}', sandboxDir) : v
+	}
+	return out
+}
+
+function delay(ms) {
+	return new Promise((res) => {
+		const t = setTimeout(res, ms)
+		t.unref?.()
+	})
+}

package/templates/config.json

@@ -18,7 +18,6 @@
 	},
 	"qa": {
 		"approved_threshold": 7,
-		"approved_with_notes_threshold": 5,
 		"require_proof_for_ui": true,
 		"max_fix_iterations": 3,
 		"grace": {
@@ -116,6 +115,16 @@
 	"diagram": {
 		"mode": "file"
 	},
+	"roadmap": {
+		"$comment": "Roadmap backend toggle (task 26-05-26 D-09 + D-13). 'markdown' (default) keeps the existing OSS file-write path under .aperant/roadmap/{scope}/. 'cloud-mcp' routes write-side subcommands (add-milestone, add-phase, set-phase-status, delete-phase, delete-milestone) through the Aperant Cloud MCP server. Cloud-mcp requires roadmap.cloudMcp.teamSlug + a bearer token (env MCP_ROADMAP_TOKEN OR .aperant/team.json::roadmapMcpToken). Fast Path Guarantee: a missing 'roadmap' block is byte-identical to backend='markdown'.",
+		"backend": "markdown",
+		"cloudMcp": {
+			"teamSlug": null,
+			"mcpServerUrl": null,
+			"tokenSource": null,
+			"scopeMap": {}
+		}
+	},
 	"docs_policy": {
 		"$comment": "C33 docs-coherence policy. Override via /apt:setup Batch 7. Keys are globs/paths; values are 'auto-update' | 'flag-drift' | 'skip'. Missing block → defaults from packages/framework/templates/docs-policy-defaults.json apply."
 	},

package/templates/proof-verification.md

@@ -17,7 +17,7 @@ JSON schema reference for `.aperant/proof/{app}/{date}/{run}/verification.json`
     "started": "{ISO timestamp}",
     "updated": "{ISO timestamp}",
     "spec": "{spec.md path or task description}",
-    "verdict": "pending | approved | approved_with_notes | rejected",
+    "verdict": "pending | approved | rejected | needs_human",
     "tools": ["electron", "puppeteer", "cdp_video"],
     "selected_driver": {
       "driverId": "electron",
@@ -47,6 +47,11 @@ JSON schema reference for `.aperant/proof/{app}/{date}/{run}/verification.json`
     }
   },
 
+  "gates": {
+    "automation_gate": "pass | fail",
+    "proof_gate": "pass | fail"
+  },
+
   "coverage": {
     "registry_file": ".aperant/features/{area}.json",
     "registered_count": 0,
@@ -76,7 +81,7 @@ JSON schema reference for `.aperant/proof/{app}/{date}/{run}/verification.json`
       "actual": "Grid correctly tiled to 2+1",
       "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",
+      "result": "pass | fail | blocked | skip | needs_human_with_transport",
       "severity": null
     },
     {
@@ -189,7 +194,19 @@ JSON schema reference for `.aperant/proof/{app}/{date}/{run}/verification.json`
 | `fallback_attempts` | array | IMMUTABLE | Drivers the resolver REJECTED before selecting. Each entry has `driver_id` + `reason` (missing capabilities, stability filter, hash drift, policy denial). Audit trail for coverage-loss decisions. |
 
 ### automated_checks
-Each check has `status` (pass/fail) and `output` (captured terminal output). These are populated in step 3 before any manual testing begins.
+Each check has `status` (closed set `{pass, fail}`) and `output` (captured terminal output). These are populated in Step 3 before any outcome driving begins.
+
+**Hard STOP gate (v0.9.0).** `status` MUST be one of `{pass, fail}`. The legacy `"enforced_at_commit"` dodge string is REJECTED — the workflow runner aborts at Step 3 with `automation_gate: fail` if any check carries a non-conforming status. Each check must actually execute in the run (no deferring to commit-time enforcement).
+
+### gates (v0.9.0)
+
+Top-level `{automation_gate, proof_gate}` derived from `automated_checks` (gate 1) and per-outcome evidence (gate 2). Closed set `{pass, fail}` for each. The two-gate envelope drives `meta.verdict`:
+
+| automation_gate | proof_gate | verdict |
+|---|---|---|
+| `pass` | `pass` | `approved` |
+| `pass` | `fail` | `needs_human` (UI-surface transport gap; install driver and re-run) |
+| `fail` | * | `rejected` (any of lint/typecheck/tests red) |
 
 ### coverage
 | Field | Type | Description |
@@ -219,7 +236,7 @@ Each test entry tracks one sub-feature verification. Fields:
 | `actual` | string | OVERWRITE | What actually happened (filled after testing) |
 | `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` |
+| `result` | string | OVERWRITE | `pass`, `fail`, `blocked`, `skip`, or `needs_human_with_transport` (v0.9.0 — UI-surface outcome lacks driver transport; host must install MCP server / driver and re-run). `blocked` keeps its legacy meaning: driver advertised the capability but couldn't perform it in this run. |
 | `severity` | string/null | OVERWRITE | `blocker`, `major`, `minor`, `cosmetic`, or `null` if pass |
 
 ### skipped (MANDATORY)
@@ -242,10 +259,12 @@ Four QA dimensions, each with `score` (1-10) and `rationale` (string). Scores ar
 - Any major in the area → max score 5
 - A dimension cannot score above 5 if any blocker exists
 
-**Verdict derivation:**
-- ALL dimensions >= 7 → `approved`
-- ALL dimensions >= 5 → `approved_with_notes`
-- ANY dimension < 5 → `rejected`
+**Verdict derivation (v0.9.0 two-gate envelope — see workflow Step 7):**
+- `automation_gate: pass` AND `proof_gate: pass` → `approved`
+- `automation_gate: pass` AND `proof_gate: fail` → `needs_human`
+- `automation_gate: fail` OR critical issues unresolved → `rejected`
+
+Dimensions are informational rationale only — they do NOT drive the verdict in v0.9.0+.
 
 ### gaps
 Issues discovered during testing. Feeds into the fix planning pipeline.