@aperant/framework 0.8.0 → 0.8.4

package/src/cli/commands/driver-doctor.mjs

@@ -0,0 +1,294 @@
+/**
+ * commands/driver-doctor.mjs — `apt-tools driver doctor <projectDir>`.
+ *
+ * Validates every discovered driver against:
+ *   1. The manifest JSON-Schema (manifest-validator.mjs).
+ *   2. IDL conformance — every declared capability has a function export.
+ *      NOTE: this step necessarily imports driver.mjs, which RUNS the
+ *      driver's top-level module code. For that reason we trust-gate the
+ *      import: bundled drivers (first-party signed, sitting under
+ *      packages/framework/drivers/) are always imported; user drivers
+ *      under .aperant/drivers/ are imported only when policy + TOFU say
+ *      it is safe. A user driver that fails the gate is reported with
+ *      `idl_conformant: false` and `idl_skipped_reason: <decision>`
+ *      rather than executed.
+ *   3. Preflight commands (declared as structured local_command per
+ *      ID-03). For each preflight whose declared transport is the
+ *      structured `{ binary, args[] }` shape, we run it via execFile
+ *      (exec.mjs — no shell) and record pass/fail + missing_deps.
+ *      Preflights without a structured `command` (declaration-only) are
+ *      marked `pending` — there is nothing to execute.
+ *
+ * Emits a JSON envelope listing pass/fail per driver. Third-party driver
+ * authors invoke this before publishing.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { err, ok } from '../util/result.mjs'
+import { execLocalCommand } from '../verify-proof/exec.mjs'
+import { IDL_VERB_NAMES } from '../verify-proof/idl/index.mjs'
+import { validateManifest } from '../verify-proof/manifest-validator.mjs'
+import { decide, readPolicy, readTofuLock } from '../verify-proof/trust.mjs'
+
+/**
+ * @typedef {Object} DriverDoctorReport
+ * @property {string} driverId
+ * @property {string} version
+ * @property {string} locality
+ * @property {boolean} manifest_valid
+ * @property {Array<{path: string, message: string}>} manifest_errors
+ * @property {boolean} idl_conformant
+ * @property {string[]} missing_exports
+ * @property {string[]} unknown_capabilities
+ * @property {string} [idl_skipped_reason] — present when conformance was skipped because the trust gate blocked driver.mjs import
+ * @property {'pending' | 'pass' | 'fail' | 'skipped'} preflight_status
+ * @property {string[]} missing_deps
+ * @property {string} [publisher_warning] — surfaced when a non-first-party manifest claims first_party_signed (v1 has no signature verification)
+ */
+
+/**
+ * Scan a drivers directory for manifest.json files. Returns
+ * (manifest, dir, locality) tuples.
+ * @param {string} rootDir
+ * @param {'bundled' | 'user'} locality
+ */
+function scanDriversDir(rootDir, locality) {
+	const out = []
+	if (!existsSync(rootDir)) return out
+	for (const entry of readdirSync(rootDir, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue
+		const driverDir = join(rootDir, entry.name)
+		const manifestPath = join(driverDir, 'manifest.json')
+		if (!existsSync(manifestPath)) continue
+		let manifest
+		try {
+			manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'))
+		} catch (e) {
+			out.push({ malformed: true, dir: driverDir, locality, parse_error: String(e) })
+			continue
+		}
+		out.push({ manifest, dir: driverDir, locality })
+	}
+	return out
+}
+
+/**
+ * @param {object} manifest
+ * @param {string} driverDir
+ * @returns {Promise<{idl_conformant: boolean, missing_exports: string[], unknown_capabilities: string[]}>}
+ */
+async function checkIdlConformance(manifest, driverDir) {
+	const driverPath = join(driverDir, 'driver.mjs')
+	if (!existsSync(driverPath)) {
+		return {
+			idl_conformant: false,
+			missing_exports: ['driver.mjs not found'],
+			unknown_capabilities: [],
+		}
+	}
+	const missing_exports = []
+	const unknown_capabilities = []
+	const idlSet = new Set(IDL_VERB_NAMES)
+	try {
+		const mod = await import(driverPath)
+		for (const cap of manifest.capabilities ?? []) {
+			if (!idlSet.has(cap)) {
+				unknown_capabilities.push(cap)
+				continue
+			}
+			if (typeof mod[cap] !== 'function') {
+				missing_exports.push(cap)
+			}
+		}
+	} catch (e) {
+		return {
+			idl_conformant: false,
+			missing_exports: [`driver.mjs import failed: ${String(e)}`],
+			unknown_capabilities: [],
+		}
+	}
+	return {
+		idl_conformant: missing_exports.length === 0 && unknown_capabilities.length === 0,
+		missing_exports,
+		unknown_capabilities,
+	}
+}
+
+/**
+ * Run a driver's preflight checks. Each declared preflight with a
+ * structured `command: { binary, args[] }` is executed via execFile
+ * (no shell). Preflights without a structured command are reported as
+ * `pending` — there is nothing to execute. Empty preflight list is
+ * `skipped`.
+ *
+ * @param {object} manifest
+ * @returns {Promise<{preflight_status: 'pending'|'pass'|'fail'|'skipped', missing_deps: string[]}>}
+ */
+async function runPreflight(manifest) {
+	const preflight = Array.isArray(manifest.preflight) ? manifest.preflight : []
+	if (preflight.length === 0) return { preflight_status: 'skipped', missing_deps: [] }
+
+	const missing_deps = []
+	let executed = 0
+	let failed = false
+
+	for (const check of preflight) {
+		// Only execute when the preflight declares a structured local-command
+		// shape. Anything else (no command, or non-structured) is left as
+		// declaration-only — caller can drive it explicitly.
+		const cmd = check?.command
+		if (
+			cmd === undefined ||
+			cmd === null ||
+			typeof cmd !== 'object' ||
+			typeof cmd.binary !== 'string' ||
+			!Array.isArray(cmd.args) ||
+			cmd.args.some((a) => typeof a !== 'string')
+		) {
+			continue
+		}
+		executed++
+		try {
+			await execLocalCommand({ transport: { local_command: cmd } }, [], { timeout: 5000 })
+		} catch {
+			failed = true
+			if (check.required !== false) {
+				missing_deps.push(check.name ?? cmd.binary)
+			}
+		}
+	}
+
+	if (executed === 0) return { preflight_status: 'pending', missing_deps: [] }
+	return { preflight_status: failed ? 'fail' : 'pass', missing_deps }
+}
+
+/**
+ * Trust-gate the driver.mjs import. Bundled drivers (locality='bundled')
+ * always pass — they live in packages/framework/drivers/ and are first-
+ * party. User drivers go through the policy + TOFU decision; only
+ * `allow` permits the dynamic import.
+ *
+ * @param {object} manifest
+ * @param {'bundled'|'user'} locality
+ * @param {string} projectDir
+ * @returns {{ok: true} | {ok: false, reason: string}}
+ */
+function trustGate(manifest, locality, projectDir) {
+	if (locality === 'bundled') return { ok: true }
+	const policy = readPolicy(projectDir)
+	const tofu = readTofuLock(projectDir)
+	const decision = decide(manifest, tofu, policy)
+	if (decision.decision === 'allow') return { ok: true }
+	return { ok: false, reason: decision.reason }
+}
+
+/**
+ * v1 has no signature verification (spec §Out of Scope). A non-Aperant
+ * publisher claiming `first_party_signed` is suspicious — surface a
+ * warning so the operator notices.
+ *
+ * @param {object} manifest
+ * @returns {string | undefined}
+ */
+function publisherWarning(manifest) {
+	const tier = manifest?.trust?.tier
+	if (tier !== 'first_party_signed') return undefined
+	const npmScope = manifest?.trust?.publisher?.npm_scope
+	const githubOrg = manifest?.trust?.publisher?.github_org
+	const looksLikeAperant = npmScope === '@aperant' || githubOrg === 'Mikalsen-AI'
+	if (looksLikeAperant) return undefined
+	return `trust.tier=first_party_signed but publisher is not @aperant — v1 does not verify signatures; treat tier as advisory`
+}
+
+/**
+ * @param {string} projectDir
+ * @param {string[]} [_extra]
+ */
+export async function cmdDriverDoctor(projectDir, _extra = []) {
+	if (!projectDir) return err('Usage: apt-tools driver doctor <project-dir>')
+	const target = resolve(projectDir)
+
+	// fileURLToPath is portable across POSIX + Windows; new URL(...).pathname
+	// returns '/C:/...' on Windows which resolve() does not handle correctly.
+	const frameworkRoot = fileURLToPath(new URL('../../..', import.meta.url))
+	const bundled = scanDriversDir(join(frameworkRoot, 'drivers'), 'bundled')
+	const user = scanDriversDir(join(target, '.aperant/drivers'), 'user')
+	const discovered = [...bundled, ...user]
+
+	const drivers = []
+	for (const d of discovered) {
+		if (d.malformed) {
+			drivers.push({
+				driverId: '(malformed)',
+				version: '?',
+				locality: d.locality,
+				manifest_valid: false,
+				manifest_errors: [{ path: '/', message: d.parse_error }],
+				idl_conformant: false,
+				missing_exports: [],
+				unknown_capabilities: [],
+				preflight_status: 'skipped',
+				missing_deps: [],
+			})
+			continue
+		}
+
+		const manifest = d.manifest
+		const schemaResult = validateManifest(manifest)
+		const manifest_valid = schemaResult.valid === true
+		const manifest_errors = schemaResult.valid === false ? schemaResult.errors : []
+
+		let idlResult = { idl_conformant: false, missing_exports: [], unknown_capabilities: [] }
+		let idl_skipped_reason
+		if (manifest_valid) {
+			const gate = trustGate(manifest, d.locality, target)
+			if (gate.ok) {
+				idlResult = await checkIdlConformance(manifest, d.dir)
+			} else {
+				// Trust gate denied. Do NOT dynamic-import the driver — that
+				// would execute arbitrary third-party code under the audit
+				// command. Report idl_conformant=false with the gate reason
+				// so the operator sees exactly why conformance was not run.
+				idl_skipped_reason = `trust gate denied: ${gate.reason}`
+			}
+		}
+
+		let preflightResult = { preflight_status: 'skipped', missing_deps: [] }
+		if (manifest_valid) {
+			preflightResult = await runPreflight(manifest)
+		}
+
+		const entry = {
+			driverId: manifest.driverId ?? '(unknown)',
+			version: manifest.version ?? '?',
+			locality: d.locality,
+			manifest_valid,
+			manifest_errors,
+			idl_conformant: idlResult.idl_conformant,
+			missing_exports: idlResult.missing_exports,
+			unknown_capabilities: idlResult.unknown_capabilities,
+			preflight_status: preflightResult.preflight_status,
+			missing_deps: preflightResult.missing_deps,
+		}
+		if (idl_skipped_reason !== undefined) entry.idl_skipped_reason = idl_skipped_reason
+		const warning = publisherWarning(manifest)
+		if (warning !== undefined) entry.publisher_warning = warning
+		drivers.push(entry)
+	}
+
+	const all_pass = drivers.every((d) => d.manifest_valid && d.idl_conformant)
+	return ok({
+		status: 'ok',
+		command: 'driver-doctor',
+		projectDir: target,
+		drivers,
+		summary: {
+			total: drivers.length,
+			pass: drivers.filter((d) => d.manifest_valid && d.idl_conformant).length,
+			fail: drivers.filter((d) => !d.manifest_valid || !d.idl_conformant).length,
+			overall: all_pass ? 'pass' : 'fail',
+		},
+	})
+}

package/src/cli/commands/gate.mjs

@@ -135,6 +135,20 @@ async function cmdGateCheck(projectDir, extraArgs) {
 	const cache = cacheMod ? cacheMod.readCache(ctx.taskDir) : {}
 
 	for (const gate of gates) {
+		// Applicability check fires BEFORE cache lookup or check() execution.
+		// Gates that don't apply to the active profile (lite vs full-pipeline)
+		// short-circuit with a skip verdict. Skip results are intentionally
+		// NOT cached (see status: 'skip' branch below), so a track change on
+		// the same task immediately reflects in the next gate-check.
+		if (typeof gate.applies_to_profile === 'function' && gate.applies_to_profile(ctx) === false) {
+			skipped.push({
+				id: gate.id,
+				severity: gate.severity,
+				reason: `profile-not-applicable: ${ctx.profile}`,
+			})
+			continue
+		}
+
 		let verdict
 		let cached = false
 		let inputHash = null
@@ -244,6 +258,7 @@ async function cmdGateCheck(projectDir, extraArgs) {
 		command: 'gate-check',
 		skill,
 		task_id: taskId,
+		profile: ctx.profile,
 		passed: passed.map((p) => p.id),
 		warned: warned.map((w) => ({ id: w.id, reason: w.reason })),
 		skipped: skipped.map((s) => ({ id: s.id, reason: s.reason })),

package/src/cli/commands/init.mjs

@@ -3,8 +3,9 @@
  * rewrite, 2026-04).
  *
  * Replaces the previous Claude-only `cp -r` installer with the per-runtime
- * transform pipeline (src/cli/install/pipeline.mjs). All 14 runtime targets
- * supported via `--<runtime>` flags or `--all`. Default with no flags in
+ * transform pipeline (src/cli/install/pipeline.mjs). Registered runtime
+ * targets are supported via `--<runtime>` flags or `--all`. Default with no
+ * flags in
  * non-TTY mode → `--claude` (backward compat — existing skills invoke
  * `apt-tools init <dir>` with no flags). Default in TTY → interactive prompt
  * with auto-detection markers.
@@ -40,12 +41,13 @@ import { buildAperantGitignoreTemplate } from '../config/upgrade-gitignore.mjs'
 import { detectPublicRemote } from '../git/remote.mjs'
 import { detectArchetype } from '../install/archetype.mjs'
 import { installKernel } from '../install/install-kernel.mjs'
+import { MANIFEST_FILENAME } from '../install/manifest.mjs'
 import {
 	discoverCanonicalFiles,
 	runInstall,
 	writeLastInstallSummary,
 } from '../install/pipeline.mjs'
-import { RUNTIMES, suggestRuntimes } from '../install/runtime-detect.mjs'
+import { getRuntime, RUNTIMES, suggestRuntimes } from '../install/runtime-detect.mjs'
 import { runLegacyCleanup } from '../install/runtime-migrate.mjs'
 import {
 	CLASS_A_SETTINGS,
@@ -392,6 +394,42 @@ function selectRuntimes(targetDir, parsedFlags) {
 	return [...suggested]
 }
 
+/**
+ * Return the runtime ids that should be installed during a no-schema-drift
+ * init. A current config is not enough to prove runtime files exist on this
+ * machine: team repos often carry `.aperant/config.json` but not local
+ * runtime roots/manifests.
+ *
+ * @param {string} targetDir
+ * @param {string[]} runtimeIds
+ * @returns {string[]}
+ */
+function runtimesMissingManifest(targetDir, runtimeIds) {
+	const missing = []
+	for (const id of runtimeIds) {
+		const runtime = getRuntime(id)
+		if (!runtime) continue
+		const manifestPath = join(targetDir, runtime.installRoot, MANIFEST_FILENAME)
+		if (!existsSync(manifestPath)) missing.push(id)
+	}
+	return missing
+}
+
+/**
+ * Current-schema init should still run the runtime installer when the user
+ * explicitly requested runtimes, when --force-runtimes is present, or when
+ * local runtime roots are suggested but have no apt manifest.
+ *
+ * @param {string} targetDir
+ * @param {ReturnType<typeof parseInstallFlags>} parsedFlags
+ * @returns {string[]}
+ */
+function selectNoDriftRuntimeInstallIds(targetDir, parsedFlags) {
+	if (parsedFlags.forceRuntimes) return selectRuntimes(targetDir, parsedFlags)
+	if (parsedFlags.runtimes_explicit) return parsedFlags.runtimes
+	return runtimesMissingManifest(targetDir, suggestRuntimes(targetDir))
+}
+
 /**
  * Non-TTY / scripted path — derive answers from flags + sensible defaults,
  * gated by the Class A/B classifier (spec R2 + R3).
@@ -663,11 +701,16 @@ async function interactiveInterview(targetDir, version, canonicalRoot, archetype
 			migration.applied_defaults.length === 0 &&
 			migration.auto_added.length === 0
 		if (noDrift) {
-			// 0.6.7 (Bug 2 fix) — `--force-runtimes` bypasses the TTY
-			// "Nothing to do." outro so the runtime walker re-stamps every
-			// manifest; cmdInit's force-runtimes synthesis path takes over.
-			if (parsedFlags.forceRuntimes) {
-				return { upgrade_noop: true, skipBootstrap, migration }
+			const runtimeInstallIds = selectNoDriftRuntimeInstallIds(targetDir, parsedFlags)
+			// Runtime repair bypasses the TTY "Nothing to do." outro so the
+			// runtime walker can re-stamp missing manifests first.
+			if (runtimeInstallIds.length > 0) {
+				return {
+					upgrade_noop: true,
+					skipBootstrap,
+					migration,
+					runtime_reinstall_runtimes: runtimeInstallIds,
+				}
 			}
 			process.stdout.write(`\n${aperantBanner(version)}\n\n`)
 			clack.intro('install')
@@ -1158,20 +1201,20 @@ export async function cmdInit(projectDir, extraArgs = []) {
 			)
 		}
 
-		// Upgrade no-drift — short-circuit before installRuntimes.
-		// /apt:update is the right surface for refreshing skills on a
-		// no-drift run; init's job here is to confirm the schema is current.
+		const noDriftRuntimeInstallIds = answers?.upgrade_noop
+			? (answers.runtime_reinstall_runtimes ??
+				selectNoDriftRuntimeInstallIds(installTarget, parsedFlags))
+			: []
+
+		// Upgrade no-drift with no runtime work — short-circuit before
+		// installRuntimes. /apt:update remains the right surface for refreshing
+		// already-manifested skills; init only repairs selected or suggested
+		// runtime roots that lack manifests.
 		// The bootstrap auto-chain still runs (it's deterministic and
 		// idempotent — preserves PROJECT.md, refreshes sidecar from it).
 		// In TTY mode clack already rendered "Nothing to do." to stdout,
 		// so suppress the JSON envelope (matches the cancelled path).
-		//
-		// 0.6.7 (Bug 2 fix) — `--force-runtimes` bypasses this short-circuit
-		// so `/apt:update` can re-stamp every runtime manifest even when
-		// `.aperant/config.json` is at the current schema. We synthesize a
-		// real InstallAnswers shape from the existing config so
-		// installRuntimes + finishInit run their normal upgrade path.
-		if (answers?.upgrade_noop && !parsedFlags.forceRuntimes) {
+		if (answers?.upgrade_noop && noDriftRuntimeInstallIds.length === 0) {
 			if (interactiveTty) return rawText('', 0)
 			const bootstrap = answers.skipBootstrap
 				? { status: 'skipped', reason: '--skip-bootstrap flag' }
@@ -1187,18 +1230,14 @@ export async function cmdInit(projectDir, extraArgs = []) {
 			})
 		}
 
-		// 0.6.7 (Bug 2 fix) — when forceRuntimes is set on a no-drift run,
-		// synthesize a real InstallAnswers shape from the existing config so
-		// the runtime walker re-stamps every manifest. Visibility/autonomy/
-		// cross-verification are read from answers.migration.migrated (already
-		// in memory from nonInteractiveAnswers — avoids a second config read);
-		// runtimes resolved via selectRuntimes helper shared with the upgrade path.
+		// Current-schema runtime install — synthesize a real InstallAnswers
+		// shape from the existing config so installRuntimes + finishInit run
+		// their normal upgrade path.
 		let effectiveAnswers = answers
-		if (answers?.upgrade_noop && parsedFlags.forceRuntimes) {
+		if (answers?.upgrade_noop && noDriftRuntimeInstallIds.length > 0) {
 			const existing = answers.migration?.migrated || {}
-			const runtimes = selectRuntimes(installTarget, parsedFlags)
 			effectiveAnswers = {
-				runtimes,
+				runtimes: noDriftRuntimeInstallIds,
 				autonomyDefault: existing?.autonomy?.default ?? 1,
 				visibility: existing?.share?.visibility === 'team' ? 'team' : 'solo',
 				crossVerificationTools: existing?.multi_model?.cross_verification?.tools ?? [],
@@ -1211,12 +1250,15 @@ export async function cmdInit(projectDir, extraArgs = []) {
 			}
 		}
 
-		// FRAMEWORK-BUG-021 — sweep the legacy `.agents/skills/` codex tree
+		// FRAMEWORK-BUG-021 — sweep the legacy `.codex/` codex tree
 		// BEFORE the install pipeline runs so the install can re-stamp
-		// `.codex/` against a clean slate. Only fires when codex is in the
-		// requested runtime set and `--keep-legacy` was not passed; the
-		// helper itself is conservative (no-op on managed installs, no-op
-		// when no legacy framework files are present).
+		// `.agents/skills/<folder>/SKILL.md` (Codex CLI's documented
+		// surface, per https://developers.openai.com/codex/skills) against
+		// a clean slate. Only fires when codex is in the requested runtime
+		// set and `--keep-legacy` was not passed; the helper itself is
+		// conservative (no-op on managed installs, no-op when no legacy
+		// framework files are present). The v0.8.2 inversion is
+		// documented in `runtime-migrate.mjs:7-12`.
 		let legacyCleanup = null
 		if (effectiveAnswers.runtimes.includes('codex')) {
 			if (parsedFlags.keepLegacy) {
@@ -1226,7 +1268,7 @@ export async function cmdInit(projectDir, extraArgs = []) {
 				legacyCleanup = { runtime: 'codex', ...cleanup }
 				if (cleanup.ran && cleanup.retained.length > 0) {
 					process.stderr.write(
-						`[apt-tools] legacy_cleanup retained ${cleanup.retained.length} user-added path(s) under .agents/skills/: ${cleanup.retained.join(', ')}\n`,
+						`[apt-tools] legacy_cleanup retained ${cleanup.retained.length} user-added path(s) under .codex/: ${cleanup.retained.join(', ')}\n`,
 					)
 				}
 			}

package/src/cli/commands/install-from-source.mjs

@@ -0,0 +1 @@
+export { cmdInstallFromSource } from '../install/install-from-source.mjs'

package/src/cli/commands/modes.mjs

@@ -1,5 +1,5 @@
 /**
- * commands/modes.mjs — `apt-tools modes list` (Pocock adoption ST-13, AC12).
+ * commands/modes.mjs — `apt-tools modes list`.
  *
  * Power-user discoverability tool. Returns a JSON envelope with one
  * record per discovered skill, exposing modes / flags / content-formats /

package/src/cli/commands/route.mjs

@@ -28,7 +28,11 @@ import { existsSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { getTaskIsolationConfig, getTrustedSkillSources } from '../config/load.mjs'
+import {
+	getTaskIsolationConfig,
+	getTrustedSkillSources,
+	loadMergedProjectConfig,
+} from '../config/load.mjs'
 import '../gate/gates/index.mjs'
 import * as gateRegistry from '../gate/registry.mjs'
 import { detectHost, SUPPORTED_HOSTS } from '../host/detect.mjs'
@@ -264,6 +268,19 @@ export function cmdRoute(projectDir, extraArgs) {
 		else if (f === 'debug') track_override = 'DEBUG'
 	}
 
+	// FRAMEWORK-RFC-001 — consent signal for spar pipeline auto-inject.
+	// Reads merged config (config.json ∪ config.local.json) via the same
+	// helper apt-setup writes through. AUDIT-001 — spar fields live in
+	// .aperant/config.local.json, not shared config. Resolved once and
+	// folded into the envelope by both classify branches below.
+	// `loadMergedProjectConfig` returns null when no shared config exists
+	// (first-time init path) — treat as consent-off + no partner.
+	const merged = loadMergedProjectConfig(targetDir) ?? {}
+	const sparEnabled = merged.spar?.enabled === true
+	const sparPartner = merged.spar?.partner ?? null
+	const userPassedExplicitSparGates =
+		rawInput.includes('--spar-gates') || flags.some((f) => f.startsWith('spar-gates'))
+
 	const taskDescription = normalizeAptInvocation(rawInput.replace(/--\w+/g, '').trim())
 
 	const configPath = join(targetDir, '.aperant', 'config.json')
@@ -399,6 +416,17 @@ export function cmdRoute(projectDir, extraArgs) {
 		const agentName = spawnAgent ? index.agentOf(primarySkill) || 'apt-planner' : null
 		const options = buildTrackOptions(track)
 		const gate_preview = previewGatesFor(primarySkill)
+		// FRAMEWORK-RFC-001 — flag-override path: track is known deterministically,
+		// so we can resolve the spar gate string inline and emit it directly.
+		// QUICK/DEBUG are Fast-Path-exempt — no inject. User-passed --spar-gates
+		// wins over consent (no double-inject). Field omitted entirely when null
+		// so the envelope stays byte-equivalent for users who never opted in.
+		let spar_inject_gates = null
+		if (sparEnabled && !userPassedExplicitSparGates) {
+			if (track === 'STANDARD') spar_inject_gates = 'plan'
+			else if (track === 'DEEP') spar_inject_gates = 'plan,execute'
+			// QUICK / DEBUG → stays null
+		}
 		return ok({
 			status: 'ok',
 			command: 'route',
@@ -417,6 +445,7 @@ export function cmdRoute(projectDir, extraArgs) {
 			task_isolation,
 			update_check,
 			...(gate_preview ? { gate_preview } : {}),
+			...(spar_inject_gates ? { spar_inject_gates } : {}),
 			classification: {
 				source: 'flag-override',
 				reason: `Explicit --${track_override.toLowerCase()} flag`,
@@ -467,6 +496,18 @@ export function cmdRoute(projectDir, extraArgs) {
 					reason:
 						'Track and skill classification deferred to the host LLM; see classification_meta.trust_notice.',
 				},
+				// FRAMEWORK-RFC-001 — host model composes --spar-gates from these
+				// signals + its track classification per apt/SKILL.md MODE: classify
+				// Step 4. Field is absent when consent is off (envelope stays slim).
+				...(sparEnabled
+					? {
+							spar_consent: {
+								enabled: true,
+								partner: sparPartner,
+								user_passed_explicit_gates: userPassedExplicitSparGates,
+							},
+						}
+					: {}),
 			},
 		})
 	} catch (e) {

package/src/cli/commands/triage.mjs

@@ -1,5 +1,5 @@
 /**
- * commands/triage.mjs — `apt-tools triage` (Pocock adoption ST-10, AC9).
+ * commands/triage.mjs — `apt-tools triage`.
  *
  * 5-state triage state machine with extensible metadata for v2 OSS
  * contributor primitives. Backend-configured: writes to

package/src/cli/config/load.mjs

@@ -361,11 +361,17 @@ export function getTrustedSkillSources(projectDir, cli) {
 	)
 	if (existsSync(consumerSkills)) defaults.push(consumerSkills)
 	// 4. Host CLI's installed runtime skills — only when the router knows
-	// which runtime it's in. Some hosts (codex, claude-code) install into
-	// .codex/skills / .claude/skills etc; the router picks skills from
+	// which runtime it's in. Some hosts (claude-code, gemini, …) install into
+	// .claude/skills / .gemini/skills etc; the router picks skills from
 	// the host-local directory so per-runtime transforms are honored.
+	//
+	// Codex is excluded: its transform strips frontmatter to {name, description}
+	// for codex validator compliance, and that stripped form fails the
+	// router's SkillFrontmatterSchema (contract.mjs). The canonical + kernel
+	// roots above still serve routing on Codex hosts (they carry the fat
+	// frontmatter the schema requires).
 	const installRoot = cli ? cliToInstallRoot(cli) : null
-	if (installRoot) {
+	if (installRoot && cli !== 'codex') {
 		const runtimeSkills = join(targetDir, installRoot, 'skills')
 		if (existsSync(runtimeSkills)) defaults.push(runtimeSkills)
 	}

package/src/cli/coordination/auto-emit-artifact-ready.mjs

@@ -7,7 +7,7 @@
  * postcondition of `apt-tools commit`. This closes the Conductor v2 gap
  * exposed during live verification 2026-05-15: the planner's QUICK /
  * SIMPLE track is hard-exempt from "new interaction discipline"
- * (Pocock Fast Path Guarantee ID-05), so the markdown emit step was
+ * (Aperant Fast Path Guarantee ID-05), so the markdown emit step was
  * never executed for tasks router-classified as simple. The fleet
  * never saw artifact.ready, the PlanReadyCard never auto-promoted.
  *

package/src/cli/coordination/event-schema.mjs

@@ -42,6 +42,10 @@ const CONDUCTOR_OPS = new Set([
 	'conductor.action.executed',
 	'conductor.action.gate_blocked',
 	'conductor.boot_reconciled',
+	// AC21 — MCP-server consent decisions audited to .aperant/events/*.jsonl
+	'mcp-consent.approved',
+	'mcp-consent.denied',
+	'mcp-consent.tofu-reprompt',
 ])
 
 /** Allowed values for `phase.changed.to` — PTY busy/idle only. */
@@ -133,6 +137,21 @@ export function validateConductorEvent(op, data) {
 				'blocked_reason',
 			])
 
+		// AC21 — MCP server consent audit. Three ops share the same
+		// payload shape: who approved/denied which server, with which
+		// configHash, at what time. session_id is a session-scoped string
+		// (chat-session row id).
+		case 'mcp-consent.approved':
+		case 'mcp-consent.denied':
+		case 'mcp-consent.tofu-reprompt':
+			return requireFields(op, d, [
+				'server_id',
+				'config_sha256',
+				'decided_at',
+				'decided_by',
+				'session_id',
+			])
+
 		case 'conductor.boot_reconciled': {
 			// Fleet-wide event — numeric fields only. All optional but if
 			// present must be finite numbers (zero allowed).