@zhushanwen/pi-plan 0.4.4 → 0.4.6

package/README.md

@@ -0,0 +1,37 @@
+# @zhushanwen/pi-plan
+
+轻量级规划模式 pi extension：`/plan [描述]` 触发，产出结构化 plan 文件。与 coding-workflow 的区别：无 gate / review / retrospect，只负责「想清楚再动手」的计划产出（ADR pi-ext-021 prompt-only readonly / pi-ext-022 session-manager state）。
+
+> 本 README 的核心概念词条（Plan Mode / Plan File / Brainstorming）迁自 `docs/extensions/glossary.md`「Extension 专属概念」（2026-09-13）。
+
+## 用法
+
+```
+/plan 修复项目中所有失败的测试   # 进入 plan mode（brainstorming 阶段开始）
+/plan status                    # 查看当前阶段与 plan 文件路径
+/plan abort                     # 取消活跃的 plan mode
+```
+
+## 阶段状态机
+
+`idle → brainstorming → writing → complete`（`state.ts` PlanPhase）：
+
+- **brainstorming**：需求探索。固定四步——1. Quick Overview（ls 项目根 / 读 README / package.json，30 秒内建立上下文）→ 2. 渐进式提问澄清需求 → 3. 方案探索 → 4. 假设审计。
+- **writing**：选定模板后撰写 plan 文件。
+- **complete**：完成时提示选择执行方式，恢复工具，状态重置。
+
+## plan 工具
+
+模型经 `plan` tool 驱动阶段流转，actions：`list-template` / `select-template` / `create-template` / `complete` / `complete-cancelled` / `abort`。
+
+## Plan File
+
+Plan Mode 的产出物，存储在 `.xyz-harness/{slug}/plan.md`（slug 截断 30 字符）。含 YAML frontmatter 与模板章节。进入 plan mode 时自动扫描既有 plan 文件供续写。
+
+## 模板
+
+内置 5 个（`templates/`）：`feature-plan` / `bugfix-plan` / `refactor-plan` / `implementation-plan` / `research-plan`。支持项目自定义模板（`listTemplates` / `loadTemplate` 按 projectDir 发现）。
+
+## 依赖
+
+peer 依赖 `@zhushanwen/pi-goal`（plan 完成后衔接 goal 驱动执行）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-plan",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "Lightweight plan mode for Pi coding agent",
   "type": "module",
   "main": "index.ts",
@@ -21,11 +21,14 @@
     "@earendil-works/pi-coding-agent": ">=0.73.0",
     "typebox": "*",
     "@earendil-works/pi-ai": "^0.84.4",
-    "@zhushanwen/pi-goal": "0.14.0"
+    "@zhushanwen/pi-goal": "0.14.2"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-ai": {
       "optional": true
+    },
+    "@zhushanwen/pi-goal": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -38,7 +41,8 @@
     "templates/"
   ],
   "dependencies": {
-    "@zhushanwen/pi-ext-guards": "0.3.0",
+    "@xyz-agent/extension-protocol": "0.11.0",
+    "@zhushanwen/pi-ext-guards": "0.4.0",
     "@zhushanwen/pi-extension-logger": "0.6.0"
   },
   "scripts": {

package/src/__tests__/command.test.ts

@@ -128,10 +128,12 @@ describe("registerPlanCommand", () => {
     expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan"]);
     expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.stringContaining("[PLAN MODE]"));
     expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.stringContaining("Implement User Auth"));
-    expect(pi.appendEntry).toHaveBeenCalledWith("plan-state", expect.objectContaining({
+    expect(pi.appendEntry).toHaveBeenCalledWith("plan-state", {
       isActive: true,
-      phase: "brainstorming",
-    }));
+      planFilePath: "/tmp/test-project/.xyz-harness/implement-user-auth/plan.md",
+      requirement: "Implement User Auth",
+      templateName: "",
+    });
   });
 
   it("handles special characters in requirement for slug", async () => {
@@ -158,8 +160,13 @@ describe("registerPlanCommand", () => {
     vi.clearAllMocks();
 
     await handler("", ctx);
+    // D6：phase 删除后 status 显示 plan 文件与模板，无档位行
     expect((ctx as ReturnType<typeof createMocks>["ctx"]).ui.notify).toHaveBeenCalledWith(
-      expect.stringContaining("brainstorming"),
+      expect.stringContaining("my-feature/plan.md"),
+      "info",
+    );
+    expect((ctx as ReturnType<typeof createMocks>["ctx"]).ui.notify).toHaveBeenCalledWith(
+      expect.stringContaining("Template: (not selected)"),
       "info",
     );
   });

package/src/__tests__/compact-criteria-array.test.ts

@@ -5,7 +5,7 @@
  * + 前 3 条 step preview（编号前缀、单条截断 ≤80 chars），合计 ≤4 条
  * （goal schema maxItems:8），每条单行不含 \r\n（goal handler 拒含换行条目）。
  */
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 vi.mock("node:fs", () => ({
   readFileSync: vi.fn(),
@@ -42,7 +42,6 @@ function makeCtx() {
 function makeActiveState() {
   return {
     isActive: true,
-    phase: "complete" as const,
     planFilePath: "/tmp/plan.md",
     requirement: "Add login page",
     templateName: "default",
@@ -130,19 +129,30 @@ describe("buildPlanSuccessCriteria — 1 总述 + 前 3 条 preview", () => {
 
 // --- handlePlanComplete → tryGoalInit 端到端 ---
 
-describe("handlePlanComplete — __goalInit 第 5 参数为新形态 string[]", () => {
+/**
+ * goal 桥 slot key——与 compact.ts / goal 侧 index.ts 的字符串一致（本地声明，
+ * 不 import 对方包：pi-goal 是 optional peer）。mock 挂 slot 与真实通道同构。
+ */
+const GOAL_INIT_SLOT_KEY = Symbol.for("@zhushanwen/pi-goal.goalInit");
+
+describe("handlePlanComplete — goalInit slot 第 5 参数为新形态 string[]", () => {
   let pi: ReturnType<typeof makePi>;
   let ctx: ReturnType<typeof makeCtx>;
+  let goalInitMock: ReturnType<typeof vi.fn>;
 
   beforeEach(() => {
     vi.clearAllMocks();
     pi = makePi();
     ctx = makeCtx();
-    (pi as unknown as Record<string, unknown>).__goalInit = vi.fn().mockReturnValue(true);
+    goalInitMock = vi.fn().mockReturnValue(true);
+    Reflect.set(globalThis, GOAL_INIT_SLOT_KEY, goalInitMock);
+  });
+
+  afterEach(() => {
+    Reflect.set(globalThis, GOAL_INIT_SLOT_KEY, undefined);
   });
 
   function getCriteriaArg(): string[] {
-    const goalInitMock = (pi as unknown as Record<string, unknown>).__goalInit as ReturnType<typeof vi.fn>;
     expect(goalInitMock).toHaveBeenCalled();
     return expectSingleLineArray(goalInitMock.mock.calls[0][4]);
   }
@@ -150,7 +160,7 @@ describe("handlePlanComplete — __goalInit 第 5 参数为新形态 string[]",
   it("direct isolation: 3 步 plan → 总述 + 3 条 preview", () => {
     fsMock.readFileSync.mockReturnValue(makePlanContent(["Step A", "Step B", "Step C"]));
 
-    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct");
+    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "goal");
 
     expect(getCriteriaArg()).toEqual([
       "All 3 steps of plan executed and verified",
@@ -160,10 +170,10 @@ describe("handlePlanComplete — __goalInit 第 5 参数为新形态 string[]",
     ]);
   });
 
-  it("compact isolation: onComplete 后 __goalInit 收到同形态数组", () => {
+  it("compact isolation: onComplete 后 goalInit 收到同形态数组", () => {
     fsMock.readFileSync.mockReturnValue(makePlanContent(["Step one", "Step two"]));
 
-    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "compact");
+    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "compact", "goal");
     ctx._onCompleteFns[0]();
 
     expect(getCriteriaArg()).toEqual([
@@ -177,7 +187,7 @@ describe("handlePlanComplete — __goalInit 第 5 参数为新形态 string[]",
     const steps = Array.from({ length: 12 }, (_, i) => `Step ${i + 1}`);
     fsMock.readFileSync.mockReturnValue(makePlanContent(steps));
 
-    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct");
+    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "goal");
 
     const items = getCriteriaArg();
     expect(items).toHaveLength(4);
@@ -188,7 +198,7 @@ describe("handlePlanComplete — __goalInit 第 5 参数为新形态 string[]",
   it("CRLF plan 文件 → 每条 criteria 仍单行不含 \\r \\n", () => {
     fsMock.readFileSync.mockReturnValue("## 实现步骤\r\n1. Step one\r\n2. Step two\r\n3. Step three");
 
-    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct");
+    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "goal");
 
     expect(getCriteriaArg()).toEqual([
       "All 3 steps of plan executed and verified",
@@ -198,12 +208,11 @@ describe("handlePlanComplete — __goalInit 第 5 参数为新形态 string[]",
     ]);
   });
 
-  it("0 步 plan → tryGoalInit 提前退出，__goalInit 不被调用", () => {
+  it("0 步 plan → tryGoalInit 提前退出，goalInit 不被调用", () => {
     (fsMock.readFileSync as ReturnType<typeof vi.fn>).mockReturnValue("## Overview\nNo numbered steps here.");
 
-    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct");
+    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "goal");
 
-    const goalInitMock = (pi as unknown as Record<string, unknown>).__goalInit as ReturnType<typeof vi.fn>;
     expect(goalInitMock).not.toHaveBeenCalled();
     // steer 仍发出（执行流程不因 goal 缺席中断）
     expect(pi.sendUserMessage).toHaveBeenCalled();

package/src/__tests__/compact-handler.test.ts

@@ -1,4 +1,4 @@
-import { beforeEach,describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { PlanState } from "../state.js";
 
@@ -42,7 +42,6 @@ function makeCtx() {
 function makeActiveState(): PlanState {
   return {
     isActive: true,
-    phase: "complete",
     planFilePath: "/tmp/plan.md",
     requirement: "Add login page",
     templateName: "default",
@@ -53,6 +52,30 @@ function setupFsMock(content: string) {
   fsMock.readFileSync.mockReturnValue(content);
 }
 
+/**
+ * goal 桥 slot key——与 compact.ts / goal 侧 index.ts 的字符串一致（本地声明，
+ * 不 import 对方包：pi-goal 是 optional peer，两侧靠同一字符串共享 slot）。
+ */
+const GOAL_INIT_SLOT_KEY = Symbol.for("@zhushanwen/pi-goal.goalInit");
+
+/** 在 globalThis slot 上挂 goal 桥——mock 形态与真实通道同构（goal-bridge-cross-extension.md §3.4：goal 侧 Reflect.set 挂 slot，本测试同款挂载）。 */
+function attachGoalInit(impl: () => boolean) {
+  const fn = vi.fn(impl);
+  Reflect.set(globalThis, GOAL_INIT_SLOT_KEY, fn);
+  return fn;
+}
+
+/** 清 slot 防跨用例 globalThis 泄漏（设计 §3.4：teardown 两侧通用）。 */
+afterEach(() => {
+  Reflect.set(globalThis, GOAL_INIT_SLOT_KEY, undefined);
+});
+
+/** 最近一次 steer 消息正文。 */
+function lastSteer(pi: ReturnType<typeof makePi>): string {
+  const calls = (pi.sendUserMessage as ReturnType<typeof vi.fn>).mock.calls;
+  return String(calls[calls.length - 1]?.[0]);
+}
+
 // --- handlePlanComplete tests ---
 
 describe("handlePlanComplete", () => {
@@ -66,61 +89,148 @@ describe("handlePlanComplete", () => {
     setupFsMock("## 实现步骤\n1. Step one\n2. Step two");
   });
 
-  it("compact isolation: calls compact, onComplete sends steer + tryGoalInit", () => {
-    (pi as unknown as Record<string, unknown>).__goalInit = vi.fn().mockReturnValue(true);
-
-    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "compact");
-
-    expect(ctx.compact).toHaveBeenCalledOnce();
-    ctx._onCompleteFns[0]();
-    expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.any(String), { deliverAs: "steer" });
-    expect((pi as unknown as Record<string, unknown>).__goalInit).toHaveBeenCalledWith(
-      expect.any(String),
-      undefined,
-      ctx,
-      "plan",
-      [
-        "All 2 steps of plan executed and verified",
-        "1. Step one",
-        "2. Step two",
-      ],
-    );
+  describe("compact isolation", () => {
+    it("goal mode: goalInit deferred to onComplete, then goal steer on success (D2 时序——goal entry 在压缩后世界创建)", () => {
+      const goalInit = attachGoalInit(() => true);
+
+      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "compact", "goal");
+
+      expect(outcome).toBeUndefined(); // compact 档 outcome 在回调内产生，不进同步返回值
+      expect(ctx.compact).toHaveBeenCalledOnce();
+      expect(goalInit).not.toHaveBeenCalled(); // 压缩完成前不创建 goal entry
+
+      ctx._onCompleteFns[0]();
+
+      expect(goalInit).toHaveBeenCalledWith(
+        "Execute plan: /tmp/plan.md",
+        undefined,
+        ctx,
+        "plan",
+        [
+          "All 2 steps of plan executed and verified",
+          "1. Step one",
+          "2. Step two",
+        ],
+      );
+      expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.stringContaining("Execute via /goal"), { deliverAs: "steer" });
+      expect(ctx.ui.notify).not.toHaveBeenCalled();
+    });
+
+    it("non-goal mode: onComplete sends mode steer without calling goalInit", () => {
+      const goalInit = attachGoalInit(() => true);
+
+      handlePlanComplete(pi as never, ctx as never, makeActiveState(), "compact", "subagent");
+      ctx._onCompleteFns[0]();
+
+      expect(goalInit).not.toHaveBeenCalled();
+      expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.stringContaining("subagent-driven"), { deliverAs: "steer" });
+    });
+
+    it("onError (goal mode, init-refused): compact-failure notify + degraded steer + warning notify, no /goal promise", () => {
+      attachGoalInit(() => false); // goalInit 返回 false：已有 active goal
+
+      handlePlanComplete(pi as never, ctx as never, makeActiveState(), "compact", "goal");
+      ctx._onErrorFns[0](new Error("compact failed"));
+
+      const notifyTexts = (ctx.ui.notify as ReturnType<typeof vi.fn>).mock.calls.map((c) => String(c[0]));
+      expect(notifyTexts.some((t) => t.includes("Compact failed"))).toBe(true);
+      expect(notifyTexts.some((t) => t.includes("init-refused"))).toBe(true);
+
+      const steer = lastSteer(pi);
+      expect(steer).toContain("Goal execution was not started (init-refused)");
+      expect(steer).toContain("/goal clear"); // 恢复动作
+      expect(steer).not.toContain("Execute via /goal"); // 承诺不再无凭据发出
+    });
   });
 
-  it("compact onError: falls back to notify + steer", () => {
-    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "compact");
+  describe("direct isolation", () => {
+    it("goal mode success: returns outcome synchronously, goal steer, no notify", () => {
+      attachGoalInit(() => true);
 
-    ctx._onErrorFns[0](new Error("compact failed"));
-    expect(ctx.ui.notify).toHaveBeenCalledWith(expect.any(String), "warning");
-    expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.any(String), { deliverAs: "steer" });
-  });
+      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "goal");
 
-  it("tree isolation: only notify, no compact or steer", () => {
-    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "tree");
+      expect(outcome).toEqual({ started: true });
+      expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.stringContaining("Execute via /goal"), { deliverAs: "steer" });
+      expect(ctx.compact).not.toHaveBeenCalled();
+      expect(ctx.ui.notify).not.toHaveBeenCalled();
+    });
 
-    expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("/tmp/plan.md"), "info");
-    expect(ctx.compact).not.toHaveBeenCalled();
-    expect(pi.sendUserMessage).not.toHaveBeenCalled();
+    it("non-goal mode: returns undefined, mode steer, no goalInit call", () => {
+      const goalInit = attachGoalInit(() => true);
+
+      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "single-agent");
+
+      expect(outcome).toBeUndefined();
+      expect(goalInit).not.toHaveBeenCalled();
+      expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.stringContaining("step by step"), { deliverAs: "steer" });
+      expect(ctx.compact).not.toHaveBeenCalled();
+    });
+
+    it("unknown isolation value falls through to direct delivery instead of silently dropping the choice (D1 防御形态)", () => {
+      attachGoalInit(() => true);
+
+      handlePlanComplete(pi as never, ctx as never, makeActiveState(), "tree", "goal");
+
+      expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.stringContaining("Execute via /goal"), { deliverAs: "steer" });
+      expect(ctx.compact).not.toHaveBeenCalled();
+      expect(ctx.ui.notify).not.toHaveBeenCalledWith(expect.stringContaining("/tree"), "info");
+    });
   });
 
-  it("direct isolation: directly sends steer", () => {
-    (pi as unknown as Record<string, unknown>).__goalInit = vi.fn().mockReturnValue(true);
-    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct");
-
-    expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.any(String), { deliverAs: "steer" });
-    expect(ctx.compact).not.toHaveBeenCalled();
-    expect(ctx.ui.notify).not.toHaveBeenCalled();
-    expect((pi as unknown as Record<string, unknown>).__goalInit).toHaveBeenCalledWith(
-      expect.any(String),
-      undefined,
-      ctx,
-      "plan",
-      [
-        "All 2 steps of plan executed and verified",
-        "1. Step one",
-        "2. Step two",
-      ],
-    );
+  // goal 桥五个失败出口 → GoalBridgeOutcome 五值（D2）
+  describe("tryGoalInit failure exits (goal mode, direct isolation)", () => {
+    it("goal-unavailable: bridge not mounted → degraded steer + warning notify", () => {
+      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "goal");
+
+      expect(outcome).toEqual({ started: false, reason: "goal-unavailable" });
+      const steer = lastSteer(pi);
+      expect(steer).toContain("Goal execution was not started (goal-unavailable)");
+      expect(steer).not.toContain("Execute via /goal");
+      expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("goal-unavailable"), "warning");
+    });
+
+    it("plan-unreadable: plan file read fails → recovery points at the plan file", () => {
+      attachGoalInit(() => true);
+      fsMock.readFileSync.mockImplementation(() => { throw new Error("ENOENT: plan.md"); });
+
+      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "goal");
+
+      expect(outcome).toEqual({ started: false, reason: "plan-unreadable" });
+      expect(lastSteer(pi)).toContain("Check that the plan file exists");
+      expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("plan-unreadable"), "warning");
+    });
+
+    it("no-steps: plan content has no extractable steps", () => {
+      attachGoalInit(() => true);
+      setupFsMock("# Plan\n\nProse without any numbered list.");
+
+      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "goal");
+
+      expect(outcome).toEqual({ started: false, reason: "no-steps" });
+      expect(lastSteer(pi)).toContain("Implementation Steps");
+      expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("no-steps"), "warning");
+    });
+
+    it("init-refused: goalInit returns false (active goal exists)", () => {
+      attachGoalInit(() => false);
+
+      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "goal");
+
+      expect(outcome).toEqual({ started: false, reason: "init-refused" });
+      expect(lastSteer(pi)).toContain("/goal clear");
+      expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("init-refused"), "warning");
+    });
+
+    it("internal-error: goalInit throws → outcome carries detail, notify includes it, does not propagate", () => {
+      attachGoalInit(() => { throw new Error("goalInit exploded"); });
+
+      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "goal");
+
+      expect(outcome).toEqual({ started: false, reason: "internal-error", detail: "goalInit exploded" });
+      expect(lastSteer(pi)).toContain("Goal execution was not started (internal-error)");
+      expect(lastSteer(pi)).not.toContain("Execute via /goal");
+      expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("goalInit exploded"), "warning");
+    });
   });
 });
 

package/src/__tests__/state.test.ts

@@ -5,7 +5,6 @@ import {
   DEFAULT_PLAN_STATE,
   getPlanState,
   persistPlanState,
-  type PlanPhase,
   type PlanSessionMap,
   type PlanState,
   reconstructPlanState,
@@ -14,20 +13,14 @@ import {
 describe("PlanState", () => {
   it("DEFAULT_PLAN_STATE has correct defaults", () => {
     expect(DEFAULT_PLAN_STATE.isActive).toBe(false);
-    expect(DEFAULT_PLAN_STATE.phase).toBe("idle");
     expect(DEFAULT_PLAN_STATE.planFilePath).toBe("");
     expect(DEFAULT_PLAN_STATE.requirement).toBe("");
     expect(DEFAULT_PLAN_STATE.templateName).toBe("");
   });
 
-  it("PlanPhase type includes all required phases", () => {
-    const phases: PlanPhase[] = ["idle", "brainstorming", "writing", "complete"];
-    expect(phases).toHaveLength(4);
-  });
-
   it("getPlanState returns cached state if exists", () => {
     const sessions: PlanSessionMap = new Map();
-    const cached: PlanState = { ...DEFAULT_PLAN_STATE, isActive: true, phase: "brainstorming" };
+    const cached: PlanState = { ...DEFAULT_PLAN_STATE, isActive: true };
     sessions.set("session-1", cached);
 
     const mockCtx = {
@@ -54,17 +47,15 @@ describe("PlanState", () => {
 
     const result = getPlanState(sessions, "session-2", mockCtx);
     expect(result.isActive).toBe(true);
-    expect(result.phase).toBe("writing");
     expect(sessions.get("session-2")).toBe(result);
   });
 });
 
 describe("State persistence", () => {
-  it("persistPlanState calls appendEntry with correct data", () => {
+  it("persistPlanState calls appendEntry with correct data (no phase field — D6)", () => {
     const mockPi = { appendEntry: vi.fn() } as unknown as ExtensionAPI;
     const state: PlanState = {
       isActive: true,
-      phase: "brainstorming",
       planFilePath: ".xyz-harness/test/plan.md",
       requirement: "test requirement",
       templateName: "feature-plan",
@@ -72,9 +63,9 @@ describe("State persistence", () => {
 
     persistPlanState(mockPi, state);
 
+    // 精确匹配：新写的 plan-state entry 无 phase 字段（V5② 守卫）
     expect(mockPi.appendEntry).toHaveBeenCalledWith("plan-state", {
       isActive: true,
-      phase: "brainstorming",
       planFilePath: ".xyz-harness/test/plan.md",
       requirement: "test requirement",
       templateName: "feature-plan",
@@ -111,7 +102,34 @@ describe("State persistence", () => {
 
     const state = reconstructPlanState(mockCtx);
     expect(state.isActive).toBe(true);
-    expect(state.phase).toBe("writing");
     expect(state.planFilePath).toBe(".xyz-harness/test/plan.md");
   });
+
+  it("reconstructPlanState ignores the legacy phase field in old entries (D6 兼容读 — V5②)", () => {
+    // 旧版（含 phase）写的 entry：重开后 plan mode 重建正常，phase 被白名单式读取自然忽略
+    const mockCtx = {
+      sessionManager: {
+        getEntries: () => [
+          {
+            type: "custom",
+            customType: "plan-state",
+            data: {
+              isActive: true,
+              phase: "brainstorming",
+              planFilePath: ".xyz-harness/legacy/plan.md",
+              requirement: "legacy",
+              templateName: "feature-plan",
+            },
+          },
+        ],
+      },
+    } as unknown as ExtensionContext;
+
+    const state = reconstructPlanState(mockCtx);
+    expect(Object.keys(state).sort()).toEqual(["isActive", "planFilePath", "requirement", "templateName"]);
+    expect(state.isActive).toBe(true);
+    expect(state.planFilePath).toBe(".xyz-harness/legacy/plan.md");
+    expect(state.requirement).toBe("legacy");
+    expect(state.templateName).toBe("feature-plan");
+  });
 });

package/src/__tests__/templates.test.ts

@@ -1,21 +1,26 @@
 import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
 
 import { describe, expect, it } from "vitest";
 
+import { extractPlanSteps } from "../compact.js";
 import { getBuiltinTemplateDir, listTemplates, loadTemplate } from "../templates.js";
 
-describe("Template system", () => {
-  it("listTemplates returns builtin templates", () => {
+const BUILTIN_TEMPLATE_NAMES = [
+  "feature-plan",
+  "bugfix-plan",
+  "refactor-plan",
+  "research-plan",
+  "implementation-plan",
+];
+
+describe("Template system (builtin single source, D3)", () => {
+  it("listTemplates returns exactly the 5 builtin templates with no source field", () => {
     const templates = listTemplates();
-    expect(templates.length).toBeGreaterThanOrEqual(5);
-    const names = templates.map((t) => t.name);
-    expect(names).toContain("feature-plan");
-    expect(names).toContain("bugfix-plan");
-    expect(names).toContain("refactor-plan");
-    expect(names).toContain("research-plan");
-    expect(names).toContain("implementation-plan");
+    expect(templates.map((t) => t.name).sort()).toEqual([...BUILTIN_TEMPLATE_NAMES].sort());
+    // 单源化后 TemplateInfo 只有 name/path —— source 等多源残留字段即红
+    for (const t of templates) {
+      expect(t).toEqual({ name: t.name, path: t.path });
+    }
   });
 
   it("loadTemplate returns content for existing builtin template", () => {
@@ -33,28 +38,23 @@ describe("Template system", () => {
     const dir = getBuiltinTemplateDir();
     expect(fs.existsSync(dir)).toBe(true);
   });
+});
 
-  it("TC8: PI_CODING_AGENT_DIR 隔离目录下扫到全局模板（getAgentDir 派生，不依赖 ~/.pi/agent）", () => {
-    const origEnv = process.env.PI_CODING_AGENT_DIR;
-    const isolated = fs.mkdtempSync(path.join(os.tmpdir(), "plan-tpl-"));
-    try {
-      process.env.PI_CODING_AGENT_DIR = isolated;
-      fs.mkdirSync(path.join(isolated, "plan-templates"), { recursive: true });
-      fs.writeFileSync(path.join(isolated, "plan-templates", "isolated-template.md"), "# t");
-
-      const templates = listTemplates();
-      const names = templates.map((t) => t.name);
-      expect(names).toContain("isolated-template");
-      // 隔离目录模板 source 为 global（getAgentDir 直接返回 PI_CODING_AGENT_DIR 值，无 .pi/agent 嵌套）
-      const tpl = templates.find((t) => t.name === "isolated-template");
-      expect(tpl?.source).toBe("global");
-      expect(tpl?.path.startsWith(isolated)).toBe(true);
-      // 仍能扫到 builtin 模板（最低优先级）
-      expect(names).toContain("feature-plan");
-    } finally {
-      if (origEnv === undefined) delete process.env.PI_CODING_AGENT_DIR;
-      else process.env.PI_CODING_AGENT_DIR = origEnv;
-      fs.rmSync(isolated, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
-    }
+describe("template ↔ extractPlanSteps alignment guard (D4)", () => {
+  // 守卫对象：模板生成端的步骤节标题与解析端正则同仓同测，漂移即红——
+  // ① 模板标题改名 → 恰一节断言失败；
+  // ② 解析正则与标题脱节 → 提取退化到 fallback 收进其他节的噪音项 → toEqual 失败。
+  it.each(BUILTIN_TEMPLATE_NAMES)("template '%s' has exactly one '## Implementation Steps' section that extractPlanSteps consumes", (name) => {
+    const content = loadTemplate(name);
+    expect(content).not.toBeNull();
+
+    expect(content!.match(/^## Implementation Steps$/gm)).toHaveLength(1);
+
+    const plan = content!
+      // 在第一个非步骤节标题后放噪音编号项（模拟 Requirements 等节含编号列表）
+      .replace(/^(## (?!Implementation Steps).+)$/m, "$1\n1. noise-from-other-section")
+      // 在步骤节标题后填编号步骤（模拟 AI 按模板写 plan.md）
+      .replace(/^## Implementation Steps$/m, "## Implementation Steps\n1. Real step A\n2. Real step B");
+    expect(extractPlanSteps(plan)).toEqual(["Real step A", "Real step B"]);
   });
 });