@zhushanwen/pi-plan 0.4.9 → 0.5.0

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

@@ -12,6 +12,7 @@ vi.mock("node:fs", () => ({
 }));
 
 import { buildPlanSuccessCriteria, handlePlanComplete } from "../compact.js";
+import { PLAN_CONTEXT_CUSTOM_TYPE } from "../state.js";
 
 const fsMock = vi.mocked(await import("node:fs"));
 
@@ -19,7 +20,7 @@ function makePi() {
   return {
     on: vi.fn(),
     appendEntry: vi.fn(),
-    sendUserMessage: vi.fn(),
+    sendMessage: vi.fn(),
   };
 }
 
@@ -160,7 +161,7 @@ describe("handlePlanComplete — goalInit slot 第 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", "goal");
+    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "execute");
 
     expect(getCriteriaArg()).toEqual([
       "All 3 steps of plan executed and verified",
@@ -173,7 +174,7 @@ describe("handlePlanComplete — goalInit slot 第 5 参数为新形态 string[]
   it("compact isolation: onComplete 后 goalInit 收到同形态数组", () => {
     fsMock.readFileSync.mockReturnValue(makePlanContent(["Step one", "Step two"]));
 
-    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "compact", "goal");
+    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "compact", "execute");
     ctx._onCompleteFns[0]();
 
     expect(getCriteriaArg()).toEqual([
@@ -187,7 +188,7 @@ describe("handlePlanComplete — goalInit slot 第 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", "goal");
+    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "execute");
 
     const items = getCriteriaArg();
     expect(items).toHaveLength(4);
@@ -198,7 +199,7 @@ describe("handlePlanComplete — goalInit slot 第 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", "goal");
+    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "execute");
 
     expect(getCriteriaArg()).toEqual([
       "All 3 steps of plan executed and verified",
@@ -211,10 +212,13 @@ describe("handlePlanComplete — goalInit slot 第 5 参数为新形态 string[]
   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", "goal");
+    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "execute");
 
     expect(goalInitMock).not.toHaveBeenCalled();
-    // steer 仍发出（执行流程不因 goal 缺席中断）
-    expect(pi.sendUserMessage).toHaveBeenCalled();
+    // steer 仍发出（执行流程不因 goal 缺席中断）——custom message 三要素 + steer options（A6）
+    expect(pi.sendMessage).toHaveBeenCalledWith(
+      { customType: PLAN_CONTEXT_CUSTOM_TYPE, content: expect.any(String), display: false },
+      { deliverAs: "steer", triggerTurn: true },
+    );
   });
 });

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

@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { PlanState } from "../state.js";
+import { PLAN_CONTEXT_CUSTOM_TYPE } from "../state.js";
 
 // Mock fs before importing compact.ts (ESM namespace is not configurable)
 vi.mock("node:fs", () => ({
@@ -18,7 +19,7 @@ function makePi() {
   return {
     on: vi.fn(),
     appendEntry: vi.fn(),
-    sendUserMessage: vi.fn(),
+    sendMessage: vi.fn(),
   };
 }
 
@@ -70,10 +71,19 @@ afterEach(() => {
   Reflect.set(globalThis, GOAL_INIT_SLOT_KEY, undefined);
 });
 
-/** 最近一次 steer 消息正文。 */
+/** 最近一次 sendMessage 的正文（P8 custom message 的 content 字段）。 */
 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]);
+  const calls = (pi.sendMessage as ReturnType<typeof vi.fn>).mock.calls;
+  const last = calls[calls.length - 1]?.[0] as { content?: string } | undefined;
+  return String(last?.content ?? "");
+}
+
+/** P8 执行通知断言形态：custom message 三要素 + streaming steer options（A6）。 */
+function executionNotice(content: unknown) {
+  return [
+    { customType: PLAN_CONTEXT_CUSTOM_TYPE, content, display: false },
+    { deliverAs: "steer", triggerTurn: true },
+  ];
 }
 
 // --- handlePlanComplete tests ---
@@ -90,10 +100,10 @@ describe("handlePlanComplete", () => {
   });
 
   describe("compact isolation", () => {
-    it("goal mode: goalInit deferred to onComplete, then goal steer on success (D2 时序——goal entry 在压缩后世界创建)", () => {
+    it("execute 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");
+      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "compact", "execute");
 
       expect(outcome).toBeUndefined(); // compact 档 outcome 在回调内产生，不进同步返回值
       expect(ctx.compact).toHaveBeenCalledOnce();
@@ -112,24 +122,39 @@ describe("handlePlanComplete", () => {
           "2. Step two",
         ],
       );
-      expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.stringContaining("Execute via /goal"), { deliverAs: "steer" });
+      expect(pi.sendMessage).toHaveBeenCalledWith(...executionNotice(expect.stringContaining("Goal tracking is active via /goal")));
       expect(ctx.ui.notify).not.toHaveBeenCalled();
     });
 
-    it("non-goal mode: onComplete sends mode steer without calling goalInit", () => {
+    it("execute mode (compact, bridge unmounted): onComplete sends degraded direct-execution steer, no goalInit", () => {
+      // execute 档整合 goal 桥：桥未挂载（goal-unavailable）→ 降级为直接执行指引
+      handlePlanComplete(pi as never, ctx as never, makeActiveState(), "compact", "execute");
+      ctx._onCompleteFns[0]();
+
+      const steer = lastSteer(pi);
+      expect(steer).toContain("Goal tracking was not started (goal-unavailable)");
+      expect(steer).toContain("subagents"); // 降级后仍指到 auto-parallel 直接执行
+      expect(steer).toContain("current session");
+    });
+
+    it("skill mode (compact): onComplete steer carries the skill entry path (D10 skillEntryPath 通路)", () => {
       const goalInit = attachGoalInit(() => true);
+      const skillEntryPath = "/tmp/fixtures/skills/dev-flow/SKILL.md";
 
-      handlePlanComplete(pi as never, ctx as never, makeActiveState(), "compact", "subagent");
+      handlePlanComplete(pi as never, ctx as never, makeActiveState(), "compact", "skill:dev-flow", skillEntryPath);
       ctx._onCompleteFns[0]();
 
       expect(goalInit).not.toHaveBeenCalled();
-      expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.stringContaining("subagent-driven"), { deliverAs: "steer" });
+      const steer = lastSteer(pi);
+      expect(steer).toContain("skill:dev-flow"); // Execution mode 行透传 execMode
+      expect(steer).toContain("dev-flow"); // 指引按名加载
+      expect(steer).toContain("/tmp/fixtures/skills/dev-flow/SKILL.md"); // 路径读取指引（skillEntryPath = 入口文件路径，直接透传）
     });
 
-    it("onError (goal mode, init-refused): compact-failure notify + degraded steer + warning notify, no /goal promise", () => {
+    it("onError (execute 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");
+      handlePlanComplete(pi as never, ctx as never, makeActiveState(), "compact", "execute");
       ctx._onErrorFns[0](new Error("compact failed"));
 
       const notifyTexts = (ctx.ui.notify as ReturnType<typeof vi.fn>).mock.calls.map((c) => String(c[0]));
@@ -137,55 +162,79 @@ describe("handlePlanComplete", () => {
       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 tracking was not started (init-refused)");
       expect(steer).toContain("/goal clear"); // 恢复动作
-      expect(steer).not.toContain("Execute via /goal"); // 承诺不再无凭据发出
+      expect(steer).not.toContain("Goal tracking is active via /goal"); // 承诺不再无凭据发出
     });
   });
 
   describe("direct isolation", () => {
-    it("goal mode success: returns outcome synchronously, goal steer, no notify", () => {
+    it("execute mode success: returns outcome synchronously, goal steer, no notify", () => {
       attachGoalInit(() => true);
 
-      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "goal");
+      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "execute");
 
       expect(outcome).toEqual({ started: true });
-      expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.stringContaining("Execute via /goal"), { deliverAs: "steer" });
+      expect(pi.sendMessage).toHaveBeenCalledWith(...executionNotice(expect.stringContaining("Goal tracking is active via /goal")));
       expect(ctx.compact).not.toHaveBeenCalled();
       expect(ctx.ui.notify).not.toHaveBeenCalled();
     });
 
-    it("non-goal mode: returns undefined, mode steer, no goalInit call", () => {
-      const goalInit = attachGoalInit(() => true);
+    it("skill mode (direct): returns undefined, steer with skill entry path (steer 文案含 skillEntryPath，D10)", () => {
+      attachGoalInit(() => true);
+      const skillEntryPath = "/tmp/fixtures/skills/dev-flow/SKILL.md";
 
-      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "single-agent");
+      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "skill:dev-flow", skillEntryPath);
 
       expect(outcome).toBeUndefined();
-      expect(goalInit).not.toHaveBeenCalled();
-      expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.stringContaining("step by step"), { deliverAs: "steer" });
-      expect(ctx.compact).not.toHaveBeenCalled();
+      const steer = lastSteer(pi);
+      expect(steer).toContain("Execution mode: skill:dev-flow");
+      expect(steer).toContain("/tmp/fixtures/skills/dev-flow/SKILL.md");
+      expect(steer).toContain("follow its workflow");
+    });
+
+    it("skill mode (散 .md 形态): steer carries the file path itself, not a dangling joined SKILL.md", () => {
+      attachGoalInit(() => true);
+      const looseEntryPath = "/tmp/fixtures/skills/loose-tool.md";
+
+      handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "skill:loose-tool", looseEntryPath);
+
+      const steer = lastSteer(pi);
+      expect(steer).toContain("/tmp/fixtures/skills/loose-tool.md"); // 文件路径本身
+      expect(steer).not.toContain("loose-tool.md/SKILL.md"); // 不再拼接 SKILL.md（悬空指引根修）
+      expect(steer).not.toContain("/tmp/fixtures/skills/SKILL.md"); // 旧缺陷形态：散 .md 的 dirname + SKILL.md
+    });
+
+    it("skill mode without skillEntryPath falls back to name-only guidance (防御形态)", () => {
+      attachGoalInit(() => true);
+
+      handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "skill:dev-flow");
+
+      const steer = lastSteer(pi);
+      expect(steer).toContain("load the dev-flow skill");
+      expect(steer).not.toContain("SKILL.md");
     });
 
     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");
+      handlePlanComplete(pi as never, ctx as never, makeActiveState(), "tree", "execute");
 
-      expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.stringContaining("Execute via /goal"), { deliverAs: "steer" });
+      expect(pi.sendMessage).toHaveBeenCalledWith(...executionNotice(expect.stringContaining("Goal tracking is active via /goal")));
       expect(ctx.compact).not.toHaveBeenCalled();
       expect(ctx.ui.notify).not.toHaveBeenCalledWith(expect.stringContaining("/tree"), "info");
     });
   });
 
   // goal 桥五个失败出口 → GoalBridgeOutcome 五值（D2）
-  describe("tryGoalInit failure exits (goal mode, direct isolation)", () => {
+  describe("tryGoalInit failure exits (execute 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");
+      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "execute");
 
       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(steer).toContain("Goal tracking was not started (goal-unavailable)");
+      expect(steer).not.toContain("Goal tracking is active via /goal");
       expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("goal-unavailable"), "warning");
     });
 
@@ -193,7 +242,7 @@ describe("handlePlanComplete", () => {
       attachGoalInit(() => true);
       fsMock.readFileSync.mockImplementation(() => { throw new Error("ENOENT: plan.md"); });
 
-      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "goal");
+      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "execute");
 
       expect(outcome).toEqual({ started: false, reason: "plan-unreadable" });
       expect(lastSteer(pi)).toContain("Check that the plan file exists");
@@ -204,7 +253,7 @@ describe("handlePlanComplete", () => {
       attachGoalInit(() => true);
       setupFsMock("# Plan\n\nProse without any numbered list.");
 
-      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "goal");
+      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "execute");
 
       expect(outcome).toEqual({ started: false, reason: "no-steps" });
       expect(lastSteer(pi)).toContain("Implementation Steps");
@@ -214,7 +263,7 @@ describe("handlePlanComplete", () => {
     it("init-refused: goalInit returns false (active goal exists)", () => {
       attachGoalInit(() => false);
 
-      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "goal");
+      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "execute");
 
       expect(outcome).toEqual({ started: false, reason: "init-refused" });
       expect(lastSteer(pi)).toContain("/goal clear");
@@ -224,11 +273,11 @@ describe("handlePlanComplete", () => {
     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");
+      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct", "execute");
 
       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(lastSteer(pi)).toContain("Goal tracking was not started (internal-error)");
+      expect(lastSteer(pi)).not.toContain("Goal tracking is active via /goal");
       expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("goalInit exploded"), "warning");
     });
   });

package/src/__tests__/enter.test.ts

@@ -0,0 +1,172 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock typebox before importing tool（形态照 tool.test.ts；Type.Array 需在列——enter 的 skills 参数）
+vi.mock("typebox", () => ({
+  Type: {
+    Object: (props: Record<string, unknown>) => ({ type: "object", properties: props }),
+    String: (opts?: Record<string, unknown>) => ({ type: "string", ...opts }),
+    Optional: (schema: unknown) => schema,
+    Array: (item: unknown, opts?: Record<string, unknown>) => ({ type: "array", items: item, ...opts }),
+  },
+  Static: class {},
+}));
+
+vi.mock("@earendil-works/pi-ai", () => ({
+  StringEnum: (values: readonly string[]) => ({ type: "string", enum: [...values] }),
+}));
+
+// Mock node:fs（plan 目录 mkdirSync 不触真实盘——fs-guard 只白名单 tmpdir；command.test.ts 同形态）
+vi.mock("node:fs", () => ({
+  mkdirSync: vi.fn(),
+  readdirSync: vi.fn(() => []),
+  statSync: vi.fn(),
+  existsSync: vi.fn(() => false),
+  readFileSync: vi.fn(() => ""),
+}));
+
+// Mock templates（enter 的 buildPlanModePrompt 走 listTemplates；单测不扫真实模板目录）
+vi.mock("../templates.js", () => ({
+  listTemplates: vi.fn(() => []),
+  loadTemplate: vi.fn(() => null),
+  formatAvailablePlans: vi.fn(() => ""),
+}));
+
+vi.mock("../compact.js", () => ({
+  handlePlanComplete: vi.fn(),
+  detectGoalCapability: vi.fn(() => false),
+  GOAL_FAILURE_RECOVERY: {},
+}));
+
+vi.mock("../exec-skills.js", () => ({
+  detectExecSkills: vi.fn(() => []),
+}));
+
+vi.mock("../widget.js", () => ({
+  updatePlanWidget: vi.fn(),
+}));
+
+import * as fs from "node:fs";
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { registerPlanTool } from "../tool.js";
+import { type PlanState, DEFAULT_PLAN_STATE, PLAN_MODE_TOOLS } from "../state.js";
+
+const ALL_TOOL_NAMES = ["read", "bash", "grep", "find", "ls", "plan", "write", "edit"];
+
+function setup(skillCommands: Array<{ name: string; path: string }> = []) {
+  const sessions = new Map();
+  const controllers = new Map<string, AbortController>();
+  let executeFn: (id: string, p: Record<string, unknown>, sig?: AbortSignal, upd?: unknown, ctx?: unknown) => Promise<{
+    content: Array<{ type: string; text: string }>;
+    details: { action: string; requirement?: string; skills?: string[] };
+  }>;
+  const pi = {
+    registerTool: vi.fn((tool) => { executeFn = tool.execute; }),
+    appendEntry: vi.fn(),
+    setActiveTools: vi.fn(),
+    sendMessage: vi.fn(),
+    getCommands: vi.fn(() => skillCommands.map((c) => ({ name: c.name, source: "skill", sourceInfo: { path: c.path } }))),
+    getAllTools: vi.fn(() => ALL_TOOL_NAMES.map((n) => ({ name: n }))),
+  } as unknown as ExtensionAPI;
+  registerPlanTool(pi, sessions, controllers);
+
+  const ctx = {
+    sessionId: "test-session",
+    cwd: "/tmp/test-project",
+    hasUI: true,
+    mode: "tui" as const,
+    isProjectTrusted: () => true,
+    sessionManager: { getSessionId: () => "test-session", getEntries: () => [] },
+    ui: { select: vi.fn(), notify: vi.fn() },
+  } as unknown as ExtensionContext;
+
+  const exec = (params: Record<string, unknown>, signal?: AbortSignal) =>
+    executeFn!("tc0", params, signal, undefined, ctx);
+  return { pi, sessions, ctx, exec };
+}
+
+describe("plan(action='enter') — agent 自助进入（plan-mode-agent-enter U1）", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("idle 进入：收工具到白名单 + 持久化 isActive=true + tool result 携带只读纪律提示词", async () => {
+    const { exec, pi, sessions } = setup();
+    const res = await exec({ action: "enter", requirement: "重构 auth 模块" });
+
+    // 工具收拢到 plan 白名单
+    expect(pi.setActiveTools).toHaveBeenCalledWith(PLAN_MODE_TOOLS);
+    // 状态持久化 isActive=true（投影链驱动 GUI 显形的锚点）
+    expect(pi.appendEntry).toHaveBeenCalledWith("plan-state", expect.objectContaining({ isActive: true }));
+    // plan 目录创建（.tmp/plans/<slug>，slug 由 requirement 派生）
+    expect(fs.mkdirSync).toHaveBeenCalledWith(
+      expect.stringMatching(/\.tmp[/\\]plans[/\\]/),
+      expect.objectContaining({ recursive: true }),
+    );
+    // 提示词经 tool result 直返（不经对话流消息注入——对本次调用的直接响应）
+    expect(pi.sendMessage).not.toHaveBeenCalled();
+    expect(res.details.action).toBe("enter");
+    expect(res.content[0].text).toContain("[PLAN MODE] Entered plan mode");
+    expect(res.content[0].text).toContain("READ-ONLY");
+    // 状态对象已是激活态
+    const state = sessions.get("test-session") as { isActive?: boolean; requirement?: string };
+    expect(state.isActive).toBe(true);
+  });
+
+  it("已在 plan 模式：幂等返回，不重复收工具 / 不重复注入", async () => {
+    const { exec, pi, sessions } = setup();
+    await exec({ action: "enter", requirement: "first" });
+    vi.clearAllMocks();
+    // state 缓存已在（sessions map 同一对象 isActive=true）
+    expect((sessions.get("test-session") as { isActive?: boolean }).isActive).toBe(true);
+
+    const res = await exec({ action: "enter", requirement: "second" });
+    expect(res.content[0].text).toContain("Already in plan mode");
+    // 幂等：不再 setActiveTools / 不再 appendEntry
+    expect(pi.setActiveTools).not.toHaveBeenCalled();
+    expect(pi.appendEntry).not.toHaveBeenCalled();
+  });
+
+  it("携带有效 skills：解析挂载，state.skills 记录技能名", async () => {
+    const { exec, sessions } = setup([{ name: "skill:tech-design", path: "/skills/tech-design/SKILL.md" }]);
+    const res = await exec({ action: "enter", requirement: "r", skills: ["tech-design"] });
+    expect(res.details.action).toBe("enter");
+    expect(res.details.skills).toEqual(["tech-design"]);
+    const state = sessions.get("test-session") as { skills?: string[] };
+    expect(state.skills).toEqual(["tech-design"]);
+  });
+
+  it("未知技能名：throw 带可用清单自愈（同 select-template 错名先例）", async () => {
+    const { exec, pi } = setup([{ name: "skill:tech-design", path: "/x/SKILL.md" }]);
+    await expect(exec({ action: "enter", requirement: "r", skills: ["nope"] })).rejects.toThrow(
+      /Unknown skill\(s\): nope\. Available skills: .*tech-design/,
+    );
+    // 校验失败不进入：未收工具、未持久化
+    expect(pi.setActiveTools).not.toHaveBeenCalled();
+    expect(pi.appendEntry).not.toHaveBeenCalled();
+  });
+
+  it("省略 requirement：提示词回落 (from conversation context)，不阻断进入", async () => {
+    const { exec } = setup();
+    const res = await exec({ action: "enter" });
+    expect(res.details.action).toBe("enter");
+    expect(res.content[0].text).toContain("(from conversation context)");
+  });
+
+  it("新轮次进入：上轮残留的 reviewStateSource 随进入失效（跨 plan run 残留防护，§3.4 清除点）", async () => {
+    const { exec, pi, sessions } = setup();
+    // 模拟上轮残留：崩溃/bad-response 等绕过 resetPlanState 的路径留下的来源标记
+    sessions.set("test-session", { ...DEFAULT_PLAN_STATE, isActive: false, reviewStateSource: "explain" });
+
+    const res = await exec({ action: "enter", requirement: "new round" });
+
+    expect(res.details.action).toBe("enter");
+    // activatePlanMode 新轮次重置组清来源标记（与 resetPlanState 对齐）
+    const state = sessions.get("test-session") as { reviewStateSource?: string };
+    expect(state.reviewStateSource).toBeUndefined();
+    // 新轮 entry 无来源标记（undefined 序列化自然消失——D4）
+    const lastEntry = (pi.appendEntry as ReturnType<typeof vi.fn>).mock.calls.at(-1)?.[1] as PlanState;
+    expect(lastEntry.reviewStateSource).toBeUndefined();
+  });
+});