@zhushanwen/pi-plan 0.5.2 → 1.0.0

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");
+    });
+  });
+});

package/src/__tests__/{compact.test.ts → extract-plan-steps.test.ts}

@@ -1,6 +1,6 @@
 import { describe, expect,it } from "vitest";
 
-import { extractPlanSteps } from "../compact.js";
+import { extractPlanSteps } from "../execution-notice.js";
 
 describe("extractPlanSteps", () => {
   it("extracts numbered steps from 实现步骤 section", () => {
@@ -8,6 +8,7 @@ describe("extractPlanSteps", () => {
 
 ## 背景
 Some context
+1. Background numbered line that must not leak
 
 ## 实现步骤
 1. Create the user model
@@ -27,7 +28,10 @@ Run tests`;
   it("extracts numbered steps from 实施步骤 section", () => {
     const plan = `## 实施步骤
 1. Step one
-2. Step two`;
+2. Step two
+
+## 验证
+1. Verification line that must not leak`;
     const steps = extractPlanSteps(plan);
     expect(steps).toEqual(["Step one", "Step two"]);
   });
@@ -35,7 +39,10 @@ Run tests`;
   it("extracts steps from English Steps section", () => {
     const plan = `## Steps
 1. First step
-2. Second step`;
+2. Second step
+
+## Notes
+1. Notes line that must not leak`;
     const steps = extractPlanSteps(plan);
     expect(steps).toEqual(["First step", "Second step"]);
   });
@@ -43,7 +50,10 @@ Run tests`;
   it("extracts steps from Implementation section", () => {
     const plan = `## Implementation Steps
 1. Create file
-2. Add exports`;
+2. Add exports
+
+## Validation
+1. Validation line that must not leak`;
     const steps = extractPlanSteps(plan);
     expect(steps).toEqual(["Create file", "Add exports"]);
   });
@@ -72,16 +82,6 @@ Run tests`;
     ]);
   });
 
-  it("returns empty array when no steps section and no numbered items", () => {
-    const plan = `## 背景
-Some context
-
-## 方案
-Option A is preferred`;
-    const steps = extractPlanSteps(plan);
-    expect(steps).toEqual([]);
-  });
-
   it("fallback: collects numbered items when no steps section header", () => {
     const plan = `# Plan
 1. First thing
@@ -95,8 +95,17 @@ Option A is preferred`;
     const plan = `## 实现步骤
 1. Valid step
 
-2. Another valid step`;
+2. Another valid step
+3.
+4. ${"   "}`;
     const steps = extractPlanSteps(plan);
     expect(steps).toEqual(["Valid step", "Another valid step"]);
   });
+
+  it("fallback cap: collects at most the first 10 numbered items when no steps section header", () => {
+    const plan = Array.from({ length: 12 }, (_, i) => `${i + 1}. step ${i + 1}`).join("\n");
+    const steps = extractPlanSteps(plan);
+    expect(steps).toHaveLength(10);
+    expect(steps[9]).toBe("step 10");
+  });
 });