immune-brain 5.0.0 → 5.1.1

package/README.md

@@ -14,7 +14,7 @@ Immune-Brain brings a structured engineering workflow to AI coding assistants (*
 - **Explicit trigger when rigor matters** — When you want engineering discipline, invoke `imm-brainstorm`, `imm-planner`, or `imm-run`.
 - **Plans become trackable tasks** (`TaskIntent` + `TaskRecord`) — Progress lives on disk (Git + `.imm/`), surviving restarts and context wipes.
 - **Quality is enforced by code, not promises** — Automated QA and isolated review subagents must pass before a task can complete.
-- **Ready Initiatives can run as a batch** — One confirmed batch authorization lets `imm-run` work through a published Initiative's children serially, while every child is still enrolled, QA'd, reviewed, and settled on its own.
+- **Ready Initiatives can run as a batch (serial or parallel lanes)** — One confirmed batch authorization lets the batch advance published children without manual handoffs per task; supports default serial progression or opt-in parallel lanes (Git worktree physical isolation, scope-disjoint scheduling, and integration verification guards), while every child is still enrolled, QA'd, reviewed, and settled on its own.
 
 Pi and Claude Code are the supported hosts. Undeclared adapters remain unsupported. Minimum Claude Code is `2.1.236`, the lowest version verified with interactive server-initiated MCP elicitation. Current real-Host evidence is recorded in [Claude native elicitation conformance](docs/verification/claude-native-elicitation-authority-conformance.md); historical reports remain under [docs/verification/archive/](docs/verification/archive/). Either host can use the model provider you configure — Immune-Brain works on top of Kernel authority, not a vendor chat.
 
@@ -25,6 +25,8 @@ Pi and Claude Code are the supported hosts. Undeclared adapters remain unsupport
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [How to Use](#how-to-use)
+- [Recommended Workflows: Composing with mattpocock/skills](#recommended-workflows-composing-with-mattpocockskills)
+- [Real-World Case Studies](#real-world-case-studies)
 - [Core Philosophy: Turn "Judgment" into "Table Lookup"](#core-philosophy-turn-judgment-into-table-lookup-harnessing-multi-model-tiers-with-determinism)
 - [The 7 Skills](#the-7-skills)
 - [Lifecycle](#lifecycle)
@@ -84,7 +86,7 @@ mise run check-dist-sync           # verify generated docs are in sync
 Immune-Brain follows a **Skill-explicit** model: ordinary conversation is just standard, lightweight AI coding. The managed workflow activates **only when you explicitly invoke a skill**.
 
 **1. Call a skill when you need structured engineering**:
-- Fuzzy idea that needs scoping? Run `/imm-brainstorm` (or ask the agent to use `imm-brainstorm`).
+- Fuzzy idea, ambiguous design, or high-stakes feature? Run `/grill-me` (from `mattpocock/skills`, recommended) for relentless Socratic design interrogation (or use built-in `/imm-brainstorm` for lightweight framing).
 - Ready to design and build? Run `/imm-planner` (or ask the agent to use `imm-planner`).
 
 *(Ordinary questions like "What does this function do?" or "Fix this typo" stay host-native — zero workflow ceremony.)*
@@ -112,11 +114,11 @@ Immune-Brain provides two clean modes: **Host-native** for daily coding, and **M
 | Your situation | What to say / do | What happens |
 |---|---|---|
 | Daily coding, quick fix, general Q&A | Normal conversation ("Fix typo in README", "Explain this function") | **Host-native**: Standard Pi / Claude Code behavior. Zero workflow overhead. |
-| Fuzzy idea, needs scoping & risk analysis | `/imm-brainstorm` "Help me think through webhook support" | → `imm-brainstorm` frames requirements, constraints, and risks (read-only, no code edits) |
+| Fuzzy idea, needs architectural stress-testing & scoping | `/grill-me` (recommended) or `/imm-brainstorm` | → `/grill-me` interviews you through the design tree to lock decisions; `/imm-brainstorm` provides built-in read-only problem framing |
 | Clear goal, want formal plan & specs | `/imm-planner` "Plan the webhook feature" | → `imm-planner` writes `TaskIntent` + Specs with testable acceptance checks |
 | Plan confirmed, ready to build & verify | `/imm-run` | → Executor builds within scope → deterministic QA verifies → isolated Review checks → task settles |
 | Session interrupted or resuming a task | `/imm-run` | → Resumes existing task seamlessly from on-disk state (`.imm/`) |
-| Ready Initiative to run unattended | "Run initiative `<slug>` unattended" | → Host's `start_unattended_batch`: one native confirmation covers ordered plan digest, children run serially |
+| Ready Initiative to run unattended (serial or parallel lanes) | "Run initiative `<slug>` unattended" (optionally with `--max-parallel 4` or `Lane max parallel`) | → Host's `start_unattended_batch`: one native confirmation binds the plan digest. Runs serially by default, or opt-in parallel Git worktree lanes with `max_parallel` |
 | Cross-host workflow (Claude plan + Pi code) | Run `/imm-planner` in Claude Code, switch to Pi and run `/imm-run` | → Staged Spec & TaskIntent are shared on disk; Pi confirms via native TUI and executes loop |
 | PR has review comments or failing CI | `/imm-pr-fix` on that PR | → Standalone repair: minimal scoped fix in place, no managed task created |
 | Project docs out of date | `/imm-doc-prune` | → Read-only audit; deletes only user-approved stale docs from manifest |
@@ -125,7 +127,7 @@ Immune-Brain provides two clean modes: **Host-native** for daily coding, and **M
 
 > **Core Principle: Skill-Explicit Entry**
 > - **Ordinary input stays host-native**: Natural language queries never automatically start planning or task enrollment. You choose when to turn on engineering rigor.
-> - **Managed work starts with explicit skills**: Use `imm-brainstorm` to clarify, `imm-planner` to plan, and `imm-run` to execute and resume.
+> - **Managed work starts with explicit skills**: Use `/grill-me` (or `imm-brainstorm`) to clarify decisions, `imm-planner` to plan, and `imm-run` to execute and resume.
 
 ### Cross-Host Workflow: Plan in Claude Code, Build in Pi
 
@@ -163,6 +165,146 @@ This enables a best-of-both-worlds workflow: **leverage Claude Code's deep reaso
 
 ---
 
+## Recommended Workflows: Composing with mattpocock/skills
+
+While Immune-Brain provides deterministic execution and quality enforcement once work begins, engineering failures frequently originate upstream: **models jump into code before the design tree is fully explored, trade-offs are evaluated, and edge cases are surfaced.**
+
+To prevent premature implementation and scope churn, the recommended best-practice workflow combines **`mattpocock/skills`** (by Matt Pocock) upstream with **Immune-Brain** downstream:
+
+> **The Dual-Engine Thesis**
+> - **Upstream Socratic Friction (`grill-me`)**: Deliberately slows down thinking. The AI acts as a relentless interviewer, forcing explicit decisions on every branch of the design tree before any code or spec is committed.
+> - **Downstream Deterministic Rigor (`imm-planner` + `imm-run`)**: Translates those decisions into tamper-proof machine contracts (`TaskIntent` + living Spec), enforces native human enrollment, freezes editable file boundaries, and verifies code via sandboxed child processes and isolated reviewer subagents.
+
+```text
+┌────────────────────────────────────────────────────────────────────────────────────────────────────────┐
+│ 1. Upstream Socratic Alignment (mattpocock/skills /grill-me)                                           │
+│ Role: Relentlessly interview developer down every branch of the design tree; resolve trade-offs        │
+└───────────────────────────────────────────────────┬────────────────────────────────────────────────────┘
+                                                    │ Settled decisions & architectural consensus
+                                                    ▼
+┌────────────────────────────────────────────────────────────────────────────────────────────────────────┐
+│ 2. Formal Machine Contracts (Immune-Brain /imm-planner)                                                │
+│ Role: Author living Spec & TaskIntent (.intent.json); lock scope_hint and VerificationDescriptor v2   │
+└───────────────────────────────────────────────────┬────────────────────────────────────────────────────┘
+                                                    │ Git-tracked contract artifacts
+                                                    ▼
+┌────────────────────────────────────────────────────────────────────────────────────────────────────────┐
+│ 3. Literal Human Authority Gate (Native Host Enrollment)                                               │
+│ Role: Developer confirms scope in native TUI / MCP dialog; Kernel captures baseline & acquires CAS lock │
+└───────────────────────────────────────────────────┬────────────────────────────────────────────────────┘
+                                                    │ Exclusive workspace lease
+                                                    ▼
+┌────────────────────────────────────────────────────────────────────────────────────────────────────────┐
+│ 4. Deterministic Assurance & Settlement (Immune-Brain /imm-run)                                        │
+│ Role: Scope-frozen Executor -> Sandboxed QA (bun test) -> Isolated Subagent Review -> CAS Settlement   │
+└────────────────────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Why Use `grill-me` Instead of `imm-brainstorm` for Decision Confirmation
+
+Immune-Brain includes a built-in `imm-brainstorm` skill, but for non-trivial features, architectural pivots, and security-sensitive boundaries, **`/grill-me` is the recommended choice**:
+
+| Dimension | Built-in `imm-brainstorm` | Upstream `/grill-me` (`mattpocock/skills`) | Recommended Synergy |
+|---|---|---|---|
+| **Ecosystem & Setup** | Built into Immune-Brain (zero install) | Ecosystem skill from `mattpocock/skills` (`npx skills@latest add mattpocock/skills --skill grill-me`) | Use `/grill-me` as the upstream decision partner; let Immune-Brain handle execution |
+| **Interview Style** | Structured problem framing; batched questions; read-only summary | Relentless, iterative 1-by-1 Socratic grilling; explores every decision branch | `/grill-me` actively challenges developer assumptions and refuses to let ambiguities slide |
+| **Exploration Discipline** | Explores codebase first, surfaces high-level goals & risks | Explores codebase first, proposes opinionated recommended answers for each branch | Eliminates "vibe coding" and locks down architectural consensus before any planning |
+| **Output** | `brainstorm_framing` summary block | Fully resolved decision tree | Directly feed the settled decisions into `/imm-planner` |
+| **Best Fit** | Lightweight scoping, offline setups, or simple tasks | Complex features, architectural refactors, and multi-service designs | **Recommended standard** for production engineering |
+
+### Setup & Installation
+
+Install `grill-me` into your project or global agent environment using the official Skills installer:
+
+```bash
+# Add grill-me from mattpocock/skills
+npx skills@latest add mattpocock/skills --skill grill-me
+
+# Or install the full suite
+npx skills@latest add mattpocock/skills
+```
+
+### End-to-End Workflow: `grill-me` → `imm-planner` → `imm-run`
+
+1. **Step 1: Grill the Design (`/grill-me`)**
+   - Run `/grill-me "Add Webhook Dispatcher with retry and replay protection"`.
+   - The agent reads existing codebase patterns first, then interviews you across the decision tree (storage choices, idempotency strategy, backoff policies, failure modes), presenting a recommended answer for each step.
+   - Continue until all branches are resolved: *"Decision tree complete. Ready to plan."*
+2. **Step 2: Formalize the Plan (`/imm-planner`)**
+   - Run `/imm-planner "Plan the webhook dispatcher using the decisions settled in grill-me"`.
+   - `imm-planner` consumes the resolved choices and generates:
+     - **Living Spec** (`docs/specs/webhook-dispatcher.spec.md`): Pinned code coordinates, trade-offs, and negative boundaries.
+     - **TaskIntent** (`docs/plans/webhook-dispatcher.intent.json`): Strict `scope_hint`, risk tier (`material`), and machine-executable `VerificationDescriptor v2` checks.
+3. **Step 3: Confirm Enrollment (Native Host Gate)**
+   - Stage artifacts in Git (`git add docs/`).
+   - Run `/imm-run`. The native confirmation dialog opens (Pi TUI modal / Claude Code MCP elicitation).
+   - Once confirmed, Kernel atomically captures repository baseline state (`enrollment-baseline.json`) and acquires an exclusive SQLite CAS lock.
+4. **Step 4: Execute & Verify (`/imm-run`)**
+   - **Executor**: Edits code strictly within `scope_hint`. Physical scope escapes fail closed.
+   - **Deterministic QA**: Kernel executes acceptance tests (`bun test`) in a sandboxed child process, verifying authentic exit codes.
+   - **Isolated Review**: For `material` or `critical` tasks, a separate review subagent audits immutable Git blobs against Devil's Advocate invariants.
+   - **Settlement**: Kernel records tamper-proof attestations in `.imm/audit/<task-id>/` and releases the workspace lease.
+
+---
+
+## Real-World Case Studies
+
+### Case Study 1: Greenfield Feature Development — Multi-Tenant Webhook Dispatcher
+
+- **Goal**: Implement a production-grade webhook dispatch system with HMAC signature verification, exponential backoff with jitter, and replay attack prevention.
+- **Problem without this pipeline**: An AI agent typically starts writing files immediately, pulls in arbitrary dependencies, forgets timestamp replay bounds, leaks in-memory timers, and claims "implementation complete" without verifying HTTP timeout handling.
+- **Workflow**:
+  1. **Socratic Grilling (`/grill-me`)**:
+     - *Question 1 (Persistence)*: SQLite vs external queue? *Recommendation*: Store pending dispatches in the existing SQLite CAS table to avoid external infrastructure overhead.
+     - *Question 2 (Security)*: How to prevent replay attacks? *Recommendation*: Require an `X-Webhook-Timestamp` header with a 5-minute clock-skew tolerance window and HMAC-SHA256 signature.
+     - *Question 3 (Resilience)*: What is the backoff curve and timeout? *Recommendation*: Exponential backoff with full jitter up to 5 attempts, with a hard 10s timeout via `AbortController`.
+     - *Result*: All trade-offs explicitly confirmed in 3 minutes of dialogue.
+  2. **Machine Contract Formulation (`/imm-planner`)**:
+     - Planner writes `docs/specs/webhook-dispatcher.spec.md` with explicit Negative Scope (files in `src/auth/` and `src/billing/` are forbidden).
+     - Generates `docs/plans/task-webhook-dispatcher.intent.json` with risk `material` and `VerificationDescriptor v2` running `bun test tests/webhook-dispatcher.test.ts`.
+  3. **Native Gate Enrollment**:
+     - Developer inspects Git diff and confirms via Pi TUI dialog / Claude Code MCP elicitation.
+  4. **Execution, QA & Review (`/imm-run`)**:
+     - Executor writes implementation strictly within `scope_hint`.
+     - Deterministic QA executes `bun test tests/webhook-dispatcher.test.ts`. Kernel verifies exit code `0`.
+     - Isolated Reviewer subagent inspects the Git blob `ReviewBundle`, confirming no out-of-scope edits and verifying error invariants.
+     - Kernel settles terminal proof into `.imm/audit/<task-id>/`.
+
+### Case Study 2: Critical Architectural Refactoring — CAS Storage Migration (v1 → v2)
+
+- **Goal**: Migrate the persistence layer from legacy JSON files to an atomic SQLite CAS engine while maintaining zero-downtime rollback and legacy read-only audit inspection.
+- **Problem without this pipeline**: Agents performing low-level database refactoring frequently introduce silent schema corruption, delete legacy fallback paths, and pass tests by weakening assertions.
+- **Workflow**:
+  1. **Socratic Grilling (`/grill-me`)**:
+     - *Interrogation*: "What happens to active v1 tasks during migration? Recommendation: Enforce a strict drain check (`drain_required`); refuse dual-write and abort if an active v1 task is in progress."
+     - *Interrogation*: "How is WAL corruption prevented during rollback? Recommendation: Use single-file transactions with OS-level file locking and immutable Git snapshots."
+  2. **Planning with Enforcement Floors (`/imm-planner`)**:
+     - Because `runtime/kernel/storage.ts` is in `scope_hint`, Kernel automatically clamps the risk tier floor to `critical`.
+     - Planner pins code coordinates (`storage.ts:120`) and binds verification commands including legacy migration fixtures.
+  3. **Native Enrollment**: Developer verifies the `critical` risk tier and baseline snapshot in the native host dialog.
+  4. **Deterministic QA & Review (`/imm-run`)**:
+     - Real process verification runs the full regression test suite with authentic legacy fixtures.
+     - Isolated Subagent Devil's Advocate audit executes an adversarial review over immutable Git blobs, checking backward compatibility.
+     - Atomic settlement writes tamper-proof audit records.
+
+### Case Study 3: Cross-Host Collaborative Teamwork — Claude Code (Grill + Plan) + Pi (Run + QA)
+
+- **Goal**: Maximize reasoning intelligence for architectural design while minimizing token expenditure and maximizing speed for mechanical code execution.
+- **Workflow**:
+  1. **Phase 1 in Claude Code (Desktop)**:
+     - Run `/grill-me` (from `mattpocock/skills`) to stress-test architecture with Claude's flagship reasoning model.
+     - Run `/imm-planner` to author line-pinned Living Specs and `TaskIntent` contracts.
+     - Stage artifacts (`git add docs/ && git commit -m "docs: webhook spec and plan"`).
+  2. **Phase 2 in Pi (Terminal / Remote Server)**:
+     - Open Pi in the same repository workspace.
+     - Enter `/imm-run`. Pi detects the Git-staged `TaskIntent` and opens its native TUI modal for enrollment.
+     - Pi's Executor writes code using a cost-effective, high-throughput model (Fast/Mid Tier).
+     - Deterministic QA runs locally via `bun test`.
+     - Review passes and Kernel closes the task.
+  3. **Result**: Zero context loss across hosts, full session-neutral state continuity, and ~60-70% savings on flagship reasoning tokens.
+
+---
+
 ## Core Philosophy: Turn "Judgment" into "Table Lookup", Harnessing Multi-Model Tiers with Determinism
 
 Large language models—especially lightweight, cost-effective Fast Tier models—fail in real-world software engineering not because of syntax, but because of **semantic ambiguity, scope creep, and evasive verification**.
@@ -392,7 +534,7 @@ flowchart TD
    - **Risk-Tiered Gates with Enforcement Floors**: `routine` tasks complete upon QA pass; `material` and `critical` tasks require an isolated Review subagent. Touching kernel or authority paths is forced to at least `material`.
    - **Live Refutation**: Subjective Review findings can be refuted by fresh, passing QA evidence; any new edits invalidate counterevidence and re-block the finding.
    - **Immutable Audit Trail**: Terminal task completion atomically writes signed `TaskRecord`s, Git blob `ReviewBundle`s, and QA Attestations to `.imm/audit/<task-id>/`, fully tracked in Git.
-   - **Unattended Batch**: Serial execution driven by GitHub Issues and bound by `plan_digest`, where each child independently completes its own Enrollment → QA → Review → Commit cycle.
+   - **Unattended Batch & Parallel Lanes**: Progresses via GitHub Issues bound by `plan_digest`. Supports default single-branch serial execution or physical multi-Lane parallel execution; in lane mode, the Coordinator schedules scope-disjoint Git worktrees, and Integration Guard reruns deterministic descriptors on candidate commits before fast-forwarding the batch branch, preventing concurrency contamination.
 
 Key invariants:
 
@@ -407,13 +549,70 @@ Key invariants:
 
 ## Unattended Batch Runs
 
-When an Initiative has several ready children, you can run them as one serial batch instead of task by task.
+When an Initiative contains multiple ready children, developers can run the entire batch unattended via the Host's privileged `start_unattended_batch` tool without manually driving `imm-run` for each child task.
+
+Immune-Brain supports two batch execution modes: **Default Serial Mode** and **Parallel Batch Lanes**.
+
+### 1. Batch Execution Modes Overview
+
+| Dimension | Serial Batch (Default) | Parallel Batch Lanes |
+|---|---|---|
+| **Activation** | Call `start_unattended_batch(slug)` directly | Pass `max_parallel` or configure `Lane max parallel: <n>` |
+| **Workspace Topology** | Shared single batch branch (`imm-batch/<slug>`) | Coordinator manages batch branch; each concurrent task owns a Git worktree (`imm-lane/<task-id>`) |
+| **Scheduling** | Strict sequential execution ordered by dependency layers | Scope-disjoint children execute concurrently in parallel Lanes |
+| **Authority Boundaries** | Single local Authority Store advanced sequentially | Each Lane owns its own local Authority Store, running isolated with zero global CAS contention |
+| **Integration** | Direct commit on batch branch after task QA/Review passes | Reconciles via Git plumbing, reruns Integration Guard descriptors, then fast-forwards batch branch |
+| **Ideal For** | Small initiatives, tight file coupling, resource-constrained environments | Medium/large initiatives, decoupled modules, high-compute environments |
+
+### 2. Batch Authority & Invariants
+
+- **Explicit Entry & Single Authorization:** No batch state or branch exists before calling `start_unattended_batch`; without it, `imm-run` behaves identically to single-task enrollment. The native gate (Pi TUI dialog or Claude MCP elicitation) displays the ordered child list and global `plan_digest`; this single user confirmation constitutes complete Batch Authorization.
+- **Child Authority Invariance:** A batch merely bundles authorization scope without weakening engineering rigor. Every child is still individually enrolled, scope-frozen, QA-verified via authentic child processes, reviewed in isolation, and settled with its own `TaskRecord`. A batch is a scope of authorization, not a new authority layer.
+- **Deterministic Boundaries:** Only runs published, non-`critical` children. Any required human decision (`needs_human`), budget/timeout interruption, or integration error halts the batch safely, marking dependent children as `skipped_blocked` rather than reordering. Runners never push, open PRs, or make arbitrary decisions.
+
+### 3. Parallel Batch Lanes Lifecycle & Architecture
+
+In parallel lane mode, the Coordinator (Parent Host), `lane-steward` internal role, and Lane Executor Hosts coordinate to provide physical concurrency isolation:
+
+```mermaid
+sequenceDiagram
+    participant P as Coordinator (Parent Host)
+    participant B as Batch Runtime
+    participant S as lane-steward Role
+    participant L as Lane Executor Host (Pi / Claude)
+    participant K as Lane Kernel (Isolated Store)
+
+    Note over P,B: 1. Scheduling & Scope-Disjoint Analysis
+    P->>B: start_unattended_batch(slug, max_parallel)
+    B-->>P: handoffs: provision Lane A, Lane B
+
+    Note over P,S: 2. Physical Worktree Provisioning (Provision & Admit)
+    P->>S: Provision worktree (branch imm-lane/..., base batch base)
+    S-->>P: Return isolated worktree paths
+    P->>B: Submit lane_offers admission check (cleanliness, branch, base)
+
+    Note over P,L: 3. Supervised Parallel Execution
+    B-->>P: handoffs: launch Executor A, Executor B
+    P->>L: Launch background session for imm-run (configurable Host/model)
+    L->>K: Run loop: Scope freeze -> Deterministic QA -> Review -> Settle
+
+    Note over P,B: 4. Integration Guard & Fast-Forward
+    L-->>P: Lane finish notification
+    P->>B: Coordinator reconcile tick
+    B->>K: Read Lane evidence & commit
+    B->>B: Build candidate commit + rerun Integration Guard descriptors
+    B->>B: Fast-forward batch branch (1 child 1 commit)
+    B-->>P: handoffs: release Lane A / provision Lane C
+```
+
+#### Core Mechanisms:
+
+1. **Scope-Disjoint Scheduling:** The Coordinator dynamically computes dependency layers and path overlap. A child is scheduled only when its prerequisites are integrated and its `scope_hint` is provably disjoint from all in-flight Lanes. Overlapping children wait until conflicting Lanes integrate.
+2. **Supervised Host Sessions:** The Parent Host launches an independent Executor Host process for each Lane (configurable across Hosts, models, and effort tiers, such as Pi or Claude Code). The Parent is reactively notified on session completion, polling nothing. When running inside Herdr, it opens one tab per Lane and never answers trust/login dialogs on behalf of the user.
+3. **Integration Guard:** To eliminate silent semantic conflicts, settled deliveries are not blindly merged. The Coordinator constructs candidate commits via Git plumbing and reruns deterministic descriptors for both the candidate child and all sibling tasks integrated since the lane's base. Fast-forward proceeds only if all tests pass.
+4. **Fault Isolation:** If a Lane encounters a QA failure, review rejection, or integration conflict, the batch branch stays untouched (zero-write). The failing child is parked as `needs_human`, its dependents are marked `skipped_blocked`, while independent sibling Lanes proceed unaffected.
+5. **Agents Only Create:** The Parent and `lane-steward` provision Lanes and terminal tabs but never kill sessions or delete worktrees. Once integrated, the system reports safe-to-release Lanes for the developer to inspect and clean up.
 
-- **Entry is explicit:** the Host's privileged `start_unattended_batch` tool, taking the Initiative slug. Nothing batch-related exists until it is called — without it, `imm-run` behaves exactly like per-task enrollment and creates no batch state, branch, or authorization.
-- **One confirmation, one digest:** the native gate (Pi TUI dialog or Claude MCP elicitation) shows the ordered child list and the shared plan digest; that single literal-user act is the whole Batch Authorization.
-- **Per-child authority survives:** every child is still enrolled, frozen, QA'd, reviewed, and settled by the Kernel on its own `TaskRecord`. The batch is the scope of one authorization, never a new authority layer.
-- **Closeout is automatic:** when a child reaches `done` in the foreground, the same call commits it and enrolls the next child, or marks the batch `completed`, with no new gate. A parked or stopped child is never committed for you, and a failed continuation is reported beside the result with `start_unattended_batch` as the retry. A fast-forward commit you add to the batch branch is adopted; any other HEAD movement still stops the run.
-- **Bounds:** only published, non-`critical` children run, serially on a dedicated batch branch. The run parks when a child needs a human decision or a budget, authorization, or commit failure stops it; the budget is a child count and a QA failure limit, and nothing expires with time, and dependents of a blocked child are skipped rather than reordered. The runner never pushes, opens PRs, resolves user decisions, or creates, switches, or deletes Git worktrees.
 
 ---
 
@@ -425,6 +624,10 @@ Immune-Brain has **no separate config file**. Preferences live in your host's ag
 ## Immune-Brain Preferences
 
 - Initiative carrier default: github   # or: local
+- Lane max parallel: 4                 # optional; enables lane mode
+- Lane Executor Host: claude-code      # optional; or: pi
+- Lane Executor model: <model id>      # optional; needs Lane Executor Host
+- Lane Executor effort: high           # optional; needs Lane Executor Host
 ```
 
 | Preference | Options | Default | Notes |
@@ -432,6 +635,10 @@ Immune-Brain has **no separate config file**. Preferences live in your host's ag
 | Reply language | any natural language | repo `AGENTS.md` | Machine contracts / paths stay literal |
 | Initiative carrier | `local` / `github` | none — Planner asks | Only matters when a proposal splits across multiple TaskIntents |
 | Advisory subagents | allowed / solo | allowed | Respects Pi host policy + explicit user instruction |
+| Lane max parallel | integer ≥ 1 | none — batches stay serial | Passed as `max_parallel` when a batch starts; a resumed batch keeps its recorded value |
+| Lane Executor Host | `claude-code` / `pi` | none — prefers the Parent's own Host type | Every Lane uses this Host, with no fallback to the other one |
+| Lane Executor model | a model ID of that Host | none — the Executor Host's own default | Applies only when `Lane Executor Host` is set |
+| Lane Executor effort | an effort level of that Host | none — the Executor Host's own default | Applies only when `Lane Executor Host` is set; `--effort` on Claude Code, `--thinking` on Pi |
 
 Precedence: **current message > repo agent instruction file > user-level agent instruction file > ask**. Skills read these files directly, so a preference works even when the host does not auto-load that file.
 
@@ -483,6 +690,10 @@ docs/specs/                           # Living specs (updated in place)
 
 **Why are preferences kept in AGENTS.md / CLAUDE.md instead of an external config.toml?** Immune-Brain embraces host-native simplicity with zero external configuration files. Declaring preferences (such as Initiative carriers and communication instructions) in tracked agent instruction files ensures that configuration is version-controlled, visible across all collaborators, and free from environment drift.
 
+**Why do you recommend `grill-me` instead of `imm-brainstorm` for complex tasks?** `imm-brainstorm` is a lightweight, built-in tool designed for quick problem framing without external dependencies. However, `grill-me` (from `mattpocock/skills`) provides an active, relentless Socratic interview that explores every branch of your design tree with opinionated recommendations. For non-trivial features, architectural refactors, or security boundaries, grilling the design with `grill-me` before passing the settled decisions to `imm-planner` produces significantly tighter specifications and prevents downstream rework.
+
+**Do I need to install `mattpocock/skills` to use Immune-Brain?** No. Immune-Brain is completely self-contained and functions out of the box with built-in `imm-brainstorm`. Composing with `mattpocock/skills` is an optional, highly recommended power workflow for teams seeking maximal engineering discipline.
+
 **Which AI coding assistants are supported?** Pi and Claude Code are the supported hosts (Claude Code version >= `2.1.236`). Both hosts run on the exact same Kernel authority, assurance guarantees, and multi-skill pipeline.
 
 ---