@zhushanwen/pi-plan 0.5.2 → 1.1.0

package/src/__tests__/command.test.ts

@@ -24,13 +24,14 @@ import * as path from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { parsePlanArgs, registerPlanCommand, resolveTemplateFile } from "../command.js";
-import { MAX_PLAN_REQUIREMENT_LENGTH, PLAN_CONTEXT_CUSTOM_TYPE } from "../state.js";
+import type { PlanAbortControllers } from "../state.js";
+import { createPlanCtx, freshPendingSelect, MAX_PLAN_REQUIREMENT_LENGTH, PLAN_CONTEXT_CUSTOM_TYPE } from "../state.js";
 
 const ALL_TOOL_NAMES = ["read", "bash", "grep", "find", "ls", "plan", "write", "edit"];
 
 function createMocks() {
   let capturedHandler: (args: string, ctx: ExtensionContext) => Promise<void>;
-  const controllers = new Map<string, AbortController>();
+  const planCtx = createPlanCtx();
 
   const pi = {
     registerCommand: vi.fn((_name: string, def: { handler: (args: string, ctx: ExtensionContext) => Promise<void> }) => {
@@ -47,6 +48,7 @@ function createMocks() {
     cwd: "/tmp/test-project",
     sessionManager: {
       getSessionId: () => "test-session",
+      getLeafId: () => null,
       getEntries: () => [] as unknown[],
     },
     ui: {
@@ -60,7 +62,8 @@ function createMocks() {
   return {
     pi,
     ctx,
-    controllers,
+    planCtx,
+    controllers: planCtx.controllers,
     getHandler: () => capturedHandler!,
   };
 }
@@ -74,7 +77,7 @@ describe("registerPlanCommand", () => {
   let pi: ExtensionAPI;
   let ctx: ExtensionContext;
   let handler: (args: string, ctx: ExtensionContext) => Promise<void>;
-  let controllers: Map<string, AbortController>;
+  let controllers: PlanAbortControllers;
 
   beforeEach(() => {
     vi.clearAllMocks();
@@ -82,8 +85,7 @@ describe("registerPlanCommand", () => {
     pi = mocks.pi;
     ctx = mocks.ctx;
     controllers = mocks.controllers;
-    const sessions = new Map();
-    registerPlanCommand(pi, sessions, controllers);
+    registerPlanCommand(pi, mocks.planCtx);
     handler = mocks.getHandler();
   });
 
@@ -93,38 +95,54 @@ describe("registerPlanCommand", () => {
 
   // --- abort subcommand ---
 
-  it("abort: notifies 'No active plan mode' when idle", async () => {
+  it("abort（idle 常态格）: warn 纠偏文案 + 幂等退出——不落盘、工具集幂等恢复（D-B1-1 单入口守卫极性，原 info no-op 取消）", async () => {
     await handler("abort", ctx);
-    expect((ctx as ReturnType<typeof createMocks>["ctx"]).ui.notify).toHaveBeenCalledWith("No active plan mode.", "info");
-    expect(pi.setActiveTools).not.toHaveBeenCalled();
+    expect((ctx as ReturnType<typeof createMocks>["ctx"]).ui.notify).toHaveBeenCalledWith("No active plan mode.", "warning");
+    // ④ 工具集照常幂等恢复（idle 格已是全量，重设全量 = 可观察零变化）
+    expect(pi.setActiveTools).toHaveBeenCalledWith(ALL_TOOL_NAMES);
+    // ② 跳过：idle 删 exit 边后 ok:false 不落盘（无噪音 exited entry）
+    expect(pi.appendEntry).not.toHaveBeenCalled();
   });
 
-  it("abort: resets state and restores tools when active", async () => {
-    // Enter plan mode first — handler uses the sessions map from registerPlanCommand closure
-    await handler("implement user auth", ctx);
-    expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan"]);
-    vi.clearAllMocks();
-
-    // Now abort — state is active in the sessions map
-    await handler("abort", ctx);
-
-    expect(pi.setActiveTools).toHaveBeenCalledWith(ALL_TOOL_NAMES);
-    expect((ctx as ReturnType<typeof createMocks>["ctx"]).ui.notify).toHaveBeenCalledWith("Plan mode aborted.", "info");
+  it("abort（终态格 isActive=false）: warn 纠偏指令文案 + 不落盘（V1 ⑤ 幂等退出锚）", async () => {
+    // 注入终态格：上一轮已 complete，缓存重建自 entries（空）→ 直接预置 sessions 难以
+    // 穿透 handler 闭包，改走 entries 注入 completed 残留形态
+    const terminalCtx = {
+      ...ctx,
+      sessionManager: {
+        getSessionId: () => "test-session",
+        getEntries: () => [
+          {
+            type: "custom",
+            customType: "plan-state",
+            data: { isActive: false, state: "completed", planFilePath: "", requirement: "", templateName: "" },
+          },
+        ],
+      },
+    } as unknown as ExtensionContext;
+    await handler("abort", terminalCtx);
+    expect(terminalCtx.ui.notify).toHaveBeenCalledWith(
+      expect.stringContaining("Plan mode is not active"),
+      "warning",
+    );
+    // completed 终态记录不被 exited 覆写（ok:false 跳过状态值写入，isActive=false 非坏格）
+    expect(pi.appendEntry).not.toHaveBeenCalled();
   });
 
-  it("abort 联动（E10）：controller.abort() 先于 resetPlanState 的 entry 落盘", async () => {
+  it("abort 联动（E10）：controller.abort() 先于 resetPlanState 的 entry 落盘，markDissolved('self') 先行打标", async () => {
     await handler("implement user auth", ctx);
     vi.clearAllMocks();
 
-    // 模拟一个挂起 select 的 controller（submit-review / complete 执行方式两处共用注册表）
-    const controller = new AbortController();
-    const abortSpy = vi.spyOn(controller, "abort");
-    controllers.set("test-session", controller);
+    // 模拟一个挂起 select 的 PendingSelect（submit-review / complete 执行方式两处共用注册表）
+    const pending = freshPendingSelect(controllers, "test-session");
+    const abortSpy = vi.spyOn(pending.controller, "abort");
 
     await handler("abort", ctx);
 
-    // 挂起 select 被 abort（→ resolve undefined → tool execute 已取消分支 → turn 结束 → settled → busy defer 恢复）
-    expect(controller.signal.aborted).toBe(true);
+    // 挂起 select 被 abort（→ resolve undefined → tool execute 归口分支 → turn 结束 → settled → busy defer 恢复）
+    expect(pending.controller.signal.aborted).toBe(true);
+    // D-B1-2：入口解散先打 'self' 标（同步先于 abort，等待处归口按来源直传判别）
+    expect(pending.dissolvedBy).toBe("self");
     // 顺序断言：abort 必须先于 reset entry 落盘（反序 = 挂起 select 无人 resolve → session 卡死）
     const resetCallIndex = (pi.appendEntry as ReturnType<typeof vi.fn>).mock.calls.findIndex(
       (c) => (c[1] as { isActive?: boolean }).isActive === false,
@@ -168,7 +186,7 @@ describe("registerPlanCommand", () => {
       "/tmp/test-project/.tmp/plans/implement-user-auth",
       { recursive: true },
     );
-    expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan"]);
+    expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan", "ask_user"]);
     expect(pi.sendMessage).toHaveBeenCalledWith(...planContextMessage(expect.stringContaining("[PLAN MODE]")));
     expect(pi.sendMessage).toHaveBeenCalledWith(...planContextMessage(expect.stringContaining("Implement User Auth")));
     expect(pi.appendEntry).toHaveBeenCalledWith("plan-state", {
@@ -176,9 +194,13 @@ describe("registerPlanCommand", () => {
       planFilePath: "/tmp/test-project/.tmp/plans/implement-user-auth/plan.md",
       requirement: "Implement User Auth",
       templateName: "",
+      templateProvided: undefined,
       skills: [],
       docs: [],
-      reviewState: undefined,
+      state: "planning",
+      selfReview: undefined,
+      resumeHint: undefined,
+      lastSubmitReviewDocsFingerprint: undefined,
     });
   });
 
@@ -221,6 +243,7 @@ describe("registerPlanCommand", () => {
       ...ctx,
       sessionManager: {
         getSessionId: () => "test-session",
+        getLeafId: () => null,
         getEntries: () => [
           {
             type: "custom",
@@ -272,6 +295,53 @@ describe("registerPlanCommand", () => {
     return payload.content;
   }
 
+  // --- D10②：命令反馈 notify（display:false 注入仅 LLM 可见，用户可见性由 notify 承担） ---
+
+  it("重入分支（存在既有 plan 文件）：notify 提示 + 选项清单仍走 display:false 注入", async () => {
+    vi.mocked(fs.readdirSync).mockReturnValue(["old-plan"] as unknown as ReturnType<typeof fs.readdirSync>);
+    vi.mocked(fs.statSync).mockImplementation(() => ({ isDirectory: () => true }) as unknown as fs.Stats);
+    vi.mocked(fs.existsSync).mockImplementation((p) => String(p).endsWith("/.tmp/plans/old-plan/plan.md"));
+    try {
+      await handler("", ctx);
+    } finally {
+      vi.mocked(fs.existsSync).mockImplementation(() => false);
+    }
+
+    const notify = (ctx as unknown as { ui: { notify: ReturnType<typeof vi.fn> } }).ui.notify;
+    expect(notify).toHaveBeenCalledWith(expect.stringContaining("1 existing plan file(s)"), "info");
+    // LLM 注入通路不变：custom message display:false + 选项清单全文
+    const message = sentMessage();
+    expect(message).toContain("[PLAN MODE] Found existing plan files:");
+    const calls = (pi.sendMessage as ReturnType<typeof vi.fn>).mock.calls;
+    const payload = calls[0][0] as { display: boolean };
+    expect(payload.display).toBe(false);
+  });
+
+  it("--skills 未知技能 fail-fast：notify error + 注入通路保留", async () => {
+    await handler("复盘 --skills nope", ctx);
+
+    const notify = (ctx as unknown as { ui: { notify: ReturnType<typeof vi.fn> } }).ui.notify;
+    expect(notify).toHaveBeenCalledWith(expect.stringContaining("unknown skill(s): nope"), "error");
+    expect(sentMessage()).toContain("Failed to enter: unknown skill(s): nope");
+  });
+
+  it("--template 文件缺失 fail-fast：notify error", async () => {
+    await handler("复盘 --template tpl.md", ctx);
+
+    const notify = (ctx as unknown as { ui: { notify: ReturnType<typeof vi.fn> } }).ui.notify;
+    expect(notify).toHaveBeenCalledWith(expect.stringContaining("Template file not found"), "error");
+  });
+
+  it("进入成功：notify info 携带 planFilePath（命令反馈通道，widget 之外补可达）", async () => {
+    await handler("复盘需求", ctx);
+
+    const notify = (ctx as unknown as { ui: { notify: ReturnType<typeof vi.fn> } }).ui.notify;
+    expect(notify).toHaveBeenCalledWith(
+      expect.stringContaining("Plan mode entered: /tmp/test-project/.tmp/plans/"),
+      "info",
+    );
+  });
+
   describe("--template via /plan handler", () => {
     afterEach(() => {
       // 还原默认 existsSync=false，避免路径实现泄漏到后续用例
@@ -327,11 +397,11 @@ describe("registerPlanCommand", () => {
           isActive: true,
           requirement: "retro meeting",
           templateName: "retro-template",
-          templateProvidedPath: "/tmp/test-project/docs/retro-template.md",
+          templateProvided: true,
           skills: [],
         }),
       );
-      expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan"]);
+      expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan", "ask_user"]);
       const prompt = sentMessage();
       // 直传声明 + 全文内嵌（文件内容直达模型，不赌自发 read——D5）
       expect(prompt).toContain("template was provided via --template");
@@ -349,7 +419,7 @@ describe("registerPlanCommand", () => {
 
       expect(pi.appendEntry).toHaveBeenCalledWith(
         "plan-state",
-        expect.objectContaining({ isActive: true, templateName: "retro template", templateProvidedPath: spacedAbs }),
+        expect.objectContaining({ isActive: true, templateName: "retro template", templateProvided: true }),
       );
       const prompt = sentMessage();
       expect(prompt).toContain(spacedAbs);

package/src/__tests__/enter.test.ts

@@ -27,19 +27,23 @@ vi.mock("node:fs", () => ({
 // Mock templates（enter 的 buildPlanModePrompt 走 listTemplates；单测不扫真实模板目录）
 vi.mock("../templates.js", () => ({
   listTemplates: vi.fn(() => []),
-  loadTemplate: vi.fn(() => null),
   formatAvailablePlans: vi.fn(() => ""),
 }));
 
-vi.mock("../compact.js", () => ({
+vi.mock("../execution-notice.js", () => ({
   handlePlanComplete: vi.fn(),
-  detectGoalCapability: vi.fn(() => false),
   GOAL_FAILURE_RECOVERY: {},
 }));
 
-vi.mock("../exec-skills.js", () => ({
-  detectExecSkills: vi.fn(() => []),
-}));
+// Mock 执行方式检测（D10）：单测不扫真实目录。importActual 展开：只覆写
+// detectExecSkills，其余导出（含 enter.ts re-export 的 resolveSkills 执行门禁）走
+// 真实现——mock 罩全模块会把它一并变 undefined
+vi.mock("@zhushanwen/pi-exec-skills", async () => {
+  const actual = await vi.importActual<typeof import("@zhushanwen/pi-exec-skills")>(
+    "@zhushanwen/pi-exec-skills",
+  );
+  return { ...actual, detectExecSkills: vi.fn(() => []) };
+});
 
 vi.mock("../widget.js", () => ({
   updatePlanWidget: vi.fn(),
@@ -50,13 +54,12 @@ 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";
+import { type PlanState, createPlanCtx, 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>();
+  const planCtx = createPlanCtx();
   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[] };
@@ -69,7 +72,7 @@ function setup(skillCommands: Array<{ name: string; path: string }> = []) {
     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);
+  registerPlanTool(pi, planCtx);
 
   const ctx = {
     sessionId: "test-session",
@@ -77,13 +80,13 @@ function setup(skillCommands: Array<{ name: string; path: string }> = []) {
     hasUI: true,
     mode: "tui" as const,
     isProjectTrusted: () => true,
-    sessionManager: { getSessionId: () => "test-session", getEntries: () => [] },
+    sessionManager: { getSessionId: () => "test-session", getLeafId: () => null, 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 };
+  return { pi, sessions: planCtx.states, ctx, exec };
 }
 
 describe("plan(action='enter') — agent 自助进入（plan-mode-agent-enter U1）", () => {
@@ -112,6 +115,10 @@ describe("plan(action='enter') — agent 自助进入（plan-mode-agent-enter U1
     // 状态对象已是激活态
     const state = sessions.get("test-session") as { isActive?: boolean; requirement?: string };
     expect(state.isActive).toBe(true);
+    // 状态写走 transition()：idle --enter--> planning 落盘（新会话缺省态进入；原独立
+    // 用例的转移断言并入——同通道同断言字段，仅转移源字面量与下方坏格用例不同）
+    const lastEntry = (pi.appendEntry as ReturnType<typeof vi.fn>).mock.calls.at(-1)?.[1] as PlanState;
+    expect(lastEntry.state).toBe("planning");
   });
 
   it("已在 plan 模式：幂等返回，不重复收工具 / 不重复注入", async () => {
@@ -154,19 +161,50 @@ describe("plan(action='enter') — agent 自助进入（plan-mode-agent-enter U1
     expect(res.content[0].text).toContain("(from conversation context)");
   });
 
-  it("新轮次进入：上轮残留的 reviewStateSource 随进入失效（跨 plan run 残留防护，§3.4 清除点）", async () => {
+  it("新轮次进入：上轮残留的 selfReview/resumeHint/指纹随进入失效（clearRoundFields 单函数出口的 enter 调用点，D9①防跨轮误触新鲜度门）", async () => {
     const { exec, pi, sessions } = setup();
-    // 模拟上轮残留：崩溃/bad-response 等绕过 resetPlanState 的路径留下的来源标记
-    sessions.set("test-session", { ...DEFAULT_PLAN_STATE, isActive: false, reviewStateSource: "explain" });
+    // 模拟上轮残留：崩溃/bad-response 等绕过 resetPlanState 的路径留下的降级标记与基线
+    sessions.set("test-session", {
+      ...DEFAULT_PLAN_STATE,
+      isActive: false,
+      state: "exited",
+      selfReview: "stale self-review",
+      resumeHint: "resubmit",
+      lastSubmitReviewDocsFingerprint: "old.md:3",
+    });
 
     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）
+    // activatePlanMode 经 clearRoundFields 清三字段（D4 单函数出口，与 resetPlanState 同源）
+    const state = sessions.get("test-session") as PlanState;
+    expect(state.selfReview).toBeUndefined();
+    expect(state.resumeHint).toBeUndefined();
+    expect(state.lastSubmitReviewDocsFingerprint).toBeUndefined();
+    // enter 边落盘（exited --enter--> planning 新一轮）；entry 无残留字段
+    const lastEntry = (pi.appendEntry as ReturnType<typeof vi.fn>).mock.calls.at(-1)?.[1] as PlanState;
+    expect(lastEntry.state).toBe("planning");
+    expect(lastEntry.resumeHint).toBeUndefined();
+  });
+
+  it("坏数据格（isActive=false 且 state 落活跃族）：enter 按转移 ok:false 落穿，不归一不重试（坏格自愈分支已删，C1 行为变更组——仅坏格可达，行为差锚）", async () => {
+    const { exec, pi, sessions } = setup();
+    // 手改 session 文件可达的坏格：isActive=false 却残留活跃族 state（reviewing）
+    sessions.set("test-session", {
+      ...DEFAULT_PLAN_STATE,
+      isActive: false,
+      state: "reviewing",
+    });
+
+    await exec({ action: "enter", requirement: "on a corrupt cell" });
+
+    // 落穿：不归一 idle 再进——state 保持坏值（reviewing --enter--> 非 ok），进入副作用
+    // 照常（isActive=true 已置、persist 携带现值）
+    const state = sessions.get("test-session") as PlanState;
+    expect(state.isActive).toBe(true);
+    expect(state.state).toBe("reviewing");
     const lastEntry = (pi.appendEntry as ReturnType<typeof vi.fn>).mock.calls.at(-1)?.[1] as PlanState;
-    expect(lastEntry.reviewStateSource).toBeUndefined();
+    expect(lastEntry.state).toBe("reviewing");
+    expect(lastEntry.isActive).toBe(true);
   });
 });

package/src/__tests__/exec-options-alignment.test.ts

@@ -0,0 +1,56 @@
+/**
+ * PHASE_D 散文 ↔ buildExecOptions 选项集对齐防线（plan-phase-d-prompt-options-alignment
+ * 定案：2026-09-26 登记二选一，2026-09-27 裁决 = 单源化 + 对齐测试双管）。
+ *
+ * 能单源的已单源：技能档上限 MAX_SKILL_OPTIONS（prompts.ts SSOT，散文插值 + 截断同源）、
+ * 选项 label（i18n exec.* 词典单源）。散文无法整体生成的结构性原因：面向模型的是英文
+ * 静态散文，选项是运行时按检测结果动态构造 + 用户侧 label 随 locale 本地化——两种语言、
+ * 两个受众；散文还描述「无技能直通」分支行为（无选项对象对应物）。故散文锚点靠本测试
+ * 机器锁定：数量锚、label 字面锚、两分支行为句锚，漂移即红。
+ */
+import { describe, expect, it } from "vitest";
+
+import { t } from "../i18n.js";
+import { MAX_SKILL_OPTIONS, PHASE_D_PROSE } from "../prompts.js";
+import { buildExecOptions } from "../tool.js";
+import type { ExecSkill } from "@zhushanwen/pi-exec-skills";
+
+function fixtureSkill(name: string): ExecSkill {
+  return { name, description: `${name} plan-exec skill`, skillEntryPath: `/tmp/skills/${name}/SKILL.md` } as ExecSkill;
+}
+
+describe("PHASE_D 散文 ↔ buildExecOptions 对齐", () => {
+  it("数量锚：散文技能档上限 = 截断常量（MAX_SKILL_OPTIONS 单源，改一处散文自动跟随）", () => {
+    expect(PHASE_D_PROSE).toContain(`up to ${MAX_SKILL_OPTIONS} detected plan-exec skills`);
+  });
+
+  it("截断行为锚：检测超过上限的技能只取前 MAX_SKILL_OPTIONS 个 + 固定尾部两项", () => {
+    const skills = Array.from({ length: MAX_SKILL_OPTIONS + 2 }, (_, i) => fixtureSkill(`s${i + 1}`));
+    const options = buildExecOptions(skills);
+
+    expect(options).toHaveLength(MAX_SKILL_OPTIONS + 2);
+    expect(options.slice(0, MAX_SKILL_OPTIONS).map((o) => o.mode)).toEqual(["skill:s1", "skill:s2"]);
+    expect(options.slice(MAX_SKILL_OPTIONS).map((o) => o.mode)).toEqual(["execute", "later"]);
+  });
+
+  it("label 锚：选项 label 出自 i18n 词典（en-US 基准），散文含对应英文字面", () => {
+    const en = (key: string, params?: Record<string, string | number>) => t(key, params, "en-US");
+
+    const options = buildExecOptions([fixtureSkill("dev-flow")]);
+    const [skillOption, executeOption, laterOption] = options;
+
+    // 选项 label 单源 = 词典；散文锚定词典渲染产物（技能档取 name 占位渲染形态）
+    expect(skillOption.label).toBe(en("exec.viaSkill", { name: "dev-flow" }));
+    expect(executeOption.label).toBe(en("exec.execute"));
+    expect(laterOption.label).toBe(en("exec.later"));
+
+    expect(PHASE_D_PROSE).toContain("Execute via skill: <name>");
+    // Execute 作为完整选项词（非 "Execute via" 前缀的一部分——用后随括号边界锚定）
+    expect(PHASE_D_PROSE).toContain(`${en("exec.execute")} (goal tracking integrated when available), or ${en("exec.later")}`);
+  });
+
+  it("两分支行为句锚：有技能弹表单 / 无技能直通（D7②），散文与行为分支共存", () => {
+    expect(PHASE_D_PROSE).toContain("the user picks an execution method in the completion dialog");
+    expect(PHASE_D_PROSE).toContain("When NO plan-exec skill is detected, no dialog appears and the plan executes directly");
+  });
+});

package/src/__tests__/execution-notice.test.ts

@@ -0,0 +1,197 @@
+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 execution-notice.ts (ESM namespace is not configurable)
+vi.mock("node:fs", () => ({
+  readFileSync: vi.fn(),
+}));
+
+// Import after mock setup
+import { handlePlanComplete } from "../execution-notice.js";
+
+const fsMock = vi.mocked(await import("node:fs"));
+
+// --- Shared mock factories ---
+
+function makePi() {
+  return {
+    on: vi.fn(),
+    appendEntry: vi.fn(),
+    sendMessage: vi.fn(),
+  };
+}
+
+type CtxMock = ReturnType<typeof makeCtx>;
+function makeCtx() {
+  return {
+    sessionManager: { getSessionId: () => "test-session", getEntries: () => [] as unknown[] },
+    ui: { notify: vi.fn() },
+  };
+}
+
+function makeActiveState(): PlanState {
+  return {
+    isActive: true,
+    // 生产真实形态（enter.ts：<project>/.tmp/plans/<slug>/plan.md）——合成单层路径会让
+    // slug 派生类消费面（buildPlanSlug 取 basename）在测试数据上失真
+    planFilePath: "/tmp/test-project/.tmp/plans/login-page/plan.md",
+    requirement: "Add login page",
+    templateName: "default",
+  };
+}
+
+function setupFsMock(content: string) {
+  fsMock.readFileSync.mockReturnValue(content);
+}
+
+/**
+ * goal 桥 slot key——与 execution-notice.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);
+});
+
+/** 最近一次 sendMessage 的正文（P8 custom message 的 content 字段）。 */
+function lastSteer(pi: ReturnType<typeof makePi>): string {
+  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 ---
+
+describe("handlePlanComplete", () => {
+  let pi: ReturnType<typeof makePi>;
+  let ctx: CtxMock;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    pi = makePi();
+    ctx = makeCtx();
+    setupFsMock("## 实现步骤\n1. Step one\n2. Step two");
+  });
+
+  describe("direct delivery", () => {
+    it("execute mode success: returns outcome synchronously, goal steer, no notify", () => {
+      attachGoalInit(() => true);
+
+      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "execute");
+
+      expect(outcome).toEqual({ started: true });
+      expect(pi.sendMessage).toHaveBeenCalledWith(...executionNotice(expect.stringContaining("Goal tracking is active via /goal")));
+      expect(ctx.ui.notify).not.toHaveBeenCalled();
+    });
+
+    it("skill mode: 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(), "skill:dev-flow", skillEntryPath);
+
+      expect(outcome).toBeUndefined();
+      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(), "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(), "skill:dev-flow");
+
+      const steer = lastSteer(pi);
+      expect(steer).toContain("load the dev-flow skill");
+      expect(steer).not.toContain("SKILL.md");
+    });
+  });
+
+  // goal 桥五个失败出口 → GoalBridgeOutcome 五值（D2）
+  describe("tryGoalInit failure exits (execute mode)", () => {
+    it("goal-unavailable: bridge not mounted → degraded steer + warning notify", () => {
+      const outcome = handlePlanComplete(pi as never, ctx as never, makeActiveState(), "execute");
+
+      expect(outcome).toEqual({ started: false, reason: "goal-unavailable" });
+      const steer = lastSteer(pi);
+      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");
+    });
+
+    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(), "execute");
+
+      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(), "execute");
+
+      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(), "execute");
+
+      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(), "execute");
+
+      expect(outcome).toEqual({ started: false, reason: "internal-error", detail: "goalInit exploded" });
+      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");
+    });
+  });
+});