immune-brain 2.8.2

package/README.md

@@ -0,0 +1,239 @@
+# Immune-Brain
+
+> Deterministic workflow & quality engine for [Pi](https://github.com/badlogic/pi) — turn vague ideas into shipped code with planning, execution, QA, and review.
+
+**Language:** **English** | [中文](./README.zh-CN.md)
+
+---
+
+## What Is This?
+
+Immune-Brain adds a structured engineering workflow on top of Pi:
+
+- **You describe what you want** in natural language — the agent figures out whether to clarify, plan, or execute.
+- **Plans become trackable tasks** (`TaskIntent` + `TaskRecord`) so progress survives across sessions, not just chat history.
+- **Quality is enforced by code, not promises** — automated QA and isolated review must pass before a task is marked done.
+
+Pi remains the only host. It can use any model provider (Anthropic / OpenAI / Google) — Immune-Brain works on top of whichever you configure in Pi.
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [How to Use](#how-to-use)
+- [The 5 Skills](#the-5-skills)
+- [Lifecycle](#lifecycle)
+- [Configuration](#configuration)
+- [Project Layout](#project-layout)
+- [FAQ](#faq)
+- [Development](#development)
+
+---
+
+## Installation
+
+**Prerequisites:** [Pi](https://github.com/badlogic/pi) installed, Node.js 20+, `bun` for tests.
+
+This repo is a Pi package — Pi discovers Skills and extensions from `package.json`:
+
+```json
+// package.json → pi.skills / pi.extensions
+"pi": {
+  "skills": ["./plugins/immune-brain/skills"],
+  "extensions": ["./plugins/immune-brain/.pi-extension"]
+}
+```
+
+No extra server config is needed. Installing the package via Pi makes all 5 Skills available automatically. Verify with:
+
+```bash
+bun test                          # run all tests
+mise run check-plugin              # verify package structure
+mise run check-dist-sync           # verify generated docs are in sync
+```
+
+---
+
+## Quick Start
+
+**1. Describe the change you want** — just talk to Pi in natural language:
+
+> "Add dark mode to the settings page"
+
+Pi routes it automatically: vague requests go to clarification, clear requests go to planning.
+
+**2. Confirm the plan** — Planner writes a `TaskIntent` (scope, risk, acceptance checks). Review it, then confirm enrollment in the TUI dialog (required for all risk levels). No writes happen before you confirm.
+
+**3. Let it run** — `imm-loop` executes the plan, runs QA, and triggers review. Stage your owned files when prompted:
+
+```bash
+git add -- <file-owned-by-task> <another-file>
+```
+
+QA and review run as foreground tools and report back to the host. When the tool returns `phase=done`, the task is complete.
+
+---
+
+## How to Use
+
+You rarely need to remember skill names — **just describe your intent**:
+
+| Your situation | What to say / do | What happens |
+|---|---|---|
+| Idea is fuzzy, needs scoping | "Help me think through a notification system" | → `imm-brainstorm` clarifies questions, no code changes |
+| Goal is clear, needs a plan | "Plan the dark-mode feature" or let Pi route there | → `imm-planner` writes `TaskIntent` + specs in `docs/plans/` |
+| 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 |
+
+> **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
+
+| Skill | Type | When to use | What it does |
+|---|---|---|---|
+| `imm-brainstorm` | Managed entry | Requirements are ambiguous | Frames the problem, surfaces open questions, no code edits |
+| `imm-planner` | Managed entry | Goal is clear | Authors / revises `TaskIntent` and specs; does not enroll or build |
+| `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 |
+
+Internal roles (Executor, QA, Review, Compounder) are dispatched by `imm-loop` — you never invoke them directly.
+
+**Recommended default:** let natural-language routing pick brainstorm vs. planner for you. Explicitly invoke a skill only when you want to force that phase.
+
+---
+
+## Lifecycle
+
+```
+You: natural language request
+        │
+        ├─── vague ──→ imm-brainstorm (clarify, no edits)
+        │
+        └─── clear ──→ imm-planner ──→ TaskIntent (Git-tracked)
+                              │
+                         TUI confirm (enrollment)
+                              │
+                          imm-loop
+                              ├── Executor (edits inside scope)
+                              ├── QA (deterministic checks must pass)
+                              ├── Review (material/critical: isolated subagent)
+                              └── done
+```
+
+Key invariants:
+
+- **One active step at a time**, edits only inside that step's boundary.
+- **Scope (`scope_hint`) is frozen at enrollment** — out-of-scope files are ignored.
+- **Evidence before closure** — QA is the only authority that can close a step.
+- **Advisory never implements**, execution never self-approves.
+
+---
+
+## Configuration
+
+Immune-Brain has **no separate config file**. Preferences live in `AGENTS.md` (repo root or `~/.pi/agent/AGENTS.md`):
+
+```md
+## Immune-Brain Preferences
+
+- Initiative carrier default: github   # or: local
+```
+
+| Preference | Options | Default | Notes |
+|---|---|---|---|
+| Reply language | any natural language | repo `AGENTS.md` | Machine contracts / paths stay literal |
+| Initiative carrier | `local` / `github` | `github` | Only matters when a proposal splits across multiple TaskIntents |
+| Advisory subagents | allowed / solo | allowed | Respects Pi host policy + explicit user instruction |
+
+Precedence: **current message > repo `AGENTS.md` > `~/.pi/agent/AGENTS.md` > skill default**.
+
+See [`docs/reference/immune-brain-config.md`](docs/reference/immune-brain-config.md) for details.
+
+---
+
+## Project Layout
+
+```text
+package.json                          # Pi package manifest (skills + extensions)
+plugins/immune-brain/
+├── .pi-extension/                    # Pi TUI + Kernel authority extension
+├── skills/                           # 5 public Skills (trigger shims)
+├── dist/                             # Built skill contracts & references
+├── runtime/                          # Bun + TypeScript runtime & Kernel
+└── bin/                              # CLI wrappers (→ runtime/v4_runtime.ts)
+
+.imm/                                 # Task state (worktree-local, git-ignored)
+docs/plans/                           # Active TaskIntents (*.intent.json)
+docs/specs/                           # Living specs (updated in place)
+```
+
+- `.imm/state/` — active work; `.imm/audit/<task-id>/` — settled evidence (tracked).
+- `docs/plans/*.intent.json` must be **Git-tracked** before enrollment.
+- `CONTEXT.md` is vocabulary / navigation only — not a runtime state source.
+
+---
+
+## 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.
+
+**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.
+
+**Why does enrollment show a TUI dialog?** All risk levels (`routine`/`material`/`critical`) require explicit confirmation. It binds the staged digest so you see exactly what will be tracked.
+
+**QA failed — what now?** QA returns `rework` or `replan_required`. `imm-loop` routes back to the executor or to `imm-planner` for scope changes. No manual reset needed.
+
+**Can I use it outside Pi?** No — Pi is the only supported host.
+
+---
+
+## Release
+
+This repo uses [Changesets](https://github.com/changesets/changesets) for versioning and publishing.
+
+| 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`) |
+
+**Automated flow (recommended):**
+1. Push changesets to `main` → workflow opens a “Version Packages” PR.
+2. Merge that PR → workflow publishes to npm, creates GitHub Release, and tags `immune-brain-vX.Y.Z`.
+
+Setup: add `NPM_TOKEN` (npm access token with publish permission) to GitHub repo secrets. Workflow is `.github/workflows/release.yml` using `changesets/action@v1`.
+
+**Initial publish (2.8.1):**
+```bash
+npm publish --access public   # one-time, requires npm login / NPM_TOKEN
+# or
+bun run changeset:publish
+```
+The package is scoped `@immune-brain/agent-skills` — `publishConfig.access=public` is already set. After initial publish, all future releases go through changesets.
+
+See `CHANGELOG.md` and `.changeset/config.json` (changelog: `@changesets/changelog-github`, repo: `dereknex/immune-brain`).
+
+---
+
+## Development
+
+For contributors working on Immune-Brain itself:
+
+```bash
+bun test                    # full test suite (canonical check is bun test, not tsc)
+mise run check-plugin       # plugin structure + version
+mise run check-dist-sync    # generated dist docs sync
+```
+
+- Runtime is `runtime/v4_runtime.ts` (Bun + TypeScript). Python under `scripts/` is reference-only.
+- Production CLI: `plugins/immune-brain/bin/imm-kernel` — see [`plugins/immune-brain/README.md`](plugins/immune-brain/README.md) for the full command table.
+
+---
+
+*License: MIT*

package/README.zh-CN.md

@@ -0,0 +1,239 @@
+# Immune-Brain
+
+> 面向 [Pi](https://github.com/badlogic/pi) 的确定性工程工作流与质量保障引擎 — 把模糊想法变成可交付代码，覆盖规划、执行、QA 与审查。
+
+**语言：** [English](./README.md) | **中文**
+
+---
+
+## 这是什么？
+
+Immune-Brain 在 Pi 之上提供结构化的工程工作流：
+
+- **你用自然语言描述需求**，Agent 自动判断是先澄清、先规划，还是直接执行。
+- **计划变为可追踪的任务**（`TaskIntent` + `TaskRecord`），进度落盘持久化，不依赖对话历史。
+- **质量由代码强制保障** — 自动化 QA 与隔离式 Review 必须通过，任务才会完成。
+
+Pi 是唯一支持的宿主，可配置任意模型 Provider（Anthropic / OpenAI / Google），Immune-Brain 在其之上工作。
+
+---
+
+## 目录
+
+- [安装](#安装)
+- [快速开始](#快速开始)
+- [如何使用](#如何使用)
+- [5 个 Skills](#5-个-skills)
+- [生命周期](#生命周期)
+- [配置](#配置)
+- [项目结构](#项目结构)
+- [常见问题](#常见问题)
+- [开发者指南](#开发者指南)
+
+---
+
+## 安装
+
+**前置要求：** 已安装 [Pi](https://github.com/badlogic/pi)、Node.js 20+、`bun`（用于测试）。
+
+本仓库是一个 Pi Package，Pi 通过 `package.json` 自动发现 Skills 与扩展：
+
+```json
+// package.json → pi.skills / pi.extensions
+"pi": {
+  "skills": ["./plugins/immune-brain/skills"],
+  "extensions": ["./plugins/immune-brain/.pi-extension"]
+}
+```
+
+无需额外 server 配置，通过 Pi 安装本 package 后 5 个 Skill 即自动可用。验证：
+
+```bash
+bun test                    # 全量测试
+mise run check-plugin       # 校验插件结构
+mise run check-dist-sync    # 校验生成文档同步
+```
+
+---
+
+## 快速开始
+
+**1. 用自然语言描述你要做的改动：**
+
+> "给设置页加上深色模式"
+
+Pi 会自动路由：需求模糊走澄清，目标明确走规划。
+
+**2. 确认计划** — Planner 会在 `docs/plans/` 生成 `TaskIntent`（范围、风险等级、验收条件）。检查无误后在 TUI 弹窗中确认 Enrollment（所有风险等级都需要确认，确认前零写入）。
+
+**3. 开始执行** — `imm-loop` 按计划执行、跑 QA、触发 Review。按提示暂存任务拥有的文件：
+
+```bash
+git add -- <任务拥有的文件> <另一个文件>
+```
+
+QA 与 Review 以 foreground Tool 形式运行并回传结果，返回 `phase=done` 即完成。
+
+---
+
+## 如何使用
+
+大多数情况下**无需记忆 Skill 名称**，直接描述意图即可：
+
+| 你的情况 | 你说什么 / 做什么 | 会发生什么 |
+|---|---|---|
+| 想法模糊，需要收敛 | "帮我梳理一下通知系统的方案" | → `imm-brainstorm` 提问澄清，不改代码 |
+| 目标明确，需要计划 | "规划一下深色模式功能" 或让 Pi 自动路由 | → `imm-planner` 产出 `TaskIntent` + spec |
+| 计划已确认，准备开干 | "开始构建" / `imm-loop` | → Executor 构建 → QA 验证 → Review 审查 |
+| PR 被评论 / CI 挂了 | 对该 PR 使用 `imm-pr-fix` | → 独立修复，不创建新 managed 任务 |
+| 文档过时需要清理 | `imm-doc-prune` + manifest | → 仅删除已审批的过时文档 |
+
+> **规则：** Managed 工作流（brainstorm → plan → loop）仅由显式的 `imm-brainstorm`、`imm-planner`、`imm-loop` 启动。普通问答、只读解释不会 Enrollment。
+
+---
+
+## 5 个 Skills
+
+| Skill | 类型 | 何时使用 | 职责 |
+|---|---|---|---|
+| `imm-brainstorm` | Managed 入口 | 需求存在实质歧义 | 框架化问题、提出开放问题，不做实现 |
+| `imm-planner` | Managed 入口 | 目标清晰 | 编写/修订 `TaskIntent` 与 spec，不负责 Enrollment 与构建 |
+| `imm-loop` | Managed 协调器 | 计划已验证 | 通过 foreground Tools 协调 执行 → QA → Review → 收尾 |
+| `imm-pr-fix` | 独立 | PR 需修复 | 原地修复单个 PR，不触及 managed authority |
+| `imm-doc-prune` | 独立 | 清理过时文档 | 仅删除哈希绑定的 manifest 条目 |
+
+Executor、QA、Review、Compounder 等为 `imm-loop` 内部调度的角色，无需手动调用。
+
+**推荐默认：** 让自然语言路由自动选择 brainstorm 还是 planner，仅在想强制进入某阶段时才显式调用 Skill。
+
+---
+
+## 生命周期
+
+```
+你：自然语言请求
+        │
+        ├── 模糊 ──→ imm-brainstorm（澄清，不改代码）
+        │
+        └── 明确 ──→ imm-planner ──→ TaskIntent（Git-tracked）
+                              │
+                         TUI 确认（enrollment）
+                              │
+                          imm-loop
+                              ├── Executor（仅在 scope 内编辑）
+                              ├── QA（确定性检查必须通过）
+                              ├── Review（material/critical：隔离 subagent）
+                              └── done
+```
+
+核心不变量：
+
+- **一次仅一个活跃步骤**，编辑仅在步骤边界内。
+- **范围（`scope_hint`）在 enrollment 时冻结**，范围外文件被忽略。
+- **先记录证据再关闭** — 只有 QA 能关闭步骤。
+- **Advisory 不实现，执行不自审。**
+
+---
+
+## 配置
+
+Immune-Brain **没有独立配置文件**，偏好设置写在 `AGENTS.md`（仓库根目录或 `~/.pi/agent/AGENTS.md`）：
+
+```md
+## Immune-Brain Preferences
+
+- Initiative carrier default: github   # 或 local
+```
+
+| 偏好 | 选项 | 默认 | 说明 |
+|---|---|---|---|
+| 回复语言 | 任意自然语言 | 仓库 `AGENTS.md` | 机器契约/路径/标识符保持原文 |
+| Initiative 载体 | `local` / `github` | `github` | 仅当提案拆分为多个 TaskIntent 时生效 |
+| Advisory subagent | 允许 / 单人 | 允许 | 受 Pi host 策略与用户显式指令约束 |
+
+优先级：**当前消息 > 仓库 `AGENTS.md` > `~/.pi/agent/AGENTS.md` > Skill 默认值**。
+
+详见 [`docs/reference/immune-brain-config.md`](docs/reference/immune-brain-config.md)。
+
+---
+
+## 项目结构
+
+```text
+package.json                          # Pi package manifest（skills + extensions）
+plugins/immune-brain/
+├── .pi-extension/                    # Pi TUI + Kernel 扩展
+├── skills/                           # 5 个公开 Skills（触发 shim）
+├── dist/                             # 构建后的 skill 契约与参考文档
+├── runtime/                          # Bun + TypeScript 运行时与 Kernel
+└── bin/                              # CLI wrappers（→ runtime/v4_runtime.ts）
+
+.imm/                                 # 任务状态（worktree-local，git-ignored）
+docs/plans/                           # 活跃 TaskIntents（*.intent.json）
+docs/specs/                           # Living specs（原地更新）
+```
+
+- `.imm/state/` — 活跃任务；`.imm/audit/<task-id>/` — 已结算证据（tracked）。
+- `docs/plans/*.intent.json` 必须在 enrollment 前 **Git-tracked**。
+- `CONTEXT.md` 仅作词汇与导航，不作为运行时状态来源。
+
+---
+
+## 常见问题
+
+**需要记住所有 Skill 吗？** 不需要，直接描述需求即可，Pi 会自动路由。先掌握 `imm-planner` 和 `imm-loop`，另外两个按需使用。
+
+**中途关闭 Pi 会怎样？** 状态已落盘（`.imm/` + TaskIntent），重新进入 `imm-loop` 即可恢复，以 Kernel projection 为准。
+
+**为什么 enrollment 要弹窗确认？** 所有风险等级（`routine`/`material`/`critical`）都需要显式确认，弹窗绑定 staged digest，让你清楚看到将被追踪的内容。
+
+**QA 失败怎么办？** QA 返回 `rework` 或 `replan_required`，`imm-loop` 会自动路由回 Executor 或 `imm-planner` 调整范围，无需手动重置。
+
+**可以在 Pi 之外使用吗？** 不可以，Pi 是唯一支持的宿主。
+
+---
+
+## 发布
+
+本仓库使用 [Changesets](https://github.com/changesets/changesets) 管理版本与发布。
+
+| 任务 | 命令 |
+|------|------|
+| 创建 changeset | `bunx changeset` — 选择 bump 类型（patch/minor/major）并填写说明 |
+| 升级版本 | `bun run changeset:version` — 更新 `package.json` + `CHANGELOG.md` |
+| 本地发布 | `bun run changeset:publish` — 发布到 npm（需 `NPM_TOKEN` 或 `npm login`） |
+
+**自动化流程（推荐）：**
+1. 推送 changeset 到 `main` → workflow 自动创建 “Version Packages” PR。
+2. 合并该 PR → workflow 发布到 npm、创建 GitHub Release，并打 tag `immune-brain-vX.Y.Z`。
+
+配置：在 GitHub 仓库 Secrets 中添加 `NPM_TOKEN`（有发布权限的 npm token）。Workflow 为 `.github/workflows/release.yml`，基于 `changesets/action@v1`。
+
+**首次发布（2.8.1）：**
+```bash
+npm publish --access public   # 首次发布，需 npm login / NPM_TOKEN
+# 或
+bun run changeset:publish
+```
+包名为 scoped `@immune-brain/agent-skills`，已配置 `publishConfig.access=public`。首次发布后，后续所有版本均通过 changesets 管理。
+
+详见 `CHANGELOG.md` 与 `.changeset/config.json`（changelog: `@changesets/changelog-github`，repo: `dereknex/immune-brain`）。
+
+---
+
+## 开发者指南
+
+面向 Immune-Brain 本身的贡献者：
+
+```bash
+bun test                    # 全量测试（以 bun test 为准，非 tsc）
+mise run check-plugin       # 插件结构 + 版本校验
+mise run check-dist-sync    # 生成的 dist 文档同步校验
+```
+
+- 运行时为 `runtime/v4_runtime.ts`（Bun + TypeScript），`scripts/` 下的 Python 仅为历史参考。
+- 生产 CLI：`plugins/immune-brain/bin/imm-kernel`，完整命令表见 [`plugins/immune-brain/README.md`](plugins/immune-brain/README.md)。
+
+---
+
+*License: MIT*

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "immune-brain",
+  "version": "2.8.2",
+  "description": "Immune-Brain agent skill system",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dereknex/immune-brain.git"
+  },
+  "homepage": "https://github.com/dereknex/immune-brain#readme",
+  "bugs": {
+    "url": "https://github.com/dereknex/immune-brain/issues"
+  },
+  "author": "Immune-Brain Team",
+  "license": "MIT",
+  "keywords": [
+    "pi-package"
+  ],
+  "pi": {
+    "skills": [
+      "./plugins/immune-brain/skills"
+    ],
+    "extensions": [
+      "./plugins/immune-brain/.pi-extension"
+    ]
+  },
+  "scripts": {
+    "changeset": "changeset",
+    "changeset:version": "changeset version",
+    "changeset:publish": "changeset publish",
+    "release": "bun run changeset:publish"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.5.2",
+    "@changesets/cli": "^2.29.8",
+    "zod": "^4.1.8"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "imports": {
+    "#kernel/enrollment_authority": "./plugins/immune-brain/runtime/kernel/enrollment_authority.ts",
+    "#kernel/pi_canary_prepare": "./plugins/immune-brain/runtime/kernel/pi_canary_prepare.ts",
+    "#kernel/canary_eligibility": "./plugins/immune-brain/runtime/kernel/canary_eligibility.ts",
+    "#kernel/enrollment": "./plugins/immune-brain/runtime/kernel/enrollment.ts",
+    "#kernel/authority_port": "./plugins/immune-brain/runtime/kernel/authority_port.ts",
+    "#kernel/canary_application": "./plugins/immune-brain/runtime/kernel/canary_application.ts",
+    "#kernel/backend_claim": "./plugins/immune-brain/runtime/kernel/backend_claim.ts",
+    "#kernel/storage": "./plugins/immune-brain/runtime/kernel/storage.ts",
+    "#kernel/intent": "./plugins/immune-brain/runtime/kernel/intent.ts",
+    "#kernel/reducer": "./plugins/immune-brain/runtime/kernel/reducer.ts"
+  },
+  "exports": {
+    ".": "./README.md",
+    "./package.json": "./package.json",
+    "./dist/*": "./plugins/immune-brain/dist/*",
+    "./skills/*": "./plugins/immune-brain/skills/*",
+    "./extensions/*": "./plugins/immune-brain/.pi-extension/*"
+  },
+  "files": [
+    "plugins/immune-brain/.pi-extension",
+    "plugins/immune-brain/runtime/v4_runtime.ts",
+    "plugins/immune-brain/runtime/plan_core.ts",
+    "plugins/immune-brain/runtime/commands/kernel.ts",
+    "plugins/immune-brain/runtime/kernel",
+    "plugins/immune-brain/runtime/canonical_json.ts",
+    "plugins/immune-brain/runtime/workspace_scope.ts",
+    "plugins/immune-brain/runtime/authority_commit_receipts.ts",
+    "plugins/immune-brain/runtime/managed_task_routing_policy.ts",
+    "plugins/immune-brain/runtime/github_issue_tracker.ts",
+    "plugins/immune-brain/runtime/verification_descriptor.ts",
+    "plugins/immune-brain/runtime/role_prompt_bridge.ts",
+    "plugins/immune-brain/runtime/loop_contract.ts",
+    "plugins/immune-brain/runtime/prompts",
+    "plugins/immune-brain/skills",
+    "plugins/immune-brain/dist",
+    "plugins/immune-brain/bin"
+  ]
+}