immune-brain 3.6.8 → 4.0.0

package/plugins/immune-brain/dist/docs/reference/planning-artifact-retention.md

@@ -73,18 +73,17 @@ Non-terminal artifacts remain durable at their existing paths by default.
 
 ## Authority-Owned Lifecycle
 
-An enrolled TaskIntent and the one exact active Spec bound by its `scope_hint`
-remain under `docs/plans/` and `docs/specs/` while the task is `working`. Before
-QA, the Kernel freezes both artifacts through one recoverable transaction: bytes
-move to their `archive/` paths and `TaskRecord.intent_ref.path` changes to the
-archived sidecar. Every later Kernel action rereads that recorded path.
-
-Authorized Review rework restores both artifacts before returning to `working`.
-Completion is valid only from the frozen location. Stop freezes an active pair
-before terminal settlement, so both terminal outcomes leave no active planning
-artifact. A relocation conflict or crash fails closed and converges only through
-the transaction marker; no background scanner or second status writer may infer
-or repair lifecycle state.
+An enrolled TaskIntent remains under `docs/plans/` for the whole run. A complex
+task may bind one active Spec under `docs/specs/` by content identity. Before QA,
+the Kernel freezes those artifacts in place: Git objects are bound, source paths
+do not move, and `TaskRecord.intent_ref.path` stays on the active sidecar.
+Historical files already in `archive/` remain readable. A later edit of a bound
+Spec changes the delivery identity, so prior assurance cannot be reused.
+
+Authorized Review rework returns `artifact_state` to `active` without relocating
+files. Completion and stop freeze in place; they do not archive planning
+artifacts. A crash fails closed and converges only through the store transaction;
+no background scanner or second status writer may infer or repair lifecycle state.
 
 Terminal cleanup outside that lifecycle remains a bounded TaskIntent with an
 explicit candidate list and a copy-paste verification command. It may accompany

package/plugins/immune-brain/dist/docs/reference/subagent-dispatch-protocol.md

@@ -80,7 +80,7 @@ Agent:
   schedule: ""
 ```
 
-Pi `Agent` has no `readonly` parameter; the empty tool policy, child type, and prompt contract enforce the read-only boundary. The Parent starts one foreground Agent at a time and consumes its direct result before deciding whether another child is needed. Advisory and discovery work does not call `get_subagent_result` or depend on completion notifications or host `followUp`. Kernel Review uses `subagent_type: "Review"`; its structured verdict is submitted by the Parent and validated against the current immutable snapshot. Loop `arch-explorer` uses `subagent_type: "Explore"`; other advisory/discovery and Loop internal roles use `general-purpose`.
+Pi `Agent` has no `readonly` parameter; the empty tool policy, child type, and prompt contract enforce the read-only boundary. The Parent starts one foreground Agent at a time and consumes its direct result before deciding whether another child is needed. Advisory and discovery work does not poll for deferred results or depend on completion notifications or host `followUp`. Kernel Review uses `subagent_type: "Review"`; its structured verdict is submitted by the Parent and validated against the current immutable snapshot. Loop `arch-explorer` uses `subagent_type: "Explore"`; other advisory/discovery and Loop internal roles use `general-purpose`.
 
 ## Scheduling And Visibility
 

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

@@ -11,9 +11,9 @@ This skill adheres to the **[BASELINE.md](BASELINE.md)**.
 
 Only explicit `imm-loop` entry starts or resumes this loop. Ordinary host input
 stays host-native; it never resumes a Managed owner implicitly. Read the current
-Host's `imm_kernel_canary` `status` first and verify the exact active backend
-claim, TaskIntent, and TaskRecord. Invalid or contradictory projections fail
-closed. A candidate TaskIntent is not Enrollment authority.
+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.
 
 Before the first Enrollment of a candidate TaskIntent, confirm the Planner
 returned `tracker_associated` — but only when the candidate belongs to an
@@ -36,11 +36,12 @@ Historical prose Plans and State Ledgers are read-only history, not execution
 instructions. Do not create Steps, workflow profiles, follow-up ledgers, or
 successor Plans to drive a Kernel task.
 
-At every internal role boundary call the read-only `imm_loop_action` Tool. Use
-`route` for current-context Executor work, bounded repair, architecture
-exploration, advisory review, Compounder, Kernel ownership, or scope expansion.
-Use Kernel ownership for an enrolled task. This Tool projects authority; it does
-not record execution evidence, mutate task state, or replace Kernel operations.
+At every internal role boundary call the invoking Host's read-only role-boundary
+route. Use `route` for current-context Executor work, bounded repair,
+architecture exploration, advisory review, Compounder, Kernel ownership, or
+scope expansion. Use Kernel ownership for an enrolled task. This route projects
+authority; it does not record execution evidence, mutate task state, or replace
+Kernel operations.
 Before a child dispatch, read the [Subagent Dispatch Protocol](docs/reference/subagent-dispatch-protocol.md#authorization-authority).
 Never load an internal role as a public Skill or spawn another loop process.
 The standalone `imm-pr-fix`, `imm-doc-prune`, and `imm-agent-doc-maintain` are host-native
@@ -51,26 +52,27 @@ and `pr-fix` repairs remain bounded by the enrolled TaskIntent.
 
 Continue while the current projection has a valid action:
 
-1. For active artifacts, implement only the enrolled acceptance within
-   `scope_hint` in the current conversation. Run focused checks. Executor checks
-   are diagnostic evidence, not a QA or Review approval.
-2. Before Assurance, call `freeze_artifacts` while TaskRecord is `active:active`.
-   A bound active Spec and its archive path must both be inside `scope_hint`.
-   The Kernel owns byte-preserving archival and the frozen snapshot.
-3. Call `advance_assurance` in the foreground and consume its direct terminal
-   result. Deterministic QA runs fixed acceptance descriptors atomically inside
-   the Host integration. Do not dispatch a separate per-Step QA Agent.
-4. On `review_ready`, invoke the returned `agent_params` as one exact foreground
+1. For active artifacts, implement only the enrolled acceptance within the
+   `scope_hint` envelope in the current conversation. New helpers or tests
+   inside an approved directory or glob do not require a revision. Run focused
+   checks. Executor checks are diagnostic evidence, not a QA or Review approval.
+2. Call `advance_assurance` in the foreground and consume its direct terminal
+   result. The Kernel freezes the artifacts itself before QA: it binds Git
+   content identity in place without relocating source paths. A simple task has
+   TaskIntent only; a complex task may bind one active Spec. Deterministic QA
+   runs all descriptors in a disposable delivery materialization, never against
+   unchecked live worktree source. Do not dispatch a separate per-Step QA Agent.
+3. On `review_ready`, invoke the returned `agent_params` as one exact foreground
    Agent call, then pass its structured verdict to `submit_review`. Do not
    replace this snapshot-bound reviewer with a generic role dispatch. The Parent
    cannot issue its own QA or Review pass.
-5. Follow the returned Kernel obligation. Fresh QA suffices for routine work;
+4. Follow the returned Kernel obligation. Fresh QA suffices for routine work;
    material and critical work additionally require fresh independent Review.
    Normal completion does not require a second user confirmation.
-6. For rework, follow the projected artifact state before editing. Resolve
+5. For rework, follow the projected artifact state before editing. Resolve
    findings only after fixing and verifying their cause. Changed snapshots
-   invalidate old evidence; freeze and run the newly required obligations.
-7. An unresolved decision pauses only dependent execution. On `awaiting_user`,
+   invalidate old evidence; run the newly required obligations.
+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
    the decision remains unresolved, is cancelled, or the gate fails. Otherwise
@@ -122,9 +124,9 @@ per completed child.
   enrolled intent sidecars or ask for chat pre-confirmation.
 - 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 a Pi task, invoke
-  `imm_kernel_canary({ task_id, action: { op: "request_stop" } })` directly.
-  Its single native confirmation authorizes existing Kernel stop settlement.
+- When the user explicitly asks to stop an active task, invoke the Kernel stop
+  operation through the invoking Host directly. Its single native confirmation
+  authorizes existing Kernel stop settlement.
   Cancellation is not task termination. A busy invocation must finish or be
   cancelled through existing Host controls before requesting stop; never clear
   claims manually or use this operation to force-kill QA.

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

@@ -115,8 +115,9 @@ and clarification. It does not apply to Enrolled Intent Revision.
 Before authoring a TaskIntent, trace each expected behavior from its public or
 runtime entry point through existing imports and callers to the highest focused
 behavioral tests. Include generated or packaged mirrors and every owner of the
-same state machine. Record the concrete paths in the Spec's discovery evidence;
-do not author while a referenced sibling is unresolved. Use the smallest
+same state machine. Record the concrete paths in the Spec's discovery evidence when the work is
+complex; simple TaskIntent-only work records them in `scope_hint`.
+Do not author while a referenced sibling is unresolved. Use the smallest
 coherent module directory for ordinary implementation scope. Keep Kernel,
 authority, migration, secret, and security-sensitive scope exact to the files
 proved necessary by the trace. Scope is closed by reference evidence, not by an
@@ -172,8 +173,13 @@ with `valid: true` and `enrollment_ready: true`. Resolve `../bin/imm-tracker` fr
 Initiative slug and goal, Parent projection, and every Child's `slice_id`,
 canonical TaskIntent path, bounded public `acceptance` summaries, and public
 projection. The Parent projection requires
-`problem`, `result`, and `design`, and may include `decisions`,
-`testing_strategy`, and `out_of_scope`. `design` records Initiative-level
+`short_name`, `title`, `problem`, `result`, and `design`, and may include
+`source_issue`, `decisions`,
+`testing_strategy`, and `out_of_scope`. `short_name` (1-32 characters) is the
+stable short Initiative name used in every Issue title; `title` (1-60
+characters) is the short Initiative display title; `source_issue` is the
+originating feature Issue number, rendered as a Provenance link. `design`
+records Initiative-level
 invariants, Slice boundaries and ordering, shared interfaces or state flow, and
 material compatibility decisions. Every Parent Slice must correspond to one
 published Child; future checklist-only Slices are not allowed in the batch.
@@ -181,15 +187,24 @@ 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 may contain
+be copied into public GitHub projection. 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,
-`out_of_scope`, and `agent_handoff`. The tracker rereads every canonical
+`out_of_scope`, and `agent_handoff`. The tracker composes Issue titles from
+these display names only — the Parent as `[<short_name>] <title>` and each
+Child as `[<short_name>] S<n> <title>` with `n` the declared Slice position —
+and fails the whole batch closed before any remote write when a display name
+is missing or the composed title exceeds 80 characters; it never falls back to
+goal prose and never truncates a title. The tracker rereads every canonical
 TaskIntent for identity, risk, and acceptance IDs; projection fields and public
 summaries never widen TaskIntent scope or authority. It validates the complete dependency graph before
 remote writes, creates the Parent once, creates all Children, attaches every
 Child as a native Sub-issue, creates native `blocked_by` relations, and rereads
-the complete topology. The Child Agent Brief includes a direct Parent Issue link.
+the complete topology. Every Child carries `ready-for-agent`, blocked Children
+additionally carry `blocked`, and the Parent carries neither; the tracker never
+creates labels, so a repository missing a required label fails the batch closed
+before any remote write. The Child Agent Brief includes a direct Parent Issue link.
 Internal role prompts, tool policies, review gates, model reservations, and
 prompt digests never belong in this external handoff. If
 `docs/initiatives/<slug>.md` exists, publication fails with a carrier conflict;
@@ -235,19 +250,25 @@ and an exact retry action; the strict no-amendment default is unchanged.
 ### Verification Descriptor Discipline
 
 Every acceptance verification descriptor must be a focused, deterministic,
-repository-local check that exercises only its acceptance assertion. Prefer one
-small `bun test <focused-file>` or `bun run <focused-script>` per acceptance;
-never use the full test suite, a build, package installation, network access, or
-redundant heavyweight checks. Prefer the highest existing observable behavioral
-test seam and the fewest sufficient seams. Cite relevant test prior art and
-explain how the selected seam catches the intended regression. This is a
-planning heuristic: it must not weaken acceptance-specific focused verification
-descriptors or add a mandatory user confirmation. Use the smallest `timeout_ms` and
-`max_output_bytes` that cover deterministic post-implementation QA.
+project-owned check that exercises only its acceptance assertion. Use
+`assurance_kernel/verification_descriptor/v2` and reuse an existing project
+script or host tool through its literal `command`; do not infer a language,
+package manager, or runner. Add `environment.prepare` only when the check needs
+explicit setup, and declare only the generated directories it needs in
+`environment.writable_paths`. Never hide package installation inside an
+acceptance command. Prefer the highest existing observable behavioral test seam
+and the fewest sufficient seams; never use the full test suite, a build, network
+access, or redundant heavyweight checks as acceptance. Cite relevant test prior
+art and explain how the selected seam catches the intended regression. This is
+a planning heuristic: it must not weaken acceptance-specific focused
+verification descriptors or add a mandatory user confirmation. Use the smallest
+`timeout_ms` and `max_output_bytes` that cover deterministic post-implementation
+QA. A v1 descriptor is historical-only and requires explicit Intent revision
+before execution.
 
 ## Core Responsibilities
 
-- **Decomposition**: Convert requirements into a concrete spec under `docs/specs/` and one or more TaskIntents. Treat Technical Design as one TaskIntent decomposition dimension alongside outcome, Verification, dependency, risk, rollback, compatibility, and authority.
+- **Decomposition**: Convert requirements into one or more TaskIntents. Add a Spec under `docs/specs/` only for complex work. Treat Technical Design as one TaskIntent decomposition dimension alongside outcome, Verification, dependency, risk, rollback, compatibility, and authority.
 - **Outcome Focus**: Each TaskIntent owns one independently verifiable outcome. Implementation batches are Executor work, not separately authorized read/edit/run Steps.
 - **Planning granularity**: Keep a coherent outcome together when acceptance, risk, rollback, and authority can settle together. Use the TaskIntent decomposition rules below for independent outcomes. File count, tokens, compactions, elapsed time, and review rounds are evidence for judgment, not universal gates.
 - **Historical artifacts**: v3 prose Plan mutation is retired. `imm-plan` is a read-only validator for archived Plans; create no new Roadmap, Phase, successor Plan, or State Ledger.
@@ -259,9 +280,9 @@ descriptors or add a mandatory user confirmation. Use the smallest `timeout_ms`
 - **TaskIntent decomposition**: Use the selected design boundaries as one retain/split criterion for TaskIntent slices. Keep work in one TaskIntent when the selected views describe one coherent executable slice with shared acceptance, risk treatment, rollback, and authority. Split a successor TaskIntent when a service boundary, state-machine owner, migration/compatibility boundary, independently promotable layer, or sequence dependency needs independent verification, rollback, authorization, or settlement. Do not split merely because the design names several layers, files, or services. Treat trust-boundary changes as the same kind of decomposition evidence: a TaskIntent should normally change one primary trust-boundary invariant, while merely traversing several boundaries or updating both sides of one end-to-end authority chain does not require a split. Split separate trust invariants when they can be independently verified, rolled back, authorized, migrated, or settled. Keep multiple trust-boundary changes together only when they form one atomic security outcome and splitting would create an unsafe or unusable intermediate state; record that reason in the Spec. This is Planner judgment, not a TaskIntent schema field or an Enrollment counting rule. This does not revive prose Plan, Roadmap, or Phase authority.
 - **Mermaid Use**: Mermaid is required only when a medium/high-risk design contains structure, sequence, data flow, or state transition relationships that a diagram materially clarifies. Mermaid is not a universal gate; a diagram supplements adjacent prose and never becomes a second design authority. Medium/High risk Specs record `**Diagram decision**: required|not_required` and a non-empty `**Diagram reason**:`. A `required` decision must have a Mermaid block; `not_required` explains why prose is sufficient. Low-risk Specs omit the empty ceremony and record neither field.
 - **Verification**: Every acceptance assertion has a concrete focused descriptor that can fail on the intended regression. Hypothetical evidence is not execution-ready.
-- **Executable Scope**: `scope_hint` is the mutation envelope, not discovery context. Close references across callers, tests, generated mirrors, and state-machine owners before authoring. Include bound active and archive Spec paths needed for `freeze_artifacts`. Collect all known scope gaps in one revision request; ask again only when new evidence changes the boundary.
-- **Devil's Advocate Preplan Audit**: Medium/High risk work records a `Devil's Advocate Audit` in the Spec covering rollback resilience, verification vanity, and spec dilution detection. Explain recovery from partial implementation, why verification detects the regression, and how accepted requirements remain covered. Low-risk work omits the empty template; the Spec records outcome, boundary, and concrete verification only.
-- **Execution posture**: Record `test-first` or `characterization-first` in the Spec when explicitly requested or justified by fragile untested behavior. The Executor owns the local choreography; do not create prototype or RED/GREEN/REFACTOR authority Steps. Throwaway probes must have a cleanup condition and a durable decision output.
+- **Executable Scope**: `scope_hint` is the mutation envelope, not discovery context. Close references across callers, tests, generated mirrors, and state-machine owners before authoring. Simple tasks are TaskIntent-only. A complex task binds at most one active Spec by content identity; do not add archive paths for freeze, and do not relocate artifacts. Collect all known scope gaps in one revision request; ask again only when new evidence changes the boundary.
+- **Devil's Advocate Preplan Audit**: Medium/High risk work records a `Devil's Advocate Audit` in its Spec covering rollback resilience, verification vanity, and spec dilution detection. Explain recovery from partial implementation, why verification detects the regression, and how accepted requirements remain covered. Simple TaskIntent-only work records outcome, boundary, and concrete verification on the Intent. Low-risk work omits the empty template.
+- **Execution posture**: Record `test-first` or `characterization-first` on the Spec when the work is complex, otherwise on the TaskIntent, when explicitly requested or justified by fragile untested behavior. The Executor owns the local choreography; do not create prototype or RED/GREEN/REFACTOR authority Steps. Throwaway probes must have a cleanup condition and a durable decision output.
 
 ## Settlement-Design Contract
 
@@ -350,21 +371,21 @@ preparation does not apply the revision or authorize expanded execution.
   planning heuristic: it must not weaken acceptance-specific focused
   verification descriptors or add a mandatory user confirmation.
 - **Review Mapping**: In-scope rework stays with the enrolled TaskIntent and explicit `imm-loop` entry. Cross-scope findings become a Planner decision delta with concrete missing paths and verification evidence; do not create a successor prose Plan.
-- **Brainstorm Manifest Mapping**: Record every upstream `BR-*` item in a Spec `Brainstorm Trace`, mapped to TaskIntent 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.
 - **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.
 - **Enrolled Intent**: Follow Enrolled Intent Revision for a Loop-requested scope or acceptance change; candidate preparation never changes the current owner or grants execution authority.
 - **CONTEXT.md Vocabulary**: Consult the relevant `CONTEXT.md` terms when domain meaning is unclear or changes; known file-local tasks do not require a full root-document read. `CONTEXT.md` is vocabulary and architecture navigation, not execution state.
-- **Discovery Protocol**: Read `CONTEXT.md` `## Architecture Map` before broad searching; consult relevant `docs/solutions/` evidence under Clarification supplement's history trigger. Record concrete file pointers and reasons in the Spec. Do not read or write a legacy Step discovery cache.
-- **Planning Quality Gate**: For elevated-risk work, verify contract surfaces, compatibility, interruption recovery, rollback, verification strength, and Brainstorm traceability in the Spec. Do not invoke retired Plan mutation or State Ledger synchronization.
+- **Discovery Protocol**: Read `CONTEXT.md` `## Architecture Map` before broad searching; consult relevant `docs/solutions/` evidence under Clarification supplement's history trigger. Record concrete file pointers and reasons in the Spec when one exists, otherwise on the TaskIntent. Do not read or write a legacy Step discovery cache.
+- **Planning Quality Gate**: For elevated-risk complex work, verify contract surfaces, compatibility, interruption recovery, rollback, verification strength, and Brainstorm traceability in the Spec. Simple TaskIntent-only work verifies those properties on the Intent. Do not invoke retired Plan mutation or State Ledger synchronization.
 - **Parallel Probes**: Optional read-only probes must have bounded non-overlapping scopes, expected evidence, and no file or authority writes. They are advisory discovery, not persisted Step annotations. Probe failure falls back to inline investigation with a recorded reason.
 
 ## Research Dispatch
 
 Follow [`docs/reference/subagent-dispatch-protocol.md`](docs/reference/subagent-dispatch-protocol.md) for the full dispatch lifecycle. This section defines planner-specific optional research dispatch.
 
-Use `imm_loop_action` for bounded `arch-explorer` and explicit-lens
-`advisory-reviewer` routing. Invoke the returned foreground Agent envelope
+Use the invoking Host's read-only role-boundary route for bounded
+`arch-explorer` and explicit-lens `advisory-reviewer` routing. Invoke the returned foreground Agent envelope
 exactly. The Parent owns Spec/TaskIntent synthesis, Brainstorm traceability,
 acceptance, and scope; children return evidence only. On Pi the `arch-explorer` envelope
 uses `subagent_type: "Explore"`; invoke the returned envelope rather than
@@ -382,19 +403,19 @@ optional advisory dispatch fails, continue inline and record the reason.
 
 ## Boundary
 
-- **Allowed**: Write candidate Specs and TaskIntents, Initiative planning carriers, and necessary domain vocabulary.
+- **Allowed**: Write a TaskIntent. Add a Spec only for complex work. 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-loop`. Planner owns design and decomposition, not execution authority.
 
 ## Output artifact
 
-Spec under `docs/specs/` plus canonical candidate
-`docs/plans/<task-id>.intent.json`. The Spec records outcome, discovery evidence,
+Canonical candidate `docs/plans/<task-id>.intent.json`. Simple future work does
+not require a Spec. A complex task adds one Spec under `docs/specs/` bound by
+immutable content identity, not by archive relocation. The Spec records outcome, discovery evidence,
 decisions, assumptions, Technical Design when required, output language,
 the Medium/High risk Devil's Advocate Audit, and acceptance/test mapping. Low
 risk records outcome, boundary, and concrete verification without the empty
-ceremony. Include a complete
-`Brainstorm Trace` when consuming a Brainstorm manifest. TaskIntent is authored
+ceremony. Include a complete Spec `Brainstorm Trace` for complex work that consumes a Brainstorm manifest; simple TaskIntent-only work records the same coverage on the Intent. TaskIntent is authored
 and validated through `imm-kernel`; do not write a prose iteration Plan or sync
 a State Ledger. Keep historical Plan validation strictly read-only.
 
@@ -417,7 +438,7 @@ a State Ledger. Keep historical Plan validation strictly read-only.
 
 - Acceptance verification names only hypothetical evidence with no runnable descriptor.
 - New work depends on a prose Plan validator, Step activation, or State Ledger.
-- A Brainstorm manifest lacks a complete Spec `Brainstorm Trace`.
+- A Brainstorm manifest lacks complete `BR-*` coverage on the Spec (complex) or TaskIntent (simple).
 - A Medium/High risk Spec lacks a `Devil's Advocate Audit` covering rollback resilience, verification vanity, and spec dilution detection.
 - New Spec prose ignores the document-language policy.
 - Candidate artifacts escape the approved planning scope.
@@ -425,7 +446,7 @@ a State Ledger. Keep historical Plan validation strictly read-only.
 ## Verification
 
 - Validate every candidate through `imm-kernel intent validate <path> --json` after authoring and staging. Require `valid: true` and `enrollment_ready: true` before Enrollment.
-- Verify Spec design metadata, document language, reference closure, concrete descriptor paths, and complete Brainstorm traceability before handoff.
+- 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.
 

package/plugins/immune-brain/dist/imm-review-retro.md

@@ -0,0 +1,123 @@
+---
+name: imm-review-retro
+description: Use when the user explicitly requests Immune-Brain ranking of models by cross-model review load or a project usage retro.
+---
+
+# Immune-Brain: Review Retro
+
+Rank models by how much code review their own edits triggered, and report
+basic project usage over a look-back window the user supplies in days. This
+is a standalone host-native analysis entry, not a Managed Path continuation
+and not an `imm-loop` internal-role dispatch. It reviews no diff — a diff
+review is `code-review`.
+
+## Boundary
+
+Allowed: read pi session JSONL under `~/.pi/agent/sessions` (or `--root`),
+run the bundled analyzer, and write a stdout report.
+
+Blocked: code, test, Spec, Plan, or `.imm/` edits; session-log writes;
+Kernel, TaskIntent, or TaskRecord mutation; Compounder or scheduled runs;
+`.imm/audit/` lifecycle statistics.
+
+An already active Managed task remains owned by `imm-loop`. This Skill does
+not create or resume Managed authority.
+
+## Invocation
+
+Requires explicit invocation: `imm-review-retro` or `/imm-review-retro`.
+Ordinary questions such as "which model is worse" stay host-native and do
+not enter this Skill.
+
+The look-back window in days is required input. If the user named one, use
+it. If not, ask before running, because the ranking moves with the window.
+
+Default scan is the user's full session-log tree. Pass `--project <substr>`
+when the user wants one repo or worktree. Do not invent a project filter.
+
+No daemon, no cron, no CI, no automatic commit.
+
+## Counting rules
+
+These rules keep numbers comparable across runs. Read the analyzer header
+aloud in the report so the 口径 stays visible.
+
+- `review` = an `Agent` tool call with `subagent_type` equal to `Review`.
+- Attribution = the model behind the most recent `edit`, `write`, or
+  `multiedit` in that session. If none, the row is `no-edit (review-only)`.
+- `uniq` counts distinct (session, description+prompt prefix) pairs. A wide
+  gap versus `reviews` is the same review re-run on the same code.
+- `rev/100ed` is `100 * reviews / devEdits`. Rank on both absolute `reviews`
+  and this intensity. A model can lead one axis and sit mid-pack on the
+  other.
+- `avgSc` / `pass%` parse `[SCORE: …]` and `[VERDICT: …]` tags from the
+  matching Review `toolResult`. Untagged reviews show `-`.
+- `registr` counts the Kernel `submit_review` registration in the session log.
+  It is the registration of the same review and is never added into `reviews`.
+- `rounds/task` is registrations per distinct `(cwd, task_id)`. High values
+  can be canary/QA harness re-registration, not human-visible rework.
+- Findings are `record_finding` calls, deduped per session. Summaries that
+  match `recorded cleanly`, `receipt recorded`, `round recorded`, or
+  `no finding(s)` are `bookkeep` / `noisy`, excluded from `block`/`advis`.
+
+Usage counters on the same pass: sessions with activity, assistant turns,
+edit counts, a tool-call name histogram, and the project × author table.
+
+## CLI
+
+Run the bundled analyzer. Prefer `bun`; `node` (≥23.6, type stripping) is
+an allowed equivalent. The script is erasable TypeScript with `node:` APIs
+only.
+
+```
+bun "<path-to-skill>/scripts/review_retro.ts" <days> [--root <sessions-dir>] [--project <substr>] [--top N]
+```
+
+- `<days>` must be `> 0`.
+- `--root` defaults to `~/.pi/agent/sessions`.
+- `--project` keeps sessions whose `cwd` contains the substring.
+- `--top` is the project-table row cap (default 15).
+- Malformed JSONL lines are skipped. `days <= 0` is a hard error.
+
+Do not scan live `.imm/` directories. Tests use committed fixtures under
+`tests/fixtures/review-retro/`.
+
+## Report
+
+Write-up order:
+
+1. Window and 口径 in one line (copy the analyzer header).
+2. Ranked model table, including scores.
+3. Usage section: sessions, turns, edits, tool mix.
+4. Quality and score findings.
+5. Three to five bullets of what the table means (volume versus intensity,
+   quality versus rework, where it concentrated).
+6. Caveats last.
+
+Rank on both axes, never one. Name the axis you are ranking by, and call
+out models that flip order between `reviews` and `rev/100ed`.
+
+Separate one-pass from rework: compare `uniq` to `reviews`, and read
+`rounds/task` on the kernel path.
+
+Evaluate quality: high intensity plus high score is frequent review of
+mostly minor issues; low intensity plus low score is rare review of severe
+defects. Call out REJECT or highRisk ratings.
+
+Ground each model in its projects. Cite the two or three worktrees where
+that model's reviews concentrated.
+
+## Caveats
+
+Anything the script splits out as `bookkeep` stays visible next to the
+column it contaminates. Flag any finding count you cannot trace to a real
+defect.
+
+High `rounds/task` can be canary/QA harness re-registration, not
+human-visible rework.
+
+This Skill does not persist snapshots or compute week-over-week diffs.
+Re-run with a new window when the user wants a later period.
+
+The personal python prototype under `~/.pi/agent/skills/review-retro/` is
+not this Skill and is not modified by it.

package/plugins/immune-brain/dist/registry.yaml

@@ -56,3 +56,12 @@ skills:
     output_artifacts: [maintain_report]
     next_actions: []
     boundary: Minimize tracked agent-instruction context after explicit manifest approval; no Managed authority mutation, contract installation, or reference-document creation.
+  - name: imm-review-retro
+    path: skills/imm-review-retro/SKILL.md
+    role: execute
+    title: Review Retro
+    role_class: discovery
+    canonical: true
+    output_artifacts: [retro_report]
+    next_actions: []
+    boundary: Rank models by review load and report project usage from pi session logs. Read-only. No Managed Path mutation.

package/plugins/immune-brain/dist/role-prompts/code-review.md

@@ -38,6 +38,8 @@ boundary name). Do not invent fields, and never send an anchor yourself: the
 Kernel derives it as the sha256 of the canonical `{violated.kind,
 violated.ref, caller_chain}`, so an identical claim keeps one stable identity
 across review rounds while a different call chain is a different claim. A
-passing review has no findings. If the
+passing review carries no blocking findings; non-blocking notes may ride along as
+`kind: "advisory"` findings, and every finding, advisory included, needs the
+same machine-checkable evidence. If the
 checkpoint is `awaiting_user_successor_decision`, stop without dispatch; only
 a literal user may invoke `--approve-successor`.

package/plugins/immune-brain/dist/role-prompts/executor.md

@@ -1,10 +1,10 @@
 # Internal role: executor
 
 You are the Immune-Brain Executor role inside Loop. Implement exactly the
-enrolled TaskIntent acceptance and `scope_hint` (or one accepted
-same-boundary follow-up) in the current Parent conversation. Use workspace
-tools only for the supplied target and keep every edit inside the
-authoritative Scope. Do not discover or load a Pi Skill.
+enrolled TaskIntent acceptance and `scope_hint` envelope (or one accepted
+same-boundary follow-up) in the current Parent conversation. New helpers or
+tests inside an approved directory or glob do not require a revision. Keep
+every edit inside the authorized envelope; do not stage unrelated user files. Do not discover or load a Pi Skill.
 
 Before handoff, run the permitted diagnostic checks and return commands and
 outcomes to the Parent as structured diagnostic evidence. The read-only Loop