@zhushanwen/pi-plan 0.4.3 → 0.4.5

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.3",
+  "version": "0.4.5",
   "description": "Lightweight plan mode for Pi coding agent",
   "type": "module",
   "main": "index.ts",
@@ -21,7 +21,7 @@
     "@earendil-works/pi-coding-agent": ">=0.73.0",
     "typebox": "*",
     "@earendil-works/pi-ai": "^0.84.4",
-    "@zhushanwen/pi-goal": "0.13.0"
+    "@zhushanwen/pi-goal": "0.14.1"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-ai": {
@@ -38,7 +38,8 @@
     "templates/"
   ],
   "dependencies": {
-    "@zhushanwen/pi-extension-logger": "0.4.1"
+    "@zhushanwen/pi-ext-guards": "0.3.0",
+    "@zhushanwen/pi-extension-logger": "0.6.0"
   },
   "scripts": {
     "typecheck": "npx tsc --noEmit",

package/src/compact.ts

@@ -2,11 +2,15 @@ import * as fs from "node:fs";
 import { basename } from "node:path";
 
 import type { ExtensionAPI, ExtensionContext, SessionBeforeCompactEvent, SessionBeforeTreeEvent } from "@earendil-works/pi-coding-agent";
+import { guardStaleCtx, toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import type { GoalInitFn } from "@zhushanwen/pi-goal";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
 
 import type { PlanSessionMap, PlanState } from "./state.js";
 import { getPlanState } from "./state.js";
 
+const logger = getLogger("pi-plan");
+
 export function registerPlanEventHandlers(
   pi: ExtensionAPI,
   sessions: PlanSessionMap,
@@ -217,14 +221,30 @@ export function handlePlanComplete(
     case "compact": {
       ctx.compact({
         customInstructions: `Plan file: ${planFilePath}. Read plan and execute implementation.`,
+        // E1 同构崩溃点（crash-resilience D1）：onComplete/onError 由 compact 内部
+        // Promise 链异步调用、不在 pi runner emit() 的 try/catch 内——压缩进行中用户
+        // 切换/重载 session 后，回调触碰捕获的 pi/ctx 命中 stale 同步抛错即杀 pi 进程。
+        // 守卫 stale 静默降级（执行消息不投递，用户可手动 Read plan 文件执行），非
+        // stale 错误原样上抛。plan 未注入代际计数器（低频路径），分诊依赖 PS-30 门禁
+        // 守卫的 stale 文案兜底（D1 降级语义声明的合法形态）。
         onComplete: () => {
-          pi.sendUserMessage(executeMessage, { deliverAs: "steer" });
-          tryGoalInit(pi, planFilePath, ctx);
+          guardStaleCtx(() => {
+            pi.sendUserMessage(executeMessage, { deliverAs: "steer" });
+            tryGoalInit(pi, planFilePath, ctx);
+          }, {
+            label: "plan:compact-onComplete",
+            onStale: (error) => logger.warn("plan execution notice delivery skipped (stale ctx)", { error: toErrorMessage(error) }),
+          });
         },
         onError: (_error: Error) => {
-          ctx.ui.notify("Compact failed, continuing without isolation.", "warning");
-          pi.sendUserMessage(executeMessage, { deliverAs: "steer" });
-          tryGoalInit(pi, planFilePath, ctx);
+          guardStaleCtx(() => {
+            ctx.ui.notify("Compact failed, continuing without isolation.", "warning");
+            pi.sendUserMessage(executeMessage, { deliverAs: "steer" });
+            tryGoalInit(pi, planFilePath, ctx);
+          }, {
+            label: "plan:compact-onError",
+            onStale: (error) => logger.warn("plan execution notice delivery skipped (stale ctx)", { error: toErrorMessage(error) }),
+          });
         },
       });
       break;