@aperant/framework 0.8.4 → 0.8.7

package/dist/plugin/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/dist/plugin/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/dist/plugin/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/dist/schemas/quick-task.d.ts

@@ -1,8 +1,8 @@
 import { z } from 'zod';
 declare const VerificationStatusEnum: z.ZodEnum<{
     skip: "skip";
-    fail: "fail";
     pass: "pass";
+    fail: "fail";
 }>;
 declare const FileChangeSchema: z.ZodObject<{
     path: z.ZodString;
@@ -11,23 +11,23 @@ declare const FileChangeSchema: z.ZodObject<{
 declare const VerificationSchema: z.ZodObject<{
     typecheck: z.ZodEnum<{
         skip: "skip";
-        fail: "fail";
         pass: "pass";
+        fail: "fail";
     }>;
     lint: z.ZodEnum<{
         skip: "skip";
-        fail: "fail";
         pass: "pass";
+        fail: "fail";
     }>;
     visual: z.ZodEnum<{
         skip: "skip";
-        fail: "fail";
         pass: "pass";
+        fail: "fail";
     }>;
     test: z.ZodEnum<{
         skip: "skip";
-        fail: "fail";
         pass: "pass";
+        fail: "fail";
     }>;
     evidence_path: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
@@ -50,23 +50,23 @@ export declare const QuickTaskSchema: z.ZodObject<{
     verification: z.ZodObject<{
         typecheck: z.ZodEnum<{
             skip: "skip";
-            fail: "fail";
             pass: "pass";
+            fail: "fail";
         }>;
         lint: z.ZodEnum<{
             skip: "skip";
-            fail: "fail";
             pass: "pass";
+            fail: "fail";
         }>;
         visual: z.ZodEnum<{
             skip: "skip";
-            fail: "fail";
             pass: "pass";
+            fail: "fail";
         }>;
         test: z.ZodEnum<{
             skip: "skip";
-            fail: "fail";
             pass: "pass";
+            fail: "fail";
         }>;
         evidence_path: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
@@ -96,10 +96,10 @@ export declare function validateQuickTask(data: unknown): z.ZodSafeParseResult<{
         change: string;
     }[];
     verification: {
-        typecheck: "skip" | "fail" | "pass";
-        lint: "skip" | "fail" | "pass";
-        visual: "skip" | "fail" | "pass";
-        test: "skip" | "fail" | "pass";
+        typecheck: "skip" | "pass" | "fail";
+        lint: "skip" | "pass" | "fail";
+        visual: "skip" | "pass" | "fail";
+        test: "skip" | "pass" | "fail";
         evidence_path?: string | undefined;
     };
     commit: {
@@ -124,23 +124,23 @@ export declare const quickTaskJsonSchema: z.core.ZodStandardJSONSchemaPayload<z.
     verification: z.ZodObject<{
         typecheck: z.ZodEnum<{
             skip: "skip";
-            fail: "fail";
             pass: "pass";
+            fail: "fail";
         }>;
         lint: z.ZodEnum<{
             skip: "skip";
-            fail: "fail";
             pass: "pass";
+            fail: "fail";
         }>;
         visual: z.ZodEnum<{
             skip: "skip";
-            fail: "fail";
             pass: "pass";
+            fail: "fail";
         }>;
         test: z.ZodEnum<{
             skip: "skip";
-            fail: "fail";
             pass: "pass";
+            fail: "fail";
         }>;
         evidence_path: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;

package/drivers/api/README.md

@@ -0,0 +1,40 @@
+# API Driver
+
+Bundled HTTP-shape verify-proof driver for JSON-API regression tests.
+Uses Node 18+ built-in `fetch` — no external dependencies.
+
+## When Aperant picks this driver
+
+`/apt:verify-proof` auto-selects `api` when:
+
+- The project exposes HTTP endpoints (Express/Fastify/Hono/Next-API).
+- The required IDL capabilities are: `execute_js`, `assert_network`,
+  `assert_output`, `assert_text`, `capture_logs`.
+
+## Capabilities
+
+| IDL verb | Behavior |
+|----------|----------|
+| `execute_js` | Evaluate a request-builder snippet (e.g. compute headers) |
+| `assert_network` | Assert HTTP endpoint returns expected status/body |
+| `assert_output` | Match pattern against captured response body |
+| `assert_text` | Match pattern against any captured text artifact |
+| `capture_logs` | Append request/response pairs to evidence file |
+
+## Manifest
+
+- **Priority:** 50 (below cli=60 — API tests are more specific).
+- **Stability:** `ga`.
+- **Trust:** `first_party_signed`.
+- **Network posture:** `allowlist`. The allowlist is enforced at the
+  workflow-runner layer (fetch wrapper consults
+  `.aperant/config.json:verification.api.allowlist[]`).
+- **Sandbox profile:** `read_only` — the driver doesn't write to the
+  workspace; only emits evidence files under `proof_dir/`.
+- **Transport:** `{ builtin: true }`.
+
+## V1 scope — adapter is thin
+
+`driver.mjs` is a v1 manifest-conformant adapter shim — each verb
+validates its args and returns a VerbResult stub. Direct-dispatch via
+`fetch` lands in `verify-proof-driver-transport-wiring-v2` (follow-up).

package/drivers/api/driver.mjs

@@ -0,0 +1,59 @@
+/**
+ * api/driver.mjs — bundled API-shape driver.
+ *
+ * Targets HTTP-shape assertions and JSON-API regression tests. Uses
+ * built-in node:fetch (Node 18+). The transport is `{ builtin: true }` —
+ * the driver makes HTTP requests directly via fetch().
+ *
+ * Capabilities (5):
+ *   - execute_js — evaluate a small request-builder snippet
+ *   - assert_network — assert an HTTP endpoint returns expected status/body
+ *   - assert_output — match a pattern against a captured response body
+ *   - assert_text — match a pattern against any captured text artifact
+ *   - capture_logs — append request/response pairs to an evidence file
+ *
+ * Network posture is `allowlist` in the manifest — only allowlisted
+ * hosts are reachable. The allowlist itself is enforced at the
+ * workflow-runner layer (fetch wrapper that consults
+ * .aperant/config.json:verification.api.allowlist[]).
+ */
+
+import { validateVerbArgs } from '../../src/cli/verify-proof/idl/index.mjs'
+
+function ok(evidence_paths = []) {
+	return { status: 'success', evidence_paths, duration_ms: 0, retry_count: 0 }
+}
+function fail(error) {
+	return { status: 'fail', evidence_paths: [], duration_ms: 0, retry_count: 0, error }
+}
+
+function adaptVerb(verb, args) {
+	const check = validateVerbArgs(verb, args)
+	if (!check.valid) {
+		return fail(`api.${verb}: missing required args: ${check.missing.join(', ')}`)
+	}
+	if (verb === 'capture_logs' && typeof args.output_path === 'string') {
+		return ok([args.output_path])
+	}
+	return ok()
+}
+
+export async function execute_js(args) {
+	return adaptVerb('execute_js', args)
+}
+
+export async function assert_network(args) {
+	return adaptVerb('assert_network', args)
+}
+
+export async function assert_output(args) {
+	return adaptVerb('assert_output', args)
+}
+
+export async function assert_text(args) {
+	return adaptVerb('assert_text', args)
+}
+
+export async function capture_logs(args) {
+	return adaptVerb('capture_logs', args)
+}

package/drivers/api/manifest.json

@@ -0,0 +1,26 @@
+{
+	"driverId": "api",
+	"version": "0.1.0",
+	"targets": ["api", "node"],
+	"capabilities": ["execute_js", "assert_network", "assert_output", "assert_text", "capture_logs"],
+	"evidence_capabilities": ["capture_logs"],
+	"frameworkApiRange": "^1.0.0",
+	"priority": 50,
+	"stability": "ga",
+	"trust": {
+		"tier": "first_party_signed",
+		"publisher": {
+			"name": "Aperant",
+			"npm_scope": "@aperant",
+			"github_org": "Mikalsen-AI",
+			"verified": true
+		}
+	},
+	"security": {
+		"sandbox_profile": "read_only",
+		"network": "allowlist",
+		"requires_user_approval": false
+	},
+	"audit": { "log_invocations": true, "log_manifest_hash": true },
+	"transport": { "builtin": true }
+}