@aperant/framework 0.8.1 → 0.8.6

package/src/cli/verify-proof/runtime-detect.mjs

@@ -0,0 +1,211 @@
+/**
+ * runtime-detect.mjs — pure project-shape capability detection.
+ *
+ * Extracted from packages/core/src/prompts/prompt-loader.ts:572-595 so the
+ * framework CLI is self-contained (no @aperant/core dep). Same heuristics:
+ * read package.json's dependencies + devDependencies, return a capability
+ * record the resolver can score against.
+ *
+ * Pattern: pure data in → pure data out. No filesystem walking, no exec.
+ * Use loadRuntimeCapabilities(projectDir) for the cwd-rooted variant.
+ *
+ * v0.8.6 — `loadRuntimeCapabilities` now ALSO walks `apps/*` by default
+ * (configurable via the second arg `{monorepo_globs}`) and OR-merges
+ * each match's `package.json` capabilities with the root. The default
+ * `['apps/*']` matches the canonical Aperant monorepo layout; adopters
+ * whose monorepo lives elsewhere (e.g. `packages/apps/*`) pass a
+ * custom `monorepo_globs`. Setting `monorepo_globs: []` disables the
+ * walk entirely (root-only escape hatch).
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+/**
+ * @typedef {Object} RuntimeCapabilities
+ * @property {boolean} is_electron
+ * @property {boolean} is_tauri
+ * @property {boolean} is_nextjs
+ * @property {boolean} is_nuxt
+ * @property {boolean} is_web_frontend
+ * @property {boolean} is_expo
+ * @property {boolean} is_react_native
+ * @property {boolean} has_node
+ */
+
+/** A capability record with every flag defaulted to false. */
+function emptyCapabilities() {
+	return {
+		is_electron: false,
+		is_tauri: false,
+		is_nextjs: false,
+		is_nuxt: false,
+		is_web_frontend: false,
+		is_expo: false,
+		is_react_native: false,
+		has_node: false,
+	}
+}
+
+/**
+ * Detect runtime capabilities from a parsed package.json object.
+ *
+ * @param {Record<string, unknown> | null} packageJson
+ * @returns {RuntimeCapabilities}
+ */
+export function detectFromPackageJson(packageJson) {
+	const capabilities = emptyCapabilities()
+	if (packageJson === null || typeof packageJson !== 'object') return capabilities
+
+	const allDeps = {
+		...(packageJson.dependencies ?? {}) /** @type {Record<string,string>} */,
+		...(packageJson.devDependencies ?? {}) /** @type {Record<string,string>} */,
+	}
+	const deps = new Set(Object.keys(allDeps).map((k) => k.toLowerCase()))
+
+	if (deps.has('electron') || [...deps].some((d) => d.startsWith('@electron'))) {
+		capabilities.is_electron = true
+	}
+	if (deps.has('@tauri-apps/api') || deps.has('tauri')) {
+		capabilities.is_tauri = true
+	}
+	if (deps.has('expo')) capabilities.is_expo = true
+	if (deps.has('react-native')) capabilities.is_react_native = true
+
+	// Web frontends — react/vue/svelte/angular/solid → frontend. BUT: an
+	// Electron app commonly bundles React as its renderer; in that case the
+	// runtime is "electron", not "web_frontend". Electron + react-native +
+	// expo + tauri all win over the web flag.
+	const isNativeContainer =
+		capabilities.is_electron ||
+		capabilities.is_tauri ||
+		capabilities.is_react_native ||
+		capabilities.is_expo
+	const webFrameworks = ['react', 'vue', 'svelte', 'angular', 'solid']
+	if (!isNativeContainer && webFrameworks.some((f) => deps.has(f))) {
+		capabilities.is_web_frontend = true
+	}
+
+	if (deps.has('next')) {
+		capabilities.is_nextjs = true
+		capabilities.is_web_frontend = true
+	}
+	if (deps.has('nuxt')) {
+		capabilities.is_nuxt = true
+		capabilities.is_web_frontend = true
+	}
+	if (deps.has('vite') && !isNativeContainer) {
+		capabilities.is_web_frontend = true
+	}
+
+	// Node-ish? Anything with a package.json + an entry point counts.
+	if (typeof packageJson.main === 'string' || typeof packageJson.module === 'string') {
+		capabilities.has_node = true
+	}
+	if (!capabilities.has_node && packageJson.scripts && typeof packageJson.scripts === 'object') {
+		capabilities.has_node = true
+	}
+
+	return capabilities
+}
+
+/**
+ * Load and detect capabilities from a project directory's package.json.
+ * v0.8.6 — also walks `monorepo_globs` (default `['apps/*']`) and
+ * OR-merges each match's capabilities with the root.
+ *
+ * @param {string} projectDir
+ * @param {{monorepo_globs?: string[]}} [opts]
+ * @returns {RuntimeCapabilities}
+ */
+export function loadRuntimeCapabilities(projectDir, opts) {
+	const root = resolve(projectDir)
+	const rootPkgPath = join(root, 'package.json')
+	let rootCaps = emptyCapabilities()
+	if (existsSync(rootPkgPath)) {
+		try {
+			rootCaps = detectFromPackageJson(JSON.parse(readFileSync(rootPkgPath, 'utf-8')))
+		} catch {
+			/* fall through with empty caps */
+		}
+	}
+
+	// Default to the canonical Aperant monorepo layout. Passing `[]`
+	// disables the walk entirely (root-only escape hatch per spec ID-05).
+	const globs = opts && Array.isArray(opts.monorepo_globs) ? opts.monorepo_globs : ['apps/*']
+	if (globs.length === 0) return rootCaps
+
+	let merged = rootCaps
+	for (const glob of globs) {
+		const matches = expandSimpleGlob(root, glob)
+		for (const dir of matches) {
+			const childPkgPath = join(dir, 'package.json')
+			if (!existsSync(childPkgPath)) continue
+			try {
+				const childCaps = detectFromPackageJson(JSON.parse(readFileSync(childPkgPath, 'utf-8')))
+				merged = orMergeCapabilities(merged, childCaps)
+			} catch {
+				/* skip malformed package.json */
+			}
+		}
+	}
+	return merged
+}
+
+/**
+ * Expand a simple `prefix/*` glob against the root. Supports ONLY the
+ * `<dir>/*` shape (matches each direct subdirectory of `<dir>`). Other
+ * glob syntax is intentionally rejected — v1 keeps the dep surface
+ * small. Fails closed on malformed patterns (returns []).
+ *
+ * @param {string} root
+ * @param {string} glob
+ * @returns {string[]}
+ */
+function expandSimpleGlob(root, glob) {
+	if (typeof glob !== 'string' || !glob.endsWith('/*')) return []
+	const prefix = glob.slice(0, -2)
+	if (prefix.length === 0 || prefix.includes('*')) return []
+	const dir = join(root, prefix)
+	if (!existsSync(dir)) return []
+	let entries
+	try {
+		entries = readdirSync(dir)
+	} catch {
+		return []
+	}
+	const matches = []
+	for (const name of entries) {
+		const sub = join(dir, name)
+		try {
+			if (statSync(sub).isDirectory()) matches.push(sub)
+		} catch {
+			/* skip unreadable entries */
+		}
+	}
+	return matches
+}
+
+/**
+ * Boolean OR-merge of two capability records. Any flag true in either
+ * input is true in the output. The "Electron wins over web" rule from
+ * `detectFromPackageJson` is preserved when this is called repeatedly —
+ * each child's flags are honest about that child's own shape, and the
+ * OR-merge just unions them.
+ *
+ * @param {RuntimeCapabilities} a
+ * @param {RuntimeCapabilities} b
+ * @returns {RuntimeCapabilities}
+ */
+function orMergeCapabilities(a, b) {
+	return {
+		is_electron: a.is_electron || b.is_electron,
+		is_tauri: a.is_tauri || b.is_tauri,
+		is_nextjs: a.is_nextjs || b.is_nextjs,
+		is_nuxt: a.is_nuxt || b.is_nuxt,
+		is_web_frontend: a.is_web_frontend || b.is_web_frontend,
+		is_expo: a.is_expo || b.is_expo,
+		is_react_native: a.is_react_native || b.is_react_native,
+		has_node: a.has_node || b.has_node,
+	}
+}

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

@@ -0,0 +1,187 @@
+/**
+ * trust.mjs — driver trust enforcement (TOFU lock + policy file + decision).
+ *
+ * Implements ID-03:
+ *   - 4 trust tiers: first_party_signed (default-allow), community_verified,
+ *     community_unverified, local_unverified.
+ *   - Default policy: only first_party_signed auto-runs.
+ *   - Non-first-party drivers require one-time user approval; approval is
+ *     bound to a TOFU lock at .aperant/driver-tofu.json keyed by
+ *     {driver_id, version, manifest_sha256, artifact_digest}. Any drift
+ *     re-prompts.
+ *
+ * The audit log (audit.mjs) writes one line per decision (allow/deny).
+ * The execution layer (exec.mjs) enforces structured-only local_command.
+ *
+ * This module is decision-only: it does NOT prompt the user. The caller
+ * (workflow runner / apt-tools driver doctor) decides whether to invoke
+ * the prompt UX, then calls recordApproval() to persist the TOFU entry.
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+/**
+ * @typedef {import('@aperant/framework/driver-sdk').DriverManifest} DriverManifest
+ */
+
+const TOFU_PATH = '.aperant/driver-tofu.json'
+const POLICY_PATH = '.aperant/policy.json'
+
+/**
+ * Compute a stable manifest hash for TOFU + audit lines.
+ * @param {DriverManifest} manifest
+ * @returns {string}
+ */
+export function manifestSha256(manifest) {
+	const stable = JSON.stringify(manifest, Object.keys(manifest).sort())
+	return createHash('sha256').update(stable).digest('hex')
+}
+
+/**
+ * Read the TOFU lock file. Returns an empty object if missing or malformed.
+ * @param {string} projectDir
+ * @returns {Record<string, {manifest_sha256: string, artifact_digest?: string, approved_at: string, trust_tier: string}>}
+ */
+export function readTofuLock(projectDir) {
+	const path = join(resolve(projectDir), TOFU_PATH)
+	if (!existsSync(path)) return {}
+	try {
+		return JSON.parse(readFileSync(path, 'utf-8'))
+	} catch {
+		return {}
+	}
+}
+
+/**
+ * Persist a TOFU lock file (atomic-ish: write + rename not used since we
+ * append-only to a tiny JSON; conflicting writes from parallel agents
+ * would clobber an entry but `.aperant/driver-tofu.json` is per-project,
+ * not per-agent).
+ *
+ * @param {string} projectDir
+ * @param {Record<string, unknown>} tofu
+ */
+export function writeTofuLock(projectDir, tofu) {
+	const path = join(resolve(projectDir), TOFU_PATH)
+	mkdirSync(dirname(path), { recursive: true })
+	writeFileSync(path, JSON.stringify(tofu, null, 2) + '\n', 'utf-8')
+}
+
+/**
+ * Build the canonical TOFU key for a (driver, version) pair. The hash is
+ * NOT part of the key — the value's manifest_sha256 + artifact_digest
+ * detect drift.
+ * @param {string} driverId
+ * @param {string} version
+ * @returns {string}
+ */
+export function tofuKey(driverId, version) {
+	return `${driverId}@${version}`
+}
+
+/**
+ * Read the project's policy file. Returns the default policy if missing.
+ * @param {string} projectDir
+ * @returns {{mode: 'first_party_only' | 'allowlist', allowed: string[], denied: string[]}}
+ */
+export function readPolicy(projectDir) {
+	const path = join(resolve(projectDir), POLICY_PATH)
+	const defaults = { mode: 'first_party_only', allowed: [], denied: [] }
+	if (!existsSync(path)) return defaults
+	try {
+		const parsed = JSON.parse(readFileSync(path, 'utf-8'))
+		return {
+			mode: parsed.mode === 'allowlist' ? 'allowlist' : 'first_party_only',
+			allowed: Array.isArray(parsed.allowed) ? parsed.allowed : [],
+			denied: Array.isArray(parsed.denied) ? parsed.denied : [],
+		}
+	} catch {
+		return defaults
+	}
+}
+
+/**
+ * Decide whether a driver invocation is allowed.
+ *
+ * @param {DriverManifest} manifest
+ * @param {ReturnType<typeof readTofuLock>} tofu
+ * @param {ReturnType<typeof readPolicy>} policy
+ * @returns {{decision: 'allow' | 'deny' | 'requires_approval', reason: string, expected_manifest_sha256?: string}}
+ */
+export function decide(manifest, tofu, policy) {
+	const tier = manifest.trust?.tier
+	const driverId = manifest.driverId
+	const version = manifest.version
+
+	// Policy denylist always wins.
+	if (policy.denied.includes(driverId)) {
+		return { decision: 'deny', reason: `policy denies driver ${driverId}` }
+	}
+
+	// first_party_signed: default-allow under either policy mode (unless
+	// explicitly denied above).
+	if (tier === 'first_party_signed') {
+		return { decision: 'allow', reason: 'first_party_signed driver — default allow' }
+	}
+
+	// first_party_only mode blocks every other tier.
+	if (policy.mode === 'first_party_only') {
+		return {
+			decision: 'deny',
+			reason: `policy.mode=first_party_only blocks ${tier} driver`,
+		}
+	}
+
+	// allowlist mode: require explicit allow entry AND a valid TOFU lock.
+	if (!policy.allowed.includes(driverId)) {
+		return {
+			decision: 'deny',
+			reason: `policy.mode=allowlist but ${driverId} not in allowed[]`,
+		}
+	}
+
+	// Check TOFU lock.
+	const key = tofuKey(driverId, version)
+	const entry = tofu[key]
+	const currentHash = manifestSha256(manifest)
+
+	if (!entry) {
+		return {
+			decision: 'requires_approval',
+			reason: `no TOFU entry for ${key} — first run requires approval`,
+			expected_manifest_sha256: currentHash,
+		}
+	}
+
+	if (entry.manifest_sha256 !== currentHash) {
+		return {
+			decision: 'requires_approval',
+			reason: `TOFU manifest_sha256 drift for ${key} — driver changed since approval, re-prompt required`,
+			expected_manifest_sha256: currentHash,
+		}
+	}
+
+	return { decision: 'allow', reason: `TOFU entry valid for ${key}` }
+}
+
+/**
+ * Persist a one-time approval for a (driver, version) pair into the TOFU
+ * lock. The caller is responsible for actually prompting the user; this
+ * function just writes the entry.
+ *
+ * @param {string} projectDir
+ * @param {DriverManifest} manifest
+ */
+export function recordApproval(projectDir, manifest) {
+	const tofu = readTofuLock(projectDir)
+	const key = tofuKey(manifest.driverId, manifest.version)
+	tofu[key] = {
+		manifest_sha256: manifestSha256(manifest),
+		artifact_digest: manifest.trust?.integrity?.artifact_digest,
+		approved_at: new Date().toISOString(),
+		trust_tier: manifest.trust?.tier,
+	}
+	writeTofuLock(projectDir, tofu)
+}

package/templates/adr-format.md

@@ -1,11 +1,3 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/ADR-FORMAT.md
-Licensed under MIT. Modifications: ported as the Aperant ADR template
-emitted by `apt-tools adr write` with Nygard's 3-gate filter
-(hard-to-reverse AND surprising-without-context AND real-trade-off).
--->
-
 # ADR-NNNN: {Title}
 
 **Status:** {Proposed | Accepted | Deprecated | Superseded}

package/templates/aperant-claude-md-appendix.md

@@ -1,6 +1,6 @@
 This project uses the [Aperant Framework](https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework) for AI-assisted development.
 
-### Fast Path Guarantee (Pocock adoption ID-05)
+### Fast Path Guarantee
 
 QUICK track is **hard-exempt** from PRD-shaped spec.md, HITL/AFK metadata,
 vertical-slice subtask schema, TDD iron law (`apt:execute --tdd`), triage

package/templates/context-format.md

@@ -1,15 +1,7 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md
-Licensed under MIT. Modifications: ported as the Aperant CONTEXT.md
-template emitted by `apt-tools context write`. Adds the "Project glossary"
-header and example dialogue section.
--->
-
 # Project glossary (CONTEXT.md)
 
 This file is the persistent project glossary. Each term-block carries the
-following fields per Pocock's CONTEXT.md format:
+following fields per the Aperant CONTEXT.md format:
 
 - **{Term}** — definition (one line).
   - **Aliases to avoid:** comma-separated synonyms or near-synonyms that

package/templates/proof-verification.md

@@ -18,7 +18,17 @@ JSON schema reference for `.aperant/proof/{app}/{date}/{run}/verification.json`
     "updated": "{ISO timestamp}",
     "spec": "{spec.md path or task description}",
     "verdict": "pending | approved | approved_with_notes | rejected",
-    "tools": ["electron", "puppeteer", "cdp_video"]
+    "tools": ["electron", "puppeteer", "cdp_video"],
+    "selected_driver": {
+      "driverId": "electron",
+      "version": "0.1.0",
+      "manifest_sha256": "abc123...",
+      "trust_tier": "first_party_signed",
+      "sandbox_profile": "workspace_write"
+    },
+    "fallback_attempts": [
+      { "driver_id": "browser", "reason": "missing required capabilities: dump_state" }
+    ]
   },
 
   "automated_checks": {
@@ -43,7 +53,13 @@ JSON schema reference for `.aperant/proof/{app}/{date}/{run}/verification.json`
     "tested_count": 0,
     "skipped_count": 0,
     "percent": 0,
-    "gate_result": "pass | warn | block"
+    "gate_result": "pass | warn | block",
+    "by_surface": {
+      "electron": { "tested": 0, "total": 0 },
+      "web": { "tested": 0, "total": 0 },
+      "cli": { "tested": 0, "total": 0 },
+      "api": { "tested": 0, "total": 0 }
+    }
   },
 
   "tests": [
@@ -51,14 +67,33 @@ JSON schema reference for `.aperant/proof/{app}/{date}/{run}/verification.json`
       "id": "TEST-01",
       "registry_id": "terminals-grid-auto-tile",
       "name": "Three Terminal Grid Auto-Tile",
+      "outcome_id": "O3",
+      "surface": "electron",
+      "transport": "mcp",
       "precondition": "2 terminals active",
       "action": "Press Cmd+T",
       "expected": "Grid reflows to 2+1 layout",
       "actual": "Grid correctly tiled to 2+1",
-      "evidence": "screenshots/03-grid.png",
+      "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",
       "severity": null
+    },
+    {
+      "id": "TEST-02",
+      "registry_id": "settings-theme-picker",
+      "name": "Theme picker — cross-surface",
+      "outcome_id": "O5",
+      "surface": "web",
+      "transport": "skill",
+      "precondition": "App loaded in web shell",
+      "action": "Click 'Dark mode' in the theme picker",
+      "expected": "Background flips to dark; persists across reload",
+      "actual": "Dark mode applied, persisted across reload",
+      "evidence": "web/screenshots/05-dark-mode.png",
+      "analysis": "Screenshot shows app body with #111 background, all text legible on dark surface. After reload, dark mode is still active — localStorage entry confirmed.",
+      "result": "pass",
+      "severity": null
     }
   ],
 
@@ -66,8 +101,8 @@ JSON schema reference for `.aperant/proof/{app}/{date}/{run}/verification.json`
     {
       "registry_id": "terminals-settings-scrollback-slider",
       "name": "Scrollback buffer slider",
-      "reason": "blocked_by_platform",
-      "detail": "Slider interaction not supported via current MCP tools"
+      "reason": "unsatisfied_optional_capability",
+      "detail": "Selected driver does not implement the IDL verb required for slider interaction"
     }
   ],
 
@@ -149,7 +184,9 @@ JSON schema reference for `.aperant/proof/{app}/{date}/{run}/verification.json`
 | `updated` | string | OVERWRITE | ISO timestamp, updated on every write |
 | `spec` | string | IMMUTABLE | Path to spec or task description |
 | `verdict` | string | OVERWRITE | Derived from dimension scores after all tests |
-| `tools` | array | IMMUTABLE | MCP tools detected as available |
+| `tools` | array | IMMUTABLE | MCP tools / auxiliary capture tools detected as available |
+| `selected_driver` | object | IMMUTABLE | The verify-proof driver chosen by the resolver per ID-02. Fields: `driverId`, `version`, `manifest_sha256`, `trust_tier`, `sandbox_profile`. |
+| `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.
@@ -163,6 +200,7 @@ Each check has `status` (pass/fail) and `output` (captured terminal output). The
 | `skipped_count` | number | Number of entries in the skipped array |
 | `percent` | number | `tested_count / registered_count * 100` |
 | `gate_result` | string | `block` if < 50%, `warn` if < 80%, `pass` if >= 80% |
+| `by_surface` | object | v0.8.6 — per-surface rollup. Each surface key (`electron`, `web`, `cli`, `api`) maps to `{tested, total}` so reviewers can tell which surface fell short. |
 
 ### tests
 Each test entry tracks one sub-feature verification. Fields:
@@ -172,11 +210,14 @@ Each test entry tracks one sub-feature verification. Fields:
 | `id` | string | IMMUTABLE | Sequential ID: TEST-01, TEST-02, etc. |
 | `registry_id` | string | IMMUTABLE | Must match a sub-feature `id` from `.aperant/features/{area}.json` |
 | `name` | string | IMMUTABLE | Human-readable test name |
+| `outcome_id` | string | IMMUTABLE | v0.8.6 — positional ID from `## User Outcomes` (e.g. `O1`, `O2`). Synthesized by `parseUserOutcomes`; passed through verbatim by `resolveDriversForOutcomes`. Optional for legacy specs without `## User Outcomes`. |
+| `surface` | string | IMMUTABLE | v0.8.6 — one of `electron | web | cli | api`. Drives the per-surface screenshot path and the `coverage.by_surface` rollup. Cross-surface outcomes (`[electron+web]`) produce TWO test entries with the same `outcome_id` and different `surface` values. |
+| `transport` | string | OVERWRITE | v0.8.6 — `skill | mcp | binary | http`. Populated by the workflow runner from the dispatcher's directive (per Step 7a of `workflows/verify-proof.md`). For browser-driver web outcomes on Skill-capable hosts the value is `"skill"`; on legacy MCP hosts it falls back to `"mcp"`. |
 | `precondition` | string | IMMUTABLE | What must be true before testing |
 | `action` | string | IMMUTABLE | Specific action to perform |
 | `expected` | string | IMMUTABLE | Specific observable result expected |
 | `actual` | string | OVERWRITE | What actually happened (filled after testing) |
-| `evidence` | string | OVERWRITE | Screenshot filename or video timestamp |
+| `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` |
 | `severity` | string/null | OVERWRITE | `blocker`, `major`, `minor`, `cosmetic`, or `null` if pass |
@@ -188,9 +229,11 @@ Every registered sub-feature that does NOT have a test MUST appear here. Silence
 |-------|------|-------------|
 | `registry_id` | string | The sub-feature `id` from the feature registry |
 | `name` | string | Human-readable name of the skipped feature |
-| `reason` | string | One of: `time_constraint`, `blocked_by_platform`, `depends_on_other`, `not_applicable` |
+| `reason` | string | One of: `time_constraint`, `unsatisfied_optional_capability` (preferred), `depends_on_other`, `not_applicable`. **Legacy alias:** `blocked_by_platform` is read by the schema reader as an alias for `unsatisfied_optional_capability` and emits a deprecation warning. New writes MUST use the new reason. |
 | `detail` | string | Brief explanation of why this feature was skipped |
 
+> **Fail-closed, not a skip.** If a REQUIRED IDL capability has no implementing driver in the resolver chain, the resolver throws `unsatisfied_required_capability` (per ID-02) — aborts the run. That entry does NOT land in `skipped[]`; coverage loss is loud, deliberate, and audited via `meta.fallback_attempts[]`.
+
 ### dimensions
 Four QA dimensions, each with `score` (1-10) and `rationale` (string). Scores are evidence-based, never assumed.