fix: prepare 0.4.2 release

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.4.1-2f855a?style=flat-square" alt="Status: mancode Continuity v0.4.1" />
+  <img src="https://img.shields.io/badge/status-Continuity%20v0.4.2-2f855a?style=flat-square" alt="Status: mancode Continuity v0.4.2" />
   <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>
 
@@ -137,6 +137,13 @@ the code baseline, then run
 `MANCODE_GIT_REF_DEFERRED_SYNC_REQUIRED`; cross-clone synchronization is
 complete only after the push returns a receipt.
 
+Atomic git-ref mutations that explicitly require `--sync`, such as
+`workflow update`, complete the remote CAS before materializing the local
+projection. If a resumable `in_progress` or `blocked` task leaves tracked
+`.mancode/shared` changes, commit that projection and run the same
+`team sync push` with the unchanged task revision to rebind the remote code
+head. Another clone must not resume until this push returns a receipt.
+
 For a new project, start with one platform you actually use:
 
 ```bash
@@ -374,7 +381,7 @@ it should behave, and why previous decisions were made.
 
 ## Installation
 
-**Status**: mancode Continuity v0.4.1. Claude Code, Cursor, Codex in the ChatGPT
+**Status**: mancode Continuity v0.4.2. 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
@@ -481,7 +488,7 @@ mancode version
 Simplified output:
 
 ```text
-mancode v0.4.1
+mancode v0.4.2
 
 Project:     my-app
 Runtime:     ready
@@ -628,14 +635,16 @@ mancode/
 - 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.
+- Merge the final candidate into `main`, then run
+  `npm run release:check -- --candidate <full-commit-sha>` from that same
+  `origin/main` commit 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.
 
-See [0.4.1 Continuity Release Acceptance](./docs/release-acceptance.md) for the complete gate.
+See [0.4.2 Continuity Release Acceptance](./docs/release-acceptance.md) for the complete gate.
 
 ## Troubleshooting
 
@@ -660,7 +669,9 @@ hook architecture still uses `mancode init --legacy --force`.
 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
+and `--confirm`. A successful confirmation removes that operation's staging
+preview so internal temporary files cannot make a later Git sync report a dirty
+worktree. 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.
 

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.4.1-2f855a?style=flat-square" alt="状态：mancode Continuity v0.4.1" />
+  <img src="https://img.shields.io/badge/status-Continuity%20v0.4.2-2f855a?style=flat-square" alt="状态：mancode Continuity v0.4.2" />
   <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>
 
@@ -116,6 +116,12 @@ git-ref 下的 workflow create、requirements、plan、review 和 verification 
 `--sync` 会返回 `MANCODE_GIT_REF_DEFERRED_SYNC_REQUIRED`；只有拿到 push receipt
 才表示跨 clone 同步完成。
 
+`workflow update` 等明确要求 `--sync` 的原子 git-ref mutation 会先完成远端 CAS，
+再 materialize 本地投影。如果仍需 resume 的 `in_progress` 或 `blocked` 任务因此产生
+tracked `.mancode/shared` 变更，应先提交这些投影，再用不变的 task revision 执行同一条
+`team sync push`，把远端 code head 重绑到新提交；另一个 clone 只能在这次 push 返回
+receipt 后 resume。
+
 在全新项目中，从一个实际使用的平台开始：
 
 ```bash
@@ -329,7 +335,7 @@ src/components/
 
 ## 安装
 
-**状态**：mancode Continuity v0.4.1。Claude Code、Cursor、ChatGPT 桌面端中的
+**状态**：mancode Continuity v0.4.2。Claude Code、Cursor、ChatGPT 桌面端中的
 Codex、Codex CLI、GitHub Copilot 和 ZCode adapter 均已接入。
 
 需要 Node.js 20 或更高版本。原生支持 macOS、Linux、Windows CMD、
@@ -434,7 +440,7 @@ mancode version
 以下是简化输出示例：
 
 ```text
-mancode v0.4.1
+mancode v0.4.2
 
 Project:     my-app
 Runtime:     ready
@@ -570,11 +576,11 @@ mancode/
 ## 仍在推进
 
 - 在同一发布候选上完成 Claude Code、Codex、Cursor、GitHub Copilot 和 ZCode 的真实宿主 session 验收；宿主自动 session 和显式双 session 都是合法证据路径。
-- 使用 `npm run release:check -- --candidate <完整提交 SHA>` 完成干净 checkout、自动双 clone/legacy、tarball SHA-256 和安装 smoke；另完成跨真实宿主恢复。
+- 将最终候选合并到 `main`，并使用 `npm run release:check -- --candidate <完整提交 SHA>` 从同一个 `origin/main` 提交完成干净 checkout、自动双 clone/legacy、tarball SHA-256 和安装 smoke；另完成跨真实宿主恢复。
 - 确认 ZCode 项目级 skill 发现和 workspace command 路径；完成前继续标记为 provisional。
 - 根据真实需求评估 Windsurf、Cline 和 Roo Code adapter。
 
-完整发布条件见 [0.4.1 Continuity 发布验收](./docs/release-acceptance.md)。
+完整发布条件见 [0.4.2 Continuity 发布验收](./docs/release-acceptance.md)。
 
 ## 故障排查
 
@@ -596,7 +602,8 @@ mancode/
 
 该平台的目标文件缺失或 digest 不匹配。先运行
 `mancode adapter upgrade --platform <platform> --dry-run`，确认 staging 结果后再用
-该预览返回的 `--operation-id` 和 active session 执行 `--confirm`。
+该预览返回的 `--operation-id` 和 active session 执行 `--confirm`。确认成功后会删除
+该 operation 的 staging 预览，避免内部临时文件让后续 Git 同步误判工作区不干净。
 对于 Codex、ZCode 和 Copilot，`AGENTS.md` 或 `.github/copilot-instructions.md`
 中的受控区可能被手动编辑或删除了。
 

docs/12-lifecycle.md

@@ -56,6 +56,10 @@ session 是本地便利状态。关闭一个 session 不会关闭任务，也不
 
 `context session spike` 记录真实宿主的窗口隔离、子命令传播、子 agent 继承和 hook approval，但不保存原始宿主 session key 或显式 session ID。证据模式为 `host` 或 `explicit`：前者通过后可授权受信宿主身份，后者只证明两个已存在、active、client 匹配的显式 session 隔离，不改变运行时的 `explicit_required` 策略。内部 `context beta` 接受与平台能力匹配的任一路径，并要求所有证据绑定同一个 immutable release candidate。
 
-`npm run release:check -- --candidate <完整提交 SHA>` 从 `origin/develop` 创建干净 checkout，运行完整自动化、真实双 clone/legacy fixture、audit、pack 与 tarball 安装 smoke，并把报告和候选 tarball 保存在 `.mancode/local/release-evidence/`。该命令不会执行 `npm publish` 或修改 dist-tag。
+`npm run release:check -- --candidate <完整提交 SHA>` 从最终 `origin/main` 候选创建干净
+checkout，运行完整自动化、真实双 clone/legacy fixture、audit、pack 与 tarball 安装
+smoke，并把报告和候选 tarball 保存在 `.mancode/local/release-evidence/`。候选必须同时
+等于本地 HEAD 和 `origin/main`，检查期间 main 不得变化。该命令不会执行 `npm publish`
+或修改 dist-tag。
 
 尚未完成的验收见 [release-acceptance.md](./release-acceptance.md)。

docs/architecture.md

@@ -77,4 +77,11 @@ mancode team sync push shared:<ULID> --expected-task-revision N --session <ID>
 `team sync push`。直接传入 `--sync` 会稳定返回
 `MANCODE_GIT_REF_DEFERRED_SYNC_REQUIRED`，防止未发布的本地成功被误报为跨 clone 成功。
 
+明确要求 `--sync` 的原子 git-ref mutation 会在一次 CAS 中更新远端 bundle/fence，随后
+materialize 本地投影。若仍可 resume 的 `in_progress` 或 `blocked` 任务留下 tracked
+`.mancode/shared` 变更，owner 提交该投影后必须用不变的 task revision 再执行
+`team sync push`。这个受限的 same-revision 操作只能把 code head 快进重绑到新提交；
+task revision、aggregate digest、owner 和 ownership epoch 都不得变化。另一 clone 应在
+该 receipt 到达后同步 Git、pull transport 并 resume。
+
 远端不会自动同步业务代码。bundle、ownership fence 和 remote revision 只协调 mancode 权威；调用者仍需自行同步 Git 分支。

docs/engineering.md

@@ -36,7 +36,14 @@ npm run build
 npm run test:dist
 ```
 
-发布候选先运行 `npm run prepublishOnly`。提交并推送最终 `develop` 后，运行 `npm run release:check -- --candidate <完整提交 SHA>`，由远端候选的干净 checkout 重跑完整门禁、跨 clone、legacy、audit、pack 和 tarball 安装 smoke，并生成本地 SHA-256 证据。涉及 Windows 原子文件行为时追加 `npm run test:windows-smoke`；涉及网站时运行对应网站测试和浏览器检查。
+发布候选先运行 `npm run prepublishOnly`。开发集成通过后把最终变更合并并推送到
+`main`，等待该 main 提交的 Quality/Windows checks 成功，再运行
+`npm run release:check -- --candidate <完整提交 SHA>`。脚本必须从同一个
+`origin/main` 提交创建干净 checkout，重跑完整门禁、跨 clone、legacy、audit、pack
+和 tarball 安装 smoke，并生成本地 SHA-256 证据。涉及 Windows 原子文件行为时追加
+`npm run test:windows-smoke`；涉及网站时运行对应网站测试和浏览器检查。只有所有真实
+宿主与 Beta 证据也绑定该 main SHA 后才允许发布；npm `gitHead`、tag 和 GitHub Release
+必须继续指向同一个提交。
 
 不要把历史测试数量写入长期文档。报告当前命令、退出码和失败原因即可。