# Master Agent Evolution Engine Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 给 Boss 主Agent 增加一套统一的自动进化引擎，并支持 `controlled` 与 `autonomous` 两种模式以及双分支交付。

**Architecture:** 在现有 `boss-data` 与 `boss-master-agent` 上新增 evolution state、engine 和 API。共享内核一次实现，分支差异只保留在默认模式与自动采纳开关上，避免维护两份逻辑。

**Tech Stack:** Next.js 16、TypeScript、文件型状态存储、Node test runner

---

### Task 1: 增加 Evolution 状态模型与持久化

**Files:**
- Modify: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/src/lib/boss-data.ts`
- Test: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/tests/master-agent-evolution-state.test.ts`

- [ ] **Step 1: 写失败测试，定义 evolution state 的默认结构与读写**

```ts
test("boss state 初始化时包含 master agent evolution 默认配置与空集合", async () => {
  const state = await readState();
  assert.deepEqual(state.masterAgentEvolutionConfig?.mode, "controlled");
  assert.deepEqual(state.masterAgentEvolutionSignals, []);
  assert.deepEqual(state.masterAgentEvolutionProposals, []);
  assert.deepEqual(state.masterAgentEvolutionRules, []);
  assert.deepEqual(state.masterAgentEvolutionRunLogs, []);
});
```

- [ ] **Step 2: 运行测试，确认当前失败**

Run: `npx tsx --test tests/master-agent-evolution-state.test.ts`
Expected: FAIL，提示缺少 `masterAgentEvolution*` 字段或断言不匹配

- [ ] **Step 3: 在 `boss-data.ts` 中新增类型和默认状态**

```ts
export type MasterAgentEvolutionMode = "controlled" | "autonomous";

export interface MasterAgentEvolutionConfig {
  mode: MasterAgentEvolutionMode;
  autoApplyLowRiskRules: boolean;
  updatedAt: string;
}
```

- [ ] **Step 4: 扩展 `BossState`、normalize 逻辑和默认初始值**

Run: `npx tsx --test tests/master-agent-evolution-state.test.ts`
Expected: PASS

- [ ] **Step 5: 提交**

```bash
git add src/lib/boss-data.ts tests/master-agent-evolution-state.test.ts
git commit -m "feat: add master agent evolution state"
```

### Task 2: 实现 Evolution Engine 核心

**Files:**
- Create: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/src/lib/master-agent-evolution.ts`
- Test: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/tests/master-agent-evolution-engine.test.ts`

- [ ] **Step 1: 写失败测试，覆盖 signal -> proposal 的最小闭环**

```ts
test("recording repeated deterministic questions creates a fast_path_rule proposal", async () => {
  await recordMasterAgentEvolutionSignal({
    kind: "repeated_question",
    projectId: "master-agent",
    account: "17600003315",
    content: "当前主节点在线吗",
  });
  const proposals = await listMasterAgentEvolutionProposals();
  assert.equal(proposals[0]?.proposalType, "fast_path_rule");
});
```

- [ ] **Step 2: 运行测试，确认失败**

Run: `npx tsx --test tests/master-agent-evolution-engine.test.ts`
Expected: FAIL，提示函数或 proposal 类型不存在

- [ ] **Step 3: 实现最小 engine API**

```ts
export async function recordMasterAgentEvolutionSignal(...) {}
export async function listMasterAgentEvolutionProposals(...) {}
export async function applyMasterAgentEvolutionProposal(...) {}
```

- [ ] **Step 4: 实现第一批 proposal 生成规则**

规则最小集：
- repeated deterministic questions -> `fast_path_rule`
- repeated backend/model corrections -> `routing_preference_patch`
- repeated user preference statements -> `memory_patch`

- [ ] **Step 5: 运行测试确认通过**

Run: `npx tsx --test tests/master-agent-evolution-engine.test.ts`
Expected: PASS

- [ ] **Step 6: 提交**

```bash
git add src/lib/master-agent-evolution.ts tests/master-agent-evolution-engine.test.ts
git commit -m "feat: add master agent evolution engine"
```

### Task 3: 把 Evolution Engine 挂到主Agent主链

**Files:**
- Modify: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/src/lib/boss-master-agent.ts`
- Test: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/tests/master-agent-evolution-integration.test.ts`

- [ ] **Step 1: 写失败测试，验证快路径未命中后会记录 signal**

```ts
test("master agent slow deterministic query records evolution signal when fast path misses", async () => {
  await replyToMasterAgentUserMessage({
    requestText: "当前线程是不是正在运行",
    requestedBy: "Boss 超级管理员",
    requestedByAccount: "17600003315",
    mode: "enqueue",
  });
  const signals = await listMasterAgentEvolutionSignals();
  assert.ok(signals.some((item) => item.kind === "fast_path_candidate"));
});
```

- [ ] **Step 2: 运行测试，确认失败**

Run: `npx tsx --test tests/master-agent-evolution-integration.test.ts`
Expected: FAIL

- [ ] **Step 3: 在 `replyToMasterAgentUserMessage()` 和相关成功/失败路径中记录 signal**

最小挂载点：
- Fast Path 命中
- Fast Path 未命中但命中确定性查询模式
- 后端 fallback
- 用户手动切模型/切后端/切接管

- [ ] **Step 4: 运行测试确认通过**

Run: `npx tsx --test tests/master-agent-evolution-integration.test.ts`
Expected: PASS

- [ ] **Step 5: 提交**

```bash
git add src/lib/boss-master-agent.ts tests/master-agent-evolution-integration.test.ts
git commit -m "feat: integrate evolution engine into master agent"
```

### Task 4: 实现 Evolution API

**Files:**
- Create: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/src/app/api/v1/master-agent/evolution/route.ts`
- Create: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/src/app/api/v1/master-agent/evolution/config/route.ts`
- Create: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/src/app/api/v1/master-agent/evolution/proposals/[proposalId]/approve/route.ts`
- Create: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/src/app/api/v1/master-agent/evolution/proposals/[proposalId]/reject/route.ts`
- Test: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/tests/master-agent-evolution-routes.test.ts`

- [ ] **Step 1: 写失败测试，定义 GET/POST contract**

```ts
test("GET /api/v1/master-agent/evolution returns config proposals and rules", async () => {
  const response = await GET(request);
  const payload = await response.json();
  assert.equal(payload.ok, true);
  assert.ok(Array.isArray(payload.proposals));
});
```

- [ ] **Step 2: 运行测试，确认失败**

Run: `npx tsx --test tests/master-agent-evolution-routes.test.ts`
Expected: FAIL

- [ ] **Step 3: 实现读接口和 config 切换接口**

- [ ] **Step 4: 实现 approve / reject 接口**

- [ ] **Step 5: 运行测试确认通过**

Run: `npx tsx --test tests/master-agent-evolution-routes.test.ts`
Expected: PASS

- [ ] **Step 6: 提交**

```bash
git add src/app/api/v1/master-agent/evolution src/app/api/v1/master-agent/evolution/config src/app/api/v1/master-agent/evolution/proposals tests/master-agent-evolution-routes.test.ts
git commit -m "feat: add master agent evolution routes"
```

### Task 5: 加入 Controlled / Autonomous 自动采纳分界

**Files:**
- Modify: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/src/lib/master-agent-evolution.ts`
- Test: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/tests/master-agent-evolution-autonomous.test.ts`

- [ ] **Step 1: 写失败测试，验证 controlled 不自动采纳、autonomous 可自动采纳低风险 proposal**

```ts
test("controlled mode keeps proposal pending_review", async () => {
  await setMasterAgentEvolutionMode("controlled");
  // record signal...
  assert.equal(proposals[0]?.status, "pending_review");
});

test("autonomous mode auto applies low risk routing preference patch", async () => {
  await setMasterAgentEvolutionMode("autonomous");
  // record signal...
  assert.equal(proposals[0]?.status, "auto_applied");
});
```

- [ ] **Step 2: 运行测试，确认失败**

Run: `npx tsx --test tests/master-agent-evolution-autonomous.test.ts`
Expected: FAIL

- [ ] **Step 3: 实现 mode gating 与低风险自动采纳白名单**

白名单：
- `memory_patch`
- `routing_preference_patch`
- `fast_path_rule`

黑名单：
- 管理员全局主提示词修改
- 高风险提示词覆盖

- [ ] **Step 4: 运行测试确认通过**

Run: `npx tsx --test tests/master-agent-evolution-autonomous.test.ts`
Expected: PASS

- [ ] **Step 5: 提交**

```bash
git add src/lib/master-agent-evolution.ts tests/master-agent-evolution-autonomous.test.ts
git commit -m "feat: add controlled and autonomous evolution modes"
```

### Task 6: 更新交接文档并切双分支

**Files:**
- Modify: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/docs/architecture/ai_handoff_index_cn.md`
- Modify: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/docs/architecture/current_runtime_and_deploy_status_cn.md`
- Modify: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/docs/superpowers/specs/2026-04-16-master-agent-evolution-engine-design.md`

- [ ] **Step 1: 文档中加入 evolution engine 与两种模式说明**

- [ ] **Step 2: 运行组合验证**

Run: `npx tsx --test tests/master-agent-evolution*.test.ts tests/master-agent-message-queue.test.ts tests/master-agent-chat-controls.test.ts`
Expected: PASS

Run: `npm run build`
Expected: PASS

- [ ] **Step 3: 提交共享内核**

```bash
git add docs/architecture/ai_handoff_index_cn.md docs/architecture/current_runtime_and_deploy_status_cn.md docs/superpowers/specs/2026-04-16-master-agent-evolution-engine-design.md
git commit -m "docs: document master agent evolution engine"
```

- [ ] **Step 4: 创建 controlled 分支并推送**

```bash
git branch codex/master-agent-controlled-evolution
git push gitea codex/master-agent-controlled-evolution
```

- [ ] **Step 5: 创建 autonomous 分支，在其上把默认 mode 切到 autonomous 并推送**

```bash
git checkout -b codex/master-agent-autonomous-evolution
git push gitea codex/master-agent-autonomous-evolution
```