immune-brain 2.8.3 → 3.0.2

package/plugins/immune-brain/dist/docs/reference/code-quality-guard.md

@@ -0,0 +1,58 @@
+# Code Quality Guard
+
+This contract protects correctness and review signal in LLM-assisted implementation. It is a project-specific guard, not a universal style guide.
+
+## Correctness Invariants
+
+### Real implementation
+
+- Do not ship mocks, fixtures, hard-coded success, placeholder output, disabled assertions, or weakened tests as production completion.
+- If required behavior cannot be implemented with the available evidence or scope, stop and report the missing condition. Do not manufacture a passing result.
+
+### Error semantics
+
+- Catch only errors that the code can recover from, translate, or enrich.
+- Do not turn an unknown or unrecoverable error into `null`, `undefined`, empty output, or a success result.
+- When translating an error, preserve its cause and the contract-visible meaning.
+
+### Trust boundaries
+
+- Validate user input, file contents, network payloads, deserialized data, and cross-process data at the boundary where they enter the system.
+- Once an invariant is established by a trusted caller or validator, avoid speculative internal guards that hide a violated invariant or change failure semantics.
+
+### Dependency and API authenticity
+
+- Verify new imports against the repository's installed dependencies or the standard library.
+- Verify new third-party API calls against the installed version or repository source; do not rely on memory.
+- Do not add a dependency for small, clear logic already served by local code or the platform.
+
+### Behavior integrity
+
+- Refactoring preserves observable inputs, outputs, errors, side effects, and ordering unless the accepted task authorizes a behavior change.
+- Do not mix unrelated bug fixes, cleanup, or speculative refactors into the task.
+
+### Executable relevance
+
+- Do not add configuration, switches, extension points, exports, or production paths without a current caller or accepted requirement.
+- Remove unused imports, dead branches, commented-out implementations, and duplicate domain rules introduced by the change.
+
+## Maintainability Heuristics
+
+Use these as contextual investigation signals, not universal gates:
+
+- Names should communicate the domain meaning in their local context.
+- Functions should have a coherent responsibility and a complexity that remains verifiable.
+- Parameters should model a real input relationship rather than hide unrelated values.
+- Comments should explain constraints or reasons that are not apparent from the code.
+- Repetition is a problem when it duplicates domain knowledge, not merely because text looks similar.
+- Introduce an abstraction when existing complexity or multiple real consumers justify it; do not add interfaces, factories, strategies, flags, or configuration for hypothetical future use.
+
+There are no hard line-count, parameter-count, nesting, complexity, boolean-parameter, or identifier blacklist thresholds. A heuristic becomes review-relevant only when the current change creates a concrete correctness, regression, security, or material maintenance risk.
+
+## Review Decision Policy
+
+- `blocking`: a concrete correctness, security, error-state, dependency/API authenticity, test-integrity, or unauthorized-behavior defect.
+- `advisory`: a concrete task-local maintenance risk worth fixing in this change, with an affected path and failure rationale.
+- Pure formatting, naming preference, line count, parameter count, design taste, and hypothetical extensibility produce no finding.
+- A passing Review has no findings. Do not turn low-value suggestions into `rework` merely to preserve them.
+- Findings identify the affected path and risk. Review reports risks and verification criteria; it does not edit code or generate patches.

package/plugins/immune-brain/dist/docs/reference/immune-brain-config.md

@@ -1,6 +1,6 @@
 # Immune-Brain Pi Preferences
 
-Pi is the only supported code-agent host. Immune-Brain does not load an
+Pi and Claude Code are supported code-agent hosts. Immune-Brain does not load an
 agent-local TOML file or Immune-Brain-specific environment overrides. User and
 project preferences belong in Pi-injected `AGENTS.md` instructions.
 

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

@@ -22,7 +22,7 @@ Apply the gate when the task touches one or more of these surfaces:
 - **design-depth classification**: for a change with a Technical Design concern, record why it is Low, Medium, or High risk. Every new or revised Spec records `**Design risk**: Low|Medium|High` with an adjacent rationale. Medium/High risk requires a Technical Design baseline in the Spec; Low risk may remain concise only when it has no contract, ownership, security, persistence, compatibility, or multi-component concern.
 - **Technical Design baseline**: keep the Spec as the single design authority and make each Plan Step reference the applicable decision or invariant instead of duplicating design prose.
 - **design-view selection**: for Medium/High risk, select every materially relevant technical-design view from architecture layers, service/component interfaces, data flow, state transitions, and temporal sequence. Record selected views and why omitted views cannot affect the design. Low risk remains concise.
-- **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. Do not split merely because the design names several layers, files, or services, and do not revive prose Plan authority.
+- **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.
 - **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. Every new or revised Spec records `**Diagram decision**: required|not_required` and a non-empty `**Diagram reason**:`. A `required` decision must include Mermaid; `not_required` explains why prose is sufficient.
 - **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`.

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

@@ -56,11 +56,13 @@ Immune-Brain owns Role, evidence, authority, tool policy, and output contracts.
 Pi Host owns model, provider, and thinking defaults. Immune-Brain does not define
 model tiers, provider mapping, cost routing, or provider fallback.
 
-Agent 默认继承当前 Pi session model。只有 Parent 有明确需求时，才通过
-host-native `Agent.model` 选择另一个 Pi 已配置模型。Kernel authority Review 的
-reservation 不生成也不匹配 `model`/`thinking`：Pi Host 解析的 execution
-configuration 不是 Review authority 身份，receipt matching 只对 reserved
-authority parameters 要求 exact 一致。
+Agent defaults to the current Pi session model. Only an explicit Parent requirement
+selects another Pi-configured model through host-native `Agent.model`. Kernel
+Review returns a complete foreground `Agent` envelope with empty `name`, `model`,
+`thinking`, `resume`, and `schedule` fields so Pi Host resolves the Review agent
+configuration. The Parent may use any compatible foreground Agent adapter and
+submits the resulting structured verdict directly; lifecycle event matching is
+not part of the local authority contract.
 
 ## Pi Agent Invocation
 
@@ -69,23 +71,27 @@ Agent:
   subagent_type: "general-purpose"
   description: "<role>/<lens> review"
   prompt: <delegation packet>
-  model: <optional Pi-configured model id; omit to inherit>
+  name: <optional; empty for Kernel authority Review>
+  model: <optional Pi-configured model id; empty to inherit the Review agent config>
+  thinking: <optional; empty to inherit the Review agent config>
   inherit_context: false
   run_in_background: false
+  resume: ""
+  schedule: ""
 ```
 
-Pi `Agent` 没有 `readonly` 参数；只读边界由空工具策略、child 类型和 prompt contract 共同保证。Parent 每次只启动一个 foreground Agent，等待其 direct terminal result 后再决定是否需要下一个 child。普通 advisory/discovery 不调用 `get_subagent_result`，不依赖 completion notification 或 host `followUp`。Kernel authority Review 使用专属类型：`advance_assurance` 返回的保留参数使用 `subagent_type: "Review"`（Pi 原生只读 Review 类型），仍遵循本文档的 foreground、单 child、退火匹配与 receipt 校验规则；advisory/discovery 与 Loop 内部 roles 继续使用 `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 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`.
 
 ## Scheduling And Visibility
 
 1. Planning、repository exploration、specialist advisory Review 和 work probe 必须 foreground 执行。Parent launches one child at a time，消费 direct terminal result，并在每个结果后 re-evaluates the remaining dispatch budget；不得把多个 foreground Agent 假定为并发 batch。
 2. 普通 interactive advisory 不建立 acknowledgement deadline、后台 progress UI、completion push 或 late-notification recovery。活跃 Agent 使用 Pi 原生 foreground Tool row、host cancellation 和 steer。Footer 保持严格为空；No defined-value `setStatus` call is allowed。
-3. Kernel Assurance runs in the foreground Tool call. `advance_assurance` awaits deterministic QA, emits bounded native updates, and returns a direct `review_ready` result containing exact `Agent` parameters with `run_in_background: false`. The Parent invokes that Agent once, then calls `submit_review` after the `tool_call`/`tool_result`/`tool_execution_end` bridge validates the receipt. `request_authorization` is the only literal-user confirmation path. AbortSignal cancellation is honored before the authority commit boundary; snapshot/CAS revalidation remains mandatory.
+3. Kernel Assurance runs in the foreground Tool call. `advance_assurance` awaits deterministic QA, emits bounded native updates, and returns `review_ready` with foreground `Agent` parameters. The Parent invokes a reviewer, reads its direct result, and passes the structured verdict to `submit_review`. `request_authorization` is the only literal-user confirmation path. AbortSignal cancellation before authority commit and snapshot/CAS revalidation remain mandatory.
 4. Kernel Assurance chat uses native Tool rendering only. It does not publish completion messages or wake a later parent turn; the direct Tool result is the continuation boundary. `awaiting_user` remains valid until the host-built authorization operation is confirmed and the immutable snapshot is revalidated.
 5. Child 不得再次派发 child，nested delegation 一律禁止。Parent 保留综合与最终判断责任。
-6. Kernel authority Review 对每个 immutable snapshot 恰好一个 primary reviewer，turn 预算按 workload 缩放（Quick 12 / Standard 16 / Heavy 24），并使用该 snapshot 对应的 Quick/Standard/Heavy 执行档位；不存在从 initial dispatch 起算的单一端到端总预算。Reviewer 必须先验证 immutable bundle provenance，只围绕 acceptance assertions 与 bundle 中的 `dirty_files`（diff payload）和 `neighborhood_files`（同状态机 context）内容审查，不探索无关 repository paths，并预留最后一轮输出唯一 strict JSON verdict。`path_provenance` 明确标记每个 bundled path 为 `diff` 或 `neighborhood`；所有 neighborhood context 只能从 canonical `scope_hint` 内的 Git index 选择，继续受单文件 256 KiB 与总包 2 MiB 上限约束，Reviewer 仍只能读取 bundle bytes。对 settlement-class change，Reviewer 必须先枚举 bundle 内每条 terminal、cancellation、timeout 与 race path，再对全部路径给出判断；finding summary 必须以受影响的 bundle path 开头，以便 verdict v2 引用 neighborhood context。每个 acceptance 的执行结果已由 deterministic QA 在 review 前验证并内嵌于 immutable bundle 的 `outcomes` 字段（acceptance_id -> {status, summary}）；Reviewer 不得重跑 descriptor，也不得把本地没有测试运行当作 finding——Review 只审 bundle provenance、代码正确性、回归、安全与缺失测试。除该 reviewer 外，同一触发点最多两个相互独立的 advisory/discovery children；它们只能并行读，不能写 workflow state、关闭 QA 或产生 authority。
-7. Foreground assurance never sleeps, polls, or schedules a completion callback. One Tool call owns QA preparation and execution; one explicit Parent turn owns the native Agent receipt; one explicit authorization operation owns the user decision. Duplicate or stale event sequences fail closed and cannot create a second reviewer or authority write.
-8. Review receipt validation requires the reserved operation, immutable snapshot digest, exact reserved authority parameters, matching tool-call ID, terminal tool result, and terminal execution event. Agent output is advisory and cannot apply Kernel authority. A malformed, cancelled, inverted, duplicate, or stale receipt leaves the TaskRecord unchanged; the user authorization operation revalidates record revision, Intent hash, workspace revision, and diff hash before applying the verdict.
+6. Kernel authority Review 对每个 immutable snapshot 恰好一个 primary reviewer，turn 预算按 workload 缩放（Quick 12 / Standard 16 / Heavy 24），并使用该 snapshot 对应的 Quick/Standard/Heavy 执行档位；不存在从 initial dispatch 起算的单一端到端总预算。Reviewer 必须先验证 immutable v5 manifest 的 `base_head`、`review_commit`、单一 parent、`review_tree` 与 `manifest_digest`，再用只读 Git 命令从 synthetic revision 获取源码；manifest 只有 metadata，不复制 source bytes，也不枚举 neighborhood files。审查只围绕 acceptance assertions 与 `changed_paths`，未变更路径只有在 acceptance、changed caller 或同一 state machine 直接需要时按需读取并注明理由；Reviewer 不探索无关 repository paths。对 settlement-class change，Reviewer 必须先枚举 immutable revision 内每条 terminal、cancellation、timeout 与 race path，再对全部路径给出判断；finding summary 必须以受影响路径开头。每个 acceptance 的执行结果已由 deterministic QA 在 review 前验证并内嵌于 manifest 的 `outcomes` 字段（acceptance_id -> {status, summary}）；Reviewer 不得重跑 descriptor，也不得把本地没有测试运行当作 finding——Review 只审 revision provenance、代码正确性、回归、安全与缺失测试。除该 reviewer 外，同一触发点最多两个相互独立的 advisory/discovery children；它们只能并行读，不能写 workflow state、关闭 QA 或产生 authority。
+7. Foreground assurance never sleeps, polls, or schedules a completion callback. One Tool call owns QA; one Parent turn obtains and submits the reviewer verdict; one explicit authorization operation owns the critical-risk user decision.
+8. `submit_review` validates the verdict contract, task identity, immutable snapshot digest, and fresh record/Intent/workspace/diff revisions before applying Review authority. Malformed verdicts are retryable without rebuilding evidence. Stale verdicts leave the TaskRecord unchanged and release the stale reservation. Local execution trusts the Parent to relay the reviewer verdict and does not require Agent lifecycle receipts.
 9. The assurance Tool checks the immutable snapshot before each phase and returns a terminal structured state directly: `cancelled`, `rework`, `review_ready`, `awaiting_user`, `blocked`, or `settlement_unknown`. The commit boundary is non-cancellable. No silent task, status timer, completion notification, or result retrieval path is permitted.
 
 ## Result Synthesis
@@ -100,6 +106,6 @@ Parent workflow role 必须：
 
 普通 advisory/discovery 的每次启动都消耗一个 candidate budget slot；失败、取消、timeout 或 result_untrusted 均丢弃该输出且不得自动重试。Parent 仅在剩余候选仍独立有用且 evidence budget 仍需要时继续，否则转 solo/fail-closed fallback，并记录 `dispatch_failed` 或 `child_timeout`。该规则不改变 Kernel authority Review 的显式恢复协议。Child 永远不获得实现、Plan write、workflow mutation 或 QA closure authority。
 
-Kernel authority Review 的 provider 失败分类（no-verdict dispatch failure）：standard Agent 派发因 provider quota/transport 失败（429/rate-limit/quota/overloaded/503/ECONN*/ETIMEDOUT）抛错时，归类为 no-verdict dispatch failure——零 authority 写入、reserved operation 保持有效、不产生 terminal review 事件、不消耗 review follow-up round，并允许对同一 reserved operation 恰好一次重派（reservation 复用）。第二次同类失败或非 provider 失败转入 `dispatch_unknown` settlement：reservation 释放、evidence artifact 在 terminal settlement 或显式 release 时移除。Immutable review bundle artifact（evidence.json）在 reservation 未 terminal 前永不被 GC；dispatch 或 settlement 发现 artifact 缺失时 fail closed、零写入，并通过重跑 review 命令暴露显式 re-reserve 路径。artifact 生命周期由 trigger（settle、release、crash、shutdown）x state（reserved、dispatched、settling、terminal）枚举，单 owner 每状态。
+If Kernel Review dispatch fails, the Parent does not call `submit_review`; the existing Review reservation and immutable evidence remain available for a later foreground retry. A malformed verdict may be corrected and resubmitted. A stale snapshot, explicit release, successful settlement, or session shutdown removes the reservation and evidence. There is no retry counter, dispatch receipt state machine, or provider-specific recovery path.
 
-本协议是 provider-agnostic、Pi-host-specific：模型 provider 可变化，code-agent host 不可变化。
+This protocol is provider- and host-adapter-agnostic for local execution.

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

@@ -19,8 +19,8 @@ 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.
+envelopes use `run_in_background: false` and return a direct result to the Parent
+before any workflow mutation.
 
 ## Workflow Profiles
 
@@ -52,7 +52,7 @@ 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.
+   - 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 foreground reviewer and pass its structured verdict to `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.
@@ -150,9 +150,8 @@ 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
+the foreground reviewer and pass its structured verdict to `submit_review`;
+`request_authorization` remains the user authorization boundary. Foreground
+results replace background continuation 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.

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

@@ -217,7 +217,7 @@ descriptors or add a mandatory user confirmation. Use the smallest `timeout_ms`
 - **Design-Depth Classification**: Classify change design risk with the smallest sufficient tier: **Low risk** (copy, configuration, trivial rename, or contained local fix) may omit a separate Technical Design; **Medium risk** (non-trivial single-module behavior or internal contract) records affected components, decisions, invariants, failure behavior, and verification implications; **High risk** (cross-module/API/data-flow/state-machine, security, migration, concurrency, architecture ownership, cross-runtime/package-contract, or persisted-state work) records boundaries, interfaces or flow, alternatives, invariants, rollback/compatibility, and verification implications. Medium and High risk require Technical Design in the Spec. Do not classify a change as Low risk when it has a contract, ownership, security, persistence, compatibility, or multi-component concern. Every new or revised Spec records `**Design risk**: Low|Medium|High` with an adjacent rationale.
 - **Design-view selection**: For Medium and High risk, select every materially relevant technical-design view from architecture layers, service/component interfaces, data flow, state transitions, and temporal sequence. Record a short `Design views` statement naming the selected views and why any omitted view cannot affect the design. Do not write empty architecture, interface, data-flow, state, or sequence sections. Low risk remains concise and may omit Technical Design. When a selected view is recorded, also record its required decision content: architecture layers need layer responsibilities, dependency direction, ownership, and prohibited coupling; service/component interfaces need inputs, outputs, errors, compatibility/versioning, and caller/callee ownership; data flow needs source, transformations, validation, destination, and failure handling; state transitions need states, legal transitions, trigger, invariant, terminal ownership, and recovery; temporal sequence needs ordered interactions, authority at each point, interruption behavior, and idempotency.
 - **Technical Design Authority**: The Spec is the single Technical Design baseline. TaskIntent acceptance and scope reference the applicable design decisions or invariants without copying Technical Design prose. If discovery invalidates the baseline, stop execution and return to Planner to update the Spec and decide whether `replan` is required. TaskIntent and Initiative text do not duplicate Technical Design prose or become a prose Plan substitute.
-- **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. This does not revive prose Plan, Roadmap, or Phase authority.
+- **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. Every new or revised Spec records `**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.
 - **Verification**: Every step must name the result and verification path. If the evidence path is still hypothetical, do not label the step execution-ready.
 - **Executable Scope**: Every new code-changing Step must declare one or more bounded project-relative paths in `- Scope: \`path\`, \`directory/\`, ...`. Runtime derives the actual Git delta and rejects evidence outside these paths. Keep Scope wide enough for the promised Result but never use an unbounded wildcard. Omitting `Scope` does not relax the boundary, it removes it: there is nothing to compare the delta against, so runtime records the evidence as `scope_boundary: undeclared` and review inherits a change set with no statement of what was supposed to change. `Discovery cache` does not substitute — it names paths worth reading, not paths this Step commits to changing.

package/plugins/immune-brain/dist/imm-pr-fix.md

@@ -55,6 +55,15 @@ uncertain. Never delegate push, merge, approval, or scope decisions.
 When a blocker requires a product decision or work outside the PR's intended
 scope, stop and report the exact decision or scope expansion needed.
 
+## Code Quality Guard
+
+Apply the packaged Code Quality Guard reference at
+`docs/reference/code-quality-guard.md` when repairing implementation
+blockers. Do not make a PR appear healthy by swallowing unexpected errors,
+fabricating success, weakening tests, inventing APIs or dependencies, changing
+unrelated behavior, or widening the blocker scope. Style-only preferences are
+not repair blockers.
+
 ### 4. Verify and close out
 
 Run the smallest checks that reproduce each blocker, then any repository check

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

@@ -1,15 +1,35 @@
 # Internal role: code-review
 
-You are the Immune-Brain read-only code review role inside Loop. Review only
-the bounded change surface and the evidence supplied by the Parent. Classify
-findings, state observable verification criteria, and preserve the current
-review gate identity. Do not edit files, mutate workflow state, approve a successor, or invoke another role.
-
-The stable Review Gate is `imm-code-review`. Return exactly one JSON object
-with the fields required by the Loop review contract: `contract`, `role`,
-`task_id`, `snapshot_digest`, `decision` (`pass` or `rework`), and for
-`pass` include `approval` (`kind`, `authority_role`, `summary`), for `rework`
-include `findings` (`id`, `kind`, `acceptance_id`, `summary`). Do not invent
-fields. A passing review has no findings. If the checkpoint is
-`awaiting_user_successor_decision`, stop without dispatch; only a literal user
-may invoke `--approve-successor`.
+You are the Immune-Brain read-only code review role inside Loop. Review the
+immutable Git revision and bounded evidence supplied by the Parent. For
+`assurance_kernel/review_manifest/v5`, read the metadata manifest first, verify
+`base_head`, `review_commit`, its single parent, `review_tree`, and
+`manifest_digest`, then inspect source only with read-only Git commands such as
+`git diff <base_head> <review_commit>` and `git show <review_commit>:<path>`.
+Never read live worktree bytes as evidence, enumerate neighborhood files, or
+infer task ownership from unchanged paths. Read an unchanged path only when an
+acceptance assertion, changed caller, or same state machine directly requires
+it, and cite the path and reason in the finding. The manifest is metadata only;
+source content must not be copied into the review envelope.
+
+Do not edit files, mutate workflow state, approve a successor, or invoke
+another role. The stable Review Gate is `imm-code-review`.
+
+## Code Quality Guard
+
+Apply the Code Quality Guard reference to the immutable revision: reject
+fabricated success, unknown-error suppression, missing external-boundary
+validation, invented imports/APIs, weakened tests, unauthorized behavior
+changes, and speculative production paths when the diff creates a concrete
+risk. Report only evidence-based correctness, security, regression, or
+material task-local maintenance risks. Pure naming, length, complexity
+thresholds, formatting, and design preference are not findings and must not
+cause style-only rework.
+
+Return exactly one JSON object with the fields required by the Loop review
+contract: `contract`, `role`, `task_id`, `snapshot_digest`, `decision` (`pass`
+or `rework`), and for `pass` include `approval` (`kind`, `authority_role`,
+`summary`), for `rework` include `findings` (`id`, `kind`, `acceptance_id`,
+`summary`). Do not invent fields. A passing review has no findings. 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

@@ -11,3 +11,17 @@ action. Preserve failed and blocked attempts. Do not perform QA,
 review, plan mutation, successor approval, Compounder work, or authority
 writes. If the requested change needs scope expansion, stop and return an
 `imm-planner` route with the concrete missing scope and verification reason.
+
+## Code Quality Guard
+
+Before handoff, check the implementation for real implementation rather than
+mock or hard-coded success, swallowed unexpected errors, missing validation at
+external trust boundaries, invented dependencies or APIs, unauthorized
+observable behavior changes, and production paths without a current caller.
+Do not weaken tests or hide an incomplete result to make Verification pass.
+Treat naming, function length, parameter count, nesting, and abstraction taste
+as contextual signals, never as automatic failure thresholds.
+
+Fix in-scope integrity defects before Verification. If fixing one requires
+behavior, scope, or authority beyond the active Step, stop and route the
+concrete reason to `imm-planner`.

package/plugins/immune-brain/dist/role-prompts/pr-fix.md

@@ -60,6 +60,15 @@ shard on failure; on second failure, fall back to solo repair.
 Re-run project checks and PR-related conflict checks. Compare local HEAD
 against PR head expectation before push.
 
+## Code Quality Guard
+
+Apply the same integrity boundary while repairing a blocker. Do not clear CI or
+review feedback by swallowing unexpected errors, fabricating success, or using
+a repair that would weaken tests, invent an unavailable API or dependency,
+change unrelated behavior, or widen the PR beyond the named blocker. Preserve
+the PR's observable intent. If the correct repair needs new scope or a product
+decision, stop and report it to the Parent.
+
 ## Boundary
 
 Work only inside the supplied Plan, `plan_id`, changed-file boundary, review

package/plugins/immune-brain/dist/role-prompts/test-fixer.md

@@ -1,3 +1,10 @@
 # Internal role: test-fixer
 
 You are the Immune-Brain bounded test-repair role inside Loop. Edit only the delegated test files listed in `focus_delta.specific_changes` for the active target. Run the supplied `verification_hint`, return structured child evidence, and stop when the delegated test boundary is satisfied. Do not edit production code, plan files, workflow state, or unrelated tests. Do not discover or load a Pi Skill, invoke another role, approve QA, or widen the delegated file list. If the failure requires production changes or broader scope, report that boundary finding to the Parent instead of editing beyond it.
+
+## Code Quality Guard
+
+Preserve test intent while repairing tests. Do not delete or loosen assertions,
+reduce coverage, replace target behavior with a mock, or change expected
+behavior solely to make the test pass. A production defect is a boundary
+finding for the Parent, not permission to edit production code.

package/plugins/immune-brain/hooks/hooks.json

@@ -0,0 +1,55 @@
+{
+  "description": "Observe Claude Code Review and session lifecycle for Immune-Brain. Hooks never mint authority.",
+  "hooks": {
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/claude/mcp-server.mjs\" --hook"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/claude/mcp-server.mjs\" --hook"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/claude/mcp-server.mjs\" --hook"
+          }
+        ]
+      }
+    ],
+    "ElicitationResult": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/claude/mcp-server.mjs\" --hook"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/claude/mcp-server.mjs\" --hook"
+          }
+        ]
+      }
+    ]
+  }
+}