@zhushanwen/pi-plan 0.4.9 → 0.5.0

package/README.md

@@ -1,35 +1,63 @@
 # @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）。
+轻量级规划模式 pi extension：`/plan [描述]` 触发，只读探索并产出结构化计划文档。与 coding-workflow 的区别：无 gate / review / retrospect，只负责「想清楚再动手」的计划产出（ADR pi-ext-021 prompt-only readonly / pi-ext-022 session-manager state）。
 
 ## 用法
 
 ```
-/plan 修复项目中所有失败的测试   # 进入 plan mode（brainstorming 阶段开始）
-/plan status                    # 查看当前阶段与 plan 文件路径
-/plan abort                     # 取消活跃的 plan mode
+/plan 修复项目中所有失败的测试                      # 进入 plan mode（模板流程）
+/plan 重构 auth 模块 --skills tech-design,dev-flow  # 进入 plan mode（挂载技能流程）
+/plan 复盘事故 --template ~/docs/retro.md           # 进入 plan mode（直传模板文件）
+/plan status                                       # 查看状态、技能与产物清单
+/plan abort                                        # 取消活跃的 plan mode
 ```
 
-## 阶段状态机
+`--skills` 接受逗号分隔的技能名（按逗号原样切分 + 去首尾空格，含中文/内部空格的技能名不丢字符）。技能名经 `pi.getCommands()` 的 `source === "skill"` 枚举校验，不存在则不进入计划模式并回复可用技能清单。未指定 `--skills` 时回落模板流程。
 
-`idle → brainstorming → writing → complete`（`state.ts` PlanPhase）：
+`--template <path>` 直传任意外部 md 文件作模板（与 `--skills` 互斥，同给 fail-fast）：`~` 前缀展开、含空格路径无需引号（flag 后整段即路径）；文件不存在 / 非 .md 分别报错（不进入计划态）。进入后提示词内嵌该文件全文且不注入模板清单段，无需 select-template。
 
-- **brainstorming**：需求探索。固定四步——1. Quick Overview（ls 项目根 / 读 README / package.json，30 秒内建立上下文）→ 2. 渐进式提问澄清需求 → 3. 方案探索 → 4. 假设审计。
-- **writing**：选定模板后撰写 plan 文件。
-- **complete**：完成时提示选择执行方式，恢复工具，状态重置。
+## 计划态生命周期
+
+进入后 agent 限只读工具集（read/bash/grep/find/ls/plan），按注入提示词产出文档：
+
+- **技能流程**（挂载 `--skills`）：按技能 SKILL.md 流程产出文档（AI 自行 read 技能文件）。
+- **模板流程**（未挂载）：从三源发现的模板清单中选型后撰写 plan.md（见下节）。
+
+文档全部就绪后调 `submit-review` 提交审阅；taiji rpc 宿主（`TAIJI_AGENT_EXT_LOG=1` 且 rpc 模式）挂 `PLAN_REVIEW_MARKER` select 弹 GUI 审批（approve 确认执行 / revise 提交评论修订，取消走 dismiss 非批准），独立 pi / 非 rpc 形态返回文本软门（对话中反馈评论，满意后调 `complete`）。
 
 ## plan 工具
 
-模型经 `plan` tool 驱动阶段流转，actions：`list-template` / `select-template` / `create-template` / `complete` / `complete-cancelled` / `abort`。
+模型经 `plan` tool 驱动状态流转，actions 六项：`enter` / `select-template` / `register-doc` / `submit-review` / `complete` / `abort`。
+
+- `register-doc`：登记一份产物文档（同 fileName 重登 = version+1 覆盖），供 GUI 产物 tab 展示与内容刷新。
+- `submit-review`：全部文档就绪后请求审阅。docs 为空或计划态已退出时返回错误提示（E6 双守卫）。
+- `complete`：先弹执行方式选择（GUI 宿主经统一表单协议单 choice 问题）。选项 = 自动检测的 plan-exec skill 档（≤2 个，label `Execute via skill: <name>`）+ Execute 档（goal 跟踪已整合：可用时先建 goal 跟踪，再按复杂度派发 subagent 并行、小步/紧耦合本会话直执）+ 暂不执行（Not now，留在 plan mode）。headless 无 UI 默认 execute 不弹选择；通道失败（channel-error / non-json）与用户取消同折叠为 complete-cancelled result，留在 plan mode 不炸 turn。
+- `abort`：直接退出。两者退出后恢复工具集；状态落 isActive=false + docs 保留（产物跨重开留存）。
+
+## 执行方式与 plan-exec skill
+
+`complete` 选项中的 skill 档来自运行时自动检测：skill 作者在 SKILL.md frontmatter 标记 `plan-exec: true`，该 skill 即被提议为执行方式（label `Execute via skill: <name>`）。检测对过 description 必填门的 skill 二次读 frontmatter 判定；`disable-model-invocation` 与 plan-exec 并存不过滤。
+
+四根扫描（单根枚举复用 pi 公开导出的 `loadSkillsFromDir`，跨根组装同构 pi 本体加载序）：project `.pi/skills` → 祖先链 `.agents/skills`（近→远，git root 级含）→ `<agentDir>/skills` → `~/.agents/skills`；同名 first-writer-wins + realPath 去重；untrusted 项目跳过前两族。complete 时现扫无缓存（技能热装即见）。
+
+检测失败降级为空集，绝不炸 complete 交互闭环：每根 existsSync 守卫 + 整根 try/catch（EACCES 等 fs 错 → 跳过该根 + warn），单 skill frontmatter 读/解析失败跳过该项。
 
 ## Plan File
 
-Plan Mode 的产出物，存储在 `.taiji-harness/{slug}/plan.md`（slug 截断 30 字符）。含 YAML frontmatter 与模板章节。进入 plan mode 时自动扫描既有 plan 文件供续写。
+模板流程的产出物，存储在 `.taiji-harness/{slug}/plan.md`（slug 截断 30 字符）。含 YAML frontmatter 与模板章节。进入 plan mode 时自动扫描既有 plan 文件供续写。技能流程的产物文档同写在该目录下，经 `register-doc` 登记。
 
 ## 模板
 
-内置 5 个（`templates/`）：`feature-plan` / `bugfix-plan` / `refactor-plan` / `implementation-plan` / `research-plan`。支持项目自定义模板（`listTemplates` / `loadTemplate` 按 projectDir 发现）。
+三源发现（同名 last-writer-wins，项目 > 用户 > 内置）：
+
+1. **内置**（包内 `templates/`）：`feature-plan` / `bugfix-plan` / `refactor-plan` / `implementation-plan` / `research-plan`
+2. **用户级** `~/.agents/plans/*.md`：个人模板投放点
+3. **项目级** `<project>/.agents/plans/*.md`：项目/团队模板投放点（项目级覆盖用户级覆盖内置）
+
+进入计划态时全量清单以 `<available-plans>` 段随提示词一次性注入（name + location），模型自选后调 `select-template`——返回的 content 携带胜者文件全文（章节骨架直达，无需再 read）；错名报错自带可用清单，模型当场自愈。`--template <path>` 直传时跳过选型（见用法节）。
+
+**goal 桥结构建议**：自定义模板（含直传文件）建议包含 `## Implementation Steps` 编号步骤节——`complete` 选 Execute 档且 goal 跟踪可用时，步骤提取（`extractPlanSteps` 正则）硬依赖该节；无该节会退化到 fallback（扫全部编号项，可能收进其他节噪音）或提取失败（no-steps 启动失败，有恢复文案）。
 
 ## 依赖
 
-peer 依赖 `@zhushanwen/pi-goal`（plan 完成后衔接 goal 驱动执行）。
+依赖：`@zhushanwen/extension-protocol`（PLAN_REVIEW_MARKER + PlanReviewRequest/Response 契约 + ui-form（`uiFormInteract` / `FormQuestion`，统一提问表单协议），dependencies）；peer 依赖：`@zhushanwen/pi-goal`（plan 完成后衔接 goal 驱动执行）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-plan",
-  "version": "0.4.9",
+  "version": "0.5.0",
   "description": "Lightweight plan mode for Pi coding agent",
   "type": "module",
   "main": "index.ts",
@@ -10,6 +10,9 @@
   "pi": {
     "extensions": [
       "./index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "keywords": [
@@ -18,12 +21,16 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.73.0",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
     "typebox": "*",
     "@earendil-works/pi-ai": "^0.84.4",
-    "@zhushanwen/pi-goal": "0.14.5"
+    "@zhushanwen/pi-goal": "0.14.6"
   },
   "peerDependenciesMeta": {
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
     "@earendil-works/pi-ai": {
       "optional": true
     },
@@ -32,18 +39,21 @@
     }
   },
   "devDependencies": {
+    "@earendil-works/pi-tui": "^0.84.4",
     "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8"
   },
   "files": [
     "index.ts",
     "src/",
+    "skills/",
     "templates/"
   ],
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.12.0",
+    "@zhushanwen/extension-protocol": "0.13.0",
     "@zhushanwen/pi-ext-guards": "0.4.1",
-    "@zhushanwen/pi-extension-logger": "0.6.1"
+    "@zhushanwen/pi-extension-logger": "0.6.1",
+    "@zhushanwen/pi-llm-shared": "0.9.0"
   },
   "scripts": {
     "typecheck": "npx tsc --noEmit",

package/skills/plan-ext-config/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: plan-ext-config
+description: "使用或排查 @zhushanwen/pi-plan（计划模式 plan mode）时加载。说明 /plan 命令用法（--skills / --template / status / abort）、plan 工具六 action（enter / select-template / register-doc / submit-review / complete / abort）、审阅两键裁决（approve / revise）、执行方式选项集（plan-exec skill 检测 + Execute + 暂不执行）、数据存储模型（session JSONL 的 plan-state entry，无独立配置文件）、reviewState 崩溃恢复语义。触发词：plan mode、计划模式、/plan、plan 工具、submit-review、register-doc、plan-state、计划文档登记、审阅挂起、计划模式排查、plan-ext-config。"
+---
+
+# plan 使用与存储指南
+
+> @zhushanwen/pi-plan：轻量计划模式扩展。进入后 agent 限只读工具集（read/bash/grep/find/ls/plan），只读探索并产出计划文档，用户审阅批准后才进入实施——「想清楚再动手」。
+
+**重要前提**：plan **没有独立的配置文件**。计划态以 append-only 方式存储在 session JSONL 的 `plan-state` custom entry 中（见下文「数据存储位置」）。排查「plan 状态存哪 / 重启后为什么还在计划态 / 审阅挂起怎么恢复」都必须基于此模型理解，不要去找独立的 plan 配置文件。
+
+## 如何进入/退出计划模式
+
+### 1. `/plan` slash 命令（用户输入）
+
+| 用法 | 作用 |
+|------|------|
+| `/plan <需求>` | 进入计划模式（模板流程） |
+| `/plan <需求> --skills a,b` | 进入计划模式（挂载技能流程，技能名经 pi 已加载技能枚举校验，未知名不进入并回复可用清单） |
+| `/plan <需求> --template <path>` | 进入计划模式（直传任意外部 md 作模板；`~` 前缀展开；与 `--skills` 互斥 fail-fast） |
+| `/plan status` | 查看状态、技能与产物清单 |
+| `/plan abort` | 取消活跃的 plan mode |
+
+无参 `/plan`：活跃时显示 status；非活跃时扫描 `.tmp/plans/` 下既有 plan 文件，找到则让用户选择继续/实施/新建。
+
+### 2. `plan` tool（AI 调用，六 action）
+
+- **`enter`**：agent 自助进入（无需用户确认——plan mode 只读无害，进入事实经 GUI PlanModeBar 显形，用户随时可退出）。参数 `requirement` + 可选 `skills`。
+- **`select-template`**：模板流程选型（`--template` 直传后调用会报错）。返回 content 携带胜者模板全文；错名报错自带可用清单自愈。
+- **`register-doc`**：登记一份产物文档（参数 `fileName` 必须是 plan 目录内纯文件名，路径分隔符/`..` 被拒；同 fileName 重登 = version+1 原位覆盖，UI tab 顺序不跳动）。absPath 由扩展从 plan 目录推导，不信任 LLM 申报路径。
+- **`submit-review`**：全部文档就绪后请求审阅（docs 为空或已退出计划态返回错误提示，不挂交互）。
+- **`complete`**：用户 approve 后退出计划态，先弹执行方式选择（见下节）。
+- **`abort`**：直接退出。
+
+退出（complete/abort）恢复完整工具集；`plan-state` 落 isActive=false，docs 清单保留（产物文档跨重开可回看，至下次 /plan 同 slug 覆写）。
+
+## 审阅闭环（submit-review → 两键裁决）
+
+- **taiji rpc 宿主**（`TAIJI_AGENT_EXT_LOG=1` 且 `mode==='rpc'`）：挂 `PLAN_REVIEW_MARKER` select 弹 GUI 审批条，用户两键裁决——**approve**（确认执行，自动走 complete 流程）/ **revise**（提交 `{quote, comment}[]` 评论，注入对话要求修订）。取消（dismiss）非批准：result 明确禁止实施、停止审批循环等用户指示。
+- **独立 pi / 非 rpc 形态**：文本软门——result 指示 agent 请用户直接在对话中反馈；用户满意确认后 agent 调 `complete`。
+- **修订闭环**：revise 后逐条评论 rewrite 文件 + 重新 `register-doc`（version+1），全部处理完再调 `submit-review` 重挂，循环直至 approve。
+- **重提交无变化检测**：上次 submit-review 后无任何 register-doc（docs 指纹相同）再次 submit-review 时，result 末行追加确定性警告，提示必须先 rewrite + re-register。
+
+## 执行方式选项集（complete 时）
+
+选项 = **≤2 个检测到的 plan-exec skill 档**（label `Execute via skill: <name>`）+ **Execute 档** + **暂不执行（Not now）**：
+
+- **plan-exec skill 档**：skill 作者在 SKILL.md frontmatter 标记 `plan-exec: true` 即被提议。四根扫描（project `.pi/skills` → 祖先链 `.agents/skills` → `<agentDir>/skills` → `~/.agents/skills`，同构 pi 本体加载序，untrusted 项目跳过前两族），root 序同名 first-writer-wins，取前 2 个。complete 时现扫无缓存（技能热装即见）；检测失败降级为空集，绝不阻断交互。
+- **Execute 档**：goal 跟踪已整合——goal 扩展可用时先建 goal 跟踪（`/goal`），再按复杂度执行：独立可并行任务派发 subagent、小步/紧耦合在本会话直执；goal 不可用/启动失败降级为直接执行（notify 提示 + result 带恢复动作）。
+- **暂不执行**：留在 plan mode，不派发实施。
+
+headless（json/print 无 UI）默认 execute 不弹选择；通道失败（channel-error / non-json）与用户取消同折叠为 complete-cancelled result，留在 plan mode 不炸 turn。
+
+**goal 桥结构建议**：计划文档建议包含 `## Implementation Steps` 编号步骤节——Execute 档的 goal 步骤提取硬依赖该节；缺失会退化 fallback（扫全部编号项）或提取失败（no-steps，有恢复文案）。
+
+## 数据存储位置（排查必读）
+
+**当前版本采用 session JSONL 的 append-only event sourcing，没有独立数据文件。**
+
+- 每次状态变更调 `pi.appendEntry('plan-state', {...})`，customType 固定为 `plan-state`；重建时取 session 内**最后一条** plan-state entry 为当前态（逐字段白名单降级读，旧版 entry 缺字段归一为空/无值）。
+- 字段：`isActive` / `planFilePath` / `requirement` / `templateName` / `templateProvidedPath`（--template 直传标记）/ `skills`（挂载技能名）/ `docs`（产物清单 `PlanDocMeta[]`：fileName + absPath + sourceSkill + version）/ `reviewState` / `lastSubmitReviewDocsFingerprint` / `reviewStateSource`。
+- **产物文档本体**写在 `<cwd>/.tmp/plans/<slug>/`（slug 截断 30 字符）——文档是普通文件，agent 经 bash 写入；`register-doc` 只登记元数据。未产任何文档即退出会清理空 slug 目录（非空一律保留）。
+- **模板三源发现**（同名 last-writer-wins，项目 > 用户 > 内置）：内置（包内 `templates/`，5 个）+ 用户级 `~/.agents/plans/*.md` + 项目级 `<project>/.agents/plans/*.md`。进入时清单以 `<available-plans>` 段一次性注入。
+
+## reviewState 崩溃恢复（E3）
+
+`reviewState` 两值：`awaiting`（submit-review 挂起前落盘）| `revising`（revise 消费后落盘）| 无值 = 进行中。挂起的交互（审批 select / 执行方式 form）随 pi 进程消亡，但持久态经 entry 存活：
+
+- session 重启（session_start）时若 `reviewState='awaiting'`：steer 指示 agent 重调 `submit-review` 重挂审批，并落 `reviewStateSource='resubmit'`（GUI 据此渲染「会话已重启，尚未重新提交」降级态；submit-review 重挂起时清空）。
+- `reviewState='revising'`：steer 指示继续按已注入的评论修订文档并重新提交。
+- 「approve 后执行方式选择窗口中断」不自动恢复（与探索期在持久态上不可区分，防误报），由用户重发消息自然恢复。
+
+## 排障
+
+- **submit-review 返回「taiji host does not understand the plan review marker」**：taiji 宿主版本过旧（select 回显 payload 的确定性识别）。不要重挂（会同样回显循环），指引升级 taiji 或固定 plan 扩展版本。
+- **submit-review 返回 cancelled**：用户 dismiss 或 plan mode 退出——非批准，禁止实施，等用户指示。
+- **重提交总带「no documents changed」警告**：必须先 rewrite 文件 + `register-doc`（version+1）再 submit-review，警告按 docs 指纹逐次检测。
+- **plan-exec skill 没出现在执行选项里**：确认 frontmatter 有 `plan-exec: true`（严格布尔 true，字符串 "true" 不算）；确认 skill 过了 pi 的 description 必填门且未被 settings overrides（`-`/`!`）禁用；untrusted 项目不扫 `.pi/skills` 与祖先链两族。
+- **goal 跟踪未启动（no-steps / plan-unreadable 等）**：result 文本带逐原因恢复动作（如补 `## Implementation Steps` 节后重调 complete）；goal 扩展未装时属正常降级（直接执行）。
+- **调试**：`TAIJI_AGENT_DEBUG=1` 后看 `~/.pi/agent/logs/` 下 `[pi-plan]` 前缀日志。
+
+## 备注
+
+- **宿主信号**：taiji runtime 对托管 pi 恒注入 `TAIJI_AGENT_EXT_LOG=1`（引导文案注入 + marker 交互判据之一）；marker 交互另需 `mode==='rpc'`，env 泄漏到独立 pi TUI 时回落文本软门（不挂乱码 select）。
+- **计划态工具白名单**：read / bash / grep / find / ls / plan——bash 在白名单内，文件写约束来自注入的计划模式提示词（产物只写 plan 目录）。
+- **无配置 schema 可编辑**：plan 的所有状态都由运行时命令/工具产生，没有可手动编辑的配置文件。

package/src/__tests__/command.test.ts

@@ -1,4 +1,7 @@
-import { beforeEach,describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// --template 直传注入的全文 fixture（vi.hoisted：vi.mock 工厂引用需先于模块体初始化）
+const TEMPLATE_FILE_FIXTURE = vi.hoisted(() => "# retro skeleton\n\n## Implementation Steps\n- step one\n");
 
 // Mock dependencies before importing
 vi.mock("node:fs", () => ({
@@ -6,6 +9,8 @@ vi.mock("node:fs", () => ({
   readdirSync: vi.fn(() => []),
   statSync: vi.fn(),
   existsSync: vi.fn(() => false),
+  // --template 直传的全文内嵌读取（v2b：prompts 分支消费）
+  readFileSync: vi.fn(() => TEMPLATE_FILE_FIXTURE),
 }));
 
 vi.mock("../widget.js", () => ({
@@ -13,15 +18,19 @@ vi.mock("../widget.js", () => ({
 }));
 
 import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-import { registerPlanCommand } from "../command.js";
+import { parsePlanArgs, registerPlanCommand, resolveTemplateFile } from "../command.js";
+import { 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 pi = {
     registerCommand: vi.fn((_name: string, def: { handler: (args: string, ctx: ExtensionContext) => Promise<void> }) => {
@@ -29,7 +38,8 @@ function createMocks() {
     }),
     appendEntry: vi.fn(),
     setActiveTools: vi.fn(),
-    sendUserMessage: vi.fn(),
+    sendMessage: vi.fn(),
+    getCommands: vi.fn(() => []),
     getAllTools: vi.fn(() => ALL_TOOL_NAMES.map((n) => ({ name: n }))),
   } as unknown as ExtensionAPI;
 
@@ -50,22 +60,30 @@ function createMocks() {
   return {
     pi,
     ctx,
+    controllers,
     getHandler: () => capturedHandler!,
   };
 }
 
+/** custom message 形态断言 helper（A2 三要素：customType/content/display + triggerTurn options；P1-P4 无 deliverAs） */
+function planContextMessage(content: unknown) {
+  return [{ customType: PLAN_CONTEXT_CUSTOM_TYPE, content, display: false }, { triggerTurn: true }];
+}
+
 describe("registerPlanCommand", () => {
   let pi: ExtensionAPI;
   let ctx: ExtensionContext;
   let handler: (args: string, ctx: ExtensionContext) => Promise<void>;
+  let controllers: Map<string, AbortController>;
 
   beforeEach(() => {
     vi.clearAllMocks();
     const mocks = createMocks();
     pi = mocks.pi;
     ctx = mocks.ctx;
+    controllers = mocks.controllers;
     const sessions = new Map();
-    registerPlanCommand(pi, sessions);
+    registerPlanCommand(pi, sessions, controllers);
     handler = mocks.getHandler();
   });
 
@@ -94,6 +112,31 @@ describe("registerPlanCommand", () => {
     expect((ctx as ReturnType<typeof createMocks>["ctx"]).ui.notify).toHaveBeenCalledWith("Plan mode aborted.", "info");
   });
 
+  it("abort 联动（E10）：controller.abort() 先于 resetPlanState 的 entry 落盘", 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);
+
+    await handler("abort", ctx);
+
+    // 挂起 select 被 abort（→ resolve undefined → tool execute 已取消分支 → turn 结束 → settled → busy defer 恢复）
+    expect(controller.signal.aborted).toBe(true);
+    // 顺序断言：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,
+    );
+    expect(resetCallIndex).toBeGreaterThanOrEqual(0);
+    expect(abortSpy.mock.invocationCallOrder[0]).toBeLessThan(
+      (pi.appendEntry as ReturnType<typeof vi.fn>).mock.invocationCallOrder[resetCallIndex],
+    );
+    // 注册表条目已清理
+    expect(controllers.has("test-session")).toBe(false);
+  });
+
   // --- status subcommand ---
 
   it("status: notifies 'No active plan mode' when idle", async () => {
@@ -122,17 +165,20 @@ describe("registerPlanCommand", () => {
     await handler("Implement User Auth", ctx);
 
     expect(fs.mkdirSync).toHaveBeenCalledWith(
-      "/tmp/test-project/.taiji-harness/implement-user-auth",
+      "/tmp/test-project/.tmp/plans/implement-user-auth",
       { recursive: true },
     );
     expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan"]);
-    expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.stringContaining("[PLAN MODE]"));
-    expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.stringContaining("Implement User Auth"));
+    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", {
       isActive: true,
-      planFilePath: "/tmp/test-project/.taiji-harness/implement-user-auth/plan.md",
+      planFilePath: "/tmp/test-project/.tmp/plans/implement-user-auth/plan.md",
       requirement: "Implement User Auth",
       templateName: "",
+      skills: [],
+      docs: [],
+      reviewState: undefined,
     });
   });
 
@@ -140,7 +186,7 @@ describe("registerPlanCommand", () => {
     await handler("Fix bug #123: 中文标题!", ctx);
 
     expect(fs.mkdirSync).toHaveBeenCalledWith(
-      expect.stringContaining("/.taiji-harness/fix-bug-123"),
+      expect.stringContaining("/.tmp/plans/fix-bug-123"),
       { recursive: true },
     );
   });
@@ -150,11 +196,50 @@ describe("registerPlanCommand", () => {
     await handler("", ctx);
 
     expect(fs.mkdirSync).toHaveBeenCalledWith(
-      "/tmp/test-project/.taiji-harness/untitled",
+      "/tmp/test-project/.tmp/plans/untitled",
       { recursive: true },
     );
   });
 
+  it("超长 requirement 进入：state/entry 按 64KB 封顶，提示词仍携带全文（MF-1-3）", async () => {
+    const huge = "x".repeat(MAX_PLAN_REQUIREMENT_LENGTH + 10000);
+    await handler(huge, ctx);
+
+    // entry（plan 帧数据源）封顶 + 省略标记
+    const entry = (pi.appendEntry as ReturnType<typeof vi.fn>).mock.calls[0][1] as { requirement: string };
+    expect(entry.requirement.length).toBeLessThan(huge.length);
+    expect(entry.requirement).toContain("characters omitted");
+    // 进入提示词携带全文直达模型（该通路由 message content 注册表登记兜底，不在此封顶）
+    const payload = (pi.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0]?.[0] as { content: string };
+    expect(payload.content.length).toBeGreaterThan(MAX_PLAN_REQUIREMENT_LENGTH);
+  });
+
+  it("进入新 plan 轮次清掉 entry 重建残留的指纹基线（重置清单与 resetPlanState 对齐，MF-1-4）", async () => {
+    // 旧版/异常 entry 形态：isActive=false 但指纹残留——重建进内存态后，新轮次进入
+    // 不得把它当「无变化」检测基线（否则首次 submit-review 误报 unchanged）
+    const staleCtx = {
+      ...ctx,
+      sessionManager: {
+        getSessionId: () => "test-session",
+        getEntries: () => [
+          {
+            type: "custom",
+            customType: "plan-state",
+            data: { isActive: false, lastSubmitReviewDocsFingerprint: "design.md:1" },
+          },
+        ],
+      },
+    } as unknown as ExtensionContext;
+
+    await handler("second round feature", staleCtx);
+
+    const entry = (pi.appendEntry as ReturnType<typeof vi.fn>).mock.calls.at(-1)?.[1] as {
+      lastSubmitReviewDocsFingerprint?: string;
+    };
+    expect(entry.lastSubmitReviewDocsFingerprint).toBeUndefined();
+    expect(entry.isActive).toBe(true);
+  });
+
   it("shows status when active with no args", async () => {
     await handler("my feature", ctx);
     vi.clearAllMocks();
@@ -170,4 +255,199 @@ describe("registerPlanCommand", () => {
       "info",
     );
   });
+
+  // --- --template 直传（D5：校验 + 解析 + 最小进入）---
+
+  /**
+   * 取第一条 sendMessage 的 content 文本（fail-fast 回复 / 进入提示词共用通道），
+   * 并断言 custom message 形态三要素（A2：customType/display + 无 deliverAs 时 triggerTurn）
+   */
+  function sentMessage(): string {
+    const calls = (pi.sendMessage as ReturnType<typeof vi.fn>).mock.calls;
+    expect(calls.length).toBeGreaterThan(0);
+    const [payload, options] = calls[0] as [{ content: string }, Record<string, unknown>];
+    expect(payload.customType).toBe(PLAN_CONTEXT_CUSTOM_TYPE);
+    expect(payload.display).toBe(false);
+    expect(options).toEqual({ triggerTurn: true });
+    return payload.content;
+  }
+
+  describe("--template via /plan handler", () => {
+    afterEach(() => {
+      // 还原默认 existsSync=false，避免路径实现泄漏到后续用例
+      vi.mocked(fs.existsSync).mockImplementation(() => false);
+    });
+
+    it("mutual exclusion with --skills: fail-fast — no entry, no tool restriction, both usage forms in reply", async () => {
+      await handler("复盘 --template tpl.md --skills a", ctx);
+
+      // 不进入计划模式（§3.1：不写 entry / 不限制工具 / 不注入计划提示词）
+      expect(pi.appendEntry).not.toHaveBeenCalled();
+      expect(pi.setActiveTools).not.toHaveBeenCalled();
+      expect(pi.sendMessage).toHaveBeenCalledOnce();
+      const message = sentMessage();
+      expect(message).toContain("--template and --skills are mutually exclusive");
+      expect(message).toContain("/plan <requirement> --skills a,b");
+      expect(message).toContain("/plan <requirement> --template <path>");
+    });
+
+    it("missing file: fail-fast reports resolved absolute path + usage sample", async () => {
+      // existsSync 默认 false（模块 mock 出厂实现）
+      await handler("复盘 --template tpl.md", ctx);
+      expect(pi.appendEntry).not.toHaveBeenCalled();
+      expect(pi.setActiveTools).not.toHaveBeenCalled();
+      const message = sentMessage();
+      expect(message).toContain("Template file not found: /tmp/test-project/tpl.md");
+      expect(message).toContain("e.g. /plan <requirement> --template /path/to/template.md");
+    });
+
+    it("existing non-markdown file: fail-fast reports 'Not a markdown file' (文案分家)", async () => {
+      vi.mocked(fs.existsSync).mockImplementation((p) => p === "/tmp/test-project/notes.txt");
+      await handler("复盘 --template notes.txt", ctx);
+      expect(pi.appendEntry).not.toHaveBeenCalled();
+      const message = sentMessage();
+      expect(message).toContain("Not a markdown file: /tmp/test-project/notes.txt");
+      expect(message).not.toContain("not found");
+    });
+
+    it("flag with no value: fail-fast (与 --skills 空值同款显式错误)", async () => {
+      await handler("复盘 --template", ctx);
+      expect(pi.appendEntry).not.toHaveBeenCalled();
+      const message = sentMessage();
+      expect(message).toContain("--template was given but no path followed it");
+    });
+
+    it("valid template: enters plan mode — basename + 直传分支（全文内嵌 + 清单段抑制，v2b 终态）", async () => {
+      vi.mocked(fs.existsSync).mockImplementation((p) => p === "/tmp/test-project/docs/retro-template.md");
+      await handler("retro meeting --template docs/retro-template.md", ctx);
+
+      expect(pi.appendEntry).toHaveBeenCalledWith(
+        "plan-state",
+        expect.objectContaining({
+          isActive: true,
+          requirement: "retro meeting",
+          templateName: "retro-template",
+          templateProvidedPath: "/tmp/test-project/docs/retro-template.md",
+          skills: [],
+        }),
+      );
+      expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan"]);
+      const prompt = sentMessage();
+      // 直传声明 + 全文内嵌（文件内容直达模型，不赌自发 read——D5）
+      expect(prompt).toContain("template was provided via --template");
+      expect(prompt).toContain("/tmp/test-project/docs/retro-template.md");
+      expect(prompt).toContain(TEMPLATE_FILE_FIXTURE);
+      expect(prompt).toContain("Do NOT call plan(action='select-template')");
+      // 清单段抑制：guide 行与「模板已指定」并存会诱导画蛇添足调 select-template
+      expect(prompt).not.toContain("<available-plans>");
+    });
+
+    it("spaced path with ~ prefix: whole-segment value + homedir expansion reach validation and entry", async () => {
+      const spacedAbs = path.join(os.homedir(), "my plans", "retro template.md");
+      vi.mocked(fs.existsSync).mockImplementation((p) => p === spacedAbs);
+      await handler("retro --template ~/my plans/retro template.md", ctx);
+
+      expect(pi.appendEntry).toHaveBeenCalledWith(
+        "plan-state",
+        expect.objectContaining({ isActive: true, templateName: "retro template", templateProvidedPath: spacedAbs }),
+      );
+      const prompt = sentMessage();
+      expect(prompt).toContain(spacedAbs);
+      expect(prompt).toContain(TEMPLATE_FILE_FIXTURE);
+    });
+  });
+});
+
+describe("parsePlanArgs (--template 整段取值语义, D5)", () => {
+  it("no flag: templatePath undefined", () => {
+    const parsed = parsePlanArgs("重构 auth 模块");
+    expect(parsed.templatePath).toBeUndefined();
+    expect(parsed.skills).toBeUndefined();
+  });
+
+  it("value = whole text after the flag — spaces preserved without quoting (整段取值)", () => {
+    const parsed = parsePlanArgs("复盘事故 --template ~/docs/my retro template.md");
+    expect(parsed.requirement).toBe("复盘事故");
+    expect(parsed.templatePath).toBe("~/docs/my retro template.md");
+  });
+
+  it("flag at the very start leaves empty requirement", () => {
+    const parsed = parsePlanArgs("--template tpl.md");
+    expect(parsed.requirement).toBe("");
+    expect(parsed.templatePath).toBe("tpl.md");
+  });
+
+  it("'--templatex' is not treated as the flag (word boundary)", () => {
+    const parsed = parsePlanArgs("req --templatex is part of requirement");
+    expect(parsed.templatePath).toBeUndefined();
+    expect(parsed.requirement).toBe("req --templatex is part of requirement");
+  });
+
+  it("both flags present (either order): both parsed — caller fail-fasts mutual exclusion", () => {
+    const templateFirst = parsePlanArgs("req --template a.md --skills b");
+    expect(templateFirst.templatePath).toBeDefined();
+    expect(templateFirst.skills).toBeDefined();
+
+    const skillsFirst = parsePlanArgs("req --skills b --template a.md");
+    expect(skillsFirst.templatePath).toBeDefined();
+    expect(skillsFirst.skills).toBeDefined();
+  });
+});
+
+describe("resolveTemplateFile (D5 校验与文案分家)", () => {
+  afterEach(() => {
+    vi.mocked(fs.existsSync).mockImplementation(() => false);
+  });
+
+  it("empty value is an explicit error (flag given, nothing followed)", () => {
+    const res = resolveTemplateFile("   ", "/tmp/test-project");
+    expect(res.ok).toBe(false);
+    if (!res.ok) expect(res.problem).toContain("--template was given but no path followed it");
+  });
+
+  it("~ prefix expands against os.homedir and missing file reports absolute path", () => {
+    const res = resolveTemplateFile("~/docs/retro.md", "/tmp/test-project");
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.problem).toContain(`Template file not found: ${path.join(os.homedir(), "docs/retro.md")}`);
+    }
+  });
+
+  it("~name form is not expanded (no per-user home semantics): resolves against projectDir verbatim", () => {
+    // `~foo` 不是用户名展开场景（D5 最小语义：仅 `~` 本身与 `~/` 前缀展开）——
+    // 按字面路径相对 projectDir 解析，不得吞进 os.homedir()
+    vi.mocked(fs.existsSync).mockImplementation((p) => p === path.resolve("/tmp/test-project", "~foo/plan.md"));
+    const res = resolveTemplateFile("~foo/plan.md", "/tmp/test-project");
+    expect(res.ok).toBe(true);
+    if (res.ok) {
+      expect(res.absPath).toBe(path.resolve("/tmp/test-project", "~foo/plan.md"));
+      expect(res.absPath).not.toContain(os.homedir());
+    }
+  });
+
+  it("relative path resolves against projectDir; not-found message carries usage sample", () => {
+    const res = resolveTemplateFile("tpl.md", "/tmp/test-project");
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.problem).toContain("Template file not found: /tmp/test-project/tpl.md");
+      expect(res.problem).toContain("e.g. /plan <requirement> --template /path/to/template.md");
+    }
+  });
+
+  it("existing non-markdown file reports 'Not a markdown file' (文案分家)", () => {
+    vi.mocked(fs.existsSync).mockImplementation((p) => p === "/tmp/test-project/notes.txt");
+    const res = resolveTemplateFile("notes.txt", "/tmp/test-project");
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.problem).toContain("Not a markdown file: /tmp/test-project/notes.txt");
+      expect(res.problem).not.toContain("not found");
+    }
+  });
+
+  it("existing markdown file resolves ok with absolute path", () => {
+    vi.mocked(fs.existsSync).mockImplementation((p) => p === "/tmp/test-project/docs/retro.md");
+    const res = resolveTemplateFile("docs/retro.md", "/tmp/test-project");
+    expect(res.ok).toBe(true);
+    if (res.ok) expect(res.absPath).toBe("/tmp/test-project/docs/retro.md");
+  });
 });