@aperant/framework 0.11.0 → 0.12.1

package/drivers/mobile/driver.mjs

@@ -0,0 +1,106 @@
+/**
+ * mobile/driver.mjs — bundled unified mobile driver (iOS + Android).
+ *
+ * Wraps the `mobile-mcp` MCP server (mobile-next/mobile-mcp, Apache-2.0),
+ * the single UI-driving backend for BOTH platforms (decision D-01). The
+ * platform/device is chosen INSIDE the tool call (mobile_list_available_
+ * devices → device id), NOT at resolver time — that is why one driver
+ * targets ios/android/expo/react-native.
+ *
+ * The app lifecycle (build / install / launch / Metro / ready-gate) is
+ * owned by `apt-tools mobile prepare`, NOT this driver (D-03/D-04). This
+ * driver assumes a foregrounded, JS-ready app and only drives UI + captures
+ * evidence.
+ *
+ * Per ID-01 — the workflow prose NEVER names mcp__mobile-mcp__* tools; the
+ * verb→tool mapping lives ONLY here. Transport dispatch happens at the
+ * workflow-runner layer (which holds the model's tool surface).
+ *
+ * IDL verb → mobile-mcp tool mapping:
+ *   launch         → mobile_use_device (select the booted device/simulator)
+ *   click          → mobile_click_on_screen_at_coordinates
+ *   type           → mobile_type_keys
+ *   key            → mobile_press_button
+ *   swipe          → mobile_swipe_on_screen
+ *   screenshot     → mobile_save_screenshot
+ *   capture_logs   → mobile_device_logs
+ *   assert_visible → mobile_list_elements_on_screen (element present)
+ *   assert_text    → mobile_list_elements_on_screen (text match)
+ *   teardown       → mobile_terminate_app (best-effort)
+ *
+ * The driver is a thin adapter: it validates input shape via the IDL
+ * arg-metadata and returns a VerbResult. The actual transport dispatch
+ * happens at the workflow runner layer. For conformance testing we expose
+ * the verb signatures as identity stubs returning VerbResult — the SDK
+ * conformance kit then validates the shape contract.
+ */
+
+import { validateVerbArgs } from '../../src/cli/verify-proof/idl/index.mjs'
+
+/** Build a success VerbResult. */
+function ok(evidence_paths = []) {
+	return { status: 'success', evidence_paths, duration_ms: 0, retry_count: 0 }
+}
+function fail(error) {
+	return { status: 'fail', evidence_paths: [], duration_ms: 0, retry_count: 0, error }
+}
+
+/**
+ * Validate args + return a VerbResult shape stub. Real transport invocation
+ * happens at the workflow-runner layer (model holds the tool surface —
+ * mcp__mobile-mcp__*).
+ *
+ * @param {string} verb
+ * @param {Record<string, unknown>} args
+ * @returns {{status: 'success'|'fail'|'skip', evidence_paths: string[], duration_ms: number, retry_count: number, error?: string}}
+ */
+function adaptVerb(verb, args) {
+	const check = validateVerbArgs(verb, args)
+	if (!check.valid) {
+		return fail(`mobile.${verb}: missing required args: ${check.missing.join(', ')}`)
+	}
+	if (verb === 'screenshot' && typeof args.output_path === 'string') {
+		return ok([args.output_path])
+	}
+	return ok([])
+}
+
+export async function launch(args) {
+	return adaptVerb('launch', args)
+}
+
+export async function click(args) {
+	return adaptVerb('click', args)
+}
+
+export async function type(args) {
+	return adaptVerb('type', args)
+}
+
+export async function key(args) {
+	return adaptVerb('key', args)
+}
+
+export async function swipe(args) {
+	return adaptVerb('swipe', args)
+}
+
+export async function screenshot(args) {
+	return adaptVerb('screenshot', args)
+}
+
+export async function capture_logs(args) {
+	return adaptVerb('capture_logs', args)
+}
+
+export async function assert_visible(args) {
+	return adaptVerb('assert_visible', args)
+}
+
+export async function assert_text(args) {
+	return adaptVerb('assert_text', args)
+}
+
+export async function teardown(args) {
+	return adaptVerb('teardown', args)
+}

package/drivers/mobile/manifest.json

@@ -0,0 +1,49 @@
+{
+	"driverId": "mobile",
+	"version": "0.1.0",
+	"targets": ["ios", "android", "expo", "react-native"],
+	"capabilities": [
+		"launch",
+		"click",
+		"type",
+		"key",
+		"swipe",
+		"screenshot",
+		"capture_logs",
+		"assert_visible",
+		"assert_text",
+		"teardown"
+	],
+	"evidence_capabilities": ["screenshot", "capture_logs"],
+	"frameworkApiRange": "^1.0.0",
+	"priority": 80,
+	"stability": "ga",
+	"trust": {
+		"tier": "first_party_signed",
+		"publisher": {
+			"name": "Aperant",
+			"npm_scope": "@aperant",
+			"github_org": "Mikalsen-AI",
+			"verified": true
+		}
+	},
+	"security": {
+		"sandbox_profile": "workspace_write",
+		"network": "deny",
+		"requires_user_approval": false
+	},
+	"audit": { "log_invocations": true, "log_manifest_hash": true },
+	"preflight": [
+		{
+			"name": "xcrun (iOS Simulator toolchain)",
+			"command": { "binary": "xcrun", "args": ["simctl", "help"] },
+			"required": false
+		},
+		{
+			"name": "adb (Android platform-tools)",
+			"command": { "binary": "adb", "args": ["--version"] },
+			"required": false
+		}
+	],
+	"transport": { "mcp_server_id": "mobile-mcp" }
+}

package/package.json

@@ -1,139 +1,139 @@
 {
-	"name": "@aperant/framework",
-	"version": "0.11.0",
-	"description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
-	"author": "Mikalsen AI <hello@mikalsen.ai>",
-	"type": "module",
-	"main": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"bin": {
-		"framework": "./bin/apt-tools.mjs",
-		"apt-tools": "./bin/apt-tools.mjs",
-		"apt-proof-video": "./bin/apt-proof-video.mjs"
-	},
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js"
-		},
-		"./types": {
-			"types": "./dist/types/index.d.ts",
-			"import": "./dist/types/index.js"
-		},
-		"./cost": {
-			"types": "./dist/cost/index.d.ts",
-			"import": "./dist/cost/index.js"
-		},
-		"./mappers": {
-			"types": "./dist/mappers/index.d.ts",
-			"import": "./dist/mappers/index.js"
-		},
-		"./schemas": {
-			"types": "./dist/schemas/index.d.ts",
-			"import": "./dist/schemas/index.js"
-		},
-		"./standalone": {
-			"types": "./dist/standalone/index.d.ts",
-			"import": "./dist/standalone/index.js"
-		},
-		"./driver-sdk": {
-			"types": "./dist/driver-sdk/index.d.ts",
-			"import": "./dist/driver-sdk/index.js"
-		},
-		"./coordination/event-schema": {
-			"types": "./src/cli/coordination/event-schema.d.ts",
-			"import": "./src/cli/coordination/event-schema.mjs"
-		},
-		"./roadmap/conductor-view": {
-			"types": "./src/cli/roadmap/conductor-view.d.ts",
-			"import": "./src/cli/roadmap/conductor-view.mjs"
-		},
-		"./design/scan": {
-			"import": "./src/cli/design/scan.mjs"
-		},
-		"./design/extract-repo": {
-			"import": "./src/cli/design/extract-repo.mjs"
-		},
-		"./design/synthesize": {
-			"import": "./src/cli/design/synthesize.mjs"
-		}
-	},
-	"scripts": {
-		"build": "tsc && node scripts/extract-personas-schema.mjs",
-		"dev": "tsc --watch --preserveWatchOutput",
-		"typecheck": "tsc --noEmit",
-		"lint": "biome check . --diagnostic-level=error",
-		"lint:fix": "biome check --write . --diagnostic-level=error",
-		"clean": "rm -rf dist",
-		"test": "vitest run",
-		"c28:cutover": "node scripts/c28-cutover.mjs",
-		"build-plugin": "node scripts/build-plugin.mjs",
-		"publish-plugin": "node scripts/publish-plugin.mjs",
-		"publish:verdaccio": "node scripts/publish-verdaccio.mjs",
-		"release:verdaccio": "pnpm build && pnpm publish:verdaccio",
-		"ship:verdaccio": "npm version patch --no-git-tag-version && pnpm build && pnpm publish:verdaccio"
-	},
-	"files": [
-		"dist/",
-		"bin/",
-		"src/cli/",
-		"src/cost/",
-		"commands/",
-		"skills/",
-		"agents/",
-		"prompts/",
-		"templates/",
-		"context/",
-		"workflows/",
-		"drivers/",
-		"examples/",
-		"LICENSE",
-		"README.md",
-		"CHANGELOG.md",
-		"!**/__tests__/**",
-		"!**/*.test.*",
-		"!**/*.spec.*",
-		"!**/*.test.d.ts.map",
-		"!**/*.test.js.map"
-	],
-	"keywords": [
-		"ai",
-		"framework",
-		"coding-assistant",
-		"claude-code",
-		"codex",
-		"aperant"
-	],
-	"license": "AGPL-3.0-only",
-	"homepage": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework#readme",
-	"bugs": {
-		"url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/issues"
-	},
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop.git",
-		"directory": "packages/framework"
-	},
-	"engines": {
-		"node": ">=18.0.0"
-	},
-	"publishConfig": {
-		"access": "public"
-	},
-	"dependencies": {
-		"@clack/prompts": "^1.2.0",
-		"proper-lockfile": "^4.1.2",
-		"yaml": "^2.8.3",
-		"zod": "^4.3.6"
-	},
-	"optionalDependencies": {
-		"@babel/parser": "^7.29.2",
-		"@babel/traverse": "^7.29.0",
-		"@google/genai": "^1.50.1",
-		"css-tree": "^3.2.1",
-		"playwright": "^1.59.1"
-	},
-	"devDependencies": {
-		"@vitest/coverage-v8": "^4.1.5"
-	}
-}
+  "name": "@aperant/framework",
+  "version": "0.12.1",
+  "description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
+  "author": "Mikalsen AI <hello@mikalsen.ai>",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "framework": "./bin/apt-tools.mjs",
+    "apt-tools": "./bin/apt-tools.mjs",
+    "apt-proof-video": "./bin/apt-proof-video.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.js"
+    },
+    "./cost": {
+      "types": "./dist/cost/index.d.ts",
+      "import": "./dist/cost/index.js"
+    },
+    "./mappers": {
+      "types": "./dist/mappers/index.d.ts",
+      "import": "./dist/mappers/index.js"
+    },
+    "./schemas": {
+      "types": "./dist/schemas/index.d.ts",
+      "import": "./dist/schemas/index.js"
+    },
+    "./standalone": {
+      "types": "./dist/standalone/index.d.ts",
+      "import": "./dist/standalone/index.js"
+    },
+    "./driver-sdk": {
+      "types": "./dist/driver-sdk/index.d.ts",
+      "import": "./dist/driver-sdk/index.js"
+    },
+    "./coordination/event-schema": {
+      "types": "./src/cli/coordination/event-schema.d.ts",
+      "import": "./src/cli/coordination/event-schema.mjs"
+    },
+    "./roadmap/conductor-view": {
+      "types": "./src/cli/roadmap/conductor-view.d.ts",
+      "import": "./src/cli/roadmap/conductor-view.mjs"
+    },
+    "./design/scan": {
+      "import": "./src/cli/design/scan.mjs"
+    },
+    "./design/extract-repo": {
+      "import": "./src/cli/design/extract-repo.mjs"
+    },
+    "./design/synthesize": {
+      "import": "./src/cli/design/synthesize.mjs"
+    }
+  },
+  "files": [
+    "dist/",
+    "bin/",
+    "src/cli/",
+    "src/cost/",
+    "commands/",
+    "skills/",
+    "agents/",
+    "prompts/",
+    "templates/",
+    "context/",
+    "workflows/",
+    "drivers/",
+    "examples/",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "!**/__tests__/**",
+    "!**/*.test.*",
+    "!**/*.spec.*",
+    "!**/*.test.d.ts.map",
+    "!**/*.test.js.map"
+  ],
+  "keywords": [
+    "ai",
+    "framework",
+    "coding-assistant",
+    "claude-code",
+    "codex",
+    "aperant"
+  ],
+  "license": "AGPL-3.0-only",
+  "homepage": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework#readme",
+  "bugs": {
+    "url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop.git",
+    "directory": "packages/framework"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "proper-lockfile": "^4.1.2",
+    "yaml": "^2.8.3",
+    "zod": "^4.3.6"
+  },
+  "optionalDependencies": {
+    "@babel/parser": "^7.29.2",
+    "@babel/traverse": "^7.29.0",
+    "@google/genai": "^1.50.1",
+    "css-tree": "^3.2.1",
+    "playwright": "^1.59.1"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.5"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/extract-personas-schema.mjs",
+    "dev": "tsc --watch --preserveWatchOutput",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check . --diagnostic-level=error",
+    "lint:fix": "biome check --write . --diagnostic-level=error",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "c28:cutover": "node scripts/c28-cutover.mjs",
+    "build-plugin": "node scripts/build-plugin.mjs",
+    "publish-plugin": "node scripts/publish-plugin.mjs",
+    "publish:verdaccio": "node scripts/publish-verdaccio.mjs",
+    "release:verdaccio": "pnpm build && pnpm publish:verdaccio",
+    "ship:verdaccio": "npm version patch --no-git-tag-version && pnpm build && pnpm publish:verdaccio"
+  }
+}

package/prompts/inbox-clarification.md

@@ -0,0 +1,17 @@
+Run one read-only clarification turn using Work Record context, prior chat history, and the latest user response.
+Return semantic readiness updates and either the next single focused clarification question or ready status, without mutating project files or external systems.
+
+You are the Aperant clarification agent.
+First call readPhaseOutput with phase="triage" to inspect the triage output.
+If triage is already specific and high-confidence, set status="ready" and omit nextChatMessage.
+Otherwise, populate nextChatMessage with EXACTLY ONE focused, concrete question that addresses the highest-impact remaining readiness gap. Do not batch multiple questions into one turn.
+Ground the question in the triage findings, the inbox title and description, and the prior message history. Acknowledge what the user already said when relevant.
+Set nextChatMessage.dimensionKey to the readiness dimension the question targets, and nextChatMessage.cardId to the matching open clarification card when one exists.
+Keep nextClarificationQuestions as the ordered list of remaining open questions (one per open dimension); the UI renders this list as a chip row alongside the chat.
+If the user's prior answer did not raise the targeted dimension's readinessAssessment score above its scoreThreshold, the next question MUST target the same dimensionKey with a sharper or more concrete follow-up. Otherwise, advance to a different open dimension.
+Target the gating dimension whose acceptance-criteria slots are still open; do not jump to a dimension whose slots are already grounded.
+Emit proposedAcceptanceCriteriaUpdates as field-level patches ({ acIndex, fieldPath, value, source, groundedness }) that fill the targeted acceptance-criteria slots from the user's answer; fieldPath is one of statement, given, when, thenOutcome, verificationMethod.
+Mark a slot patch groundedness:'tentative' when you are filling it from a vague answer or your own assumption, and groundedness:'grounded' only when the user's answer concretely specifies the field.
+On an explicit not_applicable reply, do not write a value; on an explicit agent_assume reply, fill the slot with source:'agent_assume'. Otherwise use source:'user_answer'.
+Ask EXACTLY ONE question per turn, and do not re-grill the same dimension more than three turns.
+Use repository tools only when needed to sharpen the question.

package/prompts/inbox-triage.md

@@ -0,0 +1,21 @@
+Refine one Inbox Work Item into structured triage output.
+Use supplied repository evidence and preserve read-only behavior.
+Return semantic findings, readiness evidence, and clarification prompts without mutating project files or external systems.
+
+You are the Aperant triage agent.
+Produce structured JSON only via the provided schema.
+Semantic capability mapping: repository_evidence maps to listFiles and readFile tools.
+Use listFiles and readFile tools to ground claims in repository evidence.
+Return a triage dossier with repo-evidenced facts, inferred assumptions, risks, acceptance criteria, and clarification plan.
+Always include readinessEvaluation with rubricVersion, dimensions, missingDimensions, hardBlockers, and justificationSummary.
+Universal readiness keys: problem_clarity, scope_definition, repo_evidence, risk_identification, acceptance_criteria_quality.
+Bug-specific keys: repro_steps, expected_vs_actual, impact_assessment.
+Feature-specific keys: user_value, solution_shape, dependency_mapping.
+Enhancement-specific keys: current_behavior_baseline, incremental_scope, migration_safety.
+Every readiness dimension requires key, score (0-100), evidence, justification, and optional hardBlocker.
+Only place verified repository findings in repoEvidencedFacts.
+For every inferred assumption, set disposition to requires_hitl_confirmation or accepted_assumption.
+Do not present product commitments as facts unless repository evidence directly supports them.
+Each proposed acceptance criterion must include a verificationMethod and Given/When/Then fields when behavior is being specified.
+Tag each proposed acceptance criterion with the readiness dimensionKey it supports (one of the universal or type-specific readiness keys listed above) so the clarification gate can map each acceptance criterion to its dimension exactly.
+Prefer concise summaries and concrete touch points.

package/prompts/qa_orchestrator_agentic.md

@@ -66,10 +66,10 @@ The reviewer writes `qa_report.md` and updates `implementation_plan.json` with a
 
 Read the `qa_signoff` from `implementation_plan.json`. The reviewer now writes dimension scores alongside the status.
 
-Read the dimension scores:
-- If ALL dimensions >= 7 and status is "approved" -> Build passes. Write final QA report. Done.
-- If ALL dimensions >= 5 and status is "approved-with-notes" -> Accept with notes. Write final QA report with improvement suggestions. Done.
-- If ANY dimension < 5 -> Analyze which dimensions are lowest (Phase 4)
+Read the gates + dimension scores:
+- If `automation_gate: pass` AND `proof_gate: pass` AND status is "approved" -> Build passes. Write final QA report. Done.
+- If `automation_gate: pass` AND `proof_gate: fail` AND status is "needs_human" -> Transport gap. Write final QA report listing what the human must install (e.g. an MCP server). Done.
+- If `automation_gate: fail` OR critical findings unresolved -> status is "rejected". Spawn fixer (Phase 4).
 - If no scores written -> Reviewer failed to score. Re-spawn with explicit scoring instructions: "You MUST score all 4 dimensions (completeness, correctness, code_quality, test_coverage) on 1-10 before writing a verdict."
 - If no signoff written at all -> Reviewer failed to update the file. Retry with explicit instructions.
 
@@ -100,10 +100,10 @@ When the reviewer rejects, triage based on dimension scores from the qa_signoff,
 - Documentation formatting
 - Non-functional improvements
 
-**Decision Framework:**
-- If ONLY cosmetic issues and ALL dimension scores >= 5 -> approve with notes (write qa_signoff: approved-with-notes)
-- If ALL dimension scores >= 7 and no critical issues -> approve the build (write qa_signoff: approved)
-- If ANY dimension < 5 -> spawn qa_fixer with targeted guidance focused on the lowest-scoring dimension
+**Decision Framework (v0.9.0 two-gate envelope):**
+- If `automation_gate: pass` AND `proof_gate: pass` AND no critical issues -> approve the build (write qa_signoff: approved)
+- If `automation_gate: pass` AND `proof_gate: fail` (UI-surface outcome missing driver transport) -> write qa_signoff: needs_human with a `transport_gap` array
+- If `automation_gate: fail` OR critical issues unresolved -> spawn qa_fixer with targeted guidance
 - If the same critical issue appears 3+ times -> escalate to human
 
 ### Phase 5: Fix Cycle
@@ -137,19 +137,20 @@ Track iteration count. Your goal is to converge quickly:
 
 ## QUALITY GATES
 
-### Approval Criteria (Score-Based)
+### Approval Criteria (v0.9.0 two-gate envelope)
 Approve when ALL of these are true:
-- All 4 dimension scores >= 7 (for "approved") or >= 5 (for "approved-with-notes")
+- `automation_gate: pass` (tests + typecheck + lint all green)
+- `proof_gate: pass` (every outcome has surface-appropriate evidence)
 - No critical issues in the issues array
-- Automated checks (tests, typecheck, lint) all pass
+- Dimensions land >= 7 as informational rationale (does NOT drive the verdict)
 
-### Score Thresholds
-- **approved**: ALL dimensions >= 7 AND no critical issues
-- **approved-with-notes**: ALL dimensions >= 5 AND no critical issues
-- **rejected**: ANY dimension < 5 OR critical issues found
+### Verdict Closed Set
+- **approved**: `automation_gate: pass` AND `proof_gate: pass` AND no critical issues
+- **needs_human**: `automation_gate: pass` AND `proof_gate: fail` (transport gap)
+- **rejected**: `automation_gate: fail` OR critical issues unresolved
 
-### Acceptable Imperfections (for approved-with-notes)
-These should NOT block approval when all dimensions are >= 5:
+### Acceptable Imperfections (cited in `findings.notes` on an `approved` verdict)
+These do NOT block approval and ride along as notes:
 - Missing optional features (if spec marks them as optional)
 - Code style deviations (if functionality is correct)
 - Missing edge case handling for unlikely scenarios

package/prompts/qa_reviewer.md

@@ -37,13 +37,15 @@ You MUST score 4 dimensions on a 1-10 scale. The verdict is DERIVED from scores
 **3-4 (Poor):** Significant problems. Multiple issues.
 **1-2 (Failed):** Fundamentally broken or missing.
 
-### Verdict Derivation (NOT your choice -- derived from scores)
+### Verdict Derivation (v0.9.0 two-gate envelope; NOT your choice -- derived from gates)
 
-- **approved**: ALL dimensions >= 7 AND no critical issues
-- **approved-with-notes**: ALL dimensions >= 5 AND no critical issues
-- **rejected**: ANY dimension < 5 OR critical issues found
+Verdict is the closed set `{approved, rejected, needs_human}`. It derives from the two-gate envelope (`automation_gate` AND `proof_gate`) per `/apt:verify-proof`. Dimensions are informational rationale only.
 
-You MUST write scores BEFORE writing the verdict. The verdict follows from the scores.
+- **approved**: `automation_gate: pass` AND `proof_gate: pass` AND no critical findings.
+- **needs_human**: `automation_gate: pass` AND `proof_gate: fail` (typically: UI-surface outcome with no driver transport — see verify-proof workflow).
+- **rejected**: `automation_gate: fail` OR critical findings unresolved.
+
+You MUST write scores BEFORE writing the verdict. The verdict follows from the gates, with dimensions as rationale.
 
 ---
 
@@ -440,7 +442,7 @@ Create a comprehensive QA report with dimension scores:
 | test_coverage | {N}/10 | {evidence} |
 
 **Minimum score:** {min}
-**Derived verdict:** {approved|approved-with-notes|rejected}
+**Derived verdict:** {approved|rejected|needs_human}
 
 ## Summary
 
@@ -514,7 +516,7 @@ For each critical/major issue, describe what the Coder Agent should do:
 
 **Next Steps**:
 - [If approved: Ready for merge]
-- [If approved-with-notes: List notes for future improvement]
+- [If needs_human: Install the missing driver transport (e.g. MCP server) and re-run /apt:verify-proof]
 - [If rejected: List of fixes needed, then re-run QA]
 ```
 
@@ -566,17 +568,17 @@ EOF
 # Only commit actual code changes to the project
 ```
 
-### If APPROVED-WITH-NOTES:
+### If NEEDS_HUMAN (transport gap):
 
-Same as approved, but with status "approved-with-notes" and an additional `notes` array:
+Same as approved, but with status `"needs_human"` and a `transport_gap` array describing what the human must install (e.g. an MCP server, a binary):
 
 ```json
 {
   "qa_signoff": {
-    "status": "approved-with-notes",
-    "notes": [
-      "Minor issue: [description]",
-      "Suggestion: [description]"
+    "status": "needs_human",
+    "transport_gap": [
+      "Missing MCP server: puppeteer (drivers/browser/manifest.json :: transport.mcp_server_id)",
+      "After install, re-run /apt:verify-proof"
     ],
     "dimension_scores": {
       "completeness": "[N]",
@@ -762,11 +764,11 @@ QA will automatically re-run after fixes.
 
 The QA -> Fix -> QA loop continues until:
 
-1. **All dimension scores >= 7** (for approved) or **>= 5** (for approved-with-notes)
+1. **`automation_gate: pass`** (lint + typecheck + tests all green) AND **`proof_gate: pass`** (every outcome has surface-appropriate evidence)
 2. **No critical issues remain**
 3. **All tests pass**
 4. **No regressions**
-5. **QA derives approved or approved-with-notes verdict**
+5. **QA derives `approved`** (the only ship-eligible verdict; `needs_human` requires installing the missing transport, `rejected` requires code fixes)
 
 Maximum iterations: 5 (configurable)
 

package/skills/apt/SKILL.md

@@ -687,10 +687,10 @@ When spawning agents, follow these rules:
 3. **Agent type from route result.** The `agent` field in the route JSON tells you which agent to spawn.
 4. **Model selection:** Use `sonnet` for agents unless the task is complex (DEEP track), then use the default model.
 5. **Always include task_dir.** Every agent needs to know where to read/write artifacts.
-6. **Capability-based spawning:** Before spawning agents for task mode (execution_mode = "auto"), check the reconciled orchestration mode:
+6. **Capability-based spawning:** Before spawning agents for task mode (execution_mode = "auto"), check the reconciled orchestration mode. Pass the task's `{track}` (from Step 0c) via `--track` so per-track defaults from `.aperant/config.json:orchestration.per_track` apply — without it, a STANDARD task whose configured mode is `sequential` silently resolves to the host's most-capable mode (e.g. `agent-team`) and over-delegates:
 
 ```bash
-node packages/framework/bin/apt-tools.mjs reconcile .
+node packages/framework/bin/apt-tools.mjs reconcile . --track {track}
 ```
 
 Use `resolved.phase_delegation` to decide how agents are launched: