immune-brain 3.0.2 → 3.2.1

package/README.md

@@ -23,7 +23,7 @@ Pi and Claude Code are the supported hosts. Undeclared adapters remain unsupport
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [How to Use](#how-to-use)
-- [The 5 Skills](#the-5-skills)
+- [The 6 Skills](#the-6-skills)
 - [Lifecycle](#lifecycle)
 - [Configuration](#configuration)
 - [Project Layout](#project-layout)
@@ -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
@@ -87,12 +87,13 @@ You rarely need to remember skill names — **just describe your intent**:
 | Plan is approved, ready to build | "Start building" / `imm-loop` | → Executor builds, QA verifies, Review checks |
 | PR needs fixes after review | `imm-pr-fix` on that PR | → Standalone repair, no new managed task |
 | Docs are stale after changes | `imm-doc-prune` with manifest | → Prunes only approved stale docs |
+| Agent instruction files are bloated | `imm-agent-doc-maintain` with manifest | → Keeps only necessary non-discoverable rules |
 
 > **Rule:** Managed work (brainstorm → plan → loop) starts only from explicit `imm-brainstorm`, `imm-planner`, or `imm-loop`. Ordinary Q&A or read-only requests stay host-native and never enroll a task.
 
 ---
 
-## The 5 Skills
+## The 6 Skills
 
 | Skill | Type | When to use | What it does |
 |---|---|---|---|
@@ -101,6 +102,7 @@ You rarely need to remember skill names — **just describe your intent**:
 | `imm-loop` | Managed coordinator | Plan is validated | Drives execution → QA → Review → completion via foreground tools |
 | `imm-pr-fix` | Standalone | CI failed / review comments on a PR | Repairs one PR in place, no managed authority |
 | `imm-doc-prune` | Standalone | Stale current docs | Deletes only the hash-approved manifest entries |
+| `imm-agent-doc-maintain` | Standalone | Bloated agent instructions | Minimizes tracked AGENTS/CLAUDE/GEMINI.md to necessary context |
 
 Internal roles (Executor, QA, Review, Compounder) are dispatched by `imm-loop` — you never invoke them directly.
 
@@ -163,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)
@@ -181,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.
 
@@ -200,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

@@ -23,7 +23,7 @@ Pi 与 Claude Code 是支持的宿主。未声明的适配器仍不受支持。C
 - [安装](#安装)
 - [快速开始](#快速开始)
 - [如何使用](#如何使用)
-- [5 个 Skills](#5-个-skills)
+- [6 个 Skills](#6-个-skills)
 - [生命周期](#生命周期)
 - [配置](#配置)
 - [项目结构](#项目结构)
@@ -46,7 +46,7 @@ Pi 与 Claude Code 是支持的宿主。未声明的适配器仍不受支持。C
 }
 ```
 
-无需额外 server 配置，通过 Pi 安装本 package 后 5 个 Skill 即自动可用。验证：
+无需额外 server 配置，通过 Pi 安装本 package 后 6 个 Skill 即自动可用。验证：
 
 ```bash
 bun test                    # 全量测试
@@ -87,12 +87,13 @@ QA 与 Review 以 foreground Tool 形式运行并回传结果，返回 `phase=do
 | 计划已确认，准备开干 | "开始构建" / `imm-loop` | → Executor 构建 → QA 验证 → Review 审查 |
 | PR 被评论 / CI 挂了 | 对该 PR 使用 `imm-pr-fix` | → 独立修复，不创建新 managed 任务 |
 | 文档过时需要清理 | `imm-doc-prune` + manifest | → 仅删除已审批的过时文档 |
+| Agent instruction 文件膨胀 | `imm-agent-doc-maintain` + manifest | → 只保留不可直接推导的必要规则 |
 
 > **规则：** Managed 工作流（brainstorm → plan → loop）仅由显式的 `imm-brainstorm`、`imm-planner`、`imm-loop` 启动。普通问答、只读解释不会 Enrollment。
 
 ---
 
-## 5 个 Skills
+## 6 个 Skills
 
 | Skill | 类型 | 何时使用 | 职责 |
 |---|---|---|---|
@@ -101,6 +102,7 @@ QA 与 Review 以 foreground Tool 形式运行并回传结果，返回 `phase=do
 | `imm-loop` | Managed 协调器 | 计划已验证 | 通过 foreground Tools 协调 执行 → QA → Review → 收尾 |
 | `imm-pr-fix` | 独立 | PR 需修复 | 原地修复单个 PR，不触及 managed authority |
 | `imm-doc-prune` | 独立 | 清理过时文档 | 仅删除哈希绑定的 manifest 条目 |
+| `imm-agent-doc-maintain` | 独立 | Agent instruction 膨胀 | 将 tracked AGENTS/CLAUDE/GEMINI.md 压到最小必要上下文 |
 
 Executor、QA、Review、Compounder 等为 `imm-loop` 内部调度的角色，无需手动调用。
 
@@ -163,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）
@@ -181,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 为准。
 
@@ -200,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.0.2",
+  "version": "3.2.1",
   "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.0.2",
+  "version": "3.2.1",
   "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/immune-brain-config.md

@@ -35,10 +35,14 @@ TaskRecords. Set one of these fixed directives in `AGENTS.md`:
 
 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.
+confirms the Initiative name, immutable slug, complete Parent/Child decomposition,
+granularity, and dependencies before the first remote mutation. Planner reports
+the selected carrier and its source. After confirmation it publishes the complete
+Issue graph in one idempotent batch and reports the recommended first unblocked
+Task, stable dependency order, and parallel groups. Projection failure is reported
+with a batch retry action and does not invalidate the authored planning files,
+but it blocks Enrollment and execution handoff for that Initiative until the same
+complete batch succeeds. It never silently switches carrier.
 
 ## Other Preferences
 

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

@@ -0,0 +1,137 @@
+---
+name: imm-agent-doc-maintain
+description: Use to minimize tracked AGENTS.md, CLAUDE.md, and GEMINI.md files to necessary non-discoverable context after an explicit, hash-bound, user-approved manifest; never installs or validates project contracts.
+---
+
+# Immune-Brain: Agent Doc Maintain
+
+Minimize tracked agent instruction files in one Git repository to the smallest
+set of persistent rules that are non-obvious, repeatable, stable, and costly to
+violate. This is a standalone host-native maintenance entry, not a Managed Path
+continuation and not an `imm-loop` internal-role dispatch.
+
+## Authority Boundary
+
+This Skill maintains agent instruction files without creating or mutating
+TaskIntent, TaskRecord, Kernel, Spec, or Plan authority. An already active
+Managed task remains owned by `imm-loop`. Read-only inventory and manifest
+production remain available. Classify each candidate overlapping the active
+TaskIntent `scope_hint` as `BLOCKED_ACTIVE_SCOPE` and continue auditing
+unaffected candidates. If the routing owner or scope cannot be read reliably,
+fail closed for mutation. This Skill does not invoke `imm-doc-prune`; stale
+deletion of evidence-proven content remains that Skill's separate job.
+
+## Invocation
+
+Requires explicit invocation: `imm-agent-doc-maintain` or
+`/imm-agent-doc-maintain`. Ordinary "is this AGENTS.md too long?" questions stay
+host-native and do not enter this Skill.
+
+- `imm-agent-doc-maintain audit`: read-only. Produce the manifest and stop.
+- `imm-agent-doc-maintain`: produce the manifest, then wait for exact manifest
+  approval before any mutation.
+
+No automatic invocation. No daemon, no telemetry, no automatic learning, no
+cron, no CI, no allowlist, no runtime, no persistent report, and no automatic
+commit.
+
+## Ordered Maintenance Protocol
+
+1. **Establish repository safety.** Mutation requires a Git worktree. Only
+   tracked regular files named exactly `AGENTS.md`, `CLAUDE.md`, or `GEMINI.md`,
+   at the repository root or in nested tracked directories, are candidates.
+   Git-tracked symlinks (`120000`) and other non-regular modes are `BLOCKED`
+   before inventory, reading, or mutation, even when the basename matches.
+   User-level and external files, including `~/.pi/agent/AGENTS.md` and
+   `~/.agents/`, are never inventoried or modified. Record the candidate path,
+   blob/content hash, tracked status, candidate-local worktree status, Git file
+   mode, line count, and byte count. Unrelated dirty files do not block the run;
+   a dirty or untracked candidate is `BLOCKED`.
+
+2. **Resolve Managed ownership.** Read the existing routing projection without
+   creating authority. An already active Managed task remains owned by
+   `imm-loop`. A candidate overlapping its `scope_hint` is
+   `BLOCKED_ACTIVE_SCOPE`; continue auditing unaffected candidates. If the
+   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.
+
+4. **Build repository facts.** Resolve current truth in this order:
+   executable/public registries, package exports, CLI/runtime entrypoints;
+   behavior tests; active Spec/TaskIntent; current `CONTEXT.md`/ADR/
+   reference/README; Solution/Brainstorm/archive. Repository facts are evidence
+   for classification, not a reason to copy discoverable context into
+   instructions.
+
+5. **Apply the four-part persistent-rule value gate.** A retained or newly
+   proposed persistent rule must be all of: non-obvious from ordinary
+   repository inspection; plausibly repeatable across later tasks; stable beyond
+   the current task; and costly to violate. Repository overviews, directory
+   listings, technology summaries, discoverable command inventories, vague
+   exhortations, and unconditional broad exploration or testing fail this gate
+   unless the manifest proves they encode a hidden behavioral constraint.
+
+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.
+
+7. **Produce one exact manifest.** `audit` mode stops after the manifest.
+   Mutation mode also stops until the literal user approves exact manifest
+   entries (for example, "all recommendations except 4 and 7"). Broad approval
+   such as "clean AGENTS.md" is insufficient. Interruption starts a fresh scan;
+   no manifest is persisted. No fixed line, byte, percentage, or Token target
+   authorizes removal.
+
+8. **Revalidate and mutate minimally.** Re-read candidate bytes, Git status,
+   content hash, references, precedence evidence, and active scope immediately
+   before each approved change. Drift blocks that item. Never execute commands
+   copied from instruction files. Never alter ordinary documentation, install
+   project contracts, commit, or mutate Managed authority. Necessary hard
+   guardrails, security constraints, data-loss prevention, accessibility
+   basics, and explicit user requirements are never simplified away for
+   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
+   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`,
+   `Moved to pointer`, `Kept`, `Blocked`, `Unverified`, `Verification`, and
+   before/after line and byte counts. Do not translate byte changes into Token
+   or task-success claims.
+
+## Mutation Envelope
+
+This Skill may modify only approved agent instruction files. It must stop when
+completion requires creating a new reference document, changing ordinary docs,
+runtime behavior, business-test semantics, package exports, public API,
+credentials, network writes, Git history rewriting, project-contract
+installation or continuous validation, automatic rule learning, or any Managed
+authority mutation.
+
+A failed focused check leaves an inspectable diff and stops; this Skill does
+not stash, reset, checkout, or revert user work.
+
+## Non-goals
+
+- User-level and external instruction files are never inventoried or modified.
+- Runtime still does not install or continuously validate project-level
+  `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `IMMUNE.md`, or `CONTEXT.md`
+  contracts.
+- No daemon, telemetry, automatic learning, persistent report, or automatic
+  commit.
+- No 200-line, Token, or success-rate target.
+- `imm-doc-prune` remains able to remove evidence-proven stale
+  agent-instruction content; the two Skills never invoke each other.

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

@@ -14,7 +14,7 @@ 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` and `imm-doc-prune` are host-native and are never dispatched as the Loop role.
+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.
 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

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

@@ -140,56 +140,65 @@ 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 and its immutable slug before the first remote mutation.
-Surface that name, slug, and the proposed Parent/Child creation together as soon
-as decomposition establishes multiple TaskIntents. Recommend one answer so the
-user may adopt the complete current decision frontier in bulk. A prior bulk
-approval cannot confirm a name or slug that had not yet been shown.
-Resolve `../bin/imm-tracker` from this packaged contract; do not assume a bare
-command is on `PATH`. After the first TaskIntent has been authored, staged, and
-validated with `valid: true` and `enrollment_ready: true`, and both the named
-Initiative and its immutable slug are confirmed, attempt the GitHub projection
-before returning the final Planner result or invoking Enrollment: call
-`imm-tracker create-initiative --stdin --json` once with the confirmed goal,
-stable Slice summaries, and the public Parent projection fields. `create-initiative`
-receives the stable Initiative goal and Slice summaries plus the public Parent
-projection fields `problem`, `result`, `decisions`, `testing_strategy`, and
-`out_of_scope`. It creates a result-oriented Parent title
-`[<initiative>] <result>` and never rewrites an existing Parent.
-
-Then call
-`imm-tracker upsert-task --initiative-id <slug> --slice-id <id> --intent <path> --projection-json <json> --json`
-to create one neutral open Child Issue and attach it to the Parent as a native
-Sub-issue. The projection JSON is public planning context only and may contain
-`result`, `current_behavior`, `desired_behavior`, `key_interfaces`,
-`verification`, `blocked_by` Task IDs, `out_of_scope`, and `agent_handoff`.
-The tracker rereads the canonical TaskIntent for identity, risk, and acceptance;
-projection fields never widen TaskIntent scope or authority. The Child title is
-`[<initiative>/<slice>] <result>` with no `IB:` prefix or Task ID. Its body is an
-Agent Brief with Parent, What to build, Current behavior, Desired behavior, Key
-interfaces, Acceptance criteria, Verification, Blocked by, Out of scope, Agent
-handoff, and Authority boundary sections. Native `blocked_by` relations are
-created only for exact marker-owned Task Issues and are idempotently observed.
+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 packaged contract; do not assume a bare command is on `PATH`. Submit the entire approved set once through
+`imm-tracker publish-initiative --stdin --json`. Its input contains the confirmed
+Initiative slug and goal, Parent projection, and every Child's `slice_id`,
+canonical TaskIntent path, 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, the tracker fails with a
-carrier conflict; Local mode performs zero GitHub operations. A future Slice remains a parent checklist entry until its own TaskIntent is
-canonically authored and validated.
+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 both
-operations return `created`, `updated`, or `already_current`;
-`awaiting_user_initiative_confirmation` with the single pending Initiative
-name-and-slug decision; or `tracker_projection_failed` with the returned failure
-and exact retry action.
-A candidate Initiative name or slug 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 retry action, but
-do not block planning, Enrollment, execution, QA, Review, settlement, or another
-association. 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 later one-way
-projection updates to that same Initiative; they never grant execution authority.
+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
 

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

@@ -47,3 +47,12 @@ skills:
     output_artifacts: [prune_report]
     next_actions: []
     boundary: Prune stale current documentation after explicit manifest approval; no Managed authority mutation or authority-artifact deletion.
+  - name: imm-agent-doc-maintain
+    path: skills/imm-agent-doc-maintain/SKILL.md
+    role: execute
+    title: Agent Doc Maintain
+    role_class: repair
+    canonical: true
+    output_artifacts: [maintain_report]
+    next_actions: []
+    boundary: Minimize tracked agent-instruction context after explicit manifest approval; no Managed authority mutation, contract installation, or reference-document creation.