@aperant/framework 0.8.1 → 0.8.6

package/src/cli/commands/context.mjs

@@ -1,8 +1,8 @@
 /**
- * commands/context.mjs — `apt-tools context write` (Pocock adoption ST-5, AC4).
+ * commands/context.mjs — `apt-tools context write`.
  *
  * Upserts a term-block into the project's CONTEXT.md (the persistent
- * project glossary). Format ported from Pocock's CONTEXT-FORMAT.md
+ * project glossary). Format ported from the Aperant CONTEXT-FORMAT.md
  * (see packages/framework/templates/context-format.md for the MIT
  * attribution + field semantics).
  *
@@ -192,7 +192,7 @@ export function cmdContext(subcommand, projectDir, extraArgs) {
 	} else {
 		source = `${HEADER}\n\n${HEADER_NOTE}\n\n`
 	}
-	// Ensure the file starts with the header even if it existed pre-Pocock.
+	// Ensure the file starts with the header even if it existed pre-vertical-slice.
 	if (!source.startsWith(HEADER)) {
 		source = `${HEADER}\n\n${HEADER_NOTE}\n\n${source}`
 	}

package/src/cli/commands/coverage-check.mjs

@@ -1,10 +1,20 @@
 /**
  * commands/coverage-check.mjs — plan-to-spec verification coverage validator (C29).
+ *
+ * v0.8.6 adds a second gate: `## User Outcomes` parsing + gate (see
+ * coverage-check/user-outcomes.mjs). The new gate is ADDITIVE — it does
+ * NOT change the existing AC parsing branch and does NOT block when
+ * only Acceptance Criteria are present (outcomes and ACs are
+ * independent concerns per spec §ID-01). QUICK-track plans
+ * (`complexity: "simple"` OR no `vertical_slice_schema_version`) skip
+ * the User Outcomes branch entirely per Fast Path Guarantee (ID-08).
  */
 
 import { existsSync, readFileSync } from 'node:fs'
-import { join, resolve } from 'node:path'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { parseAcceptanceCriteria, resolveSpecPath } from '../config/coverage-ac.mjs'
+import { parseUserOutcomes, userOutcomesGateResult } from '../coverage-check/user-outcomes.mjs'
 import { err, ok } from '../util/result.mjs'
 
 export function cmdCoverageCheck(subcommand, projectDir, extraArgs) {
@@ -125,31 +135,64 @@ export function cmdCoverageCheck(subcommand, projectDir, extraArgs) {
 				}
 			}
 
+			// Build the User Outcomes payload — additive, ID-08 QUICK-exempt.
+			// Plans with `complexity: "simple"` OR no
+			// `vertical_slice_schema_version` are QUICK-track per the Fast
+			// Path Guarantee — skip the gate entirely (the payload's
+			// `user_outcomes` key is OMITTED).
+			const isQuickTrack = plan.complexity === 'simple' || !plan.vertical_slice_schema_version
+			let userOutcomesPayload = null
+			if (!isQuickTrack && resolvedSpec.path) {
+				const specContentForOutcomes = readFileSync(resolvedSpec.path, 'utf-8')
+				const parsedOutcomes = parseUserOutcomes(specContentForOutcomes)
+				const frameworkVersion = readFrameworkVersion()
+				const gateResult = userOutcomesGateResult(parsedOutcomes, frameworkVersion)
+				userOutcomesPayload = {
+					header_present: parsedOutcomes.header_present,
+					body_kind: parsedOutcomes.body_kind,
+					outcomes_count: parsedOutcomes.outcomes.length,
+					gate_result: gateResult,
+				}
+				if (parsedOutcomes.epic) userOutcomesPayload.epic = parsedOutcomes.epic
+				if (parsedOutcomes.validation_warnings && parsedOutcomes.validation_warnings.length > 0) {
+					userOutcomesPayload.validation_warnings = parsedOutcomes.validation_warnings
+				}
+				if (gateResult === 'warn') {
+					userOutcomesPayload.migration_deadline =
+						'## User Outcomes section becomes a hard block in v0.9.0 — add it now, or use the empty-with-note escape (`_No user-observable changes — pure refactor._`) for refactor-only specs.'
+				}
+			}
+
 			// Zero-criteria guard — do NOT silently report ok when there is
 			// nothing to verify. This is the motivating bug: zero criteria
 			// trivially pass unmapped.length === 0, which produced a false
 			// green signal. Treat it as incomplete with an explicit reason.
 			if (criteria.length === 0) {
-				return ok({
-					status: 'incomplete',
-					command: 'coverage-validate',
-					criteria_count: 0,
-					mapped_count: 0,
-					unmapped_criteria: [],
-					coverage: [],
-					subtask_verifications: plan.subtasks.map((st) => ({
-						id: st.id,
-						title: st.title || st.id,
-						verification: st.verification || '',
-						acceptance_criteria: st.acceptance_criteria || [],
-					})),
-					reason: 'no-criteria-found',
-					suggestion:
-						'Add acceptance criteria to spec.md under ## Acceptance Criteria, or add plan.acceptance_criteria to implementation_plan.json',
-					sources_checked: sourcesChecked,
-					spec_path: resolvedSpec.path,
-					autonomy_action: autonomyLevelEarly <= 1 ? 'stop-and-ask' : 'generate-stubs',
-				})
+				return ok(
+					withUserOutcomes(
+						{
+							status: 'incomplete',
+							command: 'coverage-validate',
+							criteria_count: 0,
+							mapped_count: 0,
+							unmapped_criteria: [],
+							coverage: [],
+							subtask_verifications: plan.subtasks.map((st) => ({
+								id: st.id,
+								title: st.title || st.id,
+								verification: st.verification || '',
+								acceptance_criteria: st.acceptance_criteria || [],
+							})),
+							reason: 'no-criteria-found',
+							suggestion:
+								'Add acceptance criteria to spec.md under ## Acceptance Criteria, or add plan.acceptance_criteria to implementation_plan.json',
+							sources_checked: sourcesChecked,
+							spec_path: resolvedSpec.path,
+							autonomy_action: autonomyLevelEarly <= 1 ? 'stop-and-ask' : 'generate-stubs',
+						},
+						userOutcomesPayload,
+					),
+				)
 			}
 
 			// Classify verification methods for each subtask (D-19)
@@ -221,32 +264,71 @@ export function cmdCoverageCheck(subcommand, projectDir, extraArgs) {
 			}
 
 			if (unmapped.length > 0) {
-				return ok({
-					status: 'incomplete',
-					command: 'coverage-validate',
-					criteria_count: criteria.length,
-					mapped_count: mappedCount,
-					unmapped_criteria: unmapped.map((u) => u.criterion),
-					coverage,
-					subtask_verifications: subtaskVerifications,
-					suggestion: 'generate test stubs',
-					autonomy_action: autonomyLevel <= 1 ? 'stop-and-ask' : 'generate-stubs',
-					spec_path: resolvedSpec.path,
-					sources_checked: sourcesChecked,
-				})
+				return ok(
+					withUserOutcomes(
+						{
+							status: 'incomplete',
+							command: 'coverage-validate',
+							criteria_count: criteria.length,
+							mapped_count: mappedCount,
+							unmapped_criteria: unmapped.map((u) => u.criterion),
+							coverage,
+							subtask_verifications: subtaskVerifications,
+							suggestion: 'generate test stubs',
+							autonomy_action: autonomyLevel <= 1 ? 'stop-and-ask' : 'generate-stubs',
+							spec_path: resolvedSpec.path,
+							sources_checked: sourcesChecked,
+						},
+						userOutcomesPayload,
+					),
+				)
 			}
-			return ok({
-				status: 'ok',
-				command: 'coverage-validate',
-				criteria_count: criteria.length,
-				mapped_count: mappedCount,
-				coverage,
-				subtask_verifications: subtaskVerifications,
-				spec_path: resolvedSpec.path,
-				sources_checked: sourcesChecked,
-			})
+			return ok(
+				withUserOutcomes(
+					{
+						status: 'ok',
+						command: 'coverage-validate',
+						criteria_count: criteria.length,
+						mapped_count: mappedCount,
+						coverage,
+						subtask_verifications: subtaskVerifications,
+						spec_path: resolvedSpec.path,
+						sources_checked: sourcesChecked,
+					},
+					userOutcomesPayload,
+				),
+			)
 		}
 		default:
 			return err(`Unknown coverage-check subcommand: ${subcommand}. Available: validate`)
 	}
 }
+
+/**
+ * Attach the `user_outcomes` payload to a coverage-check envelope when
+ * present (i.e. STANDARD/DEEP plan with a spec on disk). QUICK plans
+ * pass `null` and the key is OMITTED from the envelope entirely — Fast
+ * Path Guarantee (ID-08).
+ */
+function withUserOutcomes(envelope, userOutcomesPayload) {
+	if (userOutcomesPayload === null) return envelope
+	return { ...envelope, user_outcomes: userOutcomesPayload }
+}
+
+/**
+ * Read the running kernel's framework version from its own package.json.
+ * Used to gate the `## User Outcomes` missing-header behavior — warn in
+ * v0.8.x, hard-block from v0.9.0 forward. Returns `'0.0.0'` on failure
+ * so the gate fails-soft to warn (callers treat unknown version as
+ * pre-0.9.0).
+ */
+function readFrameworkVersion() {
+	try {
+		const here = dirname(fileURLToPath(import.meta.url))
+		const pkgPath = resolve(here, '..', '..', '..', 'package.json')
+		const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+		return typeof pkg.version === 'string' ? pkg.version : '0.0.0'
+	} catch {
+		return '0.0.0'
+	}
+}

package/src/cli/commands/detect-runtime.mjs

@@ -0,0 +1,143 @@
+/**
+ * commands/detect-runtime.mjs — `apt-tools detect-runtime <projectDir>`.
+ *
+ * Exposes runtime-detect.mjs at the CLI surface so adopters can preview
+ * which driver Aperant will pick for /apt:verify-proof.
+ *
+ * Returns:
+ *   { status: 'ok', command: 'detect-runtime', projectDir,
+ *     runtime: { is_electron, is_tauri, is_nextjs, is_web_frontend, ... },
+ *     selected_driver_id: string | null,
+ *     fallback_attempts: [{ driver_id, reason }] }
+ */
+
+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 { resolveDriver } from '../verify-proof/resolver.mjs'
+import { loadRuntimeCapabilities } from '../verify-proof/runtime-detect.mjs'
+
+/** Default required capabilities — the smallest set that proves a driver is usable. */
+const DEFAULT_REQUIRED_CAPABILITIES = ['screenshot']
+
+/**
+ * Discover every driver manifest bundled with @aperant/framework.
+ * @param {string} frameworkRoot — absolute path to packages/framework or .aperant/deps/.../@aperant/framework
+ * @returns {Array<object>}
+ */
+function discoverBundledDrivers(frameworkRoot) {
+	const dir = join(frameworkRoot, 'drivers')
+	if (!existsSync(dir)) return []
+	const manifests = []
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue
+		const manifestPath = join(dir, entry.name, 'manifest.json')
+		if (!existsSync(manifestPath)) continue
+		try {
+			const parsed = JSON.parse(readFileSync(manifestPath, 'utf-8'))
+			manifests.push({ ...parsed, locality: 'bundled' })
+		} catch {
+			/* skip malformed manifests */
+		}
+	}
+	return manifests
+}
+
+/**
+ * Discover every user-installed driver manifest at .aperant/drivers/.
+ * @param {string} projectDir
+ * @returns {Array<object>}
+ */
+function discoverUserDrivers(projectDir) {
+	const dir = join(projectDir, '.aperant/drivers')
+	if (!existsSync(dir)) return []
+	const manifests = []
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue
+		const manifestPath = join(dir, entry.name, 'manifest.json')
+		if (!existsSync(manifestPath)) continue
+		try {
+			const parsed = JSON.parse(readFileSync(manifestPath, 'utf-8'))
+			manifests.push({ ...parsed, locality: 'user' })
+		} catch {
+			/* skip malformed manifests */
+		}
+	}
+	return manifests
+}
+
+/**
+ * @param {string} projectDir
+ * @param {string[]} [_extra]
+ */
+export function cmdDetectRuntime(projectDir, _extra = []) {
+	if (!projectDir) return err('Usage: apt-tools detect-runtime <project-dir>')
+	const target = resolve(projectDir)
+
+	// Read user config (used both for the monorepo walk + override).
+	let monorepoGlobs
+	let override = []
+	const configPath = join(target, '.aperant/config.json')
+	if (existsSync(configPath)) {
+		try {
+			const cfg = JSON.parse(readFileSync(configPath, 'utf-8'))
+			if (Array.isArray(cfg?.verification?.monorepo_globs)) {
+				monorepoGlobs = cfg.verification.monorepo_globs.filter((x) => typeof x === 'string')
+			}
+			if (Array.isArray(cfg?.verification?.runtimes)) {
+				override = cfg.verification.runtimes.filter((x) => typeof x === 'string')
+			}
+		} catch {
+			/* malformed config — ignore */
+		}
+	}
+
+	// Detect runtime capabilities from project's package.json + (optionally)
+	// monorepo `apps/*` walk. Default behaviour matches the canonical
+	// Aperant layout — adopters opt out via verification.monorepo_globs: [].
+	const runtime = loadRuntimeCapabilities(
+		target,
+		monorepoGlobs !== undefined ? { monorepo_globs: monorepoGlobs } : undefined,
+	)
+
+	// Discover bundled + user drivers.
+	// __dirname-equivalent under ESM: walk up from this file to the framework
+	// package root. 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 = discoverBundledDrivers(frameworkRoot)
+	const user = discoverUserDrivers(target)
+	const drivers = [...bundled, ...user]
+
+	// Try resolving with the default minimum required capability.
+	let selected = null
+	let fallback_attempts = []
+	try {
+		const result = resolveDriver({
+			drivers,
+			runtime,
+			required_capabilities: DEFAULT_REQUIRED_CAPABILITIES,
+			override,
+		})
+		selected = result.selected.driverId
+		fallback_attempts = result.fallback_attempts
+	} catch (resolveErr) {
+		fallback_attempts = resolveErr && Array.isArray(resolveErr.attempts) ? resolveErr.attempts : []
+	}
+
+	return ok({
+		status: 'ok',
+		command: 'detect-runtime',
+		projectDir: target,
+		runtime,
+		discovered_drivers: drivers.map((d) => ({
+			driverId: d.driverId,
+			version: d.version,
+			locality: d.locality,
+		})),
+		selected_driver_id: selected,
+		fallback_attempts,
+	})
+}

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 })),