immune-brain 5.1.2 → 5.2.0

package/README.md

@@ -28,7 +28,7 @@ Pi and Claude Code are the supported hosts. Undeclared adapters remain unsupport
 - [Recommended Workflows: Composing with mattpocock/skills](#recommended-workflows-composing-with-mattpocockskills)
 - [Real-World Case Studies](#real-world-case-studies)
 - [Core Philosophy: Turn "Judgment" into "Table Lookup"](#core-philosophy-turn-judgment-into-table-lookup-harnessing-multi-model-tiers-with-determinism)
-- [The 7 Skills](#the-7-skills)
+- [The 8 Skills](#the-8-skills)
 - [Lifecycle](#lifecycle)
 - [Unattended Batch Runs](#unattended-batch-runs)
 - [Configuration](#configuration)
@@ -54,7 +54,7 @@ Pi discovers Skills and extensions from `package.json` (or your global Pi config
 }
 ```
 
-No extra server config is needed. Installing the package via Pi makes all 7 Skills available automatically.
+No extra server config is needed. Installing the package via Pi makes all 8 Skills available automatically.
 
 ### In Claude Code
 
@@ -123,6 +123,7 @@ Immune-Brain provides two clean modes: **Host-native** for daily coding, and **M
 | PR has review comments or failing CI | `/imm-pr-fix` on that PR | → Standalone repair: minimal scoped fix in place, no managed task created |
 | Project docs out of date | `/imm-doc-prune` | → Read-only audit; deletes only user-approved stale docs from manifest |
 | Agent instructions bloated | `/imm-doc-slim` | → Minimizes tracked `AGENTS.md` / `CLAUDE.md` to essential non-discoverable rules |
+| Test suite bloated with redundant cases | `/imm-test-prune` | → Audits tests read-only, then merges or deletes only approved entries backed by retirement or coverage evidence |
 | Which model's edits keep coming back for review | `/imm-retro` | → Ranks models by review load and reports project usage from session logs |
 
 > **Core Principle: Skill-Explicit Entry**
@@ -412,7 +413,7 @@ Without explicit cost levers, multi-agent workflows compound expenses exponentia
 
 ---
 
-## The 7 Skills
+## The 8 Skills
 
 | Skill | Type | When to use | What it does |
 |---|---|---|---|
@@ -422,11 +423,12 @@ Without explicit cost levers, multi-agent workflows compound expenses exponentia
 | `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-doc-slim` | Standalone | Bloated agent instructions | Minimizes tracked AGENTS/CLAUDE/GEMINI.md to necessary context |
+| `imm-test-prune` | Standalone | Bloated or redundant tests | Merges, parameterizes, or deletes approved test entries without weakening assertions |
 | `imm-retro` | Standalone | Compare models by review load | Ranks authors of reviewed code and reports project usage |
 
 Internal roles (Executor, QA, Review, Compounder) are dispatched by `imm-run` — you never invoke them directly.
 
-All 7 skills are invoked explicitly. For new features, start with `imm-brainstorm` (if requirements are uncertain) or `imm-planner` (if requirements are clear), then proceed to `imm-run` once enrolled.
+All 8 skills are invoked explicitly. For new features, start with `imm-brainstorm` (if requirements are uncertain) or `imm-planner` (if requirements are clear), then proceed to `imm-run` once enrolled.
 
 ### Managed Path entries (brainstorm → planner → loop)
 
@@ -474,6 +476,11 @@ The three repair/maintenance skills are host-native: they never create a managed
 - **Trigger:** explicit request to minimize tracked `AGENTS.md` / `CLAUDE.md` / `GEMINI.md`.
 - **What it does:** keeps only the necessary non-discoverable rules in agent instruction files, under the same read-only-audit + hash-bound-manifest-approval model as `imm-doc-prune`.
 
+#### `imm-test-prune` — test suite pruning
+
+- **Trigger:** explicit request to audit or prune redundant, bloated, or orphaned tests.
+- **What it does:** inventories tests with the repository's own test and coverage commands, then merges, parameterizes, or deletes only entries you approved in an exact hash-bound manifest. Deletion needs retirement proof or coverage-backed subsumption; without coverage tooling those entries stay unverified. It never weakens an assertion or touches production source.
+
 #### `imm-retro` — review load and project usage
 
 - **Trigger:** explicit request for a cross-model review retro or project usage look-back.
@@ -652,7 +659,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/                           # 7 public Skills (trigger shims)
+├── skills/                           # 8 public Skills (trigger shims)
 ├── dist/                             # Built skill contracts & references
 ├── runtime/                          # Bun + TypeScript runtime & Kernel
 └── bin/                              # CLI wrappers (→ runtime/v4_runtime.ts)
@@ -670,7 +677,7 @@ docs/specs/                           # Living specs (updated in place)
 
 ## FAQ
 
-**Do I need to learn all 7 skills?** No. Most of the time you only need `/imm-planner` (to plan and enroll a task) and `/imm-run` (to build and verify it). Use `imm-brainstorm` when requirements need clarifying first, and the maintenance skills (`imm-pr-fix`, etc.) only when specific repair needs arise. Ordinary chat and simple edits don't need any skills at all.
+**Do I need to learn all 8 skills?** No. Most of the time you only need `/imm-planner` (to plan and enroll a task) and `/imm-run` (to build and verify it). Use `imm-brainstorm` when requirements need clarifying first, and the maintenance skills (`imm-pr-fix`, etc.) only when specific repair needs arise. Ordinary chat and simple edits don't need any skills at all.
 
 **What if I interrupt or close the session mid-task?** State is safely stored on disk (`.imm/` + TaskIntent). In Pi or Claude Code, simply re-enter `/imm-run` to resume — the Kernel projection is authoritative.
 

package/README.zh-CN.md

@@ -28,7 +28,7 @@ Pi 与 Claude Code 是支持的宿主。未声明的适配器仍不受支持。C
 - [推荐工作流：与 mattpocock/skills 组合使用](#推荐工作流与-mattpocockskills-组合使用)
 - [实战案例](#实战案例)
 - [核心设计哲学：把“判断”变成“查表”](#核心设计哲学把判断变成查表用确定性工程驾驭多模型)
-- [7 个 Skills](#7-个-skills)
+- [8 个 Skills](#8-个-skills)
 - [生命周期](#生命周期)
 - [无人值守批次运行](#无人值守批次运行)
 - [配置](#配置)
@@ -54,7 +54,7 @@ Pi 通过 `package.json`（或全局 Pi 配置）自动发现 Skills 与扩展
 }
 ```
 
-无需额外 server 配置，通过 Pi 安装本 package 后 7 个 Skill 即自动可用。
+无需额外 server 配置，通过 Pi 安装本 package 后 8 个 Skill 即自动可用。
 
 ### 在 Claude Code 中使用
 
@@ -123,6 +123,7 @@ Immune-Brain 提供两种清晰的工作模式：日常轻量编码走 **Host-na
 | PR 被评论 / CI 挂了 | 对该 PR 使用 `/imm-pr-fix` | → 独立修复：在当前 PR 内针对性修复，不创建新 managed 任务 |
 | 文档过时需要清理 | `/imm-doc-prune` | → 只读审计过时文档，仅删除经哈希审批的条目 |
 | Agent 指令文件膨胀 | `/imm-doc-slim` | → 将 tracked `AGENTS.md` / `CLAUDE.md` 压到最小必要上下文 |
+| 测试用例膨胀、重复 | `/imm-test-prune` | → 只读审计测试，仅合并或删除经审批、有退休或覆盖率证据的条目 |
 | 想知道哪个模型的改动总被审查 | `/imm-retro` | → 按模型排名审查负载，并从 session logs 汇报项目使用量 |
 
 > **核心原则：Skill 显式调用**
@@ -415,7 +416,7 @@ Immune-Brain 的核心假设是：**不要让弱模型做架构决策，把它
 
 ---
 
-## 7 个 Skills
+## 8 个 Skills
 
 | Skill | 类型 | 何时使用 | 职责 |
 |---|---|---|---|
@@ -425,11 +426,12 @@ Immune-Brain 的核心假设是：**不要让弱模型做架构决策，把它
 | `imm-pr-fix` | 独立 | PR 需修复 | 原地修复单个 PR，不触及 managed authority |
 | `imm-doc-prune` | 独立 | 清理过时文档 | 仅删除哈希绑定的 manifest 条目 |
 | `imm-doc-slim` | 独立 | Agent instruction 膨胀 | 将 tracked AGENTS/CLAUDE/GEMINI.md 压到最小必要上下文 |
+| `imm-test-prune` | 独立 | 测试膨胀或重复 | 合并、参数化或删除经审批的测试条目，不弱化断言 |
 | `imm-retro` | 独立 | 比较模型的审查负载 | 排名被审查代码的作者并汇报项目使用量 |
 
 Executor、QA、Review、Compounder 等为 `imm-run` 内部调度的角色，无需手动调用。
 
-所有 7 个 Skill 均显式调用。新需求开发时：若需求含糊先调 `imm-brainstorm`，目标清晰直接调 `imm-planner`，完成确认后调 `imm-run` 推进闭环。
+所有 8 个 Skill 均显式调用。新需求开发时：若需求含糊先调 `imm-brainstorm`，目标清晰直接调 `imm-planner`，完成确认后调 `imm-run` 推进闭环。
 
 ### Managed Path 入口（brainstorm → planner → loop）
 
@@ -477,6 +479,11 @@ Executor、QA、Review、Compounder 等为 `imm-run` 内部调度的角色，无
 - **触发方式：** 显式要求精简版本控制下的 `AGENTS.md` / `CLAUDE.md` / `GEMINI.md`。
 - **职责：** 遵循与 `imm-doc-prune` 相同的「只读审计 + 哈希清单审批」模式，仅保留无法直接推导的必要规则。
 
+#### `imm-test-prune` — 测试套件瘦身
+
+- **触发方式：** 显式要求审计或清理冗余、膨胀或孤立的测试。
+- **职责：** 使用仓库自身的测试与覆盖率命令盘点测试，按用户明确审批的哈希绑定 manifest 合并、参数化或删除条目。删除需要行为退休证明或覆盖率支撑的包含关系；项目没有覆盖率工具时这类条目保持 unverified。从不弱化断言，也不修改生产代码。
+
 #### `imm-retro` — 审查负载与项目使用回顾
 
 - **触发方式：** 显式要求跨模型审查复盘或项目使用量回顾。
@@ -660,7 +667,7 @@ Immune-Brain **没有独立配置文件**，偏好设置写在仓库根目录下
 package.json                          # Pi package manifest（skills + extensions）
 plugins/immune-brain/
 ├── .pi-extension/                    # Pi TUI + Kernel 扩展
-├── skills/                           # 7 个公开 Skills（触发 shim）
+├── skills/                           # 8 个公开 Skills（触发 shim）
 ├── dist/                             # 构建后的 skill 契约与参考文档
 ├── runtime/                          # Bun + TypeScript 运行时与 Kernel
 └── bin/                              # CLI wrappers（→ runtime/v4_runtime.ts）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "immune-brain",
-  "version": "5.1.2",
+  "version": "5.2.0",
   "description": "Immune-Brain agent skill system",
   "publishConfig": {
     "access": "public",

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

@@ -1,6 +1,6 @@
 {
   "name": "immune-brain",
-  "version": "5.1.2",
+  "version": "5.2.0",
   "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

@@ -26,7 +26,7 @@ import {
 	enrollmentGitBaseNotice,
 	initializeEnrollmentGitBase,
 } from "../runtime/assurance/enrollment_git_base";
-import { readTaskIntentForRecord } from "./imm-canary-work";
+import { piRunEntryRefusal, readTaskIntentForRecord } from "./imm-canary-work";
 import {
 	presentTaskRail,
 	presentTaskRailResult,
@@ -609,7 +609,7 @@ export default function (pi: ExtensionAPI) {
 		description: "Run one exact Kernel new-task enrollment synchronously in the foreground with host cancellation before authority commit.",
 		promptSnippet: "Kernel enrollment: invoke once in foreground and consume the direct terminal result.",
 		promptGuidelines: [
-			"Call from the Parent after natural-language routing selects Enrollment; execute once in the foreground and consume the terminal Tool result.",
+			"Call from the Parent only as the first step of an explicit imm-run entry, never from imm-planner or imm-brainstorm; execute once in the foreground and consume the terminal Tool result.",
 			"Do not run this Tool in background, poll for completion, or issue a cancel subcommand; host cancellation is the only pre-commit cancellation path.",
 		],
 		parameters: Type.Object(
@@ -647,6 +647,18 @@ export default function (pi: ExtensionAPI) {
 					message: "imm_canary_enrollment is TUI-only",
 					next_action: "invoke the TUI launcher",
 				});
+			// The phase entry gate (ADR 0019), before any preparation or dialog.
+			const entryRefusal = piRunEntryRefusal("enroll", ctx);
+			if (entryRefusal)
+				throwToolFailure({
+					tool: "imm_canary_enrollment",
+					task_id: taskId,
+					operation: action,
+					state: "blocked",
+					code: entryRefusal.reason_code,
+					message: entryRefusal.detail,
+					next_action: entryRefusal.recovery_action,
+				});
 			const authorityRegistry = await registry();
 			const result = await coordinator.run(action, taskId, signal, (foregroundSignal, beginCommit) =>
 				executeForegroundEnrollment(

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

@@ -21,6 +21,7 @@ import type { ConfirmationReferenceSource } from "../runtime/assurance/host_port
 import { execFileSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
@@ -35,6 +36,7 @@ import {
 	writeNativeReviewEvidence,
 } from "./pi-canary-review-bundle";
 import type { InvocationToken } from "./pi-canary-invocations";
+import { readAliasFile } from "../runtime/assurance/alias_file";
 import { runDeterministicQa } from "../runtime/assurance/qa";
 import {
 	captureStagedIntent,
@@ -132,6 +134,15 @@ import {
 import { reviewReworkFindings } from "../runtime/assurance/coordinator";
 import { laneWriteRefusal } from "../runtime/unattended/lane_workspace";
 import { activeTaskNotice } from "../runtime/assurance/active_task_notice";
+import {
+	admitPhaseOperation,
+	applyPrompt,
+	NO_PHASE_ENTRY,
+	recognizePhaseEntry,
+	type AliasReader,
+	type PhaseAdmission,
+	type PhaseEntryState,
+} from "../runtime/assurance/phase_entry";
 
 const LOOP_OWNERS = ["plan", "kernel", "brainstorm", "planner", "loop"] as const;
 const LOOP_TARGETS = [
@@ -287,6 +298,67 @@ export async function advancePiTask(root: string, taskId: string): Promise<any>
 	return { state: "failed", reason: (result as { reason?: string }).reason ?? "advance failed", ...facts };
 }
 
+const GLOBAL_PI_PHASE_ENTRY_KEY = Symbol.for("immune_brain.pi_phase_entry");
+
+type PhaseEntryContext = { cwd?: string; sessionManager?: { getSessionId?: () => unknown } } | undefined;
+
+// Pi loads each extension file as its own module graph, so the entry state
+// lives under a global key that every copy of this module shares. It is
+// process memory: a resumed session starts without an entry and refuses.
+function piPhaseEntries(): Map<string, PhaseEntryState> {
+	const holder = globalThis as unknown as Record<symbol, Map<string, PhaseEntryState> | undefined>;
+	return holder[GLOBAL_PI_PHASE_ENTRY_KEY] ??= new Map();
+}
+
+function piSessionId(ctx: PhaseEntryContext): string {
+	try {
+		const id = ctx?.sessionManager?.getSessionId?.();
+		return typeof id === "string" ? id : "";
+	} catch {
+		return "";
+	}
+}
+
+/** Prompt templates in the order Pi resolves them: the user's, then the project's. */
+function piAliasReader(cwd: string): AliasReader {
+	const agentDir = process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+	return (name) => {
+		for (const dir of [join(agentDir, "prompts"), join(cwd, ".pi", "prompts")]) {
+			const body = readAliasFile(join(dir, `${name}.md`));
+			if (body !== null) return body;
+		}
+		return null;
+	};
+}
+
+/**
+ * One Host input: record whether this literal prompt entered a phase. Input an
+ * extension injected is never the user's and leaves the entry state untouched.
+ */
+export function recordPiPhaseInput(event: { text?: unknown; source?: unknown }, ctx: PhaseEntryContext): void {
+	if (event.source === "extension") return;
+	const sessionId = piSessionId(ctx);
+	if (!sessionId) return;
+	const entries = piPhaseEntries();
+	const text = typeof event.text === "string" ? event.text : "";
+	const entry = recognizePhaseEntry(text, piAliasReader(ctx?.cwd ?? process.cwd()));
+	entries.set(sessionId, applyPrompt(entries.get(sessionId) ?? NO_PHASE_ENTRY, entry));
+}
+
+/**
+ * The phase entry gate for a Pi tool, checked before any preparation or
+ * authority dialog. A session without an identity refuses.
+ */
+export function piRunEntryRefusal(
+	operation: "enroll" | "start_unattended_batch",
+	ctx: PhaseEntryContext,
+): Extract<PhaseAdmission, { ok: false }> | null {
+	const sessionId = piSessionId(ctx);
+	const state = sessionId ? piPhaseEntries().get(sessionId) ?? NO_PHASE_ENTRY : null;
+	const admission = admitPhaseOperation({ kind: "tool", name: operation }, state, { activeClaim: false });
+	return admission.ok ? null : admission;
+}
+
 export default function (
 	pi: ExtensionAPI,
 	dependencies: CanaryWorkExtensionDependencies = {},
@@ -342,6 +414,7 @@ export default function (
 	});
 	pi.on("input", async (event, ctx) => {
 		if (event.source === "extension") return { action: "continue" } as const;
+		recordPiPhaseInput(event, ctx);
 		railContext = ctx;
 		clearTerminalTaskRailOnInput(ctx);
 		await refreshTaskRail(ctx);

package/plugins/immune-brain/.pi-extension/imm-unattended-batch.ts

@@ -20,7 +20,7 @@ import {
 import { createBatchKernelPort } from "../runtime/unattended/batch_kernel_port";
 import type { BatchRunnerGitPort } from "../runtime/unattended/batch_git";
 import type { InitiativeObservationReader } from "../runtime/unattended/types";
-import { advancePiTask } from "./imm-canary-work";
+import { advancePiTask, piRunEntryRefusal } from "./imm-canary-work";
 import { batchReason } from "../runtime/unattended/batch_reasons";
 import { parseFinalVerification } from "../runtime/unattended/batch_final_verification";
 import { parseLaneRevision, REVISION_DELEGATION_TEXT, type LaneRevisionRequest } from "../runtime/unattended/batch_delegation";
@@ -427,7 +427,7 @@ export default function (
 		description: "Start an unattended serial batch run for an Initiative after native confirmation.",
 		promptSnippet: "Start unattended batch run: invoke once in foreground after plan confirmation.",
 		promptGuidelines: [
-			"Call only after plan confirmation; execute once in the foreground and consume the direct terminal result.",
+			"Call only inside an explicit imm-run entry, after plan confirmation; execute once in the foreground and consume the direct terminal result.",
 			"Do not run this Tool in background, poll for completion, or issue a cancel subcommand.",
 		],
 		parameters: Type.Object({
@@ -469,6 +469,19 @@ export default function (
 					next_action: refusal.recovery_action,
 				});
 			}
+			// The phase entry gate (ADR 0019), before any preflight or dialog. The
+			// batch's own reuseOnly continuation never passes through this Tool.
+			const entryRefusal = piRunEntryRefusal("start_unattended_batch", ctx);
+			if (entryRefusal)
+				throwToolFailure({
+					tool: "imm_canary_enrollment",
+					task_id: initiativeSlug,
+					operation: "start_unattended_batch",
+					state: "blocked",
+					code: entryRefusal.reason_code,
+					message: entryRefusal.detail,
+					next_action: entryRefusal.recovery_action,
+				});
 
 			const maxParallel = parseMaxParallel(params.max_parallel);
 			const laneOffers = parseLaneOffers(params.lane_offers);

package/plugins/immune-brain/agents/immune-brain-reviewer.md

@@ -32,6 +32,11 @@ material task-local maintenance risks. Pure naming, length, complexity
 thresholds, formatting, and design preference are not findings and must not
 cause style-only rework.
 
+Test-suite growth is advisory, never blocking: note a delivered test that
+duplicates an existing assertion, asserts only private implementation, or
+leaves a test protecting behavior the change retired. Weakened or missing
+tests for an acceptance remain blocking under the rules above.
+
 When a finding repeats an acceptance id or anchor that already produced rework in
 this task, do not file it as a fresh single-trigger defect. Name the invariant
 class it belongs to and state in `evidence.trigger` why the previously accepted

package/plugins/immune-brain/dist/BASELINE.md

@@ -108,7 +108,7 @@ An existing grant for one of these never inherits another: a stage-only
 instruction stays stage-only, a commit is not push or publication authority,
 and a valid batch capability commits only its own scope-bounded child.
 
-Routine Managed enrollment uses one current-Host native confirmation bound to the TaskIntent content hash after Planner validation. Explicit Plan-only requests stop with candidate artifacts and do not invoke Enrollment; execution-bearing requests open the native gate directly without chat pre-confirmation. Enrollment validates intent, Git ownership, scope, workspace claim, and final authority preconditions without executing acceptance descriptors; deterministic QA executes them after implementation. The routine task proceeds from that single confirmation through enrollment, execution, and QA without a second human stop. Do not request confirmation for local in-scope edits, local verification, ordinary Direct rework, scoped diff review, or completion reporting. Managed evidence, QA, Review, and completion authority remain governed by their Managed contracts; R2 does not weaken them. Managed native-authority failures fail closed with one stable reason and exactly one same-Host recovery action; never offer a Pi, Direct Path, cross-Host/worktree, unmanaged, or automatic-retry fallback.
+Routine Managed enrollment is the first step of an explicit `imm-run` entry and uses one current-Host native confirmation bound to the TaskIntent content hash after Planner validation. Planner and Brainstorm stop with candidate artifacts and never invoke Enrollment, whether or not the request also asks for execution; explicit Plan-only requests stop the same way. `imm-run` opens the native gate directly without chat pre-confirmation. Enrollment validates intent, Git ownership, scope, workspace claim, and final authority preconditions without executing acceptance descriptors; deterministic QA executes them after implementation. Once the user has entered `imm-run`, the routine task proceeds from that single confirmation through enrollment, execution, and QA with no further confirmation. Do not request confirmation for local in-scope edits, local verification, ordinary Direct rework, scoped diff review, or completion reporting. Managed evidence, QA, Review, and completion authority remain governed by their Managed contracts; R2 does not weaken them. Managed native-authority failures fail closed with one stable reason and exactly one same-Host recovery action; never offer a Pi, Direct Path, cross-Host/worktree, unmanaged, or automatic-retry fallback.
 
 For an unborn symbolic Git HEAD, the same Enrollment confirmation discloses an empty root commit. After approval, the Host creates that commit without staging project content or changing the index/worktree, then revalidates ownership and rehearses Enrollment against the new base. Git identity uses existing environment/config values with an explicit automation fallback, never config writes. Decline or pre-initialization cancellation leaves HEAD unborn; if later Enrollment fails or is cancelled, report the remaining commit. Invalid Git refs are errors, not initialization candidates.