mancode 0.3.12 → 0.3.14

package/README.md

@@ -17,10 +17,8 @@
 <p align="center">
   <a href="./LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg?style=flat-square" alt="许可证：AGPL-3.0" /></a>
   <a href="https://www.npmjs.com/package/mancode"><img src="https://img.shields.io/npm/v/mancode?style=flat-square" alt="npm 版本" /></a>
-  <img src="https://img.shields.io/badge/status-stable%20v0.3.12-green?style=flat-square" alt="状态：稳定版 v0.3.12" />
-  <img src="https://img.shields.io/badge/V3-%E8%B7%A8%20CLI%20%E5%9B%A2%E9%98%9F%20Beta-FB6A21?style=flat-square" alt="V3：跨 CLI 团队协作 Beta" />
+  <img src="https://img.shields.io/badge/status-V3%20beta%20v0.3.14-orange?style=flat-square" alt="状态：V3 Beta v0.3.14" />
   <img src="https://img.shields.io/badge/platforms-Claude%20Code%20%7C%20Cursor%20%7C%20Codex%20%7C%20Copilot%20%7C%20ZCode-5865F2?style=flat-square" alt="平台：Claude Code、Cursor、ChatGPT 桌面端 Codex、Codex CLI、GitHub Copilot、ZCode" />
-  <img src="https://img.shields.io/badge/tests-passing-brightgreen?style=flat-square" alt="测试通过" />
 </p>
 
 <p align="center">
@@ -39,15 +37,15 @@
 负责调研、计划、实现和审查。
 
 mancode 当前支持 Claude Code、Cursor、ChatGPT 桌面端中的 Codex、Codex CLI、
-GitHub Copilot 和 ZCode。V3 在每个平台继续使用原 `man*` 入口，并通过静态
-bootstrap 接入统一 Context Pack 与 workflow authority。
+GitHub Copilot 和 ZCode。每个平台继续使用原来的 `man*` 入口，并通过静态
+bootstrap 接入统一的 Context Pack 与 workflow authority。
 
 mancode 会安装三类能力：
 
-1. **V3 authority**：管理显式 session、TaskRef、Context Pack、workflow 和团队协调。
+1. **工作流权威数据**：管理显式 session、TaskRef、Context Pack、workflow 和团队协调。
 2. **Skills / modes**：提供 `solo`、`/manba`、`/man`、`/manteam`、`/manps`、
    `/mansolo` 工作流模式。
-3. **平台 bootstrap**：把原入口接到 V3；只有 `--legacy` 才安装旧 hooks。
+3. **平台 bootstrap**：把原入口接到 mancode；只有 `--legacy` 才安装旧 hooks。
 
 当 AI 编码代理写太多代码、忽略已有 UI 系统、跳过计划，或者关键改动需要稳定工程流程时，
 mancode 可以作为一层本地工作流约束。
@@ -83,12 +81,31 @@ ChatGPT 桌面端、Codex CLI 和 Codex IDE 扩展会从 `.agents/skills/` 读
 和 [slash command 文档](https://learn.chatgpt.com/docs/reference/slash-commands)。
 已有 workflow 元数据继续兼容，不需要迁移。
 
-## V3 跨 CLI 与团队协作 Beta
+## 跨会话继续工作
 
-V3 为新团队项目提供稳定 `TaskRef` 上下文、隔离 session、治理账本、worktree
-claim/handoff，以及可选的 git-ref 跨 clone 协调。它是**带硬门禁的 Beta**：adapter 能为
-Claude Code、Cursor、Codex、GitHub Copilot 和 ZCode 提供 bootstrap，但不会把平台文件
-当作任务或 session 状态的权威来源。
+mancode 把目标、需求、计划、检查结果和交接信息保存在稳定 `TaskRef` 下。换一个聊天
+窗口、重启编码 Agent，或者从另一个受支持的 CLI 继续时，新会话可以恢复同一项任务，
+再按当前目的读取精简的 Context Pack，而不必依赖上一段对话仍然打开。
+
+它续接的是**任务上下文**，不是原始聊天记录。不同客户端的 session 仍然隔离；新会话
+必须使用自己的 client 身份，并显式恢复已有 TaskRef。这样既能延续工作，也不会把一个
+窗口的临时状态误当成另一个窗口的身份。
+
+```bash
+mancode status --json
+mancode context session new --client claude-code
+mancode context resume <namespace:ULID> --session <id> --client claude-code
+mancode context show --purpose orient --session <id> --client claude-code
+```
+
+原来的 `/man`、`/manba` 和 `/manteam` 入口会处理这些步骤。上面的 CLI 形式适合排查、
+自动化或手工恢复任务。
+
+## 跨客户端与团队协作
+
+mancode 为团队项目提供稳定 TaskRef、隔离 session、治理账本、worktree claim/handoff，
+以及可选的 git-ref 跨 clone 协调。Claude Code、Cursor、Codex、GitHub Copilot 和
+ZCode 都通过 bootstrap 使用同一套工作流数据；平台文件本身不保存任务或 session 副本。
 
 在全新项目中，从一个实际使用的平台开始：
 
@@ -99,30 +116,18 @@ mancode context session new --client claude-code
 mancode list-platforms
 ```
 
-普通 `mancode init` 现在就是 V3 入口，并继续生成原来的 `man`、`manba`、
-`manteam`、`manps`、`mansolo` 平台命令；不需要改用另一套 V3 命令名。
-`--v3` 仅保留为显式兼容别名；确实需要旧 `state.json` 架构时才使用
+普通 `mancode init` 会生成原来的 `man`、`manba`、`manteam`、`manps`、
+`mansolo` 平台命令，不需要改用另一套命令名。确实需要旧 `state.json` 架构时才使用
 `mancode init --legacy`。
 
 创建、恢复和协作均通过 CLI 完成：`mancode workflow create`、`mancode context resume`、
 `mancode team claim` 和 `mancode team handoff`。已有项目先运行
 `mancode migrate context --dry-run`，再按迁移报告确认 stage/activation；不要手工混写
-legacy `state.json` 与 V3 authority。
-
-### Beta 的验证边界
-
-- `main` 的 Windows 门禁会从 CMD、PowerShell 和 Git Bash 运行 smoke 测试。
-- `mancode context beta --release-candidate <commit> --json` 会检查 activation、adapter、repair、worktree binding 和
-  五个平台的 session evidence；evidence 必须绑定同一个不可变发布候选，任何 blocker 都会阻止大范围启用。
-- 每个平台都必须在真实宿主中证明两个窗口的 session 区分、子命令传播以及子 agent 继承（或记录明确的不适用原因）。
-  `context session spike` 只记录操作者报告的真实宿主结果，不会由临时环境变量自动推断传播成功；证据不保存原始 session key。
-
-在门禁通过前，继续显式传入 `--session <id>`，不要把 host identity 视为已验证。这样可以
-先试用 V3，同时避免把尚未证明的跨平台 session 行为当作事实。
+legacy `state.json` 与当前工作流权威数据。
 
 ## 安装后创建哪些文件？
 
-默认的 `mancode init` 会创建 V3 权威目录和平台适配文件：
+默认的 `mancode init` 会创建 mancode 工作流目录和平台适配文件：
 
 ```text
 .mancode/
@@ -140,7 +145,7 @@ AGENTS.md                        # Codex（ChatGPT 桌面端/CLI）：托管 ins
 .github/prompts/                 # GitHub Copilot：原 mode prompts
 ```
 
-`.mancode/` 把可共享的 V3 权威与 checkout-local 的 session、workflow 和扫描报告分开。
+`.mancode/` 把可共享的工作流数据与 checkout-local 的 session、workflow 和扫描报告分开。
 平台文件只保存 bootstrap 和原模式入口，不保存 task/session 副本。
 `mancode init --legacy` 才会创建旧的 `state.json` 布局。
 
@@ -150,7 +155,7 @@ AGENTS.md                        # Codex（ChatGPT 桌面端/CLI）：托管 ins
 - **在存在 UI 时匹配现有设计系统**：检查项目 UI 依赖、Tailwind 配置、CSS 变量和已有组件，让 agent 复用现有颜色、字体和交互模式。
 - **先把需求和计划对齐**：`/man` 会调研项目、引导澄清会改变方案的需求、推荐可行选项并生成可确认的持久计划；计划完成后不会自动进入完整实施。
 - **自由选择执行强度**：计划确认后，可只保留计划、交给默认 `solo` 轻量开发，或继续完整 `/man` 的验证与有界风险审查。
-- **保留工作流产物**：调研、计划、审查报告和总结会保存到 `.mancode/local/workflows/<taskId>/`。
+- **保留工作流产物**：调研、计划、审查报告和总结会保存到 `.mancode/<namespace>/workflows/<ULID>/`。
 - **支持团队上下文**：`/manteam` 通过 `.mancode/shared/` 的类型化实体共享已确认信息。
 - **扫描项目健康度**：`mancode manps` 检测陈旧 TODO、未使用依赖、风险依赖和硬编码设计值。
 
@@ -159,7 +164,7 @@ AGENTS.md                        # Codex（ChatGPT 桌面端/CLI）：托管 ins
 mancode 适合：
 
 - 正在使用 AI 编码代理的后端、Web、移动端、桌面端、CLI、库、数据或混合项目
-- 希望在原 `man*` 命令中使用 V3 Context Pack、skills 和显式治理的用户
+- 希望在原 `man*` 命令中使用 Context Pack、skills 和显式治理的用户
 - 希望 AI 代理复用已有组件和代码模式的团队
 - 需要可重复 AI 辅助代码审查流程的项目
 - 已有 UI 组件、主题、CSS 变量或设计约定的界面项目
@@ -205,8 +210,8 @@ mancode 不是 Claude Code、Cursor、Codex 或 Copilot 的替代品。它是在
 
 ## 使用方法
 
-V3 不再把“当前模式”写进持久状态。需要某种工作方式时，直接在 AI 编码代理的
-对话中调用原命令；入口会解析 V3 status、session、TaskRef 和 Context Pack：
+mancode 不把“当前模式”写进持久状态。需要某种工作方式时，直接在 AI 编码代理的
+对话中调用原命令；入口会解析 status、session、TaskRef 和 Context Pack：
 
 | 模式 | 适合场景 | 做什么 |
 |---|---|---|
@@ -215,7 +220,7 @@ V3 不再把“当前模式”写进持久状态。需要某种工作方式时
 | `/man` | 需要需求对齐或正式计划的改动 · 季后赛 | 调研、方案推荐和持久计划；确认后选择 solo 轻量开发或完整 9 步治理 |
 | `/manteam` | 团队项目 · 上场五人，一条心 | 共享记忆、决策记录、协作和 Conventional Commits |
 | `/manps` | 清理和维护 · 季前赛 | 输出 Markdown 和 JSON 项目健康报告 |
-| `/mansolo` | 回到轻量工作 | 不写 legacy mode；需要时执行显式 V3 handoff |
+| `/mansolo` | 回到轻量工作 | 不写 legacy mode；需要时执行显式 handoff |
 
 ## `/man` 如何工作：季后赛模式
 
@@ -223,7 +228,7 @@ V3 不再把“当前模式”写进持久状态。需要某种工作方式时
 `solo`，当用户要求先调研、给方案或出计划时，也会进入 `/man`。它会先了解项目，
 只追问会改变范围、架构、成本或验收的问题；适合由系统推荐的决策会给出 2–3 个
 方案、优缺点和明确建议。需求足够清楚后，计划才会写入
-`.mancode/local/workflows/<taskId>/plan.md`。
+`.mancode/local/workflows/<ULID>/plan.md`。
 
 计划完成不会自动开始完整开发。用户在计划关卡选择：交给 `solo` 按已确认计划
 轻量开发、继续完整 `/man`、只保留计划，或修改计划。只有选择完整 `/man` 才继续
@@ -245,16 +250,16 @@ V3 不再把“当前模式”写进持久状态。需要某种工作方式时
 
 ### Bootstrap 和 Adapters
 
-V3 默认不假设任何 hook 已获批准。平台 adapter 只安装稳定 bootstrap 与原来的
-`man/manba/manteam/manps/mansolo` 入口；任务、模式和 session 仍以 V3 authority
-为准。Claude Code 的内部 bootstrap 对用户隐藏，不会增加 `/mancode-v3` 公共命令。
+mancode 默认不假设任何 hook 已获批准。平台 adapter 只安装稳定 bootstrap 与原来的
+`man/manba/manteam/manps/mansolo` 入口；任务、模式和 session 以 mancode 工作流数据
+为准。Claude Code 的内部 bootstrap 对用户隐藏，不会增加额外的公共命令。
 没有经真实宿主验证的 session 传播时，写命令必须显式传入 `--session`。
 
 只有 `mancode init --legacy` 才安装读取 `.mancode/state.json` 的旧 Claude hooks。
 
 ### 设计 Token 感知
 
-mancode 会把检测到的 V3 项目事实写入 `.mancode/shared/context/project.json`；
+mancode 会把检测到的项目事实写入 `.mancode/shared/context/project.json`；
 checkout-local 的设计 token 缓存位于 `.mancode/local/cache/`。它可用于后端服务、
 Web、移动端、桌面端、CLI、库和混合仓库；不会预设 JavaScript 或 UI 技术栈。
 
@@ -286,7 +291,7 @@ src/components/
 
 ### 团队记忆
 
-`/manteam` 通过 V3 shared authority 读写经过确认的团队实体：
+`/manteam` 通过共享工作流数据读写经过确认的团队实体：
 
 ```text
 .mancode/shared/
@@ -300,9 +305,9 @@ src/components/
 
 ## 安装
 
-**状态**：稳定版 v0.3.12。Claude Code、Cursor、ChatGPT 桌面端中的 Codex、
-Codex CLI 和 GitHub Copilot 均已支持。ZCode adapter 已接入，但项目级 skill
-发现路径在发布前仍作为验证门禁。
+**状态**：V3 Beta v0.3.14。Claude Code、Cursor、ChatGPT 桌面端中的 Codex、
+Codex CLI 和 GitHub Copilot 均已接入；ZCode adapter 已接入。正式稳定发布仍需
+完成五平台真实宿主验收和 `context beta` B1 门禁。
 
 需要 Node.js 20 或更高版本。原生支持 macOS、Linux、Windows CMD、
 PowerShell 和 Git Bash。Git 是可选依赖：未安装时仍可初始化，只会把团队
@@ -319,7 +324,7 @@ mancode init --platform all
 
 平台支持：
 
-- Claude Code：隐藏 bootstrap 与原 mode skills；V3 默认不依赖 hooks
+- Claude Code：隐藏 bootstrap 与原 mode skills；默认不依赖 hooks
 - Cursor：`.cursor/rules/*.mdc` bootstrap 与 `.cursor/commands/` 原 mode commands
 - Codex（ChatGPT 桌面端、CLI、IDE 扩展）：托管 `AGENTS.md` block，并在
   `.agents/skills/` 下提供 `$man*` 项目 skills
@@ -340,8 +345,8 @@ mancode init --platform PLATFORMS # 一个或多个：claude-code,cursor,codex,c
 mancode init --empty      # 非交互脚本中允许安全的空目录
 mancode init --lang zh-CN # 显式指定初始化语言（zh-CN 或 en）
 mancode refresh-project   # 后续加入 Git 或项目文件后刷新项目事实
-mancode install --force   # 修复或重装所选 V3 adapter
-mancode install --minimal # V3 bootstrap 已是最小形态；保留兼容参数
+mancode install --force   # 修复或重装所选 adapter
+mancode install --minimal # bootstrap 已是最小形态；保留兼容参数
 ```
 
 ## Agent Modes
@@ -374,6 +379,8 @@ mancode list-platforms
 mancode team identity create --name "<name>"
 mancode context session new --client <platform>
 mancode workflow create <man|manba|manteam> "<task>" --session <id>
+mancode workflow list --json
+mancode workflow show <namespace:ULID> --json
 mancode context resume <local:ULID|shared:ULID> --session <id>
 mancode workflow requirements <namespace:ULID> finalize --file <requirements.json> --expected-revision <n> --session <id>
 mancode workflow plan <namespace:ULID> revise --file <plan.md> --expected-revision <n> --session <id>
@@ -392,19 +399,18 @@ mancode version
 
 ### `mancode status`
 
-以下是 V3 项目的简化输出示例：
+以下是简化输出示例：
 
 ```text
-mancode v0.3.12 (V3 authority)
+mancode v0.3.14
 
 Project:     my-app
-Activation:  v3_active
 Runtime:     ready
 Transport:   local
 Identity:    not configured
 Session evidence: explicit required
 
-V3 adapter status:
+mancode adapter status:
   ○ Claude Code: not installed
   ○ Cursor: not installed
   ✓ Codex (ChatGPT desktop/CLI): ready
@@ -425,7 +431,7 @@ Issue DB: .mancode/local/preseason-issues.json
 
 ### `mancode init`
 
-初始化 V3 authority，并把所选平台的原 mode 入口接到 V3 Context Pack 与 workflow CLI。
+初始化 mancode 工作流数据，并把所选平台的原 mode 入口接到 Context Pack 与 workflow CLI。
 不会创建 legacy `state.json`；旧架构需显式运行 `mancode init --legacy`。
 
 ```bash
@@ -434,7 +440,7 @@ mancode init
 
 ### `mancode status`
 
-显示 V3 activation、runtime binding、identity/session evidence、transport 和各平台
+显示 activation、runtime binding、identity/session evidence、transport 和各平台
 bootstrap/原 mode 入口的实际就绪状态。
 
 ```bash
@@ -444,7 +450,7 @@ mancode status --json
 
 ### `mancode workflow`
 
-创建和管理 `/manba`、`/man` 和 `/manteam` 使用的 V3 workflow。每次写入使用
+创建和管理 `/manba`、`/man` 和 `/manteam` 使用的 workflow。每次写入使用
 `namespace:ULID` TaskRef、显式 session 和最新 expected revision；requirements、plan、
 review、verification 与 completion 各走专用命令，不再使用 legacy `--step` 协议。
 
@@ -454,9 +460,11 @@ mancode context session new --client codex
 mancode workflow create man "refactor auth module" --session <id>
 mancode workflow requirements <local:ULID> finalize --file requirements.json --expected-revision <n> --session <id>
 mancode workflow plan <local:ULID> revise --file plan.md --expected-revision <n> --session <id>
+mancode workflow plan <local:ULID> confirm --plan-decision <plan_only|governed_execution> --expected-revision <n> --session <id>
 mancode workflow review <local:ULID> apply --file review-ledger.json --expected-revision <n> --session <id>
 mancode workflow verify <local:ULID> apply --file verification-ledger.json --expected-revision <n> --session <id>
 mancode workflow complete <local:ULID> --expected-revision <n> --session <id>
+mancode context compact --dry-run
 ```
 
 ### `mancode manps`
@@ -488,7 +496,7 @@ mancode manps config
 .mancode/shared/context/project.json
 ```
 
-V3 adapter 是不嵌入 task/style 快照的静态 bootstrap，因此刷新项目事实后不需要重装。
+平台 adapter 是不嵌入 task/style 快照的静态 bootstrap，因此刷新项目事实后不需要重装。
 
 ## 项目文件
 
@@ -499,7 +507,7 @@ mancode/
 │   ├── mancode status
 │   └── mancode install <platform>
 │
-├── V3 authority
+├── Workflow authority
 │   ├── shared/context + team
 │   └── local/session + workflow + cache
 │
@@ -571,23 +579,33 @@ mancode/
 （context、practice、solo）在每次对话加载。模式规则（manba、man、manteam、
 manps）按 description 触发——输入 `/manba` 等关键词即可激活。
 
-### 如何完全重装
+### 如何重装 V3 适配器
 
 ```bash
-mancode uninstall --all --force
-mancode init
-mancode install <platform>
+mancode uninstall claude-code --force
+mancode uninstall cursor --force
+mancode uninstall codex --force
+mancode uninstall copilot --force
+mancode uninstall zcode --force
+mancode install claude-code
+mancode install cursor
+mancode install codex
+mancode install copilot
+mancode install zcode
 ```
 
-### 如何完全卸载 mancode
+V3 authority 受保护，`mancode uninstall --all` 不会删除工作流权威数据。需要
+清理运行时保留记录时，先用 `mancode context compact --dry-run` 检查候选。
+
+### 如何移除 CLI
 
 ```bash
-mancode uninstall --all --force
 npm uninstall -g mancode
 ```
 
-这会移除 `.mancode/`、平台配置文件和 `.claude/settings.json` 中的 mancode
-hooks。用户自定义的 rules 和 instructions 会被保留。
+逐个平台卸载会移除对应的 mancode bootstrap，并保留用户自定义 rules、instructions
+和 V3 工作流数据。旧项目若明确使用 `mancode init --legacy`，才支持 legacy 的
+`mancode uninstall --all --force`。
 
 ## 常见问题
 
@@ -615,7 +633,7 @@ hooks。用户自定义的 rules 和 instructions 会被保留。
 
 支持。mancode 通过静态 bootstrap 和原 mode 入口支持 Claude Code、Cursor、
 ChatGPT 桌面端中的 Codex、Codex CLI、GitHub Copilot，并提供实验性 ZCode adapter。
-V3 默认不把任何平台的 hook 当成已批准能力。
+mancode 默认不把任何平台的 hook 当成已批准能力。
 
 ### mancode 能改善前端一致性吗？