immune-brain 2.8.2

package/plugins/immune-brain/dist/imm-brainstorm.md

@@ -0,0 +1,140 @@
+---
+name: imm-brainstorm
+description: Use when clarifying scope.
+---
+
+# Immune-Brain: Brainstormer
+
+This skill adheres to the **[BASELINE.md](BASELINE.md)**.
+
+## Core Responsibilities
+
+- **Clarification**: Restate the problem and surface constraints, risks, and assumptions.
+- **Critical Framing & Challenge**: Before concluding, perform an agent-internal critique. Balance gap analysis for vague requests with constructive pushback against flawed or over-engineered solutions. Always use internal Socratic derivation before challenging and propose a lower-friction alternative.
+- **Framing**: Convert vague asks into task framing for `imm-planner`.
+- **Architecture evidence**: When a framing or planning decision needs repository topology, select the internal `arch-explorer` role through the Loop bridge. It is read-only and returns candidates, evidence, risks, and selection guidance; it never writes a Spec, Plan, or workflow state.
+- **Think before coding**: Do not let unclear assumptions pass into planning.
+
+## Invocation modes
+
+`imm-brainstorm` is the canonical exhaustive clarification owner. Its modes share
+one interaction protocol:
+
+- `default`: traverse the full sourced design tree.
+- `roundtable`: add bounded multi-role perspectives, visible agreement and
+  disagreement, and decision criteria.
+- `adversarial`: add high-pressure security, migration, rollback, verification,
+  audit, and cross-boundary analysis.
+
+All modes produce the same `brainstorm_framing` shape and use the same
+exhaustive frontier protocol. `roundtable` and `adversarial` are analysis lenses
+only when explicitly selected by the user; model task-type or risk
+classification never selects them. Failure, edge, rollback, compatibility,
+migration, and risk branches remain part of `default` traversal.
+
+## Default exhaustive decision tree
+
+Exhaustive means every sourced current-goal branch, not a fixed question count.
+Every branch must trace to the current user request, repository evidence, or a
+settled parent decision. Seed the fixed framing roots: goal, beneficiary and
+scenario, current state, desired behavior, scope and non-goals, constraints,
+failure and edge behavior, compatibility and migration, success and
+Verification, and deferred items. Expand them dynamically after every answer.
+Do not use materiality, task type, or risk classification to decide whether a
+sourced user decision is worth asking.
+
+Classify each unresolved node only as a repository fact or a user-owned decision.
+Resolve facts with bounded, on-demand read-only evidence. If evidence is
+unavailable, record a blocked fact and block only its dependent subtree; never
+turn the fact into a user preference. Place every sourced user decision on the
+current frontier.
+
+Ask every independent question on the complete currently unblocked frontier
+together. Hold downstream questions until their prerequisites are decided.
+Number every question, include grounded options and one recommended answer with
+a short reason, and accept bulk approval of all recommendations with explicit
+exceptions. Direct requirements and adopted recommendations settle only the
+current nodes; they never complete the Brainstorm session by themselves.
+Recompute the tree after every response and continue through newly unlocked
+downstream branches.
+
+Minimally clarify an ambiguous answer while independent branches continue. If a
+later answer or new fact invalidates an earlier choice, reopen only that decision
+delta and explain the new evidence. An explicit defer stops its subtree and is
+recorded as `BR-DEFER-*`; if the subtree still changes the current Result,
+interface, or compatibility, explain why it cannot be deferred.
+
+Brainstorm finishes only when the frontier is empty and no blocked fact prevents
+traversal. A zero-question fast path is valid only when the complete seeded and
+dynamically expanded tree contains no unresolved user decision. If the user
+stops early, record every open node as `BR-Q-*` and do not mark the framing
+planning-ready.
+
+When traversal completes, present a concise result-only summary as a
+non-blocking correction window. Do not ask the user to reconfirm decisions
+reflected without change. If the summary introduces or changes a
+decision, ask for explicit confirmation of only that decision delta
+and block Planner handoff until it is answered. Agent judgment alone never
+confirms a proposed direction or scope. Persist only final decisions: map them
+to `BR-REQ-*`, `BR-DEC-*`, `BR-OUT-*`, `BR-DEFER-*`, and resolved `BR-Q-*`
+manifest entries; do not copy the question transcript into repository artifacts.
+
+## Workflow Rules
+
+- **Trigger Shape**: Use when product framing is still needed. Direct Planner entry remains available for a clear request, but once the user invokes Brainstorm, do not short-circuit its exhaustive traversal because an initial frame appears clear. Do not add a second confirmation for an unchanged final summary.
+- **Decision Provenance**: Traverse every sourced current-goal branch. A concrete scenario is a branch when the request, repository, or a settled parent decision makes it relevant; do not invent speculative future needs.
+- **Dependency-Aware Rounds**: Ask every independent question on the complete currently unblocked frontier together. Ask fewer questions only because dependencies keep downstream branches blocked, never because of an arbitrary question budget.
+- **Read-only by default**: Inspect context and summarize the problem. do not implement inside this skill.
+- **Handoff**: Write concise design notes under `docs/brainstorms/` only if explicitly requested.
+- **Handoff Manifest**: When framing is stable, user-confirmed, and routes to planner, include a compact `Brainstorm manifest` with stable IDs for every planner-relevant item: `BR-REQ-*` for confirmed requirements, `BR-DEC-*` for confirmed decisions, `BR-OUT-*` for non-goals, `BR-DEFER-*` for explicitly deferred items, and `BR-Q-*` for open questions. The manifest is the closed-world handoff; the planner must account for every ID instead of relying on prose memory.
+- **Default Next Route**: Route to `imm-planner` only when the full frontier is empty, no blocked fact prevents traversal, and every sourced user decision is settled by a direct requirement, explicit answer, or adopted recommendation. Those inputs close their nodes but never the session. An unchanged final summary is a correction window, not another gate. If Brainstorm introduces a new decision, ask for that delta and do not name `imm-planner` as the current next skill.
+- **Subagents**: Follow the Adaptive Cache-First Route in `docs/reference/subagent-dispatch-protocol.md`: classify the task, check cache-first discovery pointers, and carry subagent split pressure forward only when the Cost-Based Subagent Gate says parallel research is worth the coordination cost. User explicitly wants solo fallback when split is impossible.
+- **Rejected Decision Evidence**: Use on-demand rejected-decision evidence instead of a global preflight. When a live branch resembles a rejected decision, resolve its recorded reason and optional `reconsider_if` conditions through code/docs inspection before asking the user. Treat each `reconsider_if` list item as an independently sufficient trigger (OR semantics): if available evidence satisfies none, keep the rejection as a current constraint or non-goal without re-litigation; if evidence satisfies one, reopen the decision and cite the condition plus changed evidence; if a condition cannot be resolved, ask only for that concrete missing fact. When `reconsider_if` is absent, preserve the backwards-compatible "what has changed?" fallback after inspection. When `rejection_reason` is absent, inspect an explicit rejection-reason section in the body; if no reason exists, report the metadata gap without inventing a reason or reconsideration condition.
+- **CONTEXT.md Awareness**: When the user uses vague or conflicting domain terms, check `CONTEXT.md` at the repo root. If a canonical term exists, surface the conflict: "CONTEXT.md defines X as Y, but you seem to mean Z — which is it?" If CONTEXT.md does not exist, note the gap and recommend the planner create it during planning. Use CONTEXT.md vocabulary in the output artifact when available.
+- **Discovery Protocol**: Before broad searching, read `CONTEXT.md` `## Architecture Map` and the active `.imm/memory/current_iteration.json` step `discovery_cache` when present. Use matching `docs/solutions/` `key_files` frontmatter as the pattern layer. If these pointers are missing or stale, note the discovery gap in the framing instead of compensating with unbounded search.
+
+## Research Dispatch
+
+Follow [`docs/reference/subagent-dispatch-protocol.md`](docs/reference/subagent-dispatch-protocol.md) for the full dispatch lifecycle. This section defines brainstorm-specific optional research dispatch.
+
+Runtime helpers: `imm_core.buildBrainstormEnsembleRequest`, `imm_core.buildBrainstormEnsembleDispatchEnvelopes`, `imm_core.normalizePiBrainstormAgentResults`, and `imm_core.normalizeBrainstormEnsemblePacket`.
+
+### Brainstorm Ensemble Advisory
+
+A Brainstorm ensemble is optional advisory-only framing input, not a vote and not a child-owned decision. The default roles are clarify scope, divergent options, minimal solution, and risk review.
+
+All Brainstorm ensemble children are advisory-only with `tool_policy: no tools`; they do not edit code, write Specs, write Plans, mutate workflow state, or close QA. The parent `imm-brainstorm` owns final framing synthesis, Brainstorm manifest IDs, and decision-delta confirmation. Final Spec and Plan authority stays with `imm-planner`. Routine Managed enrollment uses the Planner's final `ctx.ui.custom` confirmation bound to the TaskIntent content hash as the single authority gate; Enrollment validates descriptor structure without executing acceptance descriptors, deterministic QA executes them after implementation, and the routine task proceeds without a second human stop.
+
+Pi's adapter may consume `brainstorm_ensemble` dispatch JSON to prepare advisory Pi subagent envelopes, but envelope construction is not child execution and does not transfer framing authority. Pi launches one foreground Agent at a time, consumes its direct result, and re-evaluates the remaining dispatch budget before launching another candidate. Runtime does not call any agent, poll or recover background work, mutate state, or own final Spec/Plan authority. Pi subagent children remain no-tools advisory candidates; the parent `imm-brainstorm` collects outputs before synthesis.
+
+Agreement becomes framing evidence. Disagreement becomes decision criteria or an open `BR-Q-*`. strong-model blockers become explicit risks or verification requirements for the planner handoff. Small framing tasks do not fan out by default; use solo Brainstorm unless the task has elevated framing risk or an explicit ensemble request.
+
+**Trigger condition:** Only dispatch when the task spans multiple domains (`multi_domain >= 2`) or the user explicitly requests parallel research. Do not dispatch for single-domain or lightweight framing tasks.
+
+**Retrieval budget:** Stop dispatching as soon as existing evidence is sufficient to answer the core framing question. Do not dispatch additional agents to improve phrasing, add examples, or cover non-essential details. Dispatch again only when a required constraint, convention, or risk is still missing from the current evidence set.
+
+**Dispatch behavior:** Use Pi native `Explore` subagents (`subagent_type: "Explore"`). Each prompt must state a bounded read-only scope and returns a structured summary (affected files, conventions found, risks). The parent brainstorm agent merges summaries before producing the output artifact. Research subagents do not write files, specs, plans, or `.imm/` state.
+
+**Manifest mapping:** Repo-local runtimes use `imm_core.brainstorm_research` to keep research probes host-bound and manifest-oriented. Every child summary that affects planning must map to a Brainstorm manifest ID: `BR-REQ-*`, `BR-DEC-*`, `BR-OUT-*`, `BR-DEFER-*`, or `BR-Q-*`. Any unmapped or unresolved research question becomes a `BR-Q-*`; open `BR-Q-*` items block planner handoff.
+
+**Failure handling:** If research dispatch is unavailable or fails, continue with solo inline investigation. Record the fallback reason per the shared protocol.
+
+## Boundary
+
+- **Allowed**: Clarify framing, inspect read-only context, ask narrowing questions, perform inline gap analysis.
+- **Blocked**: Implementation edits, test changes, plan writes, and runtime state updates. Do not edit implementation files, tests, specs, plans, or `.imm/memory/`.
+- **Workflow guard**: implementation continuations must go through `imm-planner` or `imm-loop`. `imm-brainstorm` frames the problem; it is not the default post-framing stage once the task is already stable enough to route forward. The `adversarial` mode remains available as an opt-in high-pressure gate for high-risk scenarios but is not a default route target.
+
+## Output artifact
+
+Concise task framing: Conclusion, In/Out scope, Assumptions/Risks, Brainstorm manifest, Next Action. The default user-facing handoff should read like a short conclusion note; when a planner handoff is ready, include the manifest IDs so confirmed scope cannot be silently dropped during planning. When a decision delta is still unconfirmed, omit the handoff manifest and phrase Next Action as a focused confirmation request rather than a skill route.
+
+## Output style
+
+Default user-facing shape: `Conclusion -> Scope -> Next Action`. For the normal success path, return only these. Only expand `Allowed` / `Blocked` / `Workflow guard` when routing needs explicit guarding. Do not force mini-headings or checklist labels.
+
+## Next Action
+
+- Gate: The exhaustive frontier is empty; no blocked fact prevents traversal; every sourced user decision is settled by a direct requirement, explicit answer, or adopted recommendation; and the result-only summary introduces no unconfirmed decision delta. **If any requested clarification remains unanswered, you MUST NOT proceed to planning or suggest the next skill.** **If a decision delta is still unconfirmed, you MUST NOT proceed to planning, must not name a next skill, and should ask the user to confirm only that delta.**
+- If gates pass: suggest `imm-planner` with a one-line reason.
+- If gates are not met: state which questions or decision deltas remain open; do not name a next skill and wait for the user's answer.

package/plugins/immune-brain/dist/imm-doc-prune.md

@@ -0,0 +1,137 @@
+---
+name: imm-doc-prune
+description: Use to prune stale current documentation from a Git repository after an explicit, hash-bound, user-approved manifest; never deletes Managed authority artifacts.
+---
+
+# Immune-Brain: Doc Prune
+
+Prune stale current documentation from one Git repository through explicit
+invocation, comprehensive inventory, evidence-based candidate narrowing,
+one exact user-approved manifest, and bounded current-only mutation. This is
+a standalone host-native maintenance entry, not a Managed Path continuation
+and not an `imm-loop` internal-role dispatch.
+
+## Authority Boundary
+
+This Skill prunes documentation
+without creating or mutating
+TaskIntent, TaskRecord, Kernel, Spec, or Plan authority. An already active
+Managed task remains owned by `imm-loop`. Read-only inventory and manifest
+production remain available. Classify each candidate overlapping the active
+TaskIntent `scope_hint` as `BLOCKED_ACTIVE_SCOPE` and continue auditing
+unaffected candidates. If the routing owner or scope cannot be read reliably,
+fail closed for mutation.
+
+## Invocation
+
+Requires explicit invocation: `imm-doc-prune` or `/imm-doc-prune`. Ordinary
+"is this doc stale?" questions stay host-native and do not enter this Skill.
+
+- `imm-doc-prune audit`: read-only. Produce the manifest and stop.
+- `imm-doc-prune`: produce the manifest, then wait for exact manifest approval
+  before any mutation.
+
+No automatic invocation. No daemon, no cron, no CI, no allowlist, no runtime,
+no persistent report, and no automatic commit.
+
+## Ordered Pruning Protocol
+
+1. **Establish repository safety.** Mutation requires a Git worktree. A
+   non-Git repository or an untracked candidate is audit-only. Record the
+   candidate path, blob/content hash, tracked status, and candidate-local
+   worktree status. Unrelated dirty files do not block the run; a dirty
+   candidate is `BLOCKED`.
+
+2. **Inventory current documentation.** Enumerate tracked `.md`, `.mdx`,
+   `.rst`, and `.adoc` files, agent instruction files such as `AGENTS.md`,
+   `CLAUDE.md`, and `GEMINI.md`, plus `.json`, `.yaml`, and `.yml` files
+   under documentation directories that are referenced by current
+   documentation. Exclude `node_modules`, vendor trees, build output,
+   caches, arbitrary business data, and source comments from semantic
+   scanning.
+
+3. **Classify document roles.** Distinguish current guidance, generated or
+   mirror content, Kernel authority artifacts, historical-by-purpose
+   records, non-authority archives, and `UNCLASSIFIED` groups. Preserve
+   `CHANGELOG`, release notes, migration records, and incident reports;
+   do not modernize historical narration merely because it describes old
+   behavior.
+
+4. **Build repository facts.** Resolve current truth in this order:
+   executable/public registries, package exports, CLI/runtime entrypoints;
+   behavior tests; active Spec/TaskIntent; current `CONTEXT.md`/ADR/
+   reference/README; Solution/Brainstorm/archive. A lower-priority historical
+   statement cannot prove a retired public surface is current.
+
+5. **Mechanically narrow candidates.** Check local paths and anchors, public
+   Skill/CLI/API names, command/import targets without executing arbitrary
+   examples, inbound local references, source/generated declarations,
+   translations with explicit source mappings, ADR/Solution owners, and
+   conflicting current claims. External URL availability is not probed in
+   the first version.
+
+6. **Apply evidence rules.** Age or zero references alone never proves
+   staleness. ADR deletion requires a removed decision object, an implemented
+   mutually exclusive replacement with current constraints preserved, a
+   retired public surface, or a successor ADR that fully carries current
+   constraints. Solution deletion requires a false `reusable_premise`,
+   vanished `key_files` without a current owner, a retired command/Skill/API/
+   workflow, or complete replacement by current guidance.
+
+7. **Produce one exact manifest.** Classify entries as `DELETE`, `EDIT`,
+   `KEEP`, `BLOCKED`, `BLOCKED_ACTIVE_SCOPE`, `UNVERIFIED`,
+   `HISTORICAL_GIT_ONLY`, or `MISSING_CURRENT_DOC`. Include evidence, exact
+   file/section action, inbound-reference treatment, Git recoverability, and
+   candidate hash. Group `UNCLASSIFIED` files; do not interrogate the user
+   file by file.
+
+8. **Gate mutation.** `audit` mode stops after the manifest. Mutation mode
+   also stops until the literal user approves exact manifest entries (for
+   example, "all recommendations except 4 and 7"). Broad approval such as
+   "clean stale docs" is insufficient. Interruption starts a fresh scan; no
+   manifest is persisted.
+
+9. **Revalidate and mutate minimally.** Re-read candidate bytes, Git status,
+   inbound references, generated ownership, and active scope immediately
+   before each approved change. Drift blocks that item. Delete a whole file
+   only when its role is wholly obsolete; otherwise delete the complete stale
+   logical section or move still-current constraints into an existing current
+   owner before deleting the obsolete source. Never renumber ADRs and never
+   create a new ADR or Solution merely to complete pruning.
+
+10. **Verify and report.** Re-scan residual names and paths, current local
+    links on current documentation, source/generated parity, existing documentation contract tests,
+    and `git diff --check`. This Skill does not execute arbitrary documented
+    commands or the full business suite unless touched executable metadata
+    requires a focused check. This Skill does not commit. Report only `Deleted`, `Edited`, `Blocked`,
+    `Unverified`, `Historical Git-only references`, `Verification`, and
+    `Recovery: git log -- <path>`.
+
+## Mutation Envelope
+
+This Skill may modify or delete approved documentation, explicit translation
+or generated mirrors, documentation sync manifests, and tests whose only
+behavior is asserting document existence or obsolete wording. It must stop
+when completion requires runtime behavior, business-test semantics, package
+exports, public API, credentials, network writes, Git history rewriting, or
+any Managed authority mutation.
+
+Generated content is never independently authored: change the source, update
+its declared sync ownership, and run the repository's existing generator. A
+failed generator or focused check leaves an inspectable diff and stops; this
+Skill does not stash, reset, checkout, or revert user work.
+
+## Authority Artifacts Excluded
+
+This Skill categorically does not delete active or frozen Specs, TaskIntents,
+TaskRecords, tombstones, or other `.imm` authority. Historical immutable
+authority references to deleted non-authority documents are allowed and
+reported as `HISTORICAL_GIT_ONLY` references with the recovering commit; they
+are not treated as current dangling links.
+
+## Recovery
+
+Git history is the archive for obsolete non-authority documentation. Every
+`DELETE` entry reports `Recovery: git log -- <path>` so the user can restore
+content from history. Untracked, dirty, or non-Git candidates are never
+deleted.

package/plugins/immune-brain/dist/imm-loop.md

@@ -0,0 +1,158 @@
+---
+name: imm-loop
+description: Use when running validated Plans to completion.
+---
+
+# Immune-Brain: Loop
+
+This skill adheres to the **[BASELINE.md](BASELINE.md)**.
+At every runtime role boundary, call the read-only `imm_loop_action` Tool. Use
+`route` for active Steps, bounded repair, architecture exploration, advisory
+review, Compounder, Kernel ownership, or scope expansion. Use `dispatch_role`
+for `qa`, `code-review`, and `ui-review`, then invoke the returned foreground
+Agent envelope exactly. Brainstorm and Planner use the same Tool for bounded
+`arch-explorer` and explicit-lens `advisory-reviewer` dispatches. Loop may
+dispatch `compounder` only when a closed Step supplies structured evidence for
+a reusable Learning; routine work without that evidence returns `next: none`
+and creates no Learning. Do not discover or load a Pi Skill for these roles. The Managed Path public entries remain `imm-brainstorm`, `imm-planner`, and `imm-loop`; standalone `imm-pr-fix` and `imm-doc-prune` are host-native and are never dispatched as the Loop role.
+Dispatch authorization follows the [shared Subagent Dispatch
+Protocol](docs/reference/subagent-dispatch-protocol.md#authorization-authority).
+Same-boundary `follow_up` is not a Plan mutation; it repeats the current
+execution, QA, and originating review gate. All internal Agent dispatch
+envelopes use `run_in_background: false` and return `tool_call`, `tool_result`,
+and `tool_execution_end` evidence to the Parent before any workflow mutation.
+
+## Workflow Profiles
+
+- `direct` has no Plan or Ledger and never invokes this skill.
+- `standard` keeps execution in the main context, closes a Plan Step when the runtime accepts passing evidence, and therefore does not dispatch the internal QA role per Step. It still dispatches every runtime-required final code/UI review gate. The last gate pass atomically performs internal terminal settlement when `compounder_requirement.required` is false.
+- `strict` preserves the full internal loop: each Step reaches isolated QA before final review, internal Compounder handoff, and terminal settlement. A missing profile is strict.
+- Reviewer `follow_up` targets always retain isolated QA. Standard Plans allow at
+  most two completed/open rounds; `review_budget_state.budget_stop` is a hard
+  stop. Never attempt a third Loop runtime action.
+- `workflow_profile`, `compounder_requirement`, and `review_budget_state` from
+  the live Kernel / Loop projection are authoritative. Do not infer or override
+  them in the host.
+
+## Core Responsibilities
+
+- **Main-context completion loop**: Drive the enrolled Kernel task in the current Pi conversation until completion or a safe stop.
+- **Context-preserving execution**: Call `imm_loop_action` with `op: route`, then follow the returned `executor` context in the current Parent conversation. Implement only the active Step or pending same-boundary `follow_up`, then record structured execution evidence through the Loop runtime action. A bounded test failure uses the returned internal `test-fixer` dispatch with its explicit delegated test-file list; PR feedback or CI repair uses the returned internal `pr-fix` dispatch inside the current Plan boundary.
+- **Independent authority isolation**: Use the host `Agent` subagent primitive for `awaiting_qa_decision` and for the exact runtime-reported review gate. Standard Plan Steps close from accepted passing evidence before an internal QA boundary exists; Strict Steps and all follow-ups retain isolated QA. The parent records accepted child decisions through the Loop runtime action.
+- **Observable progress**: Update only at major phase changes: Step start, execution evidence recorded, QA/review result, or terminal stop. Always emit a terminal summary.
+- **Kernel projection authority**: Re-read `imm_kernel_canary` `status` after every persisted action. Conversation memory never overrides the Kernel projection.
+- **External tracker boundary**: The host may attach one opted-in GitHub Issue projection after terminal settlement. Only a fresh claimless `done`/`stopped` projection plus its exact terminal tombstone projects `completed`/`not planned`; Enrollment performs no GitHub projection. Report tracker failures separately, but never treat them as evidence, stop the Loop, repeat a Kernel mutation, or import Issue state.
+- **Scope boundary**: Scope expansion always returns to `imm-planner`; Executor, test repair, and PR/CI repair stop with the concrete missing scope and verification reason instead of widening execution.
+- **Action authority**: The loop always enters through `imm_loop_action`; its projected `next` authority is `executor`, `test-fixer`, `pr-fix`, `arch-explorer`, `advisory-reviewer`, `compounder`, `imm_kernel_canary`, `imm-planner`, or `none`.
+
+## Kernel Loop
+
+Repeat this sequence; do not silently stop while a valid action remains:
+
+1. Call `imm_loop_action` with `op: route` (or `dispatch_role` at a QA/review boundary) and follow the projected `next` authority.
+2. Emit one progress line: `[target][phase] result | next: action`.
+3. Execute exactly one allowed action:
+   - Kernel ownership: call `imm_kernel_canary` for that owned task. Freeze the completed artifacts, then call `advance_assurance`; when it returns `review_ready`, invoke the exact reserved foreground Agent and call `submit_review`. When the projection calls for `request_authorization`, `approve_breaking_intent_revision`, or `repair_authority_state`, invoke the exact Tool operation directly without asking the user for chat pre-confirmation. The native host interaction is the single authority decision.
+   - Active Step / `rework_needed`: follow the returned `executor` context in the current conversation, implement only the active Step or pending same-boundary `follow_up`, verify, record structured execution evidence through the Loop runtime action, and continue. A bounded test-only repair may request internal `test-fixer` with `focus_delta.specific_changes`; PR review or CI repair may request internal `pr-fix` with the current `plan_id`, changed-file boundary, and verification. Both return child evidence to the Parent and cannot widen scope.
+   - `awaiting_qa_decision`: call `imm_loop_action` with `op: dispatch_role`, role `qa`, the current projection, Plan verification, recorded evidence, and current target identity. Invoke the returned foreground Agent envelope exactly. A `rework` or `replan` must carry validated `notes`.
+   - `review_required`: map the exact `pending_review_gate` (`imm-code-review` or `imm-ui-review`) to the internal `code-review` or `ui-review` role and call `imm_loop_action` with `op: dispatch_role`, passing `pending_review_gate`, `review_changed_files`, and `review_changed_files_signature`. Invoke the returned foreground Agent envelope exactly. Record a validated pass, or open a same-boundary follow-up through the Loop runtime action.
+   - `awaiting_user_successor_decision`: stop immediately with `recommended_authority: user`, no next skill, and no runtime action. This boundary must not dispatch Planner, transition, Compounder, or a new Pi session/subagent. Only a literal user may supply a concrete validated successor Plan through the native authority gate; the internal runtime token is `--approve-successor`, never a public Skill or user-facing entry.
+4. After every accepted runtime write, discard the old snapshot and read a fresh Kernel / Loop projection. Emit a result line only when the write completes a major phase or a subagent round.
+
+Use Pi native `Agent` subagents. Do not spawn Pi child processes or invoke a separate `imm-loop` CLI.
+
+## Authority and Failure Guards
+
+- Implementation requires a validated Plan and active Step or accepted pending `follow_up`.
+- The parent may implement but must not issue its own QA or review pass.
+- QA and reviewer children must not edit files, write Plans, mutate Kernel state, or close decisions directly.
+- Missing `Agent` support, failed or malformed child output, stale child target, runtime write failure, invalid projection, missing credentials, unclear verification, repeated unchanged failure, or user cancellation stops fail-closed with an explicit reason and no decision write.
+- `replan_needed` stops at `imm-planner`; do not widen scope or rewrite the active Plan. A replacement must use a new sequential Plan path after the current Plan reaches `completed`, or after a literal user explicitly marks it `cancelled` or `superseded`.
+- Plans never suspend, resume, queue, or execute in parallel. Do not insert a repair Plan ahead of the current Plan.
+- Same-boundary review `follow_up` repeats execution, independent QA, and the originating review gate.
+- Runtime `review_required` is the single review-gate authority. Do not invent hidden gates.
+- `imm-compounder` is an internal role and is never invoked as a public Skill. A `complete` projection carries an explicit internal Compounder handoff because the runtime determined it is required. A Standard Plan with optional Compounder is atomically finished by the last review gate and does not emit that handoff. Strict Plans preserve the successful order: current Steps and QA, required reviews, internal Compounder handoff, terminal settlement, then `awaiting_user_successor_decision` for a non-terminal Roadmap slice.
+- Successor approval is non-delegable. QA, review, Planner, Compounder, and the loop cannot approve or activate a successor, and the loop must not turn a command template into an executable successor invocation.
+
+## Stop Conditions
+
+Stop only for:
+
+- `complete` with an explicit internal Compounder handoff before terminal settlement
+- `terminal_plan_complete` after a contracted terminal Plan or a legacy Plan without successor metadata has passed internal Compounder handoff and terminal settlement; stop with no next skill, authority, or action
+- `awaiting_user_successor_decision` after finish, with literal user authority and no automatic action
+- `replan_needed`
+- blocker or required user input
+- runtime, tool, subagent, or output-contract failure
+- user cancellation (no decision write; Plan termination is a separate explicit user-confirmed runtime action)
+- repeated unchanged failure
+- explicit Step, rework, review, follow-up, or elapsed-time budget exhaustion
+
+Session-local budgets are advisory. Persisted Step, QA, review, and follow-up state controls recovery. After interruption, re-enter only by reading a fresh projection: a completed runtime write is honored once; an interrupted pre-write action is not claimed; cancellation performs no decision write; repeated unchanged failure stops unless the next attempt names a strategy change; explicit budgets stop before another action.
+
+## Observable Output Contract
+
+Do not narrate projection reads or routine runtime writes. Emit compact progress only for Step start, completed execution evidence, QA/review decisions, failures that change the plan, and terminal stop. Every subagent round still emits exactly one dispatch line and exactly one collection/result line:
+
+```text
+[Step 1/3][Executor] evidence recorded | next: QA
+[Step 1/3][QA] Agent dispatched
+[Step 1/3][QA] Agent collected: pass | next: imm-code-review
+```
+
+Do not emit a successful collection line for timeout, cancellation, malformed output, or stale identity; emit the explicit failure stop instead.
+
+Every exit, including failure, must include:
+
+```text
+Plan:
+Completed Steps:
+QA:
+Review:
+Stop reason:
+Next action:
+```
+
+Normal conversation text and visible tool calls are the correctness-level observation surface. Extension widgets are optional decoration only.
+
+## Boundary
+
+- **Allowed**: Coordinate Kernel / Loop projections, current-conversation Executor work, isolated QA/review children, runtime decision recording, same-boundary follow-up, and terminal handoff reporting.
+- **Blocked**: Plan edits, parent-owned QA/review pass, hidden review gates, direct Kernel-store edits, child-owned state mutation, automatic Compounder execution, and external loop runners.
+- **Workflow guard**: Kernel and Loop projections choose the next authority; each authority keeps its existing Skill contract.
+
+## Output artifact
+
+A visible completion trace plus terminal summary containing Plan, completed Steps, QA state, review state, stop reason, and next action.
+
+## Next Action
+
+- If no validated Plan exists: stop and route to `imm-planner`.
+- If an allowed Loop action exists: continue the loop without another user command.
+- If work is fully closed but not finished: report the explicit internal Compounder handoff and wait for terminal settlement.
+- If the projection is `awaiting_user_successor_decision`: report the candidate and preconditions, ask for the user's decision, and stop without dispatch.
+
+## Output style
+
+Default user-facing shape: checkpoint progress lines, then `Conclusion -> Evidence -> Next action` at the terminal boundary.
+
+## Kernel Canary Routing
+
+When the Kernel projection reports an active/draining backend claim, keep
+`imm-loop` as the user-facing entry and call the `imm_kernel_canary` Tool for
+that owned task. Enrollment uses the `imm_canary_enrollment` Tool and Review
+authorization remains a native TUI gate using the internal user-kind approval
+action `record-user-approval`. When the projection calls for
+`request_authorization`, `approve_breaking_intent_revision`, or
+`repair_authority_state`, invoke the exact Tool operation directly without
+asking the user for chat pre-confirmation; the native host interaction is the
+single authority decision. This action is not a public Skill or CLI route. Do
+not invoke the removed `imm-canary-work` Skill as a separate entry point.
+Invalid or contradictory projections fail closed. After implementation and focused verification, freeze the artifacts and call
+`imm_kernel_canary` `advance_assurance`. If it returns `review_ready`, invoke
+the exact reserved foreground Agent and call `submit_review`;
+`request_authorization` remains the user authorization boundary. Visible
+background state and push follow-up replace manual QA/Review sequencing and
+result polling. A terminal task leaves only an immutable task tombstone: it is
+never reactivated and never blocks unrelated v3 routing. The Kernel projection
+is advisory; every Kernel mutation re-enters Kernel store-lock validation.