mancode 0.3.18 → 0.4.1

package/README.en.md

@@ -17,7 +17,7 @@
 <p align="center">
   <a href="./LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg?style=flat-square" alt="License: 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 version" /></a>
-  <img src="https://img.shields.io/badge/status-Continuity%20v0.3.18-2f855a?style=flat-square" alt="Status: mancode Continuity v0.3.18" />
+  <img src="https://img.shields.io/badge/status-Continuity%20v0.4.1-2f855a?style=flat-square" alt="Status: mancode Continuity v0.4.1" />
   <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="Platforms: Claude Code, Cursor, Codex in ChatGPT desktop and CLI, GitHub Copilot, ZCode" />
 </p>
 
@@ -34,8 +34,9 @@ different gears for different stakes: light solo mode for daily practice, `/man`
 for playoff-level engineering discipline, and coaching-staff subagents for
 research, planning, implementation, and review.
 
-**mancode Continuity** is the continuous-context runtime that carries tasks,
-decisions, and verification evidence safely into later conversations.
+**mancode Continuity** is the cross-session and team-collaboration runtime that
+carries tasks, decisions, and verification evidence safely into later
+conversations.
 
 [Installation](#installation) · [Usage](#usage)
 
@@ -107,10 +108,15 @@ one window's temporary state as another window's identity.
 ```bash
 mancode status --brief --json
 mancode context session new --client claude-code
+mancode context session show --session <id> --client claude-code --json
 mancode context resume <namespace:ULID> --session <id> --client claude-code
 mancode context show --purpose orient --session <id> --client claude-code
 ```
 
+When the project has a local mancode install, pin one CLI binary for the whole
+task: prefer `./node_modules/.bin/mancode`, otherwise use `mancode`. Check the
+selected binary with `--version` once and do not mix versions afterward.
+
 The original `/man`, `/manba`, and `/manteam` entries handle these steps. The
 CLI form above is useful for diagnostics, automation, or manual recovery.
 
@@ -122,6 +128,15 @@ clones. Claude Code, Cursor, Codex, GitHub Copilot, and ZCode use the same
 workflow data through platform bootstraps; platform files do not hold task or
 session copies.
 
+Under git-ref transport, workflow create, requirements, plan, review, and
+verification mutations use an explicit deferred publication boundary. Run the
+mutation without `--sync`, commit the matching `.mancode/shared` changes with
+the code baseline, then run
+`mancode team sync push shared:<ULID> --expected-task-revision N`. Passing
+`--sync` directly to those commands returns
+`MANCODE_GIT_REF_DEFERRED_SYNC_REQUIRED`; cross-clone synchronization is
+complete only after the push returns a receipt.
+
 For a new project, start with one platform you actually use:
 
 ```bash
@@ -234,7 +249,9 @@ design tokens:
 </Button>
 ```
 
-The default workflow asks six questions before writing code:
+The default workflow evaluates a conditional clarity gate before writing code: it asks the user
+only when an unresolved decision could change the goal, scope, behavior, acceptance, or key
+constraints, and it proceeds without ceremonial questions when the request is already clear.
 
 1. What problem does this change solve?
 2. Can an existing implementation be reused?
@@ -243,6 +260,10 @@ The default workflow asks six questions before writing code:
 5. What is the smallest meaningful runtime check?
 6. What remains uncertain after checking the code and docs?
 
+These are internal readiness checks, not a mandatory questionnaire. Any unresolved
+decision-changing uncertainty becomes a focused question and blocks requirements finalization
+until the user answers; clear requests continue directly.
+
 <span id="usage"></span>
 
 ## Usage
@@ -353,7 +374,7 @@ it should behave, and why previous decisions were made.
 
 ## Installation
 
-**Status**: mancode Continuity v0.3.18. Claude Code, Cursor, Codex in the ChatGPT
+**Status**: mancode Continuity v0.4.1. Claude Code, Cursor, Codex in the ChatGPT
 desktop app and CLI, GitHub Copilot, and ZCode adapters are included.
 
 Requires Node.js 20 or newer. macOS, Linux, Windows CMD, PowerShell, and Git Bash
@@ -394,8 +415,9 @@ mancode init --platform PLATFORMS # One or more: claude-code,cursor,codex,copilo
 mancode init --empty      # Allow a safe empty directory in non-interactive scripts
 mancode init --lang zh-CN # Explicit initialization language (zh-CN or en)
 mancode refresh-project   # Refresh facts after Git or project files are added
-mancode install --force   # Repair or reinstall the selected adapter
-mancode install --minimal # The bootstrap is already minimal; retained for compatibility
+mancode adapter status --json # Inspect actual managed-content digests
+mancode adapter upgrade --platform codex --dry-run # Stage a preview only
+mancode adapter upgrade --platform codex --confirm --operation-id <operationId> --session <id> --client <client>
 ```
 
 ## Agent Modes
@@ -424,10 +446,16 @@ mancode init --legacy
 mancode status
 mancode status --json
 mancode status --brief --json
-mancode install <claude-code|cursor|codex|copilot|zcode>
+mancode install <claude-code|cursor|codex|copilot|zcode> --confirm --operation-id <operationId> --session <id> --client <client>
+mancode adapter status [--platform <platform>] --json
+mancode adapter upgrade <--all|--platform <platform>> --dry-run
+mancode adapter upgrade <--all|--platform <platform>> --confirm --operation-id <operationId> --session <id> --client <client>
+mancode project upgrade --policy 2 --dry-run
+mancode project upgrade --policy 2 --operation-id <operationId> --session <id> --client <client>
 mancode list-platforms
 mancode team identity create --name "<name>"
 mancode context session new --client <platform>
+mancode context session show --session <id> --client <client> --json
 mancode workflow create <man|manba|manteam> "<task>" --session <id>
 mancode workflow list --json
 mancode workflow show <namespace:ULID> --json
@@ -438,6 +466,7 @@ mancode workflow plan <namespace:ULID> confirm --plan-decision <plan_only|govern
 mancode workflow update <namespace:ULID> --status <status> --expected-revision <n> --session <id>
 mancode workflow review <namespace:ULID> apply --file <review-ledger.json> --expected-revision <n> --session <id>
 mancode workflow verify <namespace:ULID> apply --file <verification-ledger.json> --expected-revision <n> --session <id>
+mancode workflow reframe <local:ULID> --expected-revision <n> --checkpoint-id <ULID> --session <id>
 mancode workflow complete <namespace:ULID> --expected-revision <n> --session <id>
 mancode manps [area]
 mancode refresh-project
@@ -452,7 +481,7 @@ mancode version
 Simplified output:
 
 ```text
-mancode v0.3.18
+mancode v0.4.1
 
 Project:     my-app
 Runtime:     ready
@@ -594,14 +623,19 @@ mancode/
 - Irreversible operations such as force pushes, schema migrations, and bulk
   deletes require explicit human confirmation.
 
-## Roadmap
+## Remaining Work
+
+- Complete real-host session acceptance for Claude Code, Codex, Cursor,
+  GitHub Copilot, and ZCode on one release candidate; verified host sessions
+  and isolated explicit sessions are both valid evidence paths.
+- Run `npm run release:check -- --candidate <full-commit-sha>` for the clean
+  checkout, automated two-clone/legacy checks, tarball SHA-256, and install
+  smoke; complete cross-host recovery separately.
+- Confirm ZCode project-skill discovery and workspace-command paths; keep the
+  adapter provisional until then.
+- Evaluate Windsurf, Cline, and Roo Code adapters based on real demand.
 
-| Phase | Focus |
-|---|---|
-| MVP-1 | solo mode, aesthetics, and Claude Code hooks |
-| MVP-2 | `/manba`, `/man`, `/manteam`, `/manps`, and coaching-staff subagents |
-| MVP-3 | Cursor, Codex (ChatGPT desktop/CLI), and GitHub Copilot adapters |
-| Public Release | stable npm release, marketplace distribution, docs, and demos |
+See [0.4.1 Continuity Release Acceptance](./docs/release-acceptance.md) for the complete gate.
 
 ## Troubleshooting
 
@@ -616,21 +650,26 @@ a deliberately empty directory.
 ### Claude Code hooks not triggering
 
 After `mancode init`, restart Claude Code so it reloads `.claude/settings.json`.
-Run `mancode status` to verify hooks are registered. If hooks are still missing,
-run `mancode install claude-code --force` to rewrite the settings.
+Run `mancode status` to verify hooks are registered. For Continuity adapter drift, preview
+`mancode adapter upgrade --platform claude-code --dry-run`, then repair that
+preview with its `--operation-id`, an active session, and `--confirm`. The legacy
+hook architecture still uses `mancode init --legacy --force`.
 
 ### `mancode status` shows a platform as "not ready"
 
-This means the platform's target files are missing. Run
-`mancode install <platform> --force` to regenerate them. For managed-block
+This means the platform's target files are missing or their digest is stale.
+Preview `mancode adapter upgrade --platform <platform> --dry-run`, inspect the
+staged result, then run it with the returned `--operation-id`, an active session,
+and `--confirm`. For managed-block
 platforms (Codex, ZCode, Copilot), the managed block in `AGENTS.md` or
 `.github/copilot-instructions.md` may have been manually edited or deleted.
 
 ### AGENTS.md or copilot-instructions.md managed block was accidentally deleted
 
-Run `mancode install codex --force` (or `zcode`, or `copilot`) to reinsert the
-managed block. User-authored content outside the relevant mancode managed
-markers is preserved.
+Preview `mancode adapter upgrade --platform codex --dry-run` (or `zcode`, or
+`copilot`), then run it with the returned `--operation-id`, an active session,
+and `--confirm` to reinsert the managed block. User-authored content outside the
+relevant markers is preserved.
 
 ### ZCode skills not appearing
 
@@ -648,16 +687,8 @@ description field — invoke them by asking for `/manba` or similar.
 ### How to reinstall Continuity adapters
 
 ```bash
-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 adapter upgrade --all --dry-run
+mancode adapter upgrade --all --confirm --operation-id <operationId> --session <id> --client <client>
 ```
 
 Continuity authority is protected, so `mancode uninstall --all` does not delete workflow
@@ -684,8 +715,11 @@ use.
 
 ### How is mancode different from a CLAUDE.md file?
 
-A `CLAUDE.md` file is static guidance. mancode adds hooks, persisted workflow
-state, slash-command skills, and separate review subagents with clean context.
+A `CLAUDE.md` file is static guidance. Continuity maintains one always-loaded
+Claude Code bootstrap block there, while sessions, TaskRefs, requirements,
+plans, and review evidence remain structured authority under `.mancode/`.
+mancode also adds mode skills, persisted workflows, and separate review
+subagents with clean context.
 
 ### How is mancode different from Cursor rules, custom prompts, or agent instructions?
 

package/README.md

@@ -17,7 +17,7 @@
 <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-Continuity%20v0.3.18-2f855a?style=flat-square" alt="状态：mancode Continuity v0.3.18" />
+  <img src="https://img.shields.io/badge/status-Continuity%20v0.4.1-2f855a?style=flat-square" alt="状态：mancode Continuity v0.4.1" />
   <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" />
 </p>
 
@@ -36,7 +36,7 @@
 日常任务用轻量 `solo`，关键任务用季后赛级别的 `/man`，复杂任务让教练组 subagents
 负责调研、计划、实现和审查。
 
-**mancode Continuity（连续上下文运行时）**负责把任务、决策和验证证据安全地带到后续对话。
+**mancode Continuity（跨会话与团队协作运行时）**负责把任务、决策和验证证据安全地带到后续对话，并协调多人或多 Agent 的任务权威。
 
 mancode 当前支持 Claude Code、Cursor、ChatGPT 桌面端中的 Codex、Codex CLI、
 GitHub Copilot 和 ZCode。每个平台继续使用原来的 `man*` 入口，并通过静态
@@ -109,6 +109,13 @@ mancode 为团队项目提供稳定 TaskRef、隔离 session、治理账本、wo
 以及可选的 git-ref 跨 clone 协调。Claude Code、Cursor、Codex、GitHub Copilot 和
 ZCode 都通过 bootstrap 使用同一套工作流数据；平台文件本身不保存任务或 session 副本。
 
+git-ref 下的 workflow create、requirements、plan、review 和 verification 使用显式的
+延后发布边界：先不带 `--sync` 执行 mutation，将对应的 `.mancode/shared`
+变更与代码基线一起提交，再执行
+`mancode team sync push shared:<ULID> --expected-task-revision N`。这些命令若直接带
+`--sync` 会返回 `MANCODE_GIT_REF_DEFERRED_SYNC_REQUIRED`；只有拿到 push receipt
+才表示跨 clone 同步完成。
+
 在全新项目中，从一个实际使用的平台开始：
 
 ```bash
@@ -118,6 +125,16 @@ mancode context session new --client claude-code
 mancode list-platforms
 ```
 
+要只读检查一个 session（例如确认 Codex 续接时仍使用同一身份），使用：
+
+```bash
+mancode context session show --session <session-id> --client <client> --json
+```
+
+在项目同时安装 mancode 时，整项任务应固定使用项目本地 CLI：优先
+`./node_modules/.bin/mancode`，否则再使用 PATH 中的 `mancode`；先运行一次
+`--version`，后续不要混用不同版本。
+
 普通 `mancode init` 会生成原来的 `man`、`manba`、`manteam`、`manps`、
 `mansolo` 平台命令，不需要改用另一套命令名。确实需要旧 `state.json` 架构时才使用
 `mancode init --legacy`。
@@ -228,7 +245,8 @@ mancode 不把“当前模式”写进持久状态。需要某种工作方式时
 
 `/man` 既是正式计划入口，也是面向关键任务的季后赛模式。即使当前处于默认
 `solo`，当用户要求先调研、给方案或出计划时，也会进入 `/man`。它会先了解项目，
-只追问会改变范围、架构、成本或验收的问题；适合由系统推荐的决策会给出 2–3 个
+只追问会改变范围、架构、成本或验收的问题；需求足够清晰时不制造形式问题，需求
+不清晰时会停下等待用户回答；适合由系统推荐的决策会给出 2–3 个
 方案、优缺点和明确建议。需求足够清楚后，计划才会写入
 `.mancode/local/workflows/<ULID>/plan.md`。
 
@@ -248,6 +266,10 @@ mancode 不把“当前模式”写进持久状态。需要某种工作方式时
 
 跳过的步骤会被记录。所有产物保留在本地，之后可以回看当时为什么做某个决策。
 
+默认 `solo` 也执行同一个轻量清晰度判断：清晰、窄范围的需求直接做最小改动；会改变
+行为、范围、验收或关键约束的歧义必须先提问。涉及架构、owner/source of truth、迁移、
+跨模块或团队决策时，`solo` 推荐 `/man`，但不会自行切换模式。
+
 ## 工作原理
 
 ### Bootstrap 和 Adapters
@@ -307,7 +329,7 @@ src/components/
 
 ## 安装
 
-**状态**：mancode Continuity v0.3.18。Claude Code、Cursor、ChatGPT 桌面端中的
+**状态**：mancode Continuity v0.4.1。Claude Code、Cursor、ChatGPT 桌面端中的
 Codex、Codex CLI、GitHub Copilot 和 ZCode adapter 均已接入。
 
 需要 Node.js 20 或更高版本。原生支持 macOS、Linux、Windows CMD、
@@ -346,8 +368,9 @@ 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   # 修复或重装所选 adapter
-mancode install --minimal # bootstrap 已是最小形态；保留兼容参数
+mancode adapter status --json # 检查实际 managed content digest
+mancode adapter upgrade --platform codex --dry-run # 只生成 staging 预览
+mancode adapter upgrade --platform codex --confirm --operation-id <operationId> --session <id> --client <client>
 ```
 
 ## Agent Modes
@@ -376,10 +399,16 @@ mancode init --legacy
 mancode status
 mancode status --json
 mancode status --brief --json
-mancode install <claude-code|cursor|codex|copilot|zcode>
+mancode install <claude-code|cursor|codex|copilot|zcode> --confirm --operation-id <operationId> --session <id> --client <client>
+mancode adapter status [--platform <platform>] --json
+mancode adapter upgrade <--all|--platform <platform>> --dry-run
+mancode adapter upgrade <--all|--platform <platform>> --confirm --operation-id <operationId> --session <id> --client <client>
+mancode project upgrade --policy 2 --dry-run
+mancode project upgrade --policy 2 --operation-id <operationId> --session <id> --client <client>
 mancode list-platforms
 mancode team identity create --name "<name>"
 mancode context session new --client <platform>
+mancode context session show --session <id> --client <client> --json
 mancode workflow create <man|manba|manteam> "<task>" --session <id>
 mancode workflow list --json
 mancode workflow show <namespace:ULID> --json
@@ -390,6 +419,7 @@ mancode workflow plan <namespace:ULID> confirm --plan-decision <plan_only|govern
 mancode workflow update <namespace:ULID> --status <status> --expected-revision <n> --session <id>
 mancode workflow review <namespace:ULID> apply --file <review-ledger.json> --expected-revision <n> --session <id>
 mancode workflow verify <namespace:ULID> apply --file <verification-ledger.json> --expected-revision <n> --session <id>
+mancode workflow reframe <local:ULID> --expected-revision <n> --checkpoint-id <ULID> --session <id>
 mancode workflow complete <namespace:ULID> --expected-revision <n> --session <id>
 mancode manps [area]
 mancode refresh-project
@@ -404,7 +434,7 @@ mancode version
 以下是简化输出示例：
 
 ```text
-mancode v0.3.18
+mancode v0.4.1
 
 Project:     my-app
 Runtime:     ready
@@ -537,14 +567,14 @@ mancode/
 - `/manps` 默认只扫描；进入整改前应明确确认代码改动。
 - force push、schema migration、批量删除等不可逆操作需要明确人工确认。
 
-## 路线图
+## 仍在推进
+
+- 在同一发布候选上完成 Claude Code、Codex、Cursor、GitHub Copilot 和 ZCode 的真实宿主 session 验收；宿主自动 session 和显式双 session 都是合法证据路径。
+- 使用 `npm run release:check -- --candidate <完整提交 SHA>` 完成干净 checkout、自动双 clone/legacy、tarball SHA-256 和安装 smoke；另完成跨真实宿主恢复。
+- 确认 ZCode 项目级 skill 发现和 workspace command 路径；完成前继续标记为 provisional。
+- 根据真实需求评估 Windsurf、Cline 和 Roo Code adapter。
 
-| 阶段 | 重点 |
-|---|---|
-| MVP-1 | solo 模式、审美扫描、Claude Code hooks |
-| MVP-2 | `/manba`、`/man`、`/manteam`、`/manps` 和教练组 subagents |
-| MVP-3 | Cursor、Codex（ChatGPT 桌面端/CLI）、GitHub Copilot 适配 |
-| 公开发布 | npm 稳定版、marketplace 分发、文档和演示 |
+完整发布条件见 [0.4.1 Continuity 发布验收](./docs/release-acceptance.md)。
 
 ## 故障排查
 
@@ -557,18 +587,24 @@ mancode/
 ### Claude Code hooks 不生效
 
 `mancode init` 后需要重启 Claude Code 以重新加载 `.claude/settings.json`。
-运行 `mancode status` 确认 hooks 已注册。如果仍不生效，运行
-`mancode install claude-code --force` 重写配置。
+运行 `mancode status` 确认 hooks 已注册。Continuity adapter 内容异常时，先运行
+`mancode adapter upgrade --platform claude-code --dry-run`，再用该预览返回的
+`--operation-id`、active session 和 `--confirm` 完成修复。legacy hook 架构仍使用
+`mancode init --legacy --force`。
 
 ### `mancode status` 显示某平台 "not ready"
 
-该平台的目标文件缺失。运行 `mancode install <platform> --force` 重新生成。
+该平台的目标文件缺失或 digest 不匹配。先运行
+`mancode adapter upgrade --platform <platform> --dry-run`，确认 staging 结果后再用
+该预览返回的 `--operation-id` 和 active session 执行 `--confirm`。
 对于 Codex、ZCode 和 Copilot，`AGENTS.md` 或 `.github/copilot-instructions.md`
 中的受控区可能被手动编辑或删除了。
 
 ### AGENTS.md 或 copilot-instructions.md 受控区被误删
 
-运行 `mancode install codex --force`（或 `zcode`、`copilot`）重新插入受控区。
+运行 `mancode adapter upgrade --platform codex --dry-run`（或 `zcode`、`copilot`）
+检查差异，再用该预览返回的 `--operation-id` 和 active session 执行 `--confirm`
+重新插入受控区。
 对应 mancode 受控标记外的用户内容会被保留。
 
 ### ZCode skills 未出现
@@ -586,16 +622,8 @@ manps）按 description 触发——输入 `/manba` 等关键词即可激活。
 ### 如何重装 Continuity 适配器
 
 ```bash
-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 adapter upgrade --all --dry-run
+mancode adapter upgrade --all --confirm --operation-id <operationId> --session <id> --client <client>
 ```
 
 Continuity authority 受保护，`mancode uninstall --all` 不会删除工作流权威数据。需要
@@ -620,8 +648,9 @@ npm uninstall -g mancode
 
 ### mancode 和 CLAUDE.md 有什么区别？
 
-`CLAUDE.md` 是静态指导。mancode 增加 hooks、持久化工作流状态、slash-command skills
-和独立审查 subagents。
+`CLAUDE.md` 是静态指导。Continuity 只在其中维护一段始终加载的 Claude Code bootstrap，
+真正的 session、TaskRef、requirements、计划和审查证据仍由 `.mancode/` 的结构化权威管理；
+mancode 还提供 mode skills、持久化工作流和独立审查 subagents。
 
 ### mancode 和 Cursor rules、自定义 prompt、agent instructions 有什么区别？