@aperant/framework 0.8.4 → 0.8.7

package/skills/apt-research/appendices/domain-tools.md

@@ -0,0 +1,236 @@
+# Domain Tools, Gates, and Output Templates
+
+> Per-domain tool surface, reasoning gates, and synthesis output template.
+> Load when domain has been detected (Step 1d) or when synthesizing
+> (Step 10).
+
+The four domains are detected from the user's question in Step 1d and
+recorded as immutable in `research-spec.md ## Domain`. The detected
+domain determines which tools each `apt-researcher` role gets, which
+reasoning steps are enabled, and what shape the final `RESEARCH.md`
+output takes.
+
+## Domain detection signals
+
+| Domain | Signals | Examples |
+|---|---|---|
+| **mechanistic** | physics, math, distributed systems, algorithms, deterministic engineering systems with provable behavior | "how does Raft handle leader election", "what does axle stiffness do to chassis dynamics", "is this algorithm O(log n)" |
+| **empirical** | medicine, biology, nutrition, psychology, public-health, social science, anything where human variation dominates and replication matters | "does intermittent fasting cause muscle loss", "what's the effect of X on Y in older adults", "is supplement X effective" |
+| **strategic** | tool/vendor comparison, market analysis, license/contract evaluation, anything where the answer depends on vendor disclosure + ecosystem health | "best embedded DB for offline-first 2026", "should we pick Vitest or Bun test", "is Turso safe to depend on" |
+| **general** | catch-all when none of the above fit; usually broad knowledge questions or framing-questions | "what is consensus in distributed systems", "explain bitemporal databases" |
+
+Ambiguous question → `general`. The user can override with explicit
+flag (future: `--domain <name>`); for v1, signal-based detection is
+authoritative.
+
+## Per-domain tool surface
+
+Each `apt-researcher` role gets the base tools (Read, Grep, Glob,
+WebSearch, WebFetch, Context7) PLUS the domain extras below.
+
+### mechanistic
+
+| Tool | How invoked | Used by |
+|---|---|---|
+| arxiv search | `curl "http://export.arxiv.org/api/query?search_query=..."` | Retriever |
+| PDF reader | `curl -o /tmp/x.pdf {url} && pdftotext /tmp/x.pdf -` | Builder, Skeptic, Retriever |
+| Wolfram Alpha (if API key set) | `curl "https://api.wolframalpha.com/v2/query?..."` | Builder, Skeptic |
+
+First-principles derivation: **ENABLED**. Builder and Skeptic may
+produce derivations grounded in domain theory. Judge accepts them
+into `claims.json` at `source_tier: derived-theory` (weight 0.6
+in `uncertainty` formula).
+
+### empirical
+
+| Tool | How invoked | Used by |
+|---|---|---|
+| Crossref DOI resolve | `curl "https://api.crossref.org/works/{doi}"` | Retriever, citation audit |
+| PubMed E-utilities | `curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=..."` | Retriever |
+| PMC full-text fetch | `curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=pmc&id={pmcid}"` | Builder, Skeptic |
+| Europe PMC fallback | `curl "https://www.ebi.ac.uk/europepmc/webservices/rest/search?query=..."` | Retriever |
+
+First-principles derivation: **DEMOTED**. Builder/Skeptic may invoke
+theory (mechanism, leucine threshold, etc.) but Judge demotes the
+output to `source_tier: hypothesis` (weight 0.1). Hypotheses cannot
+reach `confidence: high` regardless of how compelling the reasoning
+sounds — only empirical evidence at `tier ≥ independent-test` can
+elevate a claim to `high`.
+
+Citation audit is **MANDATORY** every iteration (not every N) in
+empirical domains. Every new citation MUST be DOI/PMID-verified
+via Crossref or NCBI before promotion to `sources.json`. Failures
+go straight to `suspect-citations.md` and the claim depending on
+them is downgraded.
+
+### strategic
+
+| Tool | How invoked | Used by |
+|---|---|---|
+| GitHub releases | `gh release list -R {owner}/{repo} --limit 20` | Retriever |
+| GitHub code search | `gh search code "..." --limit 20` | Retriever, Skeptic |
+| License fetch | `gh api repos/{owner}/{repo}/license` or WebFetch raw LICENSE | Retriever |
+| Changelog fetch | WebFetch `CHANGELOG.md` or `gh api repos/{owner}/{repo}/contents/CHANGELOG.md` | Retriever |
+| Package metadata | `npm view {pkg} --json` / `pip show {pkg} --verbose` / `cargo search {pkg}` | Retriever |
+
+First-principles derivation: **DISABLED**. "Derive whether libSQL is
+stable from theory" is nonsense. Builder is instructed to synthesize
+from sources only. If Builder produces a derivation-shaped output,
+Judge rejects it with `## reason: derivation invalid in strategic domain`.
+
+Vendor-only evidence is a spar trigger (see `overnight-loop.md`
+§spar-triggers). Strategic domain treats vendor-doc as
+`source_tier: vendor-doc` (weight 0.5) — NOT a high tier.
+
+### general
+
+Default tool surface. First-principles is **SOFT-ENABLED with
+hypothesis demotion** — Builder/Skeptic may derive but Judge
+demotes to `hypothesis` until empirical or primary-doc evidence
+elevates the claim.
+
+## Output gates (Step 10 — synthesis)
+
+The synthesis template in `RESEARCH.md` has a common core (defined in
+the main SKILL.md `## 10. Synthesize`) PLUS domain-specific sections.
+
+### mechanistic
+
+Add:
+
+```markdown
+## First-principles derivations
+
+For each derivation accepted into the claim graph at
+`source_tier: derived-theory`:
+
+- **{derivation name}** — claim {C-id}
+  - Premises: {what we assumed}
+  - Steps: {compact derivation}
+  - Cross-check vs sources: {which sources confirm/contradict the derivation}
+  - Failure mode: {when does this derivation break?}
+```
+
+If a derivation contradicts an empirical source, the derivation is
+flagged as bounded — Judge MUST note the boundary condition.
+
+### empirical
+
+Add (mandatory, non-negotiable):
+
+```markdown
+## Not medical / financial / safety advice
+
+This research synthesis is informational. It is not a substitute for
+professional advice from a licensed clinician, financial advisor, or
+safety expert. Individual circumstances vary; outcomes that apply to
+populations may not apply to any specific person.
+
+## What this CAN'T tell you
+
+- {Specific question the evidence does not address}
+- {Specific population the evidence does not cover}
+- {Specific interaction or confounder the evidence cannot resolve}
+
+## Quality of evidence
+
+For each cited study supporting a critical claim:
+
+| Source | Design | n | Peer-reviewed | Replicated | Notes |
+|---|---|---|---|---|---|
+| {S-id} | {RCT/cohort/meta} | {n} | {yes/no} | {yes/no/unknown} | {note} |
+```
+
+Imperatives in the synthesis prose ("you should…", "do X", "avoid Y")
+are STRIPPED by Judge. Empirical synthesis uses descriptive language
+("evidence suggests…", "in the populations studied…").
+
+If the synthesis would recommend a course of action affecting health,
+finance, or safety, Judge inserts: "**Discuss with a qualified
+professional before acting on this synthesis.**"
+
+### strategic
+
+Add (mandatory):
+
+```markdown
+## Conditional-tree recommendation
+
+```
+if {decision-relevant condition A}:
+  → recommend {Option X}
+  → reason: {1-line}
+elif {decision-relevant condition B}:
+  → recommend {Option Y}
+  → reason: {1-line}
+else:
+  → no clear winner — {what's the unresolved question}
+```
+
+## Vendor-claim conflicts
+
+For each option where evidence is vendor-only or vendors disagree:
+
+- **{Option}** — {dimension}
+  - Vendor claim: {what the vendor says}
+  - Independent confirmation: {available | NOT AVAILABLE}
+  - Risk if vendor claim is wrong: {what breaks}
+
+## Decision blockers
+
+Questions only the user can answer that change the recommendation:
+
+- {Question} — affects: {which option(s)}
+```
+
+Single-winner output is **REJECTED** by Judge when evidence is
+vendor-only across the deciding dimension. The skill produces a
+conditional tree or explicit "no clear winner" — never a confident
+universal recommendation in those cases.
+
+### general
+
+Add:
+
+```markdown
+## Outstanding gaps
+
+- {Open question that the synthesis does not close}
+
+## Recommended next reads
+
+- {Source} — covers {what aspect}
+```
+
+## Mode-specific additions (orthogonal to domain)
+
+Applied AFTER the domain gates. From the main SKILL.md `## 10.
+Synthesize`, repeated here for the per-domain reader:
+
+- **UNDERSTAND** → mental model section with mechanism + analogy
+- **VERIFY** → verdict line (`confirmed | partially confirmed | false |
+  contested | unknown`)
+- **SOLVE** → candidate approaches table + `## Falsification status`.
+  For code-domain SOLVE: blocks `CONVERGED` if no falsification was
+  run (test / simulator / model-checker / formal-method sketch).
+  Force STALLED with `## Cannot certify without falsification` and
+  enumerate what falsification harness would be needed.
+- **COMPARE** → dimensions × options matrix + per-cell evidence
+  pointers (conditional-tree comes from the strategic domain gate)
+
+## Tool-surface fallbacks
+
+If a domain tool is unavailable in the current environment (e.g.
+`gh` not installed, no network access for Crossref), the affected
+role MUST report this in its output:
+
+```
+## Tool unavailable
+- {tool name}: {why unavailable}
+- Impact on this iteration: {what could not be done}
+```
+
+Judge records the missing capability in `iteration-log.md` and adjusts
+stop-state evaluation: a STALLED verdict resulting from missing tools
+gets `## Cannot resolve without` annotated with "tool {X} unavailable
+in this environment". The user can resolve and `--resume`.

package/skills/apt-spar/SKILL.md

@@ -47,7 +47,7 @@ Termination posture (v1.1, amending SPAR-06): the termination headline is in-con
 
 **Reads:**
 - `AGENTS.md` — project constitution (principles, conventions, tech stack)
-- `.aperant/config.json` — `router.llm.providers` for partner fallback (read-only)
+- `.aperant/config.json` — `router.llm.providers` for partner fallback (read-only). **NOTE:** `router.llm.providers.<id>.model` is NOT consulted for spar partner model selection — partner CLIs inherit their own native config (codex: `~/.codex/config.toml`; gemini: `GEMINI_MODEL` env / `~/.gemini/settings.json`). The `router.llm.providers` keys serve the cheap LLM-router classifier, a separately scoped reserved surface (see `packages/framework/src/types/config.ts:222-238`); do not conflate.
 - `.aperant/state.json` — `active_task` framing, optional
 - The live conversation transcript (when `[topic]` is empty)
 
@@ -133,7 +133,7 @@ Do NOT proceed; self-sparring is sycophancy by construction (the host cannot obj
 
 1. **Rung 1 — MCP tool** (`mcp__<partner>-mcp__*`, e.g. `mcp__codex-mcp__codex`). Detected if the host exposes its deferred-tool manifest via `CLAUDE_MCP_DEFERRED_TOOLS` and the tool is registered. When `detected: "runtime-host-only"` the framework process cannot probe the host's tool registry from outside — treat as candidate and attempt the tool call; if the tool is genuinely unavailable in the host's visible registry, fall through to rung 2.
 2. **Rung 2 — Plugin shim** (`${CLAUDE_PLUGIN_ROOT}/scripts/<partner>-companion.mjs`). Codex only (claude / gemini have no plugin shim).
-3. **Rung 3 — Raw CLI on `$PATH`** (`codex exec`, `claude -p`, `gemini -m`).
+3. **Rung 3 — Raw CLI on `$PATH`** (`codex exec`, `claude -p`, `gemini`).
 
 Walk the ladder in order; pick the first rung with `detected: true` (or `"runtime-host-only"` for MCP). **MCP rung has a hard timeout** — default 900000ms (15 min), configurable via `apt-spar.mcp_timeout_ms` in `.aperant/config.json`. The MCP rung is a structured tool call, NOT a Bash invocation, so the Bash tool's 600000ms ceiling does NOT apply — the MCP rung can carry heavy-research partner runs (e.g. Claude Code partner doing multiple minutes of Read/Grep/Bash) where the Bash rungs would hit the host ceiling. On MCP timeout, **automatically fall through to rung 2 or rung 3** — do NOT fail the whole spar. Treat MCP timeout as "rung unavailable for this invocation."
 
@@ -183,20 +183,32 @@ The table below shows the canonical command shape per (partner × rung); the act
 
 | Partner | Rung | Command | Notes |
 |---|---|---|---|
-| codex | mcp | tool call: `mcp__codex-mcp__codex({prompt})` | Preferred. 900000ms (15 min) timeout (configurable `apt-spar.mcp_timeout_ms`); on timeout fall through to plugin then CLI. |
-| codex | plugin | `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | **NO `--write`. NO `--effort` override.** Per SPAR-04 — spar is conversation, not patching. |
-| codex | cli | `codex exec "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | Precedent: `apt-pr-review/SKILL.md:1084`. Verify with `codex --help`. |
+| codex | mcp | tool call: `mcp__codex-mcp__codex({prompt, model})` where `model` is parsed from `~/.codex/config.toml`'s `model = "<value>"` line (see §5a below). | Preferred. 900000ms (15 min) timeout (configurable `apt-spar.mcp_timeout_ms`); on timeout fall through to plugin then CLI. If `~/.codex/config.toml` is missing OR the `model =` line is absent/unparseable, treat MCP rung as UNAVAILABLE and fall through to plugin/CLI — never invent a default model (the MCP server's built-in fallback is stale `gpt-5.3-codex`, which is exactly the bug we are fixing). |
+| codex | plugin | `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | No `--model` flag — `codex-companion.mjs` invokes `codex exec` which inherits `~/.codex/config.toml` automatically. **NO `--write`. NO `--effort` override.** Per SPAR-04 — spar is conversation, not patching. |
+| codex | cli | `codex exec "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | Precedent: `apt-pr-review/SKILL.md:1084`. No `--model` flag — `codex exec` inherits `~/.codex/config.toml` automatically. Verify with `codex --help`. |
 | claude | mcp | tool call: `mcp__claude-code-mcp__claude_code({prompt})` | Preferred. Same 900000ms (15 min) timeout + fallthrough rule. |
 | claude | plugin | n/a | No plugin shim exists for Claude. Skip this rung. |
 | claude | cli | `claude -p "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)" --output-format text` | Symmetric. Claude has no `--write` equivalent — asymmetric flags are a smell. |
 | gemini | mcp | tool call: `mcp__gemini-mcp__*({prompt})` | Preferred. Same 900000ms (15 min) timeout + fallthrough rule. Any `mcp__gemini-mcp__*` tool satisfies the rung. |
 | gemini | plugin | n/a | No plugin shim exists for Gemini. Skip this rung. |
-| gemini | cli | `gemini -m <model-from-router.llm.providers.gemini-cli> "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | Read the exact model name from `.aperant/config.json` at runtime — do not hardcode. |
+| gemini | cli | `gemini "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | No `-m` flag — gemini-cli resolves model via `--model` > `GEMINI_MODEL` env > `~/.gemini/settings.json` > built-in default per `docs/cli/model-routing.md:47-58`. Drop the flag, let the cascade work; users override per-shell via `GEMINI_MODEL=...` or per-project via `settings.json`. |
 
 Set the Bash tool's `timeout` parameter to `--timeout-ms` (default 300000).
 
 **Timeout calibration.** The 5-min Bash-rung default and 15-min MCP-rung default are sized for heavy-research partner runs — modern partner CLIs commonly spend multiple minutes doing real Read/Grep/Bash investigation before producing a round response. The two defaults are intentionally asymmetric: the Bash rungs (plugin shim, raw CLI) are capped at the Claude Code Bash tool's 600000ms (10 min) host ceiling, while the MCP rung — a structured tool call rather than a Bash invocation — has no host ceiling and can carry the worst-case 15-min Claude Code partner. For tighter budgets (e.g. CI), pass `--timeout-ms` explicitly. The MCP-rung override is downward-only: if you observe consistent partner-CLI wedges (auth handshakes, hosted-API stalls, CI lanes wanting fast failure), set `apt-spar.mcp_timeout_ms` BELOW the 15-min default in `.aperant/config.json` (e.g. `120000` for a 2-min fast-fail budget) — raising it above 15 min is unnecessary because the default already covers the documented worst case. Future versions may introduce per-partner defaults.
 
+## 5a. Codex MCP model resolution
+
+The codex MCP rung (table row above) requires an explicit `model` arg sourced from the user's `~/.codex/config.toml`. The MCP server (`codex-mcp-server`) does NOT read `~/.codex/config.toml` itself — when no `model` is passed it falls back to a hardcoded stale `gpt-5.3-codex`, silently overriding the user's actual configured model. Resolve the model exactly once per spar invocation, before the rung-table walk:
+
+```bash
+# Resolve the codex MCP model exactly once per spar invocation, before the rung table walk
+CODEX_MCP_MODEL="$(grep -E '^model = "[^"]+"' "$HOME/.codex/config.toml" 2>/dev/null | head -1 | sed -E 's/^model = "([^"]+)".*/\1/')"
+# If empty → codex MCP rung is UNAVAILABLE; fall through to plugin/CLI.
+```
+
+If `$CODEX_MCP_MODEL` is empty (file missing, `model =` line absent, or value not double-quoted), treat the MCP rung as UNAVAILABLE and fall through to plugin → CLI. **Never invent a default** — the upstream MCP server's built-in `gpt-5.3-codex` fallback is exactly the bug this resolution path exists to fix.
+
 **Prompt-quoting safety.** The prompt is user-controlled (it comes from `[topic]` and/or conversation context) and may legitimately contain double quotes, dollar signs, backticks, or `$(...)` substitution that bash would otherwise expand or break on. NEVER interpolate `<prompt>` directly inside a double-quoted shell argument. Instead, pipe via a here-document so the shell treats the body as opaque text:
 
 ```bash
@@ -213,7 +225,7 @@ APT_SPAR_PROMPT_EOF
 )" --output-format text
 
 # Gemini direction
-gemini -m <model-from-router.llm.providers.gemini-cli> "$(cat <<'APT_SPAR_PROMPT_EOF'
+gemini "$(cat <<'APT_SPAR_PROMPT_EOF'
 <prompt body — opaque, no shell expansion>
 APT_SPAR_PROMPT_EOF
 )"

package/skills/apt-verify-proof/SKILL.md

@@ -58,6 +58,35 @@ apt-tools detect-runtime .
 # → { runtime: {is_electron, is_nextjs, ...}, selected_driver_id: "..." }
 ```
 
+v0.8.6 — the runtime detector now walks `apps/*/package.json` by
+default and OR-merges each child's capabilities into the root. The
+canonical Aperant monorepo (Electron at `apps/desktop`, Next.js at
+`apps/web`) now reports `is_electron: true` AND `is_nextjs: true`
+without any config override.
+
+### Per-outcome dispatch (v0.8.6+)
+
+When the spec ships `## User Outcomes` (the verify-proof input
+contract — see CLAUDE.md), the workflow runner imports
+`resolveDriversForOutcomes()` from the resolver module and picks a
+driver PER OUTCOME SURFACE instead of a single per-run driver pick.
+
+```js
+import { resolveDriversForOutcomes } from '.aperant/deps/node_modules/@aperant/framework/src/cli/verify-proof/resolver.mjs'
+
+const entries = resolveDriversForOutcomes({
+  drivers, runtime,
+  outcomes: parsed.outcomes,  // from parseUserOutcomes(spec)
+})
+// → [{outcome_id: "O1", surface: "electron", driver: {...}}, ...]
+// For [electron+web] outcomes, two entries share the same outcome_id.
+```
+
+The legacy `apt-tools detect-runtime` still answers the per-run
+"which driver would be picked?" question for the override preview.
+For the per-outcome dispatch (the new contract), import
+`resolveDriversForOutcomes` directly.
+
 ### Override
 
 Force a specific driver chain in `.aperant/config.json`:
@@ -66,6 +95,15 @@ Force a specific driver chain in `.aperant/config.json`:
 { "verification": { "runtimes": ["electron", "cli"] } }
 ```
 
+v0.8.6 — `verification.monorepo_globs` is the new opt-out for the
+monorepo walk. The walk now runs by default — adopters whose
+monorepo lives at a non-canonical prefix
+(`packages/apps/*`, `services/*`) override via
+`verification.monorepo_globs: ["packages/apps/*"]`; set to `[]` to
+disable the walk entirely (root-only behaviour, backwards compat).
+The `verification.runtimes[]` override stays the final escape hatch
+and is now usually unnecessary because the walk runs by default.
+
 ### Bundled drivers (4)
 
 - **browser** (priority=100, ga) — Next.js / vanilla web frontends.
@@ -83,8 +121,9 @@ apt-tools driver doctor .
 # → { drivers: [{driverId, manifest_valid, idl_conformant, ...}], summary: {...} }
 ```
 
-See `@aperant/driver-sdk` for the IDL types, error taxonomy, and
-conformance kit.
+IDL types, error taxonomy, and conformance kit live inside the framework
+itself under `packages/framework/src/driver-sdk/` — see that directory's
+public-api-lock test for the surface contract.
 
 ## Execution
 

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

@@ -75,25 +75,16 @@ export function cmdDetectRuntime(projectDir, _extra = []) {
 	if (!projectDir) return err('Usage: apt-tools detect-runtime <project-dir>')
 	const target = resolve(projectDir)
 
-	// Detect runtime capabilities from project's package.json.
-	const runtime = loadRuntimeCapabilities(target)
-
-	// 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]
-
-	// Read user override from .aperant/config.json:verification.runtimes[].
+	// 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')
 			}
@@ -102,6 +93,24 @@ export function cmdDetectRuntime(projectDir, _extra = []) {
 		}
 	}
 
+	// 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 = []