immune-brain 5.1.1 → 5.2.0

package/plugins/immune-brain/dist/docs/reference/planning-quality-gate.md

@@ -25,7 +25,7 @@ Apply the gate when the task touches one or more of these surfaces:
 - **TaskIntent decomposition**: use Technical Design boundaries as one retain/split criterion with outcome, Verification, dependency, risk, rollback, compatibility, and authority. Split a successor TaskIntent only when a service, state-machine owner, migration, independently promotable layer, or sequence dependency needs independent verification, rollback, authorization, or settlement. A TaskIntent should normally change one primary trust-boundary invariant, but traversing several boundaries or updating both sides of one authority chain does not itself require a split. Split independently verifiable, reversible, authorizable, migratable, or settleable trust invariants. Keep multiple trust-boundary changes together only for one atomic security outcome whose split would create an unsafe or unusable intermediate state, and record that rationale in the Spec. Treat this as Planner judgment rather than a schema field or Enrollment counting rule. Do not split merely because the design names several layers, files, or services, and do not revive prose Plan authority. For a multi-TaskIntent Initiative only, require each Slice to state what is observable and verifiable when that Slice alone has landed, and no acceptance may require another unfinished Slice's work to pass; a Slice with no such statement is a horizontal layer slice and is re-cut. Record the exception for a wide mechanical refactor whose blast radius prevents any green vertical slice, with the rationale and a final integrate-and-verify Slice that the batches block.
 - **Mermaid intent**: use Mermaid only when it clarifies structure, sequence, data flow, or state transitions; it is not a universal gate or a second source of truth. Medium/High risk Specs record `**Diagram decision**: required|not_required` and a non-empty `**Diagram reason**:`. A `required` decision must include Mermaid; `not_required` explains why prose is sufficient. Low-risk Specs omit the empty ceremony and record neither field.
 - **Design Conformance**: before final closure, require Spec-to-implementation evidence. A local implementation mismatch routes to `rework`; a structural or intended design change routes to `replan` through Planner. QA cannot silently approve a design change.
-- **Brainstorm traceability**: ensure every `BR-*` item listed in `Brainstorm manifest` is mapped in `Brainstorm Trace`. Every Spec decision and every acceptance names exactly one source — an upstream `BR-*` ID, repository evidence, or a delegated technical choice — with or without an upstream manifest, and a user-owned decision that names no source is a defect the Planner removes or returns for clarification.
+- **Brainstorm traceability**: ensure every `BR-*` item listed in `Brainstorm manifest` is mapped in `Brainstorm Trace`. Every Spec decision and every acceptance names exactly one source — an upstream `BR-*` ID, repository evidence, or a delegated technical choice — with or without an upstream manifest, and a user-owned decision that names no source is a defect the Planner removes or returns for clarification. A Spec for work with a user-observable change has a `User scenarios` section; each scenario keeps its upstream `BR-SCN-<n>` ID, or on direct entry is confirmed in clarification and recorded as Spec-local `SCN-<n>`, is tagged `automated` with at least one acceptance ID or `manual` with the reason it cannot be automated, and the mapping is one-way. In a multi-TaskIntent Initiative a scenario belongs to exactly one Slice, the one that first makes it observable. `BR-SCN-*` items fall under the existing handoff completeness check, a scenario with no source is a defect, and `no user-visible change` requires a recorded reason.
 - **roadmap information preservation**: for large or multi-phase work, distinguish the Roadmap from the current executable slice, preserve deferred phase goals, open questions, promotion criteria, and candidate next Plans.
 - **executable-slice discipline**: the Plan promises only the current executable slice — one coherent set of Steps sharing acceptance, review, rollback, and authority boundaries. Future-phase logic, speculative architecture, and unvalidated assumptions belong in the Roadmap or as explicitly Deferred items, never as active Steps. Do not enforce a fixed Step count: multiple Steps inside one shared boundary are fine, and a single Step that smuggles in unvalidated future architecture is still over-planning.
 - **Plan boundary cohesion**: treat Plan granularity separately from Step and Roadmap Phase granularity. Confirm the current Plan contains one coherent executable slice and explain why its outcome, authority, risk, verification, review, and rollback boundaries belong together. Promote an independent boundary into a sequential Plan instead of hiding it inside a large Step. One Phase may therefore span multiple Plans.

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

@@ -95,8 +95,8 @@ 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.
+to `BR-REQ-*`, `BR-DEC-*`, `BR-OUT-*`, `BR-DEFER-*`, resolved `BR-Q-*`,
+and `BR-SCN-*` manifest entries; do not copy the question transcript into repository artifacts.
 
 ## Explicit exhaustive interrogation
 
@@ -119,7 +119,7 @@ empty, or report remaining blocked/open nodes if the user stops early.
 - **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.
+- **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, `BR-Q-*` for open questions, and `BR-SCN-*` for a confirmed user scenario. A `BR-SCN-*` item has exactly `Actor`, `Given`, `When`, `Then`, written in English. `Then` states a result the actor observes directly — command output, a file, an Issue or UI state — and never an internal state or a test file name. Record a scenario only for framing that changes user-observable behavior: framing without a user-observable change gets no invented scenario. 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` when the material frontier is empty, no required fact blocks the handoff, and every material user decision is settled by a direct requirement, explicit answer, or adopted recommendation. 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**: Only when optional research is needed, read Research Dispatch and its shared dispatch reference. Default to inline evidence gathering; do not load dispatch instructions merely because Brainstorm was invoked.
 - **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.
@@ -138,7 +138,7 @@ Runtime helpers: `imm_core.buildBrainstormEnsembleRequest`, `imm_core.buildBrain
 
 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 current Host's native confirmation bound to the TaskIntent revision, content hash, and preparation digest 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. A later authority-gate failure stays fail-closed in the current Host and reports exactly one same-Host recovery action; Brainstorm must never recommend another Host, worktree, or unmanaged implementation as a fallback.
+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`. Neither Brainstorm nor the Planner invokes Enrollment: the user launches `imm-planner` after framing and `imm-run` after planning, and a confirmation of a framing or a plan starts neither. Routine Managed enrollment is the first step of an explicit `imm-run` entry and uses the current Host's native confirmation bound to the TaskIntent revision, content hash, and preparation digest as the single authority gate; Enrollment validates descriptor structure without executing acceptance descriptors, and deterministic QA executes them after implementation. A later authority-gate failure stays fail-closed in the current Host and reports exactly one same-Host recovery action; Brainstorm must never recommend another Host, worktree, or unmanaged implementation as a fallback.
 
 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.
 
@@ -150,7 +150,7 @@ Agreement becomes framing evidence. Disagreement becomes decision criteria or an
 
 **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.
+**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-*`, `BR-Q-*`, or `BR-SCN-*`. 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.
 
@@ -171,5 +171,5 @@ Default user-facing shape: `Conclusion -> Scope -> Next Action`. For the normal
 ## Next Action
 
 - Gate: The material frontier is empty; no required fact blocks the handoff; every material 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 required 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 pass: suggest `imm-planner` with a one-line reason and stop. The user launches it; Brainstorm never enters `imm-planner` or `imm-run` on its own and never invokes Enrollment.
 - 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

@@ -117,7 +117,8 @@ no persistent report, and no automatic commit.
 
 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
+behavior is asserting document existence or obsolete wording; test structure and
+behavioral coverage belong to `imm-test-prune`. 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.

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

@@ -12,21 +12,18 @@ This skill adheres to the **[BASELINE.md](BASELINE.md)**.
 `imm-planner` is entered explicitly by the user for a clear repository mutation.
 Ordinary host input does not invoke this Skill through natural-language routing.
 An active Assurance projection remains authoritative and is resumed only through
-an explicit `imm-run` entry; explicit Planner entry owns planning and the later
-native Enrollment gate.
-
-Plan-only output remains non-authoritative. Planner creates or validates a
-candidate Spec/TaskIntent. Planner may request the native Enrollment gate;
-only that gate grants execution authority. Explicit Plan-only requests stop after returning the
-planning artifacts. A later literal-user request to start Enrollment is a
-non-authoritative execution trigger: invoke the native Enrollment gate directly,
-without asking for chat pre-confirmation. For a clear mutation request that
-already includes execution, invoke that gate as soon as the candidate is
-validated and Git-tracked. Literal-user confirmation in the current Host's
-native gate remains the authority boundary. A gate failure preserves candidate
-artifacts and reports its reason plus exactly one same-Host recovery action; it
-must never recommend another Host, worktree, Direct Path, unmanaged
-implementation, or automatic retry. Fast-Track may compress the same phases but
+an explicit `imm-run` entry; explicit Planner entry owns planning only.
+
+Planner output remains non-authoritative. Planner creates or validates a
+candidate Spec/TaskIntent and never invokes the native Enrollment gate;
+only that gate grants execution authority, and it opens only as the first step
+of a literal-user `imm-run` entry. Every Planner request stops after returning
+the validated planning artifacts, including a request that also asks for
+execution: report the candidate and name a literal-user `imm-run` entry as the
+only next step. A design confirmation, a generic continuation, or a request to
+start Enrollment received inside the Planner is not an `imm-run` entry and
+opens no gate. Literal-user confirmation in the current Host's
+native gate remains the authority boundary. Fast-Track may compress the same phases but
 cannot bypass that boundary, QA, Review, authorization, or completion.
 
 ## Clarification supplement
@@ -119,13 +116,12 @@ Enrollment.
 
 Host identity is implicit and never a planning input. The production boundary
 that turns a Git-tracked TaskIntent draft into managed execution authority is
-the current Host's native Enrollment gate. Invoke that Host integration
-directly when the route is ready; do not ask for chat pre-confirmation. The
-single literal-user decision is bound to the TaskIntent revision, content hash,
-and preparation digest. Enrollment validates the intent, Git ownership, scope,
-workspace claim, and final authority preconditions without executing acceptance
-descriptors. A routine task proceeds from that single confirmation through
-enrollment, execution and QA without a second human stop.
+the current Host's native Enrollment gate. `imm-run` invokes that Host
+integration as the first step of a literal-user entry; the Planner never does.
+The single literal-user decision is bound to the TaskIntent revision, content
+hash, and preparation digest. Enrollment validates the intent, Git ownership,
+scope, workspace claim, and final authority preconditions without executing
+acceptance descriptors.
 
 **Automatic policy activation**
 
@@ -237,14 +233,21 @@ confirm a name, slug, Child, or dependency that had not yet been shown.
 
 Once decomposition is complete, present one review table containing the Parent
 result and every Child's stable Slice ID, result, scope boundary, risk, blockers,
-and proposed execution order. Ask one focused question: whether the coverage,
+each Slice's scenario IDs or its exemption with the reason, and proposed execution order. Ask one focused question: whether the coverage,
 granularity, and dependencies are correct. Recommend the complete current
 frontier so the user can approve it in one response. Before that approval,
 perform zero GitHub mutations. A partial or progressively disclosed issue set is
 not eligible for publication.
 
 After approval, author, stage, and validate every TaskIntent in the decomposition
-with `valid: true` and `enrollment_ready: true`. Resolve `../bin/imm-tracker` from this packaged contract; do not assume a bare command is on `PATH`. Submit the entire approved set once through
+with `valid: true` and `enrollment_ready: true`. Before handoff, compare the
+scopes by machine: run `imm-kernel intent overlap <path> <path>... --json` over
+every TaskIntent of the Initiative, with one `--blocked-by <task-id>=<task-id>,...`
+per dependency, and report its `overlaps` (each shared entry pair) and
+`parallel_groups`. Parallel recommendations follow that output, which uses the
+same projection as the Batch Plan. Never write "disjoint" or "verified" for
+scopes by hand; when the output shows an overlap the Slices run serially unless
+a revised `scope_hint` removes it. Resolve `../bin/imm-tracker` from this packaged contract; do not assume a bare command is on `PATH`. Submit the entire approved set once through
 `imm-tracker publish-initiative --stdin --json`. Its input contains the confirmed
 Initiative slug and goal, Parent projection, and every Child's `slice_id`,
 canonical TaskIntent path, bounded public `acceptance` summaries, and public
@@ -263,7 +266,27 @@ published Child; future checklist-only Slices are not allowed in the batch.
 Each Child must provide public `acceptance` entries with `id` and a 1-500
 character `summary`. Their IDs must match every canonical TaskIntent acceptance
 ID exactly once. Canonical assertion prose is authority evidence and must never
-be copied into public GitHub projection. Each Child projection requires
+be copied into public GitHub projection. Each Child may also provide an optional
+`scenarios` array. Omitting it, or giving an empty array, renders no
+`## User scenarios` section for that Child and contributes nothing to the Parent;
+when no Task supplies scenarios the Parent and every Child body are unchanged.
+A scenario is public projection of one user-observable result: `id`
+(`BR-SCN-<n>` or `SCN-<n>`), `actor`, `given`, `when`, `then`, and `mode`.
+`automated` maps to one or more of that Task's canonical acceptance IDs and
+renders as a plain bullet; `manual` requires `manual_reason`, may name no
+acceptance ID, and renders as an unchecked task-list item that also shows the
+reason. The Parent derives one plain bullet per scenario (its ID, owning Slice
+ID, mode, When, and Then) and never a checkbox. Scenarios never widen TaskIntent
+scope or authority. The tracker rejects the whole batch before any remote write
+when a scenario lacks a field, has an id matching neither form, repeats an id
+within the Initiative, is automated with no acceptance ID, names an acceptance ID
+its TaskIntent lacks, or is manual without `manual_reason`. Every scenario list
+item starts at the beginning of its line, so no metadata comment precedes the
+marker. Each Child's ownership marker block also carries one
+`<!-- immune-brain:scenarios=<percent-encoded JSON> -->` per Task holding all of
+its scenarios verbatim; an amendment reads historical scenarios only from that
+marker, never parses the visible section, and treats a Child without it as
+having no scenarios. Each Child projection requires
 `title` (1-60 characters), the short Slice display title, and may contain
 `result`, `current_behavior`,
 `desired_behavior`, `key_interfaces`, `verification`, `blocked_by` Task IDs,
@@ -300,11 +323,9 @@ prompt digests never belong in this external handoff. If
 Local mode performs zero GitHub operations.
 
 The batch result includes an execution recommendation: the first unblocked Task,
-a stable dependency order, and parallel groups. For a plan-only request, report
-that recommendation and stop. For a request that includes execution, invoke the
-native Enrollment gate for the recommended first TaskIntent after successful
-publication; do not ask for another chat confirmation. GitHub selection never
-bypasses Enrollment.
+a stable dependency order, and parallel groups. Report that recommendation and
+stop; the user enrolls the recommended first TaskIntent through a literal-user
+`imm-run` entry. GitHub selection never bypasses Enrollment.
 
 Tracker output is observation, never authority. Before the Planner returns, its
 GitHub carrier outcome must be exactly one of: `tracker_associated` after the
@@ -485,9 +506,15 @@ when breaking, `approve_breaking_intent_revision` with the complete next intent.
 The native gate is the single user decision for a breaking revision; candidate
 preparation does not apply the revision or authorize expanded execution.
 
+A revision is warranted only when the goal, the `scope_hint`, or a user-visible
+commitment changes. A finding whose defect lies inside the current goal and scope
+is ordinary rework for the Loop, not a revision request: decline to prepare one
+that only appends a single input case to an acceptance assertion. Acceptance
+states principles; enumeration of cases belongs in tests.
+
 ## Planning Rules
 
-- **Entry Contract**: Use when Spec/TaskIntent planning is needed. An already enrolled owner remains on its current Kernel authority and resumes only through explicit `imm-run`; a validated candidate still needs native Enrollment.
+- **Entry Contract**: Use when Spec/TaskIntent planning is needed. An already enrolled owner remains on its current Kernel authority and resumes only through explicit `imm-run`; a validated candidate still needs native Enrollment, which only an explicit `imm-run` entry opens.
 - **Output Language Gate**: Before writing or revising any Spec or Plan, read the project output language policy from `AGENTS.md`, `IMMUNE.md`, or Immune-Brain plugin config. Default Spec and Plan prose to English unless the current user request, project instructions, or host/user preference contains an explicit document-language instruction. A reply-language instruction does not change document language. Keep schema fields, CLI commands, file paths, code identifiers, enum values, JSON keys, and canonical terms such as `Step`, `Plan`, `Spec`, `Verification`, `Discovery cache`, and `Devil's Advocate Audit` literal.
 - **Clarification Supplement**: If an upstream `imm-brainstorm` manifest exists, verify that every `BR-Q-*` item is resolved and every confirmed framing decision is represented; must not repeat, reopen, or rewrite confirmed decisions. Ask only a focused omission, repository-conflict, or invalidated-assumption delta tied to concrete evidence. Resolve a local delta here; return to `imm-brainstorm` when it reopens multiple product branches or changes the overall goal or Scope. Finalization requires no unresolved supplement and no unconfirmed decision introduced by Planner.
 - **Planning Bootstrap**: When no upstream `imm-brainstorm` manifest exists, preserve Direct Planner entry by resolving repository facts and deriving ordinary technical choices. An already-clear request takes the zero-question fast path to a non-blocking correction summary. Discovery of an unresolved user-owned goal, user, scope, behavior, compatibility preference, risk acceptance, or success criterion returns to `imm-brainstorm`; Planner does not convert product uncertainty into a silent assumption or duplicate Brainstorm's interview.
@@ -515,7 +542,7 @@ preparation does not apply the revision or authorize expanded execution.
   follows Enrolled Intent Revision.
 - **Review Mapping**: In-scope rework stays with the enrolled TaskIntent and explicit `imm-run` entry. Cross-scope findings become a Planner decision delta with concrete missing paths and verification evidence; do not create a successor prose Plan.
 - **Decision Provenance**: Every Spec decision and every acceptance names exactly one source: an upstream `BR-*` ID, repository evidence with a concrete path, or a delegated technical choice as defined by Clarification supplement. The rule applies with or without an upstream Brainstorm manifest, and the source does not have to be a `BR-DEC` item: Direct Planner entry and delegated technical choices stay legitimate sources. A user-owned decision — goal, user, scope, observable behavior, compatibility preference, risk acceptance, or success criterion — that names no source is a defect the Planner removes or returns for clarification under the existing Clarification supplement routes. Simple TaskIntent-only work satisfies the rule when each acceptance traces to the request text and adds no table.
-- **Brainstorm Manifest Mapping**: Record every upstream `BR-*` item in a Spec `Brainstorm Trace` when the work is complex, otherwise on the TaskIntent, mapped to acceptance, a captured decision, or an explicit reason for deferral or exclusion. Resolve every `BR-Q-*` item before handoff. Do not silently narrow confirmed framing.
+- **Brainstorm Manifest Mapping**: Record every upstream `BR-*` item in a Spec `Brainstorm Trace` when the work is complex, otherwise on the TaskIntent, mapped to acceptance, a captured decision, or an explicit reason for deferral or exclusion. Resolve every `BR-Q-*` item before handoff. Do not silently narrow confirmed framing. A Spec for work with a user-observable change has a `User scenarios` section. Each scenario keeps its upstream `BR-SCN-<n>` ID; on direct entry each scenario is confirmed in clarification and recorded as Spec-local `SCN-<n>` sourced to that confirmation, and a scenario with no source is a defect the Planner removes or returns for clarification. Each scenario is tagged `automated` with at least one acceptance ID, or `manual` with the reason it cannot be automated; a `manual` scenario may name no acceptance, and the mapping is one-way — an acceptance need not serve a scenario. In a multi-TaskIntent Initiative a scenario belongs to exactly one Slice, the one that first makes it observable, and an `automated` scenario maps only to that Slice's acceptance. `BR-SCN-*` items fall under the existing handoff completeness check like every other `BR-*` item. When the work has no user-observable change, record `no user-visible change` with a one-line reason — in the Spec for complex work, on the TaskIntent goal for simple work — write no scenario section, and `no user-visible change` requires a recorded reason.
 - **Handoff Completeness Check**: Before reporting a candidate as handoff-ready, confirm every upstream item and required phase is mapped exactly once, that required phases are delivered rather than excused by a reason, and that no confirmed outcome was conserved as a smaller deliverable. Reject a narrowed deliverable as a completeness failure; ask again only for a new material delta, never to reconfirm an unchanged clear request or an already-confirmed decision.
 - **Session Lifecycle Ownership**: The user chooses the current or a new session. Tokens, compactions, tool counts, elapsed time, and review rounds never trigger automatic session creation or termination. Recovery uses TaskRecord and the fresh Kernel projection.
 - **Subagents**: Only when optional research is needed, read Research Dispatch and its shared dispatch reference. Default to inline evidence gathering. Plan conditional reviewers such as `security-reviewer` only if their trigger surfaces are explicit; do not manufacture them.
@@ -568,7 +595,7 @@ optional advisory dispatch fails, continue inline and record the reason.
 
 - **Allowed**: Write a TaskIntent. Add a Spec only for complex work. Activate an absent routing policy under Kernel TaskIntent Routing. Initiative planning carriers and necessary domain vocabulary.
 - **Blocked**: Implementation edits, direct Kernel-store writes, enrolled intent overwrites, and QA/Review decisions.
-- **Workflow guard**: Execution continues through native Enrollment and explicit `imm-run`. Planner owns design and decomposition, not execution authority.
+- **Workflow guard**: Execution starts only from a literal-user `imm-run` entry, whose first step is native Enrollment. Planner owns design and decomposition, never Enrollment or execution authority.
 
 ## Output artifact
 
@@ -616,11 +643,10 @@ a State Ledger. Keep historical Plan validation strictly read-only.
 - Validate every candidate through `imm-kernel intent validate <path> --json` after authoring and staging. Require `valid: true` and `enrollment_ready: true` before Enrollment. When `git_base_initialization_required: true`, report that the existing native Enrollment confirmation includes an empty root commit; leave initialization to the Host. An invalid `git_base` blocks Enrollment and requires Git repair.
 - For complex work, verify Spec design metadata, document language, reference closure, concrete descriptor paths, and complete Brainstorm traceability before handoff. Simple TaskIntent-only work verifies those properties on the Intent.
 - Enrollment validates descriptor structure only. Deterministic QA owns descriptor execution after implementation; planning does not run the acceptance suite.
-- Managed execution handoff is Git-tracked TaskIntent author/validate plus current-Host native Enrollment. Do not sync a v3 State Ledger or invoke a missing dispatcher.
+- Managed execution handoff is Git-tracked TaskIntent author/validate; current-Host native Enrollment follows in `imm-run`. Do not sync a v3 State Ledger or invoke a missing dispatcher.
 
 ## Next Action
 
-- Gate: Reference closure and clarification are complete; every upstream `BR-*` item is represented; no unresolved user decision remains; Planner-introduced decision deltas are confirmed; the candidate is Git-tracked and validates with `valid: true` and `enrollment_ready: true`; each acceptance has concrete focused verification. Plan-only requests stop here.
-- If gates pass: for Kernel-managed work, invoke the current Host's native Enrollment Tool directly without chat pre-confirmation. Its single literal-user gate binds the TaskIntent revision, content hash, and preparation digest, validates Enrollment preconditions without executing acceptance descriptors, and enrolls the task to continue through `imm-run`.
-- If the native gate fails: preserve candidate artifacts and report the stable reason plus exactly one same-Host recovery action. Do not suggest another Host, worktree, Direct Path, unmanaged implementation, or automatic retry.
+- Gate: Reference closure and clarification are complete; every upstream `BR-*` item is represented; no unresolved user decision remains; Planner-introduced decision deltas are confirmed; the candidate is Git-tracked and validates with `valid: true` and `enrollment_ready: true`; each acceptance has concrete focused verification. Plan-only requests stop here, and so does every other Planner request.
+- If gates pass: report the validated candidate (and, for an Initiative, the recommended first Task) and name a literal-user `imm-run` entry as the only next step. Do not invoke the current Host's native Enrollment Tool: Enrollment is the first step of `imm-run`, and a confirmation of the plan is not that entry.
 - If gates are not met: state which validation failures, unresolved verification paths, or material decision deltas remain; do not name a next skill.

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

@@ -10,11 +10,27 @@ This skill adheres to the **[BASELINE.md](BASELINE.md)**.
 ## Kernel Canary Routing and Authority
 
 Only explicit `imm-run` entry starts or resumes this loop. Ordinary host input
-stays host-native; it never resumes a Managed owner implicitly. Read the current
+stays host-native; it never resumes a Managed owner implicitly. While a
+non-terminal TaskRecord holds the workspace, both Hosts add a read-only notice
+to ordinary input (Pi `before_agent_start`, Claude Code `UserPromptSubmit`)
+naming the task, its next obligation and its scope: before committing or
+modifying files inside that scope, read `status` and tell the user the task is
+active and what it waits for. The notice resumes nothing. Read the current
 Host's `status` projection first and verify the exact active backend claim,
 TaskIntent, and TaskRecord. Invalid or contradictory projections fail closed. A
 candidate TaskIntent is not Enrollment authority.
 
+Enrollment is the first step of an explicit `imm-run` entry and belongs to no
+other Skill. When the entry finds no active claim, resolve the validated
+candidate the user named (or the Planner's recommended first Task when the entry
+names none and exactly one candidate fits), then invoke the current Host's
+native Enrollment gate once, without chat pre-confirmation, and continue from
+the returned projection. Planner and Brainstorm never open that gate; a
+confirmation given to either is not this entry. A gate failure preserves the
+candidate and reports its stable reason plus exactly one same-Host recovery
+action; never recommend another Host, worktree, Direct Path, unmanaged
+implementation, or automatic retry.
+
 Before the first Enrollment of a candidate TaskIntent, confirm the Planner
 returned `tracker_associated` — but only when the candidate belongs to an
 identified GitHub-carried Initiative. Standalone TaskIntents and Local
@@ -55,9 +71,9 @@ Before a child dispatch, read the [Subagent Dispatch Protocol](docs/reference/su
 Never load an internal role as a public Skill or spawn another loop process;
 the only exception is a Lane's Executor Host under
 [Lane Executor Supervision](#lane-executor-supervision).
-The standalone `imm-pr-fix`, `imm-doc-prune`, and `imm-doc-slim` are host-native
-maintenance entries, never dispatched as the Loop role. Internal `test-fixer`
-and `pr-fix` repairs remain bounded by the enrolled TaskIntent.
+The standalone `imm-pr-fix`, `imm-doc-prune`, `imm-doc-slim`, and `imm-test-prune`
+are host-native maintenance entries, never dispatched as the Loop role. Internal
+`test-fixer` and `pr-fix` repairs remain bounded by the enrolled TaskIntent.
 
 ## Execution Loop
 
@@ -100,6 +116,12 @@ Continue while the current projection has a valid action:
    accepted contract and answer with `refute_finding` bound to fresh QA evidence
    for that acceptance. Escalating a local heuristic a third time instead of
    choosing one of those two responses is the loop this step exists to break.
+   A finding whose defect lies inside the TaskIntent goal and `scope_hint` is
+   ordinary rework even when no acceptance names its exact case: fix the code,
+   add the test that pins the case, and dispose the finding. It is never a
+   reason to revise the Intent. Acceptance text states principles; enumeration
+   of specific inputs belongs in tests, so never append a single input case to
+   an acceptance assertion in order to close a finding.
 6. An unresolved decision pauses only dependent execution. On `awaiting_user`,
    invoke `request_authorization` directly before ending the turn; use the
    Decisions and Recovery route for its native-gate handling. End the turn if
@@ -197,7 +219,46 @@ Only children whose scopes are provably disjoint run together; a child whose sco
 overlaps an in-flight Lane waits until that Lane is integrated. Settled children
 integrate serially, and a parked child ends only itself and its dependents while a
 disjoint sibling keeps moving. A lost Lane parks as `batch_lane_lost`, and
-`qa_failure_limit` counts each child separately. A resume with a different
+`qa_failure_limit` counts each child separately. A completed settlement inside a
+Lane changes Kernel state only and writes nothing to the tracker: the coordinator
+closes the child's Issue after it integrates that child's commit, exactly once,
+and reports the attempt in `tracker_observations`. A parked or lost child is
+never integrated, so its Issue stays open; an explicit stop inside a Lane still
+projects `not planned` at once.
+
+The lane batch confirmation offers one opt-in choice, off by default: delegate
+to the coordinator the approval of each Lane child's breaking Intent revisions
+that stay inside that child's TaskIntent as authorized for the batch (ADR 0018).
+The answer is recorded on the batch record as `revision_delegation`; a batch
+confirmed without it behaves exactly as before, and the grant ends with that
+batch — a terminal, retired or later batch never uses it. When an integrated
+child's TaskIntent equals the last revision applied under that grant, the runner
+reseals `plan_digest` and records both digests in `reseals`, so later children
+continue without retiring the batch. Any other Intent change still fails closed
+as `plan_changed` and takes the ADR 0016 retirement path.
+
+Before a new lane batch provisions any Lane, the runner compares the Kernel
+contract identifiers (TaskRecord, tombstone, projection, store schema) of the
+coordinator's runtime with those of the runtime a Lane Executor loads — never the
+plugin version number — and refuses with `batch_runtime_contract_mismatch`,
+naming both sources, when they differ; a match adds no confirmation. A Lane whose
+state exists but whose contract the coordinator refuses to read parks as
+`batch_lane_contract_mismatch` with the original parse error, distinct from a
+missing Lane's `batch_lane_lost`.
+
+Inside a Lane, the Pi extension and the Claude Code `PreToolUse` hook refuse an
+`edit`/`write` (Claude: `Edit`, `Write`, `MultiEdit`, `NotebookEdit`) whose
+resolved target lies outside the Lane, naming the Lane path. A shell command is
+not intercepted; this is no bash sandbox. When a lane batch is re-entered with a
+dirty coordinator checkout, each dirty path is restored to HEAD only if every one
+of them is an unstaged modification or untracked file that a Lane of this batch
+changed (its bytes differ from that Lane's base) and whose bytes equal the Lane's,
+in its worktree or a Lane-branch commit. The read-only preflight only attributes;
+the runner restores after the batch is authorized. The bytes are
+backed up first under `.imm/state/batches/restores/`, and the backup is recorded
+in the batch record and report as `restores`. If any change has another origin,
+or is staged or deleted, no file is touched and the refusal names it; never
+stage such changes to get past the refusal. A resume with a different
 `max_parallel` is refused with `batch_parallel_mismatch`. A Lane holds no batch
 state and its Host session never re-enters the batch.
 
@@ -220,6 +281,7 @@ source directly rather than assuming the Host injected it into context:
 | `Lane Executor Host: <host>` | `claude-code` or `pi` | Every Lane's Executor Host is that Host. When the `lane-steward` did not report it available in a Lane, that Lane has no Executor Host; the Parent does not fall back to the other one. | The Parent's own Host type, else the other allowlisted Host |
 | `Lane Executor model: <model>` | a model identifier of the configured Executor Host | Passed to the Executor Host as `--model <model>` | The Executor Host's own default |
 | `Lane Executor effort: <level>` | a level the configured Executor Host accepts | Passed as `--effort <level>` to `claude-code` and as `--thinking <level>` to `pi` | The Executor Host's own default |
+| `Batch final verification: <command>; <command>` | plain commands without shell syntax or quoting, at most 8 | Passed as `final_verification` when a new lane batch starts and shown in its native confirmation; the runner runs them on the batch branch once every child is integrated and writes each command's exit status and timing into the completion report as `final_verification`. A failing command reports the batch as not passed; integrated commits are never rolled back | The commands the repository instruction file names for its full test suite and type check, else none and the completion report says nothing was run |
 
 A model identifier and an effort level mean something only to one Host, so
 `Lane Executor model` and `Lane Executor effort` apply only together with
@@ -231,6 +293,11 @@ a resume the recorded `max_parallel` stands and the directive is not passed
 again. The directives configure how the Parent starts sessions; the runner reads
 none of them, and they grant no permission or trust option.
 
+A repository that names its full test and type-check commands in prose (for
+example "uses `bun test`; type checking is `bun run typecheck`") supplies them as
+the final verification without a directive; the Parent never invents a command
+the repository does not name.
+
 #### Lane Executor Supervision
 
 The Parent launches and supervises every Lane's Executor Host; no other role
@@ -300,7 +367,8 @@ a live tab:
    `herdr agent start <name> --kind <kind> --pane <pane_id> -- <host arguments>`.
    Host arguments are only those that load the Parent's plugin and those that
    [Lane Preferences](#lane-preferences) resolved for model and effort.
-4. Submit the entry and nothing else, and confirm the turn began:
+4. Submit the entry and nothing else (later text follows only the instruction
+   rule below), and confirm the turn began:
    `herdr agent prompt <pane_id> "<imm-run entry> <task_id>" --wait --until working --until blocked --timeout 30000`.
    The entry is the Executor Host's own `imm-run` invocation as that Host names
    it: a Claude Code Host that loaded the plugin from a directory names it
@@ -312,13 +380,52 @@ a live tab:
 
 `agent_not_ready` from step 3, or a `blocked` state at any time, means the tab
 shows a dialog only the user may answer: workspace trust, sign-in, a permission
-request or a question. The Parent sends that tab no keys and no prompt. It
-tells the user which tab and `task_id` is waiting, leaves the tab open, and
-continues the other Lanes; once the user has answered, step 3's tab is resumed
+request, a question, or a native confirmation such as an Intent revision gate.
+The Parent sends that tab no keys and no prompt, and never answers such a dialog
+for the user. As soon as the wait returns `blocked` it tells the user which tab
+and `task_id` is waiting and what the dialog asks, without waiting to be asked,
+leaves the tab open, and continues the other Lanes; once the user has answered, step 3's tab is resumed
 from step 4 if the entry was never submitted, otherwise from step 5. `idle` or
 `done` is a session end for the rules below, although the tab stays open: the
 Parent calls `start_unattended_batch`, and a relaunch submits the entry again in
-the same tab instead of creating another. A failed or timed-out `herdr` command
+the same tab instead of creating another. When that report shows the child
+neither settled nor waiting on a user decision, the Parent tells the user which
+tab and `task_id` went idle and what the Kernel projection still requires.
+
+The Parent may send one text instruction to a Lane session, and only while it is
+`idle` and its child is still running in the Lane: a correction to the
+Executor's approach, never an answer to a dialog. It first calls
+`start_unattended_batch` with `lane_instruction` (`task_id`, `text`, `kind`
+`instruction` or `correction`, and the `session_state` it just observed with
+`herdr agent get`). The runner records the text in the batch record and report
+as `interventions` and answers `lane_instruction.accepted`; only when accepted
+does the Parent submit it with `herdr agent prompt <pane_id> "<text>" --wait
+--until working --until blocked --timeout 30000` and re-arm step 5. A `blocked`
+or `working` session is refused and receives nothing. Every instruction the
+coordinator sent is therefore in the report, so Executor-initiated behavior and
+coordinator intervention can be told apart afterwards. This never applies to a
+Review agent: a dispatched reviewer is still never continued or re-prompted.
+
+When a Lane child exhausts its rework budget (the per-child `qa_failure_limit`)
+it does not park for the user at once: the report carries a
+`{ role: "coordinator", action: "correct" }` handoff and the runner makes no
+further attempt for that child. The Parent reads the findings of every round
+from that Lane's Kernel state, decides whether they point at one root cause, and
+writes one design-level correction — the invariant to hold and the shared seam to
+fix — never a patch of its own. It starts a new Executor session in the Lane
+(the old context is not reused; the new session resumes from the Kernel
+projection and the Lane workspace alone) and sends the correction as
+`lane_instruction` kind `correction`; the runner counts it. At most two
+corrections are spent per child: the third exhaustion parks the child as
+`batch_correction_limit_reached`, its dependents are skipped, siblings that do not
+depend on it keep executing and integrating, and the batch reports it at the end.
+Single tasks outside a batch keep their existing budget behavior, and Review
+independence is unchanged. A Review rework budget that the Kernel turns into a
+`replan_required` decision still needs the user's own native decision.
+
+Every live Lane session keeps exactly one `herdr agent wait` armed, so `blocked`
+and idle-without-settlement wake the Parent on their own; a Parent that has
+nothing else to do still ends its turn with those waits armed. A failed or timed-out `herdr` command
 proves nothing about delivery; inspect the session's state before repeating it.
 
 The Parent only creates: it closes no tab, including the tabs it created, and
@@ -393,9 +500,23 @@ is recorded as a separate follow-up rather than resolved here.
   no new provider or data effect.
 - Text instructions are contracts, not a hard bash sandbox. They guide and are
   reviewed; the Kernel authority gates remain the real boundary.
+- In a Lane whose batch confirmation delegated in-envelope revisions
+  (ADR 0018), the Executor does not open the gate for a revision that only
+  changes acceptance or narrows `scope_hint`: it stops and returns the complete
+  next intent to the Parent, which submits it as `lane_revision` on
+  `start_unattended_batch`. The runner applies it as a delegated approval
+  (actor `batch-coordinator`, confirmation `delegated-batch:<batch_id>@<time>`)
+  or refuses it with `batch_delegation_refused` and a `fallback`; on refusal the
+  Executor uses its own native gate below. Widening scope, changing risk, goal
+  or the bound Spec is never delegated, and nobody answers a dialog in a tab.
 - Invoke `approve_breaking_intent_revision` with the complete next intent
   directly; the native Host gate is the single user decision. Do not overwrite
-  enrolled intent sidecars or ask for chat pre-confirmation.
+  enrolled intent sidecars or ask for chat pre-confirmation. A breaking revision
+  is used only when the goal, the `scope_hint`, or a user-visible commitment
+  changes. A defect inside the existing goal and scope is rework under the
+  Execution Loop, not a revision, and the acceptance length limit is never
+  worked around by shortening words: when an assertion grows toward it, the
+  assertion is enumerating cases that belong in tests.
 - On `awaiting_user`, invoke `request_authorization` directly for a concrete
   unresolved decision or rework authorization, not risk tier alone.
 - When the user explicitly asks to stop an active task, invoke the Kernel stop
@@ -505,7 +626,11 @@ Every line reports authority evidence, not prose inference: name the exact
 task/run identity and the observed lifecycle, artifact, obligation, and claim
 facts that decided the exit. If a summary claimed more than the projection
 proves — for example a later Slice as enrolled or the task as completed — report
-the projection instead and correct the prose.
+the projection instead and correct the prose. When the bound Spec lists `manual`
+scenarios owned by the settled Task's Slice, add one line naming those scenario
+IDs as pending manual walkthrough; the line is informational and changes no
+stop reason, obligation, or completion fact, and is absent when that Slice owns
+no manual scenario.
 
 ## Failure Output