immune-brain 2.8.2

package/plugins/immune-brain/dist/docs/reference/design-contract-review-checklist.md

@@ -0,0 +1,55 @@
+# Design Contract Review Checklist
+
+This checklist gives `imm-ui-review` a project-specific, read-only review source
+for design-contract enforcement and style-neutral anti-slop review.
+
+## 1. Contract Resolution
+
+- Treat the target project root `DESIGN.md` as the highest-priority visual and
+  interaction contract when it exists.
+- Apply project-defined tokens, layout rules, components, spacing logic,
+  interaction patterns, and visual exceptions before any generic heuristic.
+- Do not replace, reinterpret, or soften explicit project design rules with a
+  fallback style preference.
+
+## 2. Missing Design Contract
+
+- If `DESIGN.md` is missing, report the missing design contract explicitly in
+  the review output.
+- State that the review can only apply generic quality heuristics until the
+  project-specific contract is authored.
+- Recommend adding `DESIGN.md` when the review surface needs stable visual or
+  interaction rules.
+- Do not write files, bootstrap templates, or synthesize a replacement
+  contract.
+
+## 3. Style-Neutral Anti-Slop Checks
+
+- Information hierarchy is intentional: primary goals, core content, and
+  secondary details are not competing for the same emphasis.
+- Layout structure is coherent: content is grouped predictably and does not
+  sprawl across arbitrary cards, panels, or decorative containers.
+- Primary actions are clear: the main action is obvious and competing
+  high-emphasis actions are justified.
+- Visual hierarchy is controlled: typography, spacing, emphasis, and contrast
+  work together without noisy stacking or accidental priority conflicts.
+- Decoration is justified: gradients, badges, icons, borders, and visual flourishes
+  must serve the product's own design language rather than novelty.
+- Pattern usage is consistent: components should feel like part of one product,
+  not a collage of unrelated demo fragments.
+- States are covered: loading, empty, disabled, error, and validation states are
+  present where the interface needs them.
+- Responsive readability is preserved: spacing and alignment remain legible
+  across supported viewport ranges.
+- Progressive disclosure is respected: advanced controls and secondary detail do
+  not crowd the primary path.
+- Product cohesion is visible: the UI should feel intentionally composed for the
+  project, not like an AI-generated showcase.
+
+## 4. Guardrails
+
+- These checks are quality heuristics, not a substitute style system.
+- Do not impose a preset product baseline, default component taxonomy, or
+  substitute design language when the project has not defined one.
+- Keep the review advisory and read-only; route fixes through normal follow-up
+  handoff paths instead of mutating project files.

package/plugins/immune-brain/dist/docs/reference/i18n-review-checklist.md

@@ -0,0 +1,110 @@
+# i18n Review Checklist
+
+Use this thin index only when UI work touches internationalization,
+localization, translated copy, locale-aware formatting, RTL layout, or localized
+theme assets. Keep review evidence tied to changed UI surfaces and avoid broad
+translation quality audits.
+
+## Trigger Signals
+
+- Locale resources: `locales/`, `i18n/`, `lang/`, `messages/`, translation
+  `.json`, `.po`, `.yaml`, or equivalent resource files.
+- Translation APIs: `t(`, `useTranslation`, `Trans`, `formatMessage`,
+  `Intl.NumberFormat`, `Intl.DateTimeFormat`, `Intl.ListFormat`,
+  `Intl.PluralRules`, or project-specific formatter wrappers.
+- UI text risks: hardcoded user-facing strings, string concatenation around
+  translated copy, pluralization, date/number/currency display, text expansion,
+  truncation, wrapping, or language-specific asset variants.
+- Directionality risks: RTL, right-to-left, `dir`, logical CSS properties,
+  mirrored icons, and directional alignment.
+
+## Core Checks
+
+1. **Hardcoded user-facing text**
+   - Flag visible UI strings added directly in components, templates, metadata,
+     buttons, labels, toasts, modals, empty states, validation messages, and
+     page titles when the project has an i18n system.
+   - Accept technical constants only when they are not rendered to users.
+
+2. **Interpolation, not concatenation**
+   - Flag translated copy assembled with `+`, template fragments, or adjacent
+     translation calls when word order can vary by locale.
+   - Prefer one translation key with named interpolation values, plural-aware
+     variants, or ICU-style messages.
+
+3. **Locale-aware formatting**
+   - Dates, times, relative times, numbers, percentages, currencies, lists, and
+     plural forms must use locale-aware formatters.
+   - Avoid fixed separators, fixed currency symbols, and English-only plural
+     suffixes such as `"s"`.
+
+4. **Text expansion and overflow**
+   - Check long words, longer translations, short CJK labels, and mixed-script
+     text in dense controls.
+   - Review wrapping, truncation, min/max width, button sizing, table cells,
+     sidebars, nav items, breadcrumbs, and mobile breakpoints.
+
+5. **RTL layout and mirrors**
+   - Check `dir` propagation, logical properties (`inline-start`,
+     `margin-inline`, etc.), flex/grid alignment, text alignment, and keyboard
+     navigation order.
+   - Directional icons, progress indicators, carousels, side panels, and arrows
+     need explicit mirror decisions.
+
+6. **Theme and localized assets**
+   - Localized images, SVGs, banners, screenshots, and icons must load safely in
+     light and dark themes.
+   - Check contrast and legibility for CJK, RTL, accented text, and small text
+     weights on dark backgrounds.
+   - Missing locale/theme assets need fallback behavior rather than broken
+     images or invisible text.
+
+## false-positive Exclusions
+
+Do not report these as i18n defects unless they are rendered directly to users:
+
+- logs, debug messages, stack traces, and `console.*` strings
+- analytics event names, experiment ids, metric keys, and telemetry dimensions
+- API field names, enum values, route names, CSS class names, test ids, and
+  data attributes
+- unit test names, fixture text, mock payloads, snapshots, and storybook-only
+  scaffolding
+- internal constants, feature flags, permissions, role ids, and storage keys
+- brand names, product names, legal names, and externally mandated copy that is
+  intentionally not translated
+
+## Severity
+
+- **P0**: A supported locale cannot complete a critical flow because text,
+  direction, formatting, or missing localized assets break the UI.
+- **P1**: A visible i18n issue corrupts meaning, hides required information, or
+  blocks important non-critical user action in a supported locale.
+- **P2**: A likely locale, RTL, formatting, or text-expansion issue degrades a
+  normal flow but has a bounded workaround.
+- **P3**: Low-risk polish, future locale hardening, or checklist cleanup that
+  does not affect current supported locales.
+
+## Evidence Expectations
+
+Every finding should include:
+
+- changed file or UI area
+- affected locale, script, formatter, or directionality condition
+- proof from code, screenshot, rendered UI, or test output
+- proposed fix or deferral reason
+- severity with the user impact in one sentence
+
+## Acceptance Checklist
+
+- User-facing text uses translation resources where the project has i18n.
+- Dynamic values use interpolation or plural-aware messages.
+- Dates, times, numbers, currencies, lists, and plurals use locale-aware
+  formatters.
+- Layout tolerates long translations and compact CJK labels on mobile and
+  desktop.
+- RTL direction, alignment, and directional icons have explicit behavior.
+- Localized assets work in light and dark themes with safe fallbacks.
+- Contrast remains legible for translated text across supported themes.
+- Reported hardcoded strings exclude technical literals and fixture-only text.
+- Findings include concrete proof and P0-P3 severity.
+- Deep semantic translation review is routed to human or specialist review.

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

@@ -0,0 +1,52 @@
+# Immune-Brain Pi Preferences
+
+Pi is the only supported code-agent host. 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.
+
+## Precedence
+
+Planner preferences resolve in this order:
+
+1. a literal instruction in the current request;
+2. the repository root `AGENTS.md`;
+3. `~/.pi/agent/AGENTS.md`; or
+4. the Skill's documented default or an explicit user question.
+
+Invalid values are reported rather than guessed.
+
+## Initiative Carrier
+
+The Initiative carrier preference applies only to proposals split across
+multiple TaskIntents. Ordinary TaskIntents remain tracked by Kernel
+TaskRecords. Set one of these fixed directives in `AGENTS.md`:
+
+```md
+## Immune-Brain Preferences
+
+- Initiative carrier default: local
+```
+
+```md
+## Immune-Brain Preferences
+
+- Initiative carrier default: github
+```
+
+A repository directive overrides the global directive. A configured `github`
+default is standing opt-in for GitHub projection, but the literal user still
+confirms the Initiative name and immutable slug before the first remote
+mutation. Planner reports the selected carrier and its source. Projection
+failure is reported with a retry action; it does not silently switch carrier or
+block TaskIntent authoring, Enrollment, or execution.
+
+## Other Preferences
+
+- Set reply-language preferences as ordinary `AGENTS.md` communication
+  instructions. Machine contracts, schema fields, paths, API names, and code
+  identifiers remain literal.
+- Project `AGENTS.md` owns standing authorization for bounded advisory
+  subagents. Explicit solo instructions and Pi host policy still take
+  precedence.
+- Agent model selection uses the active Pi session model unless a Pi `Agent`
+  invocation explicitly selects another Pi-configured model.

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

@@ -0,0 +1,94 @@
+# Planning Artifact Retention
+
+Plans and Specs are durable workflow evidence. Their paths may be referenced by
+current documentation, tests, packaged material, release records, or support
+investigations. Lifecycle is governed by signal-based terminality, not by age or
+completion status alone.
+
+## Terminality Signals
+
+An artifact is terminal when a deterministic signal proves it has no live consumer
+and no normative role. Only terminal artifacts are archived. Archival is a
+`git mv` move never a delete, with byte-preserving `R` rename.
+
+### Specs
+
+A spec under `docs/specs/<name>.spec.md` is terminal when either signal holds
+over the full `docs/plans/archive/` corpus (349 archived Plans as of this slice):
+
+- **S1 filename**: normalized spec name (strip `.spec.md`, strip `.spec`) is a
+  substring of a normalized archived plan name (strip `-plan` / `.plan` and
+  `.md`). Example: spec `2026-08-05-risk-tiered-workflow-execution` is contained
+  in plan `2026-08-05-001-refactor-risk-tiered-workflow-execution`.
+- **S2 citation**: plan text contains the literal path `docs/specs/<name>.spec.md`.
+
+`terminal(spec) := S1(spec) ∨ S2(spec)` — the union is the authority.
+Neither signal alone suffices (filename-only 113 vs citation-only 117 of 206 in
+the original measurement; union 148–150). Whatever the union leaves undetermined
+`U = activeSpecs \ union(S1,S2)` is enumerated explicitly and stays in
+`docs/specs/`; archival never guesses for `U`.
+
+### Plans and TaskIntent Sidecars
+
+- **TaskIntent sidecars** under `docs/plans/<task-id>.intent.json` are terminal
+  when `.imm/tasks/<task-id>.json` is `done`/`stopped`, or when no record exists
+  but an implementing commit touches a non-planning `scope_hint` path (commits
+  touching only `docs/plans/`, `docs/reference/v4-roadmap-taskintent-drafts.md`,
+  or `tests/planning-artifact-archival.test.ts` do not count).
+- **Prose Plans** (`docs/plans/*.md` / `*.plan.md`) are historical; all 29 were
+  archived by `2026-08-20-005` and `docs/plans/*.md` is now empty (canary
+  `.intent.json` fixtures excluded). No active prose Plan remains.
+
+## Invariants Preserved
+
+- **I1 Move never delete**: `git mv docs/plans/<name> docs/plans/archive/<name>`
+  or `git mv docs/specs/<name>.spec.md docs/specs/archive/<name>.spec.md` with
+  no byte change.
+- **I2 Link rewrite**: inbound `docs/specs/<name>.spec.md` citations in archived
+  Plans are rewritten to `docs/specs/archive/<name>.spec.md` rather than left
+  dangling, except where frozen by an external signature (see Exemptions). Stale
+  link checks (`scripts/detect-stale-refs.ts`) must report no new unresolved
+  reference beyond the pre-existing baseline for the declared scope.
+- **I3 Enumerated undetermined**: every `U` member is listed explicitly and left
+  in place; `U` is not archived by heuristic.
+- **I4 Historical preservation**: put reusable conclusions in `docs/solutions/`;
+  do not treat a solution summary as permission to remove its source evidence.
+
+## Named Exemptions
+
+At most two active specs plus one frozen plan reference are exempt from S1/S2
+even though the signals would otherwise mark them terminal. Each carries a live
+justification; a later bulk archival must not undo them.
+
+An exemption is only as good as its stated reason. The v4 deletion roadmap was
+listed here while its program was in flight; when that program closed the
+justification expired, and the spec was archived rather than left protected by
+text that no longer described it.
+
+- `docs/specs/automatic-subagent-activation.spec.md` — pinned by live planning artifacts: `scripts/dist-sync-manifest.ts`, `tests/code-review-activation-contract.test.ts`, and packaged copy `plugins/immune-brain/dist/docs/specs/automatic-subagent-activation.spec.md`.
+- `docs/specs/opencode-native-plugin.spec.md` — dual-path pinned; `tests/python-reference-boundary.test.ts` resolves it at either `docs/specs/` or `docs/specs/archive/`.
+- `docs/plans/archive/2026-06-29-001-feat-bun-typescript-runtime-migration-plan.md` — frozen plan: its `docs/specs/opencode-native-plugin.spec.md` reference is exempt from archive-path rewriting because it is part of `REFERENCE_SIGNATURE = "e89bf7809875d215c2ca0275c8f6e86e024dd451934fdc04d8e4a422bbd03a6c"` in `tests/plan-validation.test.ts`; rewriting it changes the cross-runtime signature.
+
+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.
+
+Terminal cleanup outside that lifecycle remains a bounded TaskIntent with an
+explicit candidate list and a copy-paste verification command. It may accompany
+runtime lifecycle work only when both share one declared authority boundary and
+the TaskIntent enumerates every moved artifact. Git history is rollback support,
+not a replacement for preserving links that remain part of the current
+repository.

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

@@ -0,0 +1,44 @@
+# Planning Quality Gate
+
+Use this checklist when `imm-planner` is preparing an elevated-risk plan. It is not mandatory ceremony for every plan: small, low-risk tasks should keep the normal concise Spec and Plan flow.
+
+## Trigger Signals
+
+Apply the gate when the task touches one or more of these surfaces:
+
+- Runtime state, State Ledger behavior, resume behavior, or workflow coordination.
+- Migration, compatibility, or persisted data shape.
+- Runtime/package-boundary behavior, packaged plugin output, or compiled skill contracts.
+- Reviewer, subagent, dispatch, or advisory contract behavior.
+- Rollback-sensitive workflow behavior where partial execution could leave stale state.
+
+## Required Checks
+
+- **contract surface**: name the files, skills, runtime modules, generated outputs, or docs whose behavior is part of the promised result.
+- **compatibility**: state whether existing plans, state files, Pi runtime contracts, or users need migration or backwards-compatible behavior.
+- **interruption recovery**: describe what should remain true if execution stops midway and how the next `imm-loop` run should continue.
+- **rollback path**: name the smallest coherent set of files or state entries to revert if the step fails.
+- **verification strength**: prefer parser, contract-test, unit-test, or executable command evidence over simple file-existence checks.
+- **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.
+- **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`.
+- **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.
+- **same-Phase continuation**: when sequential `roadmap-slice/v1` Plans implement the same current Phase, keep the same Roadmap source and future `Successor candidate`; never use the current Phase as its own candidate or rewrite a finished predecessor. Each activation still requires a validated distinct Plan, a fresh Ledger revision, and literal-user approval. Final review is fresh and cumulative over the explicit same-Phase continuation chain; Phase advances, terminated replacements, and legacy transition records begin a fresh review scope.
+- **scope-pressure reasoning**: record relevant file, domain, verification, dependency, or review breadth as advisory planning evidence. Do not turn file count, tokens, compactions, elapsed time, Step count, or review rounds into universal workflow gates; require a semantic retain-or-split rationale.
+- **successor authority**: when a Plan declares a `Successor candidate`, keep it to zero or one stable future Roadmap Phase and record its preconditions. A declaration is static planning metadata, not Plan creation, validation, user approval, queueing, activation, or execution; it is never the current Phase or a pointer to the next Plan.
+- **session neutrality**: preserve user ownership of session continuation. Spec, Plan, State Ledger, and handoff semantics must work whether the user continues in the current session or starts another one; no planning field may force session creation or closure.
+- **acceptance scope discipline**: ensure current acceptance criteria prove only the executable slice; draft acceptance notes for deferred phases must be labeled non-executable until a later Plan promotes them.
+- **risk-triggered exploration**: before freezing a Managed Plan, resolve unknowns that can change Scope, design, or Verification — CI environment, third-party APIs, database behavior, cross-module interfaces — using targeted read-only probes. Ask only the minimum blocking question for unclear framing, then reapply the BASELINE matrix. Read-only and Plan-only requests stay host-native without Enrollment; materially ambiguous mutations use `imm-brainstorm`; explicit Immune-Brain Skill entry starts Managed planning and literal-user Enrollment remains the authority boundary. Stop probing once Result, Scope, and Verification are concrete.
+- **supersede observability**: every new `superseded` termination must record `--reason-code` (`exploration_gap` | `scope_pivot` | `boundary_error` | `contract_change` | `execution_failure`), `--stage`, `--invalidated-assumption`, and `--avoidable yes|no`; `cancelled` terminations may record the same classification but do not require it. Legacy terminal records without observability remain readable. Planning-quality metrics count only `avoidable: yes` terminations; `scope_pivot` must use `--avoidable no` because an external requirement change is never evidence of planner failure; `execution_failure` normally routes to `rework`/`follow_up` instead of supersede.
+
+## Boundaries
+
+- This gate does not replace `IMMUNE.md` or the `imm-brainstorm` `adversarial` high-pressure gate.
+- `imm-plan` enforces declared design metadata, Medium/High Technical Design sections, and required Mermaid blocks. Untouched legacy Specs without metadata receive a compatibility warning instead of failing.
+- Do not require all plans to cite this document; use it when the trigger signals are present.

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

@@ -0,0 +1,105 @@
+# Pi Subagent Dispatch Protocol
+
+本文档定义 Immune-Brain workflow role 在 Pi 中调度 advisory child 的唯一可执行协议。公共 `imm-brainstorm`、`imm-planner`、`imm-loop` 和 runtime 内部 roles 引用本协议，不内联另一套宿主分支。
+
+## Eligibility
+
+派发前依次执行：
+
+1. 从任务摘要、changed paths 和显式请求分类为 `trivial`、`single_domain`、`multi_domain` 或 `high_risk`。
+2. 优先读取 `CONTEXT.md` Architecture Map、当前任务证据和相关 `docs/solutions/`，避免每个 child 重复探索。
+3. 低风险单领域任务可在一次直接验证可关闭时走 solo；多领域、高风险、显式 subagent 请求或有明确 bounded probe 时才派发。
+4. 只有边界清晰、Pi 暴露 `Agent` 工具且满足 authorization 时才派发。
+
+常用 fallback reason：`cost_scope_mismatch`、`unavailable_environment`、`host_authorization_required`、`trigger_not_hit`、`unclear_boundary`。
+
+## Authorization
+
+Canonical project grant:
+
+> This project authorizes bounded read-only advisory subagents and parallel probes unless the user asks for solo work.
+
+Eligibility 与 authorization 是不同门槛：
+
+1. 用户显式 solo/no-subagent 会拒绝派发。
+2. 当前请求显式要求 subagent 会授权该请求。
+3. 当前 session 的用户授权可覆盖后续符合边界的派发。
+4. 项目 `AGENTS.md` 的 standing authorization 仅在 Pi host policy 接受时有效。
+5. 否则走 solo，并记录 `host_authorization_required`。
+
+不得把项目指令描述为覆盖 Pi tool policy；也不得伪装发生过 child review。
+
+## Trigger Matching
+
+Parent 根据任务目标、changed paths 与显式请求选择 bounded advisory role。只有明确命中才派发；每个 child 只获得与其 role 相关的 path shard。未匹配文件只进入共享摘要，不复制整份 diff。
+
+Delegation packet：
+
+```text
+shared_context_summary:
+  goal: <goal>
+  changed_surface: <bounded paths>
+  project_constraints: <relevant constraints>
+
+focus_delta:
+  role: <reviewer role>
+  lens: <one lens>
+  specific_changes: <lens shard>
+  audit_question: <one concrete question>
+  tool_policy: no tools
+  boundary: advisory-only; no code edits; no plan writes; no workflow-state mutation; no QA closure
+```
+
+## Model Selection
+
+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 一致。
+
+## Pi Agent Invocation
+
+```text
+Agent:
+  subagent_type: "general-purpose"
+  description: "<role>/<lens> review"
+  prompt: <delegation packet>
+  model: <optional Pi-configured model id; omit to inherit>
+  inherit_context: false
+  run_in_background: false
+```
+
+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`。
+
+## 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.
+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.
+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
+
+Parent workflow role 必须：
+
+1. 每次消费一个 child 的 direct result 后再决定是否启动下一个候选。
+2. 合并并去重 findings。
+3. 保留 source lens 和 candidate attribution。
+4. 把 partial/error 标记为 `degraded`。
+5. 保留自身 baseline review，不把最终判断权交给 child。
+
+普通 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 每状态。
+
+本协议是 provider-agnostic、Pi-host-specific：模型 provider 可变化，code-agent host 不可变化。

package/plugins/immune-brain/dist/docs/reference/ux-heuristic-checklist.md

@@ -0,0 +1,131 @@
+# UI/UX Usability Heuristic & Experience Checklist
+
+This document compiles authoritative user experience (UX), user interface (UI), and heuristic usability principles. It serves as a progressive disclosure review lens for agents and human experts to evaluate applications page by page, component by component.
+
+---
+
+## 1. Nielsen 10 Usability Heuristics (Nielsen's 10)
+
+| **Heuristic / 原则** | **Explanation / 解释** | **Checkpoints / 检查要点** |
+| :--- | :--- | :--- |
+| **Visibility of System Status**<br>系统状态可见 | The system should always keep users informed about what is going on, through appropriate feedback within a reasonable time. | - Loading indicators or skeletons for async calls.<br>- Progress bars for long-running operations.<br>- Clear active states on buttons and tabs. |
+| **Match Between System and Real World**<br>符合现实世界 | The system should speak the users' language. Use words, phrases, and concepts familiar to the user, rather than internal jargon. | - Avoid displaying raw DB errors or stack traces to the user.<br>- Use intuitive naming conventions for tabs, menus, and actions.<br>- Map digital interactions to real-world expectations. |
+| **User Control and Freedom**<br>用户可控 | Users often perform actions by mistake and need a clearly marked "emergency exit" to leave the unwanted action without hassle. | - Support undo, cancel, or step-back on critical inputs.<br>- Allow canceling long-running background tasks.<br>- Clear "Close" or "Dismiss" options on modals and popups. |
+| **Consistency and Standards**<br>一致性 | Users should not have to wonder whether different words, situations, or actions mean the same thing. Follow platform conventions. | - Unified color palette (primary, secondary, danger, warning).<br>- Consistent button styling (e.g., solid for primary, outlined secondary).<br>- Same terminology used across all screens. |
+| **Error Prevention**<br>防止错误 | Even better than good error messages is a careful design which prevents a problem from occurring in the first place. | - Disable "Submit" buttons until mandatory fields are filled.<br>- Provide real-time validation alerts *before* submission.<br>- Double-confirm high-risk actions (e.g., delete, reset). |
+| **Recognition Rather than Recall**<br>识别优于记忆 | Minimize the user's memory load by making elements, actions, and options visible. Avoid making users remember information between pages. | - Auto-suggestion in complex search bars.<br>- Persistent labels on input fields (avoid placeholder-only labeling).<br>- Contextual help or tooltips near unfamiliar controls. |
+| **Flexibility and Efficiency of Use**<br>灵活高效 | Shortcuts — hidden from novice users — may speed up the interaction for the expert user so that the system can cater to both. | - Keyboard shortcuts for power operations.<br>- Default smart values (pre-populating fields with common choices).<br>- Bulk action capabilities in list views. |
+| **Aesthetic and Minimalist Design**<br>简洁设计 | Interfaces should not contain information which is irrelevant or rarely needed. Every extra unit of information competes with relevant info. | - High signal-to-noise ratio: prioritize core features.<br>- Clean typography with balanced padding and margins.<br>- Eliminate visual clutter and excessive lines or borders. |
+| **Help Users Recognize and Recover**<br>帮助用户恢复错误 | Error messages should be expressed in plain language (no error codes), precisely indicate the problem, and constructively suggest a solution. | - Use clear, readable explanations instead of `Error 500`.<br>- Provide direct action buttons (e.g., "Retry", "Contact Support").<br>- Highlight the exact input field that caused the error. |
+| **Help and Documentation**<br>必要帮助文档 | It is best if the system doesn't need additional explanation. However, it may be necessary to provide documentation to help users. | - Contextual tooltips explaining complex system metrics.<br>- Easily accessible FAQ or Help links in navigation.<br>- Clear step-by-step onboarding for first-time features. |
+
+---
+
+## 2. Information Architecture (IA)
+
+- **Clear Categorization (清晰分类)**:
+  - Users must immediately comprehend what each module or section does.
+  - Logical grouping of functions (e.g., "Analytics" contains only charts, "Settings" contains only configurations).
+- **Explicit Visual Hierarchy (层级明确)**:
+  - Essential content must appear first and capture immediate visual focus. Secondary actions belong in nested menus or muted elements.
+  - High-impact metrics should be larger and bolder than administrative metadata.
+- **Stable Navigation Paths (路径稳定)**:
+  - Back buttons must reliably return the user to the previous state.
+  - No dead-ends: every screen must have at least one stable way to navigate back or go home.
+- **Natural Terminology (自然命名)**:
+  - Labels must represent user intent, not database column names (e.g., "Add Member" instead of `POST /member_v2`).
+
+---
+
+## 3. Feedback First Interactive Loop
+
+An interface feels "alive" and interactive when feedback is immediate and continuous:
+
+```mermaid
+graph TD
+    A[User Clicks Action] --> B{Task Duration?}
+    B -->|< 100ms| C[Instant Active State & Success Feedback]
+    B -->|100ms - 1s| D[Visual Ripple / Button Loading Spinner]
+    B -->|> 1s| E[Skeleton Loading / Persistent Progress Bar]
+    E --> F{Completion Status?}
+    F -->|Success| G[Clear Banner / Success Notification]
+    F -->|Error| H[Readable Error Notification with 'Retry' Option]
+```
+
+- **Interactive Hover and Active States**:
+  - Buttons must transition color/scale smoothly on hover.
+  - Clicking a button triggers a satisfying change (visual ripple, spinner, or instant state toggle) so the user knows the click registered.
+- **Async Loading Skeletons**:
+  - Content containers must display skeleton loaders matching their final layout to prevent jarring page layout shifts.
+- **Long-Task Trackers**:
+  - Background processes must show a visible task status tracker (e.g., "Generating Report... 45%").
+- **Error Recovery Loops**:
+  - If a service fails, don't just show an error message. Provide a recovery button: "Try Again", "Reload Page", or "Pre-populate Cached State".
+
+---
+
+## 4. Visual Principles & Layout Excellence
+
+- **Alignment (对齐)**: Align all elements to a clean, consistent grid (left-aligned text, right-aligned numbers, centered icons). Misaligned lines signal poor craftsmanship.
+- **Contrast (对比)**: Ensure contrast ratios satisfy WCAG AA standards (minimum 4.5:1 for normal text). Dark modes must feature distinct visual depths (elevation shadows, varying card shades).
+- **Proximity (亲密性)**: Related elements must be grouped closely together. Unrelated elements must be separated by generous white space.
+- **Repetition (重复)**: Standardize repeating design patterns (margins, padding sizes, font scales, icon shapes) to create familiarity.
+- **Whitespace (留白)**: Give your layout room to breathe. Use negative space strategically to guide the user's eye and prevent overwhelming density.
+
+---
+
+## 5. Core Product Experience Principles
+
+- **Don't Make Me Think**: The primary path should be obvious without reading instructions. Labels, grouping, and visual priority should make the next action self-evident.
+- **Progressive Disclosure**: Show the most important action or decision first; reveal advanced settings, secondary metadata, and rare actions only when they are needed. Flatly-listed operations must not exceed 2 actions; all other low-frequency actions must collapse under dropdown/more menus.
+- **Recognition over Recall**: Keep context, options, and prior choices visible so users do not need to remember information across screens.
+- **Feedback First**: Every click, submit, navigation, and long task should immediately show that the system received the user's intent.
+- **Error Prevention**: Prefer constraints, confirmation, validation, and preview states that prevent mistakes before users commit them.
+- **Empty State Design**: Empty views should explain what is missing, why it matters, and the single next useful action.
+- **Consistency**: Similar actions, states, labels, and component patterns should behave the same way across the product.
+- **Default Smartness**: Use sensible defaults, prefilled values, and preserved preferences to reduce repetitive setup.
+- **User Control**: Users should be able to cancel, undo, back out, retry, or recover without losing orientation.
+- **Less but Better**: Remove low-value controls, duplicate explanations, and decorative clutter that compete with the user's goal.
+
+---
+
+## 6. 11-Point Heuristic Acceptance Checklist
+
+Before any feature is signed off by QA, it must pass these **11 criteria**:
+
+1. [ ] **Skeleton Loader**: Does every async data container show a smooth skeleton loader rather than a blank white box?
+2. [ ] **Action Spinner**: Do buttons trigger a spinner or disable themselves upon click to prevent double submissions?
+3. [ ] **Undo / Cancel**: Can the user cancel or back out of any modal / form step without losing global navigation?
+4. [ ] **Natural Error Explanation**: Are raw programming exceptions and system logs caught, replaced with human-readable guidance, and logged to console instead?
+5. [ ] **Form Validation**: Are input validation errors highlighted on the specific field in real-time, rather than only in a global pop-up?
+6. [ ] **Responsive Flow**: Does the layout remain perfectly aligned with no broken horizontal scrolling on both standard desktop and narrow viewports?
+7. [ ] **Unified Colors**: Do all interactive states (hover, active, focus, disabled) conform exclusively to the approved theme palette?
+8. [ ] **No Dead-Ends**: Is there a clear, persistent back path or navigation route visible on every single page layout?
+9. [ ] **Smart Defaults**: Are complex dropdowns or configurations pre-populated with sensible smart defaults to minimize user fatigue?
+10. [ ] **Empty States**: If data is empty or missing, is there a beautiful empty state card with a clear call-to-action button (e.g., "Add your first item")?
+11. [ ] **Action & Form Limits**: Are operations grouped to avoid flat listings of >= 3 buttons, and are inputs restricted to readable horizontal limits (max-width recommendation of ~448px or Bento Grid) to prevent stretching on wide screens?
+
+---
+
+## 7. Motion & Color Consistency Heuristics (动效与配色启发式校验)
+
+- **Motion Response (动效响应)**: Interactive micro-animations, hover effects, and view transitions must be responsive, smooth, and must not introduce perceptible lag (typically kept under 300ms) or block critical user actions.
+- **Color Accessibility (色彩与对比度)**: All text and interactive element colors must maintain strict WCAG AA color contrast ratios (minimum 4.5:1 for normal text). Brand colors must be applied consistently across states (hover, active, focus).
+
+---
+
+## 8. Design Tier Validation Rules (设计等级差异化校验)
+
+When auditing against the pre-implementation `page_design` contract, verify the implementation according to the declared `design_tier`:
+
+### Standard Tier
+- [ ] **Grid & Hierarchy**: Does the layout structure align with the section map and information hierarchy defined in the contract?
+- [ ] **Color Contrast**: Are color contrast ratios compliant with WCAG AA standards?
+- [ ] **Width Safety**: Are inputs constrained by horizontal bounds (`form_stretching_limits`) to prevent stretching across wide screens?
+- [ ] **Action Collapsing**: Are operations structured cleanly with <= 2 visible actions and low-frequency actions collapsed behind `collapsed: true` metadata?
+
+### Rich Tier
+In addition to all Standard Tier checks, audit the following:
+- [ ] **Motion Contract**: Are the view transitions and micro-animations implemented according to the durations and easing curves defined in the `motion_contract`?
+- [ ] **Aesthetic Genre**: Does the interface reflect the visual styling of the specified `aesthetic_genre` (e.g., Swiss typography, mechanical grids, HSL palettes)?
+- [ ] **Image Strategy**: Do actual images, illustrations, or placeholder styles match the texture and tone guidelines defined in the `image_strategy`?