immune-brain 3.2.0 → 3.2.2

package/README.md

@@ -46,7 +46,7 @@ This repo is a Pi package — Pi discovers Skills and extensions from `package.j
 }
 ```
 
-No extra server config is needed. Installing the package via Pi makes all 5 Skills available automatically. Verify with:
+No extra server config is needed. Installing the package via Pi makes all 6 Skills available automatically. Verify with:
 
 ```bash
 bun test                          # run all tests
@@ -165,7 +165,7 @@ See [`docs/reference/immune-brain-config.md`](docs/reference/immune-brain-config
 package.json                          # Pi package manifest (skills + extensions)
 plugins/immune-brain/
 ├── .pi-extension/                    # Pi TUI + Kernel authority extension
-├── skills/                           # 5 public Skills (trigger shims)
+├── skills/                           # 6 public Skills (trigger shims)
 ├── dist/                             # Built skill contracts & references
 ├── runtime/                          # Bun + TypeScript runtime & Kernel
 └── bin/                              # CLI wrappers (→ runtime/v4_runtime.ts)
@@ -183,7 +183,7 @@ docs/specs/                           # Living specs (updated in place)
 
 ## FAQ
 
-**Do I need to learn all 5 skills?** No. Just describe what you want — Pi routes to the right skill. Learn `imm-planner` and `imm-loop` first; the other two are occasional.
+**Do I need to learn all 6 skills?** No. Just describe what you want — Pi routes to the right skill. Learn `imm-planner` and `imm-loop` first; the other four are occasional.
 
 **What if I interrupt or close Pi mid-task?** State is on disk (`.imm/` + TaskIntent). Re-enter `imm-loop` to resume — the Kernel projection is authoritative.
 
@@ -202,8 +202,8 @@ This repo uses [Changesets](https://github.com/changesets/changesets) for versio
 | Task | Command |
 |------|---------|
 | Add a changeset | `bunx changeset` — pick bump (patch/minor/major) and write summary |
-| Bump version | `bun run changeset:version` — updates `package.json` + `CHANGELOG.md` |
-| Publish (local) | `bun run changeset:publish` — publishes to npm (needs `NPM_TOKEN` or `npm login`) |
+| Bump version | `bun run changeset:version` — updates `package.json` + `CHANGELOG.md`, then syncs and validates the Claude plugin manifest |
+| Publish (local) | `bun run changeset:publish` — validates manifest versions, then publishes to npm (needs `NPM_TOKEN` or `npm login`) |
 
 **Automated flow (recommended):**
 1. Push changesets to `main` → workflow opens a “Version Packages” PR.

package/README.zh-CN.md

@@ -46,7 +46,7 @@ Pi 与 Claude Code 是支持的宿主。未声明的适配器仍不受支持。C
 }
 ```
 
-无需额外 server 配置，通过 Pi 安装本 package 后 5 个 Skill 即自动可用。验证：
+无需额外 server 配置，通过 Pi 安装本 package 后 6 个 Skill 即自动可用。验证：
 
 ```bash
 bun test                    # 全量测试
@@ -165,7 +165,7 @@ Immune-Brain **没有独立配置文件**，偏好设置写在 `AGENTS.md`（仓
 package.json                          # Pi package manifest（skills + extensions）
 plugins/immune-brain/
 ├── .pi-extension/                    # Pi TUI + Kernel 扩展
-├── skills/                           # 5 个公开 Skills（触发 shim）
+├── skills/                           # 6 个公开 Skills（触发 shim）
 ├── dist/                             # 构建后的 skill 契约与参考文档
 ├── runtime/                          # Bun + TypeScript 运行时与 Kernel
 └── bin/                              # CLI wrappers（→ runtime/v4_runtime.ts）
@@ -183,7 +183,7 @@ docs/specs/                           # Living specs（原地更新）
 
 ## 常见问题
 
-**需要记住所有 Skill 吗？** 不需要，直接描述需求即可，Pi 会自动路由。先掌握 `imm-planner` 和 `imm-loop`，另外两个按需使用。
+**需要记住所有 Skill 吗？** 不需要，直接描述需求即可，Pi 会自动路由。先掌握 `imm-planner` 和 `imm-loop`，另外四个按需使用。
 
 **中途关闭 Pi 会怎样？** 状态已落盘（`.imm/` + TaskIntent），重新进入 `imm-loop` 即可恢复，以 Kernel projection 为准。
 
@@ -202,8 +202,8 @@ docs/specs/                           # Living specs（原地更新）
 | 任务 | 命令 |
 |------|------|
 | 创建 changeset | `bunx changeset` — 选择 bump 类型（patch/minor/major）并填写说明 |
-| 升级版本 | `bun run changeset:version` — 更新 `package.json` + `CHANGELOG.md` |
-| 本地发布 | `bun run changeset:publish` — 发布到 npm（需 `NPM_TOKEN` 或 `npm login`） |
+| 升级版本 | `bun run changeset:version` — 更新 `package.json` + `CHANGELOG.md`，然后同步并校验 Claude plugin manifest |
+| 本地发布 | `bun run changeset:publish` — 校验 manifest 版本后发布到 npm（需 `NPM_TOKEN` 或 `npm login`） |
 
 **自动化流程（推荐）：**
 1. 推送 changeset 到 `main` → workflow 自动创建 “Version Packages” PR。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "immune-brain",
-  "version": "3.2.0",
+  "version": "3.2.2",
   "description": "Immune-Brain agent skill system",
   "publishConfig": {
     "access": "public",
@@ -29,8 +29,8 @@
   },
   "scripts": {
     "changeset": "changeset",
-    "changeset:version": "changeset version && bun scripts/plugin_versioning.ts stamp",
-    "changeset:publish": "changeset publish",
+    "changeset:version": "changeset version && bun scripts/plugin_versioning.ts stamp && bun scripts/plugin_versioning.ts validate",
+    "changeset:publish": "bun scripts/plugin_versioning.ts validate && changeset publish",
     "release": "bun run changeset:publish"
   },
   "devDependencies": {

package/plugins/immune-brain/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "immune-brain",
-  "version": "3.2.0",
+  "version": "3.2.2",
   "description": "Immune-Brain Claude Code Host: native Enrollment, QA, Review, and Kernel settlement.",
   "author": {
     "name": "Immune-Brain Team"

package/plugins/immune-brain/.pi-extension/imm-canary-enroll.ts

@@ -458,9 +458,7 @@ async function executeForegroundEnrollment(
 				`Goal: ${taskIntent.intent.goal}`,
 				`Risk: ${taskIntent.intent.risk}`,
 				`Scope: ${taskIntent.intent.scope_hint.length > 0 ? taskIntent.intent.scope_hint.join(", ") : "(none)"}`,
-				`Acceptance: ${taskIntent.intent.acceptance.length} descriptor(s); press d to expand`,
-				`Intent digest: ${preparation.intent.content_hash}`,
-				`Preparation digest: ${preparation.digest}`,
+				`Acceptance: ${taskIntent.intent.acceptance.length} descriptor(s)`,
 			].join("\n");
 			const confirmationDetails = [
 				`Acceptance descriptors:`,

package/plugins/immune-brain/.pi-extension/imm-canary-work.ts

@@ -477,7 +477,7 @@ export default function (
 				presentTaskRail(ctx, {
 					task_id: taskId,
 					state: "Approval required",
-					result: "Kernel authority repair requires literal-user approval",
+					result: "Authority repair needs your approval",
 					next: "Decide whether to repair the stale claim",
 				});
 				const repairSelection = await requestAuthorityDialog(pi, ctx, {
@@ -854,7 +854,7 @@ export default function (
 		presentTaskRail(ctx, {
 			task_id: taskId,
 			state: "Approval required",
-			result: `${operation} requires literal-user approval`,
+			result: `${operation} requires your confirmation`,
 			next: `Decide ${operation}`,
 		});
 		const attention = {
@@ -870,7 +870,7 @@ export default function (
 				details: dialogDetails,
 				signal: ctx.signal,
 				actions: [
-					{ value: "authorize", label: "Authorize", description: `Apply ${operation} after freshness revalidation` },
+					{ value: "authorize", label: "Authorize", description: `Apply ${operation} after re-checking state` },
 					{ value: "cancel", label: "Cancel", description: "Leave managed authority unchanged" },
 				],
 			});

package/plugins/immune-brain/.pi-extension/pi-canary-interaction.ts

@@ -161,7 +161,14 @@ export async function requestAuthorityDialog<T extends string, R = T | undefined
 
 export function presentTaskRail(ctx: UiContext, view: TaskRailView): void {
 	try {
-		ctx.ui.setWidget(TASK_RAIL_KEY, renderTaskRail(view), { placement: "aboveEditor" });
+		ctx.ui.setWidget(TASK_RAIL_KEY, (_tui, theme) => {
+			return {
+				render(width: number): string[] {
+					return renderTaskRail(view, width, theme);
+				},
+				invalidate(): void {},
+			};
+		}, { placement: "aboveEditor" });
 		if (view.state === "Completed" || view.state === "Stopped") terminalRailUis.add(ctx.ui);
 		else terminalRailUis.delete(ctx.ui);
 	} catch {
@@ -180,7 +187,7 @@ export function presentTaskRailResult(
 	const operation = string(details.operation);
 	const rawState = string(details.state);
 	const result = string(details.result) ?? string(details.reason) ?? operation ?? rawState ?? "Task state updated";
-	const next = string(details.next_action) ?? "Continue through the projected authority";
+	const next = string(details.next_action) ?? "Follow the projected Obligation";
 	presentTaskRail(ctx, {
 		task_id: taskId,
 		state: railState({ lifecycle, obligation: string(taskState?.next_obligation), operation, state: rawState }),
@@ -286,11 +293,34 @@ function emitAttention(pi: EventPublisher, event: UserAttentionEventV1): void {
 	}
 }
 
-function renderTaskRail(view: TaskRailView): string[] {
+function formatTaskRailState(state: TaskRailState, theme?: Theme): string {
+	const symbolAndColor: Record<TaskRailState, { symbol: string; color: string }> = {
+		Planning: { symbol: "●", color: "muted" },
+		"Approval required": { symbol: "▲", color: "accent" },
+		Working: { symbol: "●", color: "accent" },
+		Verifying: { symbol: "●", color: "accent" },
+		Reviewing: { symbol: "●", color: "accent" },
+		Blocked: { symbol: "⚠", color: "warning" },
+		Completed: { symbol: "✓", color: "success" },
+		Stopped: { symbol: "■", color: "muted" },
+	};
+	const cfg = symbolAndColor[state] ?? { symbol: "●", color: "dim" };
+	if (!theme) return `${cfg.symbol} ${state}`;
+	return `${theme.fg(cfg.color, cfg.symbol)} ${theme.fg(cfg.color, state)}`;
+}
+
+function renderTaskRail(view: TaskRailView, width = 120, theme?: Theme): string[] {
+	const prefixWidth = 8; // "Result: " or "Next: "
+	const availableContentWidth = Math.max(20, width - prefixWidth);
+	const taskIdWidth = Math.max(16, Math.min(52, width - 26));
+	const stateFormatted = formatTaskRailState(view.state, theme);
+	const label = (text: string) => (theme ? theme.fg("muted", text) : text);
+	const body = (text: string) => (theme ? theme.fg("dim", text) : text);
+
 	return [
-		`Task ${boundedMiddle(view.task_id, 52)} · ${view.state}`,
-		`Result: ${bounded(view.result, 112)}`,
-		`Next: ${bounded(view.next, 112)}`,
+		`Task ${boundedMiddle(view.task_id, taskIdWidth)} · ${stateFormatted}`,
+		`${label("Result:")} ${body(bounded(view.result, availableContentWidth))}`,
+		`${label("Next:")} ${body(bounded(view.next, availableContentWidth))}`,
 	];
 }
 
@@ -338,12 +368,12 @@ function strings(value: unknown): string[] {
 }
 
 function bounded(value: string, max: number): string {
-	return value.length <= max ? value : `${value.slice(0, max - 3)}...`;
+	return value.length <= max ? value : `${value.slice(0, max - 1)}…`;
 }
 
 function boundedMiddle(value: string, max: number): string {
 	if (value.length <= max) return value;
-	const visible = max - 3;
+	const visible = max - 1;
 	const start = Math.ceil(visible / 2);
-	return `${value.slice(0, start)}...${value.slice(-(visible - start))}`;
+	return `${value.slice(0, start)}…${value.slice(-(visible - start))}`;
 }

package/plugins/immune-brain/dist/docs/reference/HANDOFF-template.md

@@ -117,6 +117,6 @@ kept for historical reference only.
 
 ## Notes
 
-- `imm-work` owns HANDOFF.md writes (boundary exception documented in skill)
-- `.imm/memory/` is the source of truth; HANDOFF.md is a convenience artifact
+- Historical: `imm-work` previously owned HANDOFF.md writes (v3 boundary exception); that writer was removed with the v3 State Ledger retirement and no current runtime code rewrites the generated block.
+- Historical: `.imm/memory/` was the v3 source of truth; it is retired. The current durable source of truth is the TaskRecord v4 under `.imm/state/tasks/`, with HANDOFF.md as a convenience artifact only.
 - Priority files list is advisory (max 5) and exists only to make Pi session continuation faster

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

@@ -65,8 +65,8 @@ 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/specs/automatic-subagent-activation.spec.md` — EXPIRED: this exemption lapsed when its program closed and the spec was archived to `docs/specs/archive/automatic-subagent-activation.spec.md` (the packaged copy pin in `tests/code-review-activation-contract.test.ts` remains in force).
+- `docs/specs/opencode-native-plugin.spec.md` — EXPIRED: this exemption lapsed when its program closed and the spec was archived to `docs/specs/archive/opencode-native-plugin.spec.md` (the dual-path resolution in `tests/python-reference-boundary.test.ts` remains in force).
 - `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.

package/plugins/immune-brain/dist/imm-agent-doc-maintain.md

@@ -55,9 +55,12 @@ commit.
    routing owner or scope cannot be read reliably, fail closed for mutation.
 
 3. **Inventory instruction relationships.** Determine nesting, explicit
-   precedence statements, inbound references, and existing authority pointers.
-   Preserve each file's native organization. Do not normalize files to a shared
-   template and do not infer unsupported cross-host inheritance semantics.
+   precedence statements, inbound references, existing authority pointers, and
+   semantic duplication within and across candidates. Preserve each file's
+   native organization. Do not normalize files to a shared template and do not
+   infer unsupported cross-host inheritance semantics. Resolve duplicate
+   ownership only from explicit precedence, authority, and inbound-reference
+   evidence; unresolved ownership remains `UNVERIFIED` or `BLOCKED`.
 
 4. **Build repository facts.** Resolve current truth in this order:
    executable/public registries, package exports, CLI/runtime entrypoints;
@@ -77,14 +80,25 @@ commit.
 6. **Classify exact actions.** Classify entries as `REMOVE`, `REWRITE`,
    `POINTER`, `KEEP`, `BLOCKED`, `BLOCKED_ACTIVE_SCOPE`, `UNVERIFIED`, or
    `MISSING_OWNER`. Every mutation entry identifies exact file/section bytes,
-   preserved meaning, evidence, candidate hash, and resulting text. `POINTER`
-   may target only an existing current authority and must include a concrete
-   trigger condition. Missing reference ownership is `MISSING_OWNER`; this Skill
-   does not create a reference document. Unknown or one-off-looking rules remain
-   `UNVERIFIED` and are not deleted by default. Unresolved precedence or
-   semantic conflicts that cannot be decided from explicit repository scope or
-   declared precedence are `BLOCKED`. Filename convention, nesting, or guessed
-   host behavior alone may not resolve a conflict.
+   preserved meaning, evidence, candidate hash, and resulting text. A retained
+   meaning has one instruction owner; duplicate copies are not all `KEEP` by
+   default. Rules already enforced deterministically by a formatter, linter,
+   schema, permission policy, Git hook, or runtime are `REMOVE` unless the agent
+   still needs a non-discoverable recovery action, in which case use the shortest
+   `REWRITE` or `POINTER`. Keep globally relevant retained rules inline. For a
+   branch-specific rule, prefer `POINTER` to an existing current authority with
+   a concrete trigger condition; when no owner exists, use `MISSING_OWNER`
+   rather than creating one. This Skill does not create a reference document.
+   Do not introduce host-specific conditional markup,
+   including `<important if>`, without an explicit current host contract and
+   repository evidence that the target file uses those semantics. Discoverable
+   code snippets, examples, and command tables are repository caches and are
+   removed or replaced with a stable pointer unless they encode a necessary
+   non-discoverable exception or recovery action. Unknown or one-off-looking
+   rules remain `UNVERIFIED` and are not deleted by default. Unresolved
+   precedence or semantic conflicts that cannot be decided from explicit
+   repository scope or declared precedence are `BLOCKED`. Filename convention,
+   nesting, or guessed host behavior alone may not resolve a conflict.
 
 7. **Produce one exact manifest.** `audit` mode stops after the manifest.
    Mutation mode also stops until the literal user approves exact manifest
@@ -103,8 +117,9 @@ commit.
    brevity.
 
 9. **Verify and report.** Re-scan modified instruction relationships, local
-   pointer targets, unresolved conflicts, source/package public-surface parity,
-   existing focused documentation contracts, and `git diff --check`. This Skill
+   pointer targets, duplicate retained meanings, unresolved conflicts,
+   source/package public-surface parity, existing focused documentation
+   contracts, and `git diff --check`. This Skill
    does not execute arbitrary documented commands, real-model success-rate
    benchmarks, or Token measurements unless the user literally requests a
    benchmark. This Skill does not commit. Report only `Removed`, `Rewritten`,

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

@@ -1,6 +1,6 @@
 ---
 name: imm-loop
-description: Use when running validated Plans to completion.
+description: Use to run an enrolled TaskIntent to completion through Kernel-governed execution, QA, and Review.
 ---
 
 # Immune-Brain: Loop
@@ -141,17 +141,22 @@ Default user-facing shape: checkpoint progress lines, then `Conclusion -> Eviden
 When the Kernel projection reports an active/draining backend claim, keep
 `imm-loop` as the user-facing entry and call the `imm_kernel_canary` Tool for
 that owned task. Enrollment uses the `imm_canary_enrollment` Tool and Review
-authorization remains a native TUI gate using the internal user-kind approval
-action `record-user-approval`. When the projection calls for
+authorization remains a native TUI gate. When the projection calls for
 `request_authorization`, `approve_breaking_intent_revision`, or
 `repair_authority_state`, invoke the exact Tool operation directly without
 asking the user for chat pre-confirmation; the native host interaction is the
-single authority decision. This action is not a public Skill or CLI route. Do
-not invoke the removed `imm-canary-work` Skill as a separate entry point.
-Invalid or contradictory projections fail closed. After implementation and focused verification, freeze the artifacts and call
-`imm_kernel_canary` `advance_assurance`. If it returns `review_ready`, invoke
-the 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.
+single authority decision. 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
+`advance_assurance`. If it returns `review_ready`, invoke the foreground
+reviewer and pass its structured verdict to `submit_review`;
+`request_authorization` remains the critical-risk user authorization boundary.
+Every QA/Review operation stays foreground and returns its next projected
+obligation directly to the Parent. The host performs any opted-in GitHub Issue
+projection only after the corresponding authority mutation: only a fresh
+claimless `done`/`stopped` projection with its exact terminal tombstone projects
+terminal closure (`completed`/`not planned`); Enrollment performs no GitHub
+projection. Treat the attached tracker result as non-authoritative observation.
+Report its failure separately, but never use it as evidence, a stop condition,
+or a reason to repeat a Kernel mutation. A terminal tombstone alone never
+blocks unrelated v3 routing.

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

@@ -1,6 +1,6 @@
 ---
 name: imm-planner
-description: Use when planning work.
+description: Use to create or revise a spec and TaskIntent from requirements; owns scope and decomposition, not implementation or Enrollment.
 ---
 
 # Immune-Brain: Planner

package/plugins/immune-brain/skills/imm-loop/SKILL.md

@@ -1,51 +1,9 @@
 ---
 name: imm-loop
-description: Use to run a validated Plan to completion in the current conversation through checkpoints and isolated QA/review authorities.
+description: Use to run an enrolled TaskIntent to completion through Kernel-governed execution, QA, and Review.
 ---
 
 # Immune-Brain: Loop
 
-Load [`../../dist/imm-loop.md`](../../dist/imm-loop.md), then run the checkpoint loop in the current Pi conversation. Keep active Step implementation in this conversation; use Pi native `Agent` subagents only when the runtime reports `awaiting_qa_decision` or a required review gate. Standard Plan Steps close from passing evidence without per-Step QA; Strict Plan Steps retain isolated QA. Return visible checkpoint progress and a final stop summary.
-At every runtime role boundary, call the read-only `imm_loop_action` Tool. Use
-`route` for active Steps, bounded repair, architecture exploration, advisory
-review, Compounder, Kernel ownership, or scope expansion. Use `dispatch_role`
-for `qa`, `code-review`, and `ui-review`, then invoke the returned foreground
-Agent envelope exactly. Brainstorm and Planner use the same Tool for bounded
-`arch-explorer` and explicit-lens `advisory-reviewer` dispatches. Loop may
-dispatch `compounder` only when a closed Step supplies structured evidence for
-a reusable Learning; routine work without that evidence returns `next: none`
-and creates no Learning. Do not discover or load a Pi Skill for these roles. The Managed Path public entries remain `imm-brainstorm`, `imm-planner`, and `imm-loop`; standalone `imm-pr-fix`, `imm-doc-prune`, and `imm-agent-doc-maintain` are host-native and are never dispatched as the Loop role.
-Subagent Dispatch Protocol](../../dist/docs/reference/subagent-dispatch-protocol.md#authorization-authority).
-All internal Agent dispatch envelopes use `run_in_background: false` and
-return a direct result to the Parent before any workflow mutation.
-
-At `terminal_plan_complete`, stop with no next skill, authority, or action. At `awaiting_user_successor_decision`, stop with `recommended_authority: user`. This boundary follows the explicit internal Compounder handoff and runtime terminal settlement; it must not dispatch Planner, Compounder, transition, or a new Pi session/subagent. Only a literal user may approve a successor through the native authority gate; the internal runtime token is `--approve-successor`, never a public Skill or user-facing entry.
-
-Scope expansion always returns to `imm-planner`; Executor and repair roles must stop with the concrete missing scope and verification reason instead of widening execution.
-
-The loop always enters through `imm_loop_action`: the projected action's `next`
-authority is `executor`, `test-fixer`, `pr-fix`, `arch-explorer`,
-`advisory-reviewer`, `compounder`, `imm_kernel_canary`, `imm-planner`, or
-`none`.
-
-When the Kernel projection reports an active/draining backend claim, keep
-`imm-loop` as the user-facing entry and call the `imm_kernel_canary` Tool for
-that owned task. Enrollment uses the `imm_canary_enrollment` Tool and Review
-authorization remains a native TUI gate. 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. 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
-`advance_assurance`. If it returns `review_ready`, invoke the foreground
-reviewer and pass its structured verdict to `submit_review`; `request_authorization` remains the
-critical-risk user authorization boundary. Every QA/Review operation stays
-foreground and returns its next projected obligation directly to the Parent. The host performs any opted-in GitHub Issue projection only after the
-corresponding authority mutation: only a fresh claimless `done`/`stopped`
-projection with its exact terminal tombstone projects terminal closure
-(`completed`/`not planned`); Enrollment performs no GitHub projection. Treat the
-attached tracker result as non-authoritative observation. Report its failure
-separately, but never use it as evidence, a stop condition, or a reason to
-repeat a Kernel mutation. A terminal tombstone alone never blocks unrelated v3
-routing.
+Load [`../../dist/imm-loop.md`](../../dist/imm-loop.md), then follow that
+canonical contract in the current host conversation.

package/plugins/immune-brain/skills/imm-planner/SKILL.md

@@ -1,232 +1,9 @@
 ---
 name: imm-planner
-description: Use to create or revise a spec and iteration plan from requirements; owns scope and plan decomposition, not implementation or step activation.
+description: Use to create or revise a spec and TaskIntent from requirements; owns scope and decomposition, not implementation or Enrollment.
 ---
 
 # Immune-Brain: Planner
 
-Load [`../../dist/imm-planner.md`](../../dist/imm-planner.md), then create or revise
-the executable plan. `mode: page_design` is the canonical pre-implementation
-design-contract mode formerly exposed as `imm-page-design`. Keep scope
-explicit, including the Devil's Advocate preplan audit and `Devil's Advocate Audit` output. Return plan path, decisions,
-first step, verification approach, and Next Action.
-
-## Clarification supplement
-
-Planner consumes an upstream Brainstorm manifest as a closed-world input and
-must not repeat, reopen, or rewrite confirmed decisions. Direct Planner entry
-and Medium/High Design Risk work must inspect relevant ADRs and rejected
-Learnings. It resolves repository facts and owns ordinary technical choices: design and component boundaries, failure behavior, compatibility, migration, recovery and
-rollback, Verification, execution slices, dependencies, scope, and delivery
-risk. It then authors the candidate Spec, Plan, or TaskIntent.
-
-Planner may ask only when concrete new evidence exposes an omission, repository
-conflict, or invalidated assumption. Ask the focused decision delta, cite the
-upstream `BR-*` item and new evidence when available, and preserve every
-unaffected decision. Resolve a local delta here; if its answer reopens multiple
-product branches or changes the overall goal or Scope, stop and return to
-`imm-brainstorm`.
-
-Direct Planner entry remains valid for clear requests. Resolve facts and derive
-technical design without a Brainstorm pass; if an unresolved user-owned product
-decision appears, return to `imm-brainstorm` instead of silently choosing it or
-starting a second exhaustive interview. A zero-question fast path is valid when
-no supplement is required. Present an unchanged result summary as a
-non-blocking correction window and do not ask the user to reconfirm existing
-decisions. If the summary itself introduces or changes a user decision, confirm
-only that decision delta before finalizing.
-
-Settlement-class intents (terminal settlement, cancellation, timeout, race, or
-authority-lifecycle semantics) must embed the `Settlement-Design Contract`
-enumeration required by the loaded contract before they are execution-ready.
-
-## Technical Design Views And Decomposition
-
-For Medium and High Design 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. The Spec is the single Technical Design baseline. Persist those decisions there; do not copy them into a TaskIntent or revive prose Plan authority. Low risk remains concise and is not forced to produce empty architecture, interface, data-flow, state, or sequence sections.
-
-Use the selected design boundaries as one TaskIntent decomposition dimension alongside outcome, Verification, dependency, risk, rollback, compatibility, and authority. Keep one TaskIntent when the selected views describe one coherent executable slice with shared acceptance, risk treatment, rollback, 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.
-
-Treat trust-boundary changes as the same kind of decomposition evidence. A TaskIntent should normally change one primary trust-boundary invariant; 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.
-
-## Reference Closure Preflight
-
-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
-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
-exhaustive filename guess.
-
-## Managed Request Routing
-
-`imm-planner` is entered explicitly by the user for a clear repository mutation.
-Ordinary host input does not invoke this Skill through natural-language routing.
-An active Assurance projection remains authoritative and is resumed only through an explicit `imm-loop` entry; explicit Planner entry owns planning and the later native Enrollment gate:
-- an active Assurance projection remains on its current owner until the user explicitly enters `imm-loop`;
-- read-only, explanation, review-only, Plan-only, and explicit no-modification
-  requests do not enroll;
-- materially ambiguous mutations go to `imm-brainstorm` before planning; and
-- clear new mutations reach this Planner phase.
-
-Plan-only output remains non-authoritative. Planner creates or validates a
-candidate Spec/TaskIntent, but it never enrolls a task or enrolls generated
-artifacts unconditionally. Explicit Plan-only requests stop after returning the
-planning artifacts. A later literal-user request to start Enrollment is a non-authoritative
-execution trigger: invoke the native Enrollment gate directly, without asking
-for chat pre-confirmation. For a clear mutation request that already includes
-execution, invoke that gate as soon as the candidate is validated and Git-tracked.
-Literal-user confirmation in the native gate remains the authority boundary.
-Fast-Track may compress the same phases but cannot bypass that boundary, QA,
-Review, authorization, or completion.
-
-## Kernel TaskIntent Routing
-
-Before producing a new managed planning artifact, resolve the canonical wrappers
-from the declared Skill location: `../../bin/imm-plan` and
-`../../bin/imm-kernel`. Invoke `imm-plan --routing-status --json` through that
-resolved wrapper and use the resolved `imm-kernel` wrapper for every Kernel
-command below. Do not assume either bare command is available on shell `PATH`.
-Then route deterministically:
-
-- an active Kernel claim routes to `imm-loop` for foreground Kernel Tool
-  coordination, not new planning;
-- an active or otherwise nonterminal v3 Plan remains on its existing v3 route;
-- no routing policy preserves the legacy v3 Planner behavior;
-- a valid `kernel_task_intent` retirement policy produces one TaskIntent draft
-  through Pi `imm-planner`;
-- an invalid, unreadable, untracked, or tracked-deleted policy rejects new
-  planning authority with `routing_policy_invalid`;
-- no Planner path enrolls a task or falls back to v3 after retirement.
-
-Current owner, phase, completion, and authority facts are authoritative only
-when read from the Assurance projection and TaskRecord. `CONTEXT.md` is
-non-authoritative vocabulary and architecture navigation, not a workflow-status
-source. If its prose conflicts with those authority facts, report stale
-documentation, preserve projection-based routing, and do not automatically
-synchronize either representation.
-
-Pi host identity is implicit and never a planning input. The production boundary
-that turns a Git-tracked TaskIntent draft into managed execution authority is the
-native host TUI: the Planner's final `ctx.ui.custom` gate (via the
-`imm_canary_enrollment` foreground Tool) provides one literal-user confirmation
-bound to the TaskIntent content hash. Invoke the Tool directly when the route is
-ready; do not ask for a chat pre-confirmation. Enrollment validates the intent,
-Git ownership, scope, workspace claim, and final authority preconditions without
-executing acceptance descriptors. A routine task proceeds from that single
-confirmation through enrollment, execution and QA without a second human stop.
-
-The Planner never writes the `docs/plans/<task-id>.intent.json` artifact
-directly and never overwrites an existing TaskIntent. Under an active
-`kernel_task_intent` policy it supplies one complete candidate to the canonical
-`imm-kernel intent author <path> --stdin --json` command, which owns strict
-parsing, verification-descriptor canonicalization, path binding, and exclusive
-file creation; then it validates the created artifact with
-`imm-kernel intent validate <path> --json`. Revisions of an enrolled intent
-continue through Kernel `revise_intent` authority and are not a Planner
-overwrite path.
-
-### Initiative Carrier Preference
-
-For a large proposal split across multiple TaskIntents, exactly one planning
-carrier is chosen per Initiative: a Local Markdown file at
-`docs/initiatives/<slug>.md` or one GitHub Parent Issue. This preference applies
-only to Initiatives; ordinary TaskIntents remain tracked by Kernel TaskRecords.
-Resolve the carrier in this order:
-
-1. a literal user instruction for the current request;
-2. `Initiative carrier default: local` or `Initiative carrier default: github`
-   in the repository root `AGENTS.md`;
-3. the same directive in `~/.pi/agent/AGENTS.md`; or
-4. ask the user when no valid directive exists.
-
-A repository directive overrides the global directive. Report an invalid value
-and ask instead of guessing. After resolving it, display one non-blocking line
-with the selected carrier and its source. A configured `github` default is
-standing opt-in for GitHub projection, but the literal user must still confirm
-the named Initiative, its immutable slug, and the complete Parent/Child
-decomposition before the first remote mutation. A prior bulk approval cannot
-confirm a name, slug, Child, or dependency that had not yet been shown.
-
-Once decomposition is complete, present one review table containing the Parent
-result and every Child's stable Slice ID, result, scope boundary, risk, blockers,
-and proposed execution order. Ask one focused question: whether the coverage,
-granularity, and dependencies are correct. Recommend the complete current
-frontier so the user can approve it in one response. Before that approval,
-perform zero GitHub mutations. A partial or progressively disclosed issue set is
-not eligible for publication.
-
-After approval, author, stage, and validate every TaskIntent in the decomposition
-with `valid: true` and `enrollment_ready: true`. Resolve `../../bin/imm-tracker` from this Skill location; do not assume a bare command is on `PATH`. Submit the entire approved set once through
-`imm-tracker publish-initiative --stdin --json`. Its input contains the confirmed
-Initiative slug and goal, Parent projection, and every Child's `slice_id`,
-canonical TaskIntent path, 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
-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.
-
-Each Child projection 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
-TaskIntent for identity, risk, and acceptance; projection fields 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.
-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;
-Local mode performs zero GitHub operations.
-
-The batch result includes an execution recommendation: the first unblocked Task,
-a stable dependency order, and parallel groups. For a plan-only request, report
-that recommendation and stop. For a request that includes execution, invoke the
-native Enrollment gate for the recommended first TaskIntent after successful
-publication; do not ask for another chat confirmation. GitHub selection never
-bypasses Enrollment.
-
-Tracker output is observation, never authority. Before the Planner returns, its
-GitHub carrier outcome must be exactly one of: `tracker_associated` after the
-complete batch returns `created`, `updated`, or `already_current`;
-`awaiting_user_initiative_confirmation` with the single pending name, slug, and
-complete-decomposition decision; or `tracker_projection_failed` with the returned
-failure and exact retry action. A candidate Initiative or partial Issue set
-recorded only in the Spec or final summary is neither user confirmation nor a
-completed carrier outcome. Report `retryable_failure`, `permanent_failure`, or
-`ambiguous_remote_state` and the exact batch retry action. This does not invalidate
-already-authored planning files, but it blocks `tracker_associated` and every
-Enrollment or execution handoff for that Initiative until the same complete
-batch succeeds. Do not infer opt-in from tracker output or Issue state, auto-close the Parent,
-import Issue state, create a TaskIntent from an Issue, or store Issue identity in
-TaskIntent or TaskRecord. Existing Issue markers grant permission only for
-idempotent retry of that same approved Initiative; they never grant execution
-authority.
-
-### 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.
-
-## Retirement Completion Contract
-
-For retirement-class work, deletion of source and contract text is a completion condition. A retirement that routes the command to a retirement wall, pins the absence with test assertions, and leaves the source in the tree is not complete. A retirement is not complete until the source and its contract text are deleted.
-
-An absence test is transitional scaffolding proving an in-progress deletion rather than a substitute for one. An absence test is transitional evidence of an in-progress deletion and may not stand in place of one. It proves a deletion in progress, not a completed result. Distinguish an absence assertion that guards something already gone, which is durable and correct, from one that stands in for a deletion still owed, which is a promise recorded as if it were a result.
-Architecture exploration and advisory review use the internal Loop bridge's
-read-only `arch-explorer` and `advisory-reviewer` roles. They can supply
-candidates, evidence, and decision criteria, but cannot write this Spec/Plan or
-activate execution.
-Agreement becomes evidence, Disagreement becomes decision criteria, and
-strong-model blockers become risks or verification requirements.
+Load [`../../dist/imm-planner.md`](../../dist/imm-planner.md), then follow that
+canonical contract. `mode: page_design` selects its page-design branch.