@zhushanwen/pi-plan 0.5.2 → 1.0.0

package/src/command.ts

@@ -7,9 +7,9 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { activatePlanMode, resolveSkills } from "./enter.js";
 import type { SkillResolution } from "./enter.js";
 import type { SkillRef } from "./prompts.js";
-import type { PlanAbortControllers, PlanSessionMap, PlanState } from "./state.js";
-import { PLAN_CONTEXT_CUSTOM_TYPE, getPlanState, resetPlanState } from "./state.js";
-import { updatePlanWidget } from "./widget.js";
+import { exitPlanMode } from "./tool.js";
+import type { PlanCtx, PlanState } from "./state.js";
+import { PLAN_CONTEXT_CUSTOM_TYPE, getPlanState } from "./state.js";
 
 /** /plan 参数解析产物：requirement = 最早 flag 标记前的自由文本；skills / templatePath 为 undefined = 未提供对应 flag */
 export interface ParsedPlanArgs {
@@ -96,8 +96,7 @@ export function resolveTemplateFile(raw: string, projectDir: string): TemplateFi
 
 export function registerPlanCommand(
   pi: ExtensionAPI,
-  sessions: PlanSessionMap,
-  controllers: PlanAbortControllers,
+  planCtx: PlanCtx,
 ): void {
   pi.registerCommand("plan", {
     description:
@@ -118,11 +117,11 @@ export function registerPlanCommand(
     handler: async (args: string, ctx: ExtensionContext) => {
       const trimmed = args.trim();
       const sessionId = ctx.sessionManager.getSessionId();
-      const state = getPlanState(sessions, sessionId, ctx);
+      const state = getPlanState(planCtx.states, sessionId, ctx);
 
       // Subcommand: abort
       if (trimmed === "abort") {
-        await handleAbort(pi, sessions, controllers, sessionId, ctx, state);
+        await handleAbort(pi, planCtx, sessionId, ctx, state);
         return;
       }
 
@@ -164,35 +163,26 @@ export function registerPlanCommand(
       }
 
       // Enter plan mode
-      handleEnterPlanMode(pi, sessions, sessionId, ctx, state, args);
+      handleEnterPlanMode(pi, planCtx, sessionId, ctx, state, args);
     },
   });
 }
 
-/** Handle /plan abort subcommand */
+/**
+ * Handle /plan abort subcommand——exit 链单入口（D-B1-1）的 command 路投影：
+ * 动作清单（解散挂起/转移落盘/widget/工具集恢复/反馈文案）全在 exitPlanMode 内，
+ * 本函数只把 ExitResult 投影为 notify。非活跃格全谱（idle/终态）统一 warn 纠偏
+ * 文案（原 isActive 前置守卫的 info no-op 已由单入口守卫极性取代，D-B1-1 行为变更）。
+ */
 async function handleAbort(
   pi: ExtensionAPI,
-  sessions: PlanSessionMap,
-  controllers: PlanAbortControllers,
+  planCtx: PlanCtx,
   sessionId: string,
   ctx: ExtensionContext,
   state: PlanState,
 ): Promise<void> {
-  if (!state.isActive) {
-    ctx.ui.notify("No active plan mode.", "info");
-    return;
-  }
-  // E10 顺序不可反（因果链）：controller.abort() → 挂起 select resolve undefined →
-  // tool execute 走「已取消」分支返回 → turn 正常结束 → agent_settled 到达 →
-  // busy defer 队列恢复投递。若先 reset 后 abort，挂起 select 无人 resolve 且
-  // runtime 不超时 → pi turn 永占用 → 后续消息永 defer → session 只能 forceQuit。
-  controllers.get(sessionId)?.abort();
-  controllers.delete(sessionId);
-  const updatedState = resetPlanState(pi, sessions, sessionId, ctx);
-  updatePlanWidget(ctx, updatedState);
-  // Restore full tool set (SDK does NOT support undefined)
-  pi.setActiveTools(pi.getAllTools().map((t: { name: string }) => t.name));
-  ctx.ui.notify("Plan mode aborted.", "info");
+  const result = exitPlanMode(pi, planCtx, sessionId, ctx, state, "command");
+  ctx.ui.notify(result.message, result.level);
 }
 
 /** Handle /plan status subcommand */
@@ -270,7 +260,7 @@ function reportTemplateFlagError(pi: ExtensionAPI, problem: string): void {
 /** Handle entering plan mode */
 function handleEnterPlanMode(
   pi: ExtensionAPI,
-  sessions: PlanSessionMap,
+  planCtx: PlanCtx,
   sessionId: string,
   ctx: ExtensionContext,
   state: PlanState,
@@ -312,7 +302,14 @@ function handleEnterPlanMode(
   // --skills E1 校验（互斥已判过后，走到这里 templatePath 必为 undefined）
   const requested = parsed.skills ?? [];
   if (parsed.skills !== undefined && requested.length === 0) {
-    reportUnknownSkills(pi, { ok: false, available: pi.getCommands().filter((c) => c.source === "skill").map((c) => c.name), missing: [] });
+    // 空 --skills 报错复用 resolveSkills 单源（C1 去重：空请求 → ok:false + 全量
+    // available + 空 missing，报错文案不变）。TS 无法静态收窄「空请求恒 ok:false」，
+    // 运行时 fail-fast 承载该不变量（tool.ts switch default 不可达断言同风格）
+    const failed = resolveSkills(pi, requested);
+    if (failed.ok) {
+      throw new Error("plan: empty --skills must fail skill resolution (invariant)");
+    }
+    reportUnknownSkills(pi, failed);
     return;
   }
   let resolved: SkillRef[] = [];
@@ -329,7 +326,7 @@ function handleEnterPlanMode(
   // 进入核心收敛到 enter.ts（plan(enter) tool 与 slash 命令共用）；本入口只负责
   // flag 解析/校验（上方）与提示词投递（下方 sendMessage custom message 注入）。
   // state 由 activatePlanMode 就地改 + persist（getPlanState 缓存同一对象）。
-  const { prompt } = activatePlanMode(pi, sessions, sessionId, ctx, {
+  const { prompt } = activatePlanMode(pi, planCtx.states, sessionId, ctx, {
     requirement,
     skills: resolved,
     projectDir: ctx.cwd,

package/src/enter.ts

@@ -3,53 +3,21 @@ import * as path from "node:path";
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
+// 技能执行门禁（resolveSkills + SkillResolution）单源在 ADR-0074 共享包
+// @zhushanwen/pi-exec-skills（plan-mode-audit-remediation 批次 4②b 迁入，含空请求
+// fail-fast 契约）；经此处 re-export 维持既有消费路径（tool.ts / command.ts / 测试
+// import "./enter.js"）不动
+export { resolveSkills } from "@zhushanwen/pi-exec-skills";
+export type { SkillResolution } from "@zhushanwen/pi-exec-skills";
+
 import { buildPlanModePrompt } from "./prompts.js";
 import type { SkillRef } from "./prompts.js";
 import type { PlanSessionMap, PlanState } from "./state.js";
-import { capPlanRequirement, getPlanState, persistPlanState, PLAN_MODE_TOOLS } from "./state.js";
+import { applyPlanEvent, capPlanRequirement, clearRoundFields, getPlanState, persistPlanState, PLAN_MODE_TOOLS } from "./state.js";
 import { updatePlanWidget } from "./widget.js";
 
 export const MAX_SLUG_LENGTH = 30;
 
-/** E1 技能解析结果：ok=false 时携带缺失项与可用清单（fail-fast 回复的材料） */
-export type SkillResolution =
-  | { ok: true; resolved: SkillRef[] }
-  | { ok: false; available: string[]; missing: string[] };
-
-/**
- * 技能名归一：剥掉 pi 命令命名空间前导 `skill:` 前缀，得到自然技能名。
- * pi.getCommands() 枚举 skill 类命令时 name 带 `skill:` 前缀（如 `skill:tech-design`），
- * 这是 pi 的实现细节，不得泄漏到输入面——slash `--skills` 与 plan(enter) 的 skills 参数
- * 都用自然技能名。枚举侧与输入侧双向剥前缀后比对，兼容两种形态。
- */
-export function normalizeSkillName(name: string): string {
-  return name.startsWith("skill:") ? name.slice("skill:".length) : name;
-}
-
-/**
- * E1 校验：pi.getCommands() 过滤 source === "skill" 枚举比对（技能枚举与路径
- * 经 pi 取得，不自扫描目录——D2）。比对前双向剥 `skill:` 前缀归一：resolved/missing
- * 用归一后的短名；available 维持枚举原形态（错误信息里可直接复制为 pi 命令）。
- * slash 命令与 plan(enter) tool 两入口共用（自 command.ts 迁入 enter.ts）。
- */
-export function resolveSkills(pi: ExtensionAPI, requested: string[]): SkillResolution {
-  const skillCommands = pi.getCommands().filter((c) => c.source === "skill");
-  const byShortName = new Map(skillCommands.map((c) => [normalizeSkillName(c.name), c.sourceInfo.path]));
-  const available = skillCommands.map((c) => c.name);
-  const resolved: SkillRef[] = [];
-  const missing: string[] = [];
-  for (const raw of requested) {
-    const name = normalizeSkillName(raw);
-    const skillPath = byShortName.get(name);
-    if (skillPath === undefined) {
-      missing.push(name);
-    } else {
-      resolved.push({ name, skillPath });
-    }
-  }
-  return missing.length > 0 ? { ok: false, available, missing } : { ok: true, resolved };
-}
-
 /** 进入 plan 模式的归一入参（slash 命令与 plan(enter) tool 两入口共用） */
 export interface ActivatePlanModeInput {
   requirement: string;
@@ -80,7 +48,8 @@ export interface ActivatePlanModeOutcome {
  * 副作用顺序钉死：状态字段 → persistPlanState（entry 落盘）→ updatePlanWidget →
  * setActiveTools → 构造 prompt。persist 先于工具收拢，保证「已持久 isActive 但工具未收」
  * 的半进入态不可达（崩溃窗口内重开 session 经 entry 恢复 isActive，session_start hook
- * 会补 setActiveTools）。
+ * 会补 setActiveTools）。生命周期写唯一通道 = applyPlanEvent('enter')（D1：idle|终态
+ * --enter--> planning 新一轮）。
  */
 export function activatePlanMode(
   pi: ExtensionAPI,
@@ -104,17 +73,29 @@ export function activatePlanMode(
   state.planFilePath = planFilePath;
   // state/entry/plan 帧侧 requirement 64KB 封顶（帧有界前提）；prompt 仍用未封顶全文直达模型
   state.requirement = capPlanRequirement(requirement);
-  // --template 直传：templateName = 去扩展名 basename（GUI / /plan status 展示）；
-  // 直传事实另落 templateProvidedPath（select-template 防御的判定信号，D7）
-  state.templateName = input.template ? path.basename(input.template.absPath, ".md") : "";
-  state.templateProvidedPath = input.template?.absPath;
+  // --template 直传：templateName = 去扩展名 basename（GUI / /plan status 展示，值域不变）；
+  // 直传事实落独立布尔字段 templateProvided（select-template 防御的判定信号，D7——
+  // 双字段合并后的形态，双向版本错配登记见 PlanState.templateProvided 注释）
+  if (input.template) {
+    state.templateName = path.basename(input.template.absPath, ".md");
+    state.templateProvided = true;
+  } else {
+    state.templateName = "";
+    delete state.templateProvided;
+  }
   state.skills = skills.map((s) => s.name);
   state.docs = [];
-  // 新轮次重置：reviewState、来源标记与指纹基线随进入失效（与 resetPlanState 对齐；
-  // reviewStateSource 残留会让新一轮降级态渲染上一轮来源文案——C-U2 同型残留）
-  delete state.reviewState;
-  delete state.reviewStateSource;
-  delete state.lastSubmitReviewDocsFingerprint;
+  // 新轮次重置：per-round 字段随进入失效（D4 单函数出口，与 resetPlanState 同源——
+  // 跨轮残留会误触新鲜度门 / 渲染上一轮降级文案（C-U2 同型残留））
+  clearRoundFields(state);
+
+  // 状态写走 transition()（D1 'enter' 边：idle|终态
+  // --enter--> planning 新一轮）。不一致格 isActive=false 且 state 落活跃族
+  //（仅坏数据/旧映射残留可达，P-6 单写入方下正常不可达）按 ok:false 落穿：不归一、不重试，
+  // 后续副作用照常（persist 携带现值）——原「归一 idle 再进」自愈分支已随
+  // plan-mode-audit-remediation 批次 3 删除（行为变更仅坏数据格可达，V5 对账归垃圾格口径）；
+  // 正常路径恒单通道 applyPlanEvent。
+  applyPlanEvent(state, "enter");
 
   persistPlanState(pi, state);
   updatePlanWidget(ctx, state);

package/src/{compact.ts → execution-notice.ts}

@@ -1,65 +1,25 @@
+/**
+ * plan complete 后的执行通知投递 + goal 桥。
+ *
+ * execute 档经 goal 桥 slot 注册执行跟踪（失败显式化五出口，不阻断执行），
+ * steer 指令承载执行方式裁决（goal 工作流 / skill / 直接执行三形态）。
+ * 压缩/分叉时的 plan 摘要由 pi 内置压缩机制承载（确定性文件操作清单 +
+ * keepRecentTokens 近端原文保留），本扩展不再接管压缩摘要。
+ */
 import * as fs from "node:fs";
-import { basename } from "node:path";
+import { basename, dirname } 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 { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import type { GoalInitFn } from "@zhushanwen/pi-goal";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
 import { t } from "./i18n.js";
-import type { PlanSessionMap, PlanState } from "./state.js";
-import { PLAN_CONTEXT_CUSTOM_TYPE, getPlanState } from "./state.js";
+import type { PlanState } from "./state.js";
+import { PLAN_CONTEXT_CUSTOM_TYPE } from "./state.js";
 
 const logger = getLogger("pi-plan");
 
-export function registerPlanEventHandlers(
-  pi: ExtensionAPI,
-  sessions: PlanSessionMap,
-): void {
-  pi.on("session_before_compact", async (event: SessionBeforeCompactEvent, ctx: ExtensionContext) => {
-    const sessionId = ctx.sessionManager.getSessionId();
-    const state = getPlanState(sessions, sessionId, ctx);
-    if (!state.isActive) return {};
-
-    const prep = event.preparation;
-
-    // Read plan file content for recovery after compact
-    const planContent = readPlanFileSafe(state.planFilePath);
-
-    // handler 已有 isActive 门——能走到这里的 plan 必然进行中（D6：phase 删除，原 phase="complete" 分支为死状态）
-    const progressNote = "\nPlan was in progress — review and continue.";
-
-    return {
-      compaction: {
-        summary:
-          `Plan mode active. Plan file: ${state.planFilePath}\n\n` +
-          `## Plan Content\n${planContent}\n\n` +
-          `Requirement: ${state.requirement}` +
-          progressNote,
-        firstKeptEntryId: prep?.firstKeptEntryId,
-        tokensBefore: prep?.tokensBefore,
-      },
-    };
-  });
-
-  pi.on("session_before_tree", async (_event: SessionBeforeTreeEvent, ctx: ExtensionContext) => {
-    const sessionId = ctx.sessionManager.getSessionId();
-    const state = getPlanState(sessions, sessionId, ctx);
-    if (!state.isActive) return {};
-
-    const planContent = readPlanFileSafe(state.planFilePath);
-
-    return {
-      summary: {
-        summary:
-          `Plan mode active. Plan file: ${state.planFilePath}\n\n` +
-          `## Plan Content\n${planContent}\n\n` +
-          `Read the plan file and execute the implementation.`,
-      },
-    };
-  });
-}
-
 /** Read plan file: ok=false 是显式信号（GoalBridgeOutcome 的 plan-unreadable 出口消费），消除哨兵字符串比较 */
 type PlanFileContent = { ok: true; content: string } | { ok: false };
 
@@ -71,12 +31,6 @@ function readPlanFile(planFilePath: string): PlanFileContent {
   }
 }
 
-/** Read plan file, return content or human-readable marker (for prompt embedding) */
-function readPlanFileSafe(planFilePath: string): string {
-  const result = readPlanFile(planFilePath);
-  return result.ok ? result.content : "(plan file could not be read)";
-}
-
 /**
  * goalInit slot key——goal 扩展的跨扩展编程式入口（goal-bridge-cross-extension.md）。
  * ⚠️ 必须与 `extensions/universal/goal/src/index.ts` 的 GOAL_INIT_SLOT_KEY 字符串完全一致：
@@ -87,7 +41,6 @@ const GOAL_INIT_SLOT_KEY = Symbol.for("@zhushanwen/pi-goal.goalInit");
 
 /**
  * goal 桥的单一断言点：goal 扩展挂在 globalThis slot 上的编程式接口（发现 7——
- * 此前 detectGoalCapability / tryGoalInit 两处 inline 断言收敛于此；
  * 桥通道从 pi API 对象挂载迁到 slot：pi 0.84.4 per-extension API 隔离使
  * pi.__goalInit 形态跨扩展恒不可见，slot 是 C-ext-06 惯例的进程级共享形态）。
  */
@@ -96,18 +49,16 @@ function getGoalInit(): GoalInitFn | undefined {
   return typeof fn === "function" ? (fn as GoalInitFn) : undefined;
 }
 
-/** Detect whether goal extension is available via its programming interface */
-export function detectGoalCapability(): boolean {
-  return getGoalInit() !== undefined;
-}
-
 /**
- * 从 plan 文件路径推导 goal slug（kebab-case；无有效字符时 fallback）。
- * 仅 widget 标题 + history 展示用，不注入 prompt。
+ * goal 桥侧 slug（仅 widget 标题 + history 展示用，不注入 prompt）。生产输入恒为
+ * <project>/.tmp/plans/<slug>/plan.md（enter.ts 构造）——展示名取目录名（requirement
+ * slug 段，2026-09-27 用户裁决；已归档缺陷档案（plan-cjk-slug-data-loss） 缺陷 3 同源修复）。
+ * kebab 链对 enter slug 幂等，只防 planFilePath 非生产形态的通用输入；提取为空回
+ * "plan-execution"。中文需求且缺陷 2（enter 期目录唯一性）未修的窗口内，plan.md 直落
+ * .tmp/plans 使本函数取到骨架名 "plans"——该形态随缺陷 2 修复消除。
  */
 function buildPlanSlug(planFilePath: string): string {
-  const stem = basename(planFilePath)
-    .replace(/\.md$/i, "")
+  const stem = basename(dirname(planFilePath))
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, "-")
     .replace(/^-+|-+$/g, "");
@@ -137,12 +88,12 @@ function truncatePreview(text: string): string {
  * 从 plan 步骤构造可检查的 successCriteria（plan 完成 = 所有步骤执行并验证）。
  * goal 的 complete 判定会对照本字段逐条做证据审计。
  *
- * 形态固定：1 条总述 `All N steps of <basename> executed and verified`
+ * 形态固定：1 条总述 `All N steps of <plan slug> executed and verified`
  * + 前 PREVIEW_COUNT 条 step preview（编号前缀、单条截断 ≤PREVIEW_MAX_CHARS），
  * 合计 ≤4 条（goal schema maxItems:8），每条单行不含 \r\n。
  */
 export function buildPlanSuccessCriteria(planFilePath: string, tasks: string[]): string[] {
-  const planName = toSingleLine(basename(planFilePath).replace(/\.md$/i, ""));
+  const planName = toSingleLine(buildPlanSlug(planFilePath));
   const items = [`All ${tasks.length} steps of ${planName} executed and verified`];
   const previews = tasks
     .slice(0, PREVIEW_COUNT)
@@ -260,7 +211,7 @@ function deliverExecutionNotice(
   skillEntryPath?: string,
 ): GoalBridgeOutcome | undefined {
   // execute 档整合 goal 桥：tryGoalInit 内部含 goal-unavailable gate（goal 未挂载走
-  // started:false 降级），无需前置 detectGoalCapability 探测
+  // started:false 降级），无需前置探测
   const outcome = execMode === "execute" ? tryGoalInit(planFilePath, ctx) : undefined;
 
   let modeHint: string;
@@ -297,58 +248,19 @@ function deliverExecutionNotice(
 }
 
 /**
- * complete 的 isolation 分发（D1 后仅 compact | direct，两档都投递执行通知）。
+ * complete 后的执行通知投递（plan-mode-audit-remediation D-B1-6：执行前压缩档
+ * 砍除——原 compact | direct 两档分发退化为单一直接投递路径）。
  *
- * 返回值：execMode=execute 且 isolation=direct 时同步返回 goalInit 的 outcome
- * （executeComplete 写进 result content 与 details）；其余情形返回 undefined——
- * skill 档无 goalInit，compact 档 goalInit 在 onComplete 回调内执行（goal 状态
- * entry 须在压缩后的世界里创建，提前到 compact 前有被压缩边界丢弃的风险，时序
- * 不动——设计 §6.2 D2），该档 result 已返回，失败报告走 steer + notify 通道。
+ * 返回值：execMode=execute 时同步返回 goalInit 的 outcome（executeComplete 写进
+ * result content 与 details）；skill 档无 goalInit，返回 undefined——该档 result
+ * 已返回，失败报告走 steer + notify 通道。
  */
 export function handlePlanComplete(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
   state: PlanState,
-  isolation: string,
   execMode: string,
   skillEntryPath?: string,
 ): GoalBridgeOutcome | undefined {
-  const planFilePath = state.planFilePath;
-
-  switch (isolation) {
-    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: () => {
-          guardStaleCtx(() => {
-            deliverExecutionNotice(pi, ctx, planFilePath, execMode, skillEntryPath);
-          }, {
-            label: "plan:compact-onComplete",
-            onStale: (error) => logger.warn("plan execution notice delivery skipped (stale ctx)", { error: toErrorMessage(error) }),
-          });
-        },
-        onError: (_error: Error) => {
-          guardStaleCtx(() => {
-            ctx.ui.notify("Compact failed, continuing without isolation.", "warning");
-            deliverExecutionNotice(pi, ctx, planFilePath, execMode, skillEntryPath);
-          }, {
-            label: "plan:compact-onError",
-            onStale: (error) => logger.warn("plan execution notice delivery skipped (stale ctx)", { error: toErrorMessage(error) }),
-          });
-        },
-      });
-      return undefined;
-    }
-
-    case "direct":
-    default: {
-      return deliverExecutionNotice(pi, ctx, planFilePath, execMode, skillEntryPath);
-    }
-  }
+  return deliverExecutionNotice(pi, ctx, state.planFilePath, execMode, skillEntryPath);
 }