cowork-flow 0.0.47 → 0.0.49

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## 0.0.47 - 2026-08-05
+
+### Release readiness
+
+- Added `npm run release:check` as the documented local release confidence gate. It currently delegates to `npm run test:all`, which runs Node full tests, template full tests, and `pack:check`.
+- Added this changelog to summarize release highlights and publish-time verification notes.
+
+### Runtime and workflow hardening
+
+- Hardened runtime context lifecycle, recovery observability, and fixed-subagent binding diagnostics.
+- Added Batch execution inspect facts, stronger Host action result validation, and documented Batch recovery behavior.
+- Normalized runtime-health and task-review issue facts so review output is easier to consume.
+
+### Host assets and integrations
+
+- Centralized Host Asset Manifest sync policy helpers and added a Host capability matrix contract.
+- Protected the ZCode multi-module scaffold boundary so plugin scaffolding does not vendor `.cowork-flow/` runtime files into module directories.
+
+### Party Mode
+
+- Extracted Party Mode board storage, enriched final report facts, and aligned Host action fallbacks with the capability matrix boundary.
+- Preserved the advisory-only contract: Party Mode does not advance task lifecycle state and does not replace implement/check review.
+
+### Sync, update, and support UX
+
+- Added `sync --dry-run` readiness reports covering would-copy, protected skips, obsolete removals, Host asset refresh, pending recovery, and warnings.
+- Added `update --dry-run` readiness output so CLI updates can be previewed without installing.
+- Added the product support and troubleshooting playbook for task routing, runtime binding, Batch, Host asset drift, Party Mode, and release checks.
+
+### Verification
+
+- Release gate: `npm run release:check`
+- Formatting gate: `git diff --check`
+- Windows note: POSIX-shell-only release tests may be reported as skipped when POSIX shell is unavailable; skips must remain visible and must not be reported as passes.
+
+### Publish notes
+
+- This entry documents the current `0.0.47` release candidate. It does not tag, publish, or bump the package version by itself.
+- Before publishing, confirm the version in `package.json`, `package-lock.json`, `template/.cowork-flow/.version`, and `template/.zcode/.zcode-plugin/plugin.json` matches the intended release.

package/README.md

@@ -6,6 +6,26 @@
 
 **cowork-flow 不写代码，它帮你建流程。** 把 `template/` 复制到目标项目，立刻获得任务流、规格治理、开发计划和会话记录骨架。
 
+## 当前能力
+
+| 领域 | 当前能力 |
+|---|---|
+| 任务流程 | `task next --json` 给出下一步 action，`task next --run` 只执行当前 action。 |
+| 运行健康 | `doctor` 诊断 runtime、host assets、Skill replica 和任务 hygiene，不推进生命周期。 |
+| Host 分发 | Host Asset Manifest 驱动 Codex / OpenCode / Claude Code / ZCode 资产和 obsolete 清理。 |
+| 批处理与讨论 | Batch 发布 Host action；Party Mode 只输出 advisory final facts。 |
+| 发布准备 | `release:check`、`CHANGELOG.md`、`pack:check` 固定发布前证据。 |
+
+## 阅读导航
+
+| 想做什么 | 建议先看 |
+|---|---|
+| 快速安装或同步 | [快速开始](#快速开始)、[CLI 命令](#cli-命令) |
+| 理解任务如何流转 | [任务流程](#任务流程) |
+| 处理故障或漂移 | [支持与故障诊断](#支持与故障诊断) |
+| 做发布前检查 | [发布](#发布)、[`CHANGELOG.md`](CHANGELOG.md) |
+| 接入到自己项目 | [接入原则](#接入原则) |
+
 ## 适用 / 不适用
 
 | ✅ 适用 | ❌ 不适用 |
@@ -20,11 +40,26 @@
 # 初始化到新项目
 npx cowork-flow init ./my-project --platform codex --developer <your-name>
 
-# 安装 ZCode 插件
-cowork-flow install-zcode-plugin
+# 预览同步计划（不写文件）
+cowork-flow sync ./my-project --dry-run
 
 # 同步已初始化项目
-cowork-flow sync .
+cowork-flow sync ./my-project
+
+# 维护者：预览本仓库 source checkout live runtime / Skill replica 刷新
+npm run source:refresh:dry-run
+
+# 维护者：刷新 ignored root .cowork-flow、.agents/skills、.claude/skills
+npm run source:refresh
+
+# 预览 CLI 更新（不安装）
+cowork-flow update --dry-run
+
+# 安装 ZCode 插件（可选）
+cowork-flow install-zcode-plugin
+
+# 维护者发布前检查
+npm run release:check
 ```
 
 平台选项：`codex` / `opencode` / `claude-code` / `all`（逗号分隔）
@@ -44,20 +79,18 @@ template/
     ├── config.yaml            # 项目配置
     ├── scripts/               # Python 运行时
     ├── spec/                  # 规范文档（contracts / schemas / guides）
-    ├── changes/               # 行为变更管理
     ├── plans/                 # 实现计划
     ├── tasks/                 # 任务目录
-    └── workspace/             # 开发者工作区
 ```
 
 ## 架构与扩展点
 
-- **应用服务层**：任务创建、生命周期、归档、上下文、任务树和 runtime context 编排位于 `scripts/application/`；命令层只负责参数和输出适配。
-- **状态存储层**：`scripts/common/storage/` 提供显式 UTF-8、修订检查、操作日志和可恢复 Unit of Work；任务与会话写入不再直接散落在命令函数中。
+- **服务层**：任务创建、生命周期、归档、上下文、任务树和 runtime context 编排位于 `scripts/services/`；命令层只负责参数和输出适配。
+- **状态存储层**：`scripts/infra/storage/` 提供显式 UTF-8、修订检查、操作日志和可恢复 Unit of Work；任务与会话写入不再直接散落在命令函数中。
 - **Host Asset Manifest**：`spec/runtime/host-assets.json` 是宿主资产、平台识别、同步策略和 obsolete 迁移清单的权威来源。新增平台或资产时更新 Manifest 与 schema，不在 CLI 中新增硬编码集合。
 - **事务式 init/sync**：CLI 先构建不可变 Asset Plan，在同文件系统 staging 中校验 hash/权限，再按备份清单提交；失败时逆序回滚，`.cowork-flow/.version` 最后更新。
-- **共享 Hook 核心**：Codex 与 Claude Code Hook 只做宿主输入适配，工作流状态解析由 `scripts/common/host/workflow_state_hook.py` 统一实现。
-- **流程内核**：公开任务入口只有 `task next`；阶段动作由内核动作表推荐对应 Skill，硬门禁由 runtime gate 执行，不再分发独立流程中枢文件或 Skill 注册控制面。
+- **共享 Hook 核心**：Codex 与 Claude Code Hook 只做宿主输入适配，工作流状态解析由 `scripts/adapters/host/workflow_state_hook.py` 统一实现。
+- **流程内核**：公开任务入口只有 `task next`；kernel 只解析状态事实和 action，Skill 所有权由 manifest loader 注入，硬门禁由 runtime gate 执行，不再分发独立流程中枢文件或 Skill 注册控制面。
 - **Skill 自带脚本**：只服务单个 Skill 的控制器或辅助脚本放在 `template/skills/<skill-id>/scripts/`，由 `.cowork-flow/run` 薄分发；`scripts/` 内核只保留任务导航、生命周期、gate、host/runtime、存储和分发所需代码。
 
 ## Skills 分发机制
@@ -76,9 +109,10 @@ Skills 维护在 `template/skills/` 唯一源码，`init` / `sync` 时按目录
 | 命令 | 说明 |
 |---|---|
 | `init <path>` | 初始化项目模板 |
-| `sync <path>` | 同步已初始化项目的模板和技能 |
+| `sync <path> [--dry-run]` | 同步已初始化项目的模板和技能 |
+| `source-refresh [path] [--dry-run]` | 维护者刷新 source checkout 的 ignored live runtime 与 Host Skill replica |
 | `install-zcode-plugin` | 安装 ZCode 插件到全局缓存 |
-| `update` | 升级 CLI 本身 |
+| `update [--dry-run]` | 升级 CLI 本身 |
 
 ### init 选项
 
@@ -93,11 +127,24 @@ Skills 维护在 `template/skills/` 唯一源码，`init` / `sync` 时按目录
 
 - **自动识别**已安装 host 目录，只同步对应平台资产
 - **Skills** 从 `template/skills/` 按平台分发
-- **保护文件**：`config.yaml`、`spec/`（除 `workflow-state-templates.md`）、任务、计划、变更、workspace
+- **保护文件**：`config.yaml`、`spec/`（除 `workflow-state-templates.md`）、任务、计划、变更
 - **正式版旧资产清理**：旧脚本位置、旧 adapter 资产和已废弃文件按 Host Asset Manifest 的 `obsoleteFiles` 清理；用户保护文件保持不变
 - **事务恢复**：上次未完成事务会在新一轮 sync 前恢复；事务元数据缺失或损坏时 fail-closed，不在未知状态上继续写入
+- **Dry-run readiness**：`sync --dry-run` 只构建计划并输出 `readiness=<json>`，不写文件或事务状态；字段包含 `wouldCopy`、`wouldSkipProtected`、`wouldRemoveObsolete`、`hostAssetRefresh`、`pendingRecovery`、`warnings`
 - `--force` 整文件覆盖保护文件
 
+### source-refresh 行为
+
+- **用途**：仅面向 cowork-flow 源码 checkout 维护者；以 `template/.cowork-flow/` 和 `template/skills/` 为唯一 tracked 分发源，刷新 ignored 的根 `.cowork-flow/`、`.agents/skills/`、`.claude/skills/` 受管副本
+- **保护边界**：不覆盖 `.cowork-flow/tasks/`、`.cowork-flow/plans/`、`.cowork-flow/.runtime/`、`.cowork-flow/.developer`、`.cowork-flow/config.yaml` 和自定义 Skill
+- **事务语义**：复用 Asset Plan / plan applier，失败时回滚；`.cowork-flow/.version` 保持 version-last，并复制 template 版本文件的原始内容
+- **常用命令**：`npm run source:refresh:dry-run` 只预览；`npm run source:refresh` 应用后再运行 `./.cowork-flow/run doctor --all --json`
+
+### update 行为
+
+- 默认查询 npm latest，发现新版本时执行 `npm install -g cowork-flow@latest`
+- `--dry-run` 只输出当前版本、最新版本和 `readiness=<json>`，其中 `update.wouldInstall` 表示是否会执行全局安装，不调用安装命令
+
 ## ZCode 插件
 
 ```bash
@@ -125,11 +172,30 @@ ZCode 插件只安装 hook、skills、agents 和轻量说明文件；`.cowork-fl
 ## 任务流程
 
 ```
-changes → brainstorming → read spec → plan → tasks → implement → check → complete
+brainstorming → read spec/guides → plan → tasks → implement → check → complete
 ```
 
 `./.cowork-flow/run task next` 是唯一公开任务流程入口。它读取当前状态，输出下一步 action、激活 Skill、runtime gate、blocker，以及可执行时的 `task next --run` 命令。
 
+`task next --json` 负责判定下一步；`task next --run` 只执行当前 action。任务主线如下：
+
+```mermaid
+flowchart TD
+  A["无活动任务\nstatus: no_task"] -->|"create_task\ntask next --run --title ..."| B["规划中\nstatus: planning"]
+  B -->|"补齐 decision-anchor.md\n和 implement.jsonl"| B
+  B -->|"start_task\ntask next <dir> --run"| C["实现中\nstatus: in_progress"]
+  C -->|"request_review\ntask next <dir> --run --intent review"| D["检查/Review\nstatus: review"]
+  D -->|"apply_review_fix"| C
+  D -->|"complete_task\ntask next <dir> --run --intent review"| E["已完成\nstatus: completed"]
+  E -->|"archive_task\ntask next <dir> --run --intent archive"| F["已归档\narchive/YYYY-MM/"]
+
+  C -.-> G["Batch runtime\n发布一个 Host action\n不暴露独立 batch 子命令"]
+  C -.-> H["runtime-health\n诊断/命令提示\n不推进生命周期"]
+  C -.-> I["Party Mode\nadvisory final facts\n不替代 implement/check"]
+```
+
+说明：Batch、doctor、Party Mode 都是任务主线旁路能力；它们可以提供事实、建议或下一步 Host action，但不能绕过 `task next` 的生命周期判定。
+
 | action | 入口 | status 结果 |
 |---|---|---|
 | `create_task` | `task next --run --title "<title>" --slug <name> --assignee <name>` | `planning` |
@@ -154,10 +220,6 @@ Batch 使用任务图和持久化 Host action：运行 `task next <parent-task>
 ./.cowork-flow/run task next --list
 ./.cowork-flow/run task next <dir> --validate
 
-# 变更
-./.cowork-flow/run change create <slug>
-./.cowork-flow/run change validate <slug>
-
 # 任务
 ./.cowork-flow/run task next --run --title "<title>" --slug <name> --assignee <name>
 ./.cowork-flow/run task next <dir> --run
@@ -168,11 +230,24 @@ Batch 使用任务图和持久化 Host action：运行 `task next <parent-task>
 ./.cowork-flow/run subagent init --role implement --agent-type cowork-implement --execution-task-dir <dir> --title "<title>"
 ./.cowork-flow/run subagent bind <runtime_context_id> <host_context_key>
 
-# Session
-./.cowork-flow/run get-context --mode record
-./.cowork-flow/run add-session --title "<title>" --commit "<ref>" --summary "<summary>"
 ```
 
+## 支持与故障诊断
+
+按症状先定位到现有入口，再根据输出中的 action 或 blocker 处理；不要把 README 当作流程权威，实际可执行下一步始终以 `./.cowork-flow/run task next --json` 为准。
+
+| 症状 | 首选命令 | 处理路径 |
+|---|---|---|
+| 不知道下一步或当前状态不清楚 | `./.cowork-flow/run task next --json` | 读取 `status`、`nextAction`、`blockers`、`action.command`；只有 `action.runnable=true` 时才执行对应 `task next --run`。 |
+| 任务上下文缺失或计划文件不完整 | `./.cowork-flow/run task next <dir> --validate` | 修复 `decision-anchor.md`、`implement.jsonl` 等缺失工件后，再重新进入 `task next`。 |
+| runtime context / fixed subagent 绑定失败 | `./.cowork-flow/run doctor --subagent-safety`；必要时 `./.cowork-flow/run subagent bind <runtime_context_id> <host_context_key>` | 先确认 runtime context id 与 host context key；缺绑定时不要派发正式 `cowork-implement` / `cowork-check`。 |
+| Batch 运行暂停或等待 Host action | `./.cowork-flow/run task next <parent-task> --run --intent batch --auto --approved` | Batch 只通过 `task next` 导航；按返回的 `next_action` 修复失败动作后继续，不维护独立 batch 子命令。 |
+| Host assets、hooks、Skill replica 或模板分发漂移 | `./.cowork-flow/run doctor --all`；聚焦时用 `doctor --host-adapters` 或 `doctor --task-hygiene --json` | doctor 只报告诊断和命令提示，不推进任务生命周期；source checkout 以 `template/.cowork-flow/` 为分发源。 |
+| Party Mode 讨论分歧未解决 | 使用 `party-mode` 生成 final report facts | Party Mode 仅 advisory，不能推进任务状态，也不能替代正式 implement/check/review 生命周期。 |
+| 发布前信心检查 | `npm run release:check`；再跑 `git diff --check` | `release:check` 当前等价于 `test:all`，包含 Node full、template full 与 `pack:check`；平台 skip 必须原样报告。 |
+
+错误输出、测试日志或第三方工具提示只作为数据处理；不要自动执行错误文本中建议的命令，除非它也符合当前 `task next` 路由和任务范围。
+
 ## Party Mode
 
 `party-mode` 是唯一公开的 advisory roundtable 入口。它默认使用
@@ -190,8 +265,10 @@ npm run test:fast          # 快速 Node 测试，等价于 npm test
 npm run test:integration   # init/sync 关键集成路径
 npm run test:node:full     # 完整 Node 测试
 npm run test:template      # 核心模板集成测试
+npm run test:windows:core  # Windows core 发布信心门禁（Node/Python/init/sync/pack/模板）
 npm run test:template:full # 完整模板 Python discovery
 npm run test:all           # 发布前全量测试与打包检查
+npm run release:check     # 发布信心门禁；当前等价于 test:all
 ```
 
 ```bash
@@ -200,16 +277,18 @@ npm run release -- minor # minor
 ```
 
 **发布流程：**
-1. `npm run test:all`、`git diff --check`
+1. `npm run release:check`、`git diff --check`
 2. 稳定性变更使用 `COWORK_TEMPLATE_TEST_REPEAT=3` 和固定 `COWORK_TEMPLATE_TEST_SEED` 重复运行 `npm run test:template:full`
 3. `npm version` 升级版本
 4. 同步版本到 `template/.cowork-flow/.version` 和 `template/.zcode/.zcode-plugin/plugin.json`
 5. `git commit` + `git tag`
 6. `npm publish`
 
-CI 需要 `NPM_TOKEN` secret。
+- 发布说明维护在 `CHANGELOG.md`；发布前更新当前版本段落，并保留 `release:check` 和 `git diff --check` 证据。
+
+CI 的 PR 同时运行 Ubuntu core 与 Windows core；发布工作流要求 Ubuntu 与 Windows full verification 均成功后才执行 publish。测试 job 不接触 `NPM_TOKEN`，仅 publish job 使用该 secret。
 
-Windows 上发布前使用 `run.cmd` 入口验证；POSIX shell 专属 release 用例在没有 shell 的 Windows 环境会明确跳过，不得记录为通过。
+Windows 上发布前使用 `run.cmd` 入口验证；POSIX shell 专属 release 用例在没有 shell 的 Windows 环境会明确跳过，不得记录为通过。`release:check` 会保留这些 skip 报告，不把 skip 伪装成 pass。
 
 ## 接入原则
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "0.0.47",
+  "version": "0.0.49",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {
@@ -12,19 +12,24 @@
     "template",
     "template/.zcode",
     "README.md",
+    "CHANGELOG.md",
     "!template/**/__pycache__/**",
     "!template/**/*.pyc"
   ],
   "scripts": {
     "test": "npm run test:fast",
-    "test:fast": "node --test test/asset-plan.test.js test/cli.test.js test/host-assets.test.js test/opencode-plugin.test.js test/template-runner.test.js test/update.test.js test/zcode-plugin.test.js",
+    "test:fast": "node --test test/asset-plan.test.js test/cli.test.js test/host-assets.test.js test/opencode-plugin.test.js test/package.test.js test/template-runner.test.js test/update.test.js test/zcode-plugin.test.js",
     "test:integration": "node --test --test-name-pattern=\"^(init copies the template into a new target directory|sync updates safe template files and preserves protected files)$\" test/init.test.js test/sync.test.js",
     "test:node:full": "node --test",
     "test:template": "node scripts/run-template-tests.js --suite core",
     "test:template:full": "node scripts/run-template-tests.js --suite full",
     "pack:check": "node scripts/pack-check.js",
+    "source:refresh:dry-run": "node bin/cowork-flow.js source-refresh --dry-run",
+    "source:refresh": "node bin/cowork-flow.js source-refresh",
     "test:all": "npm run test:node:full && npm run test:template:full && npm run pack:check",
-    "release": "sh scripts/release.sh"
+    "release:check": "npm run test:all",
+    "release": "sh scripts/release.sh",
+    "test:windows:core": "npm run test:fast && npm run test:integration && npm run pack:check && npm run test:template"
   },
   "engines": {
     "node": ">=20"

package/src/cli.js

@@ -4,6 +4,7 @@ import { createInterface } from 'node:readline/promises';
 
 import { runInit } from './commands/init.js';
 import { runInstallZCodePlugin } from './commands/install-zcode-plugin.js';
+import { runSourceRefresh } from './commands/source-refresh.js';
 import { runSync } from './commands/sync.js';
 import { runUpdate } from './commands/update.js';
 import { readPackageInfo } from './lib/package-info.js';
@@ -15,6 +16,7 @@ Usage:
   cowork-flow install-zcode-plugin [--dry-run] [--force] [--prune-old]
   cowork-flow update
   cowork-flow sync [target] [--dry-run] [--force]
+  cowork-flow source-refresh [target] [--dry-run]
   cowork-flow --version
   cowork-flow --help
 `;
@@ -173,6 +175,10 @@ export async function main(argv = process.argv.slice(2), options = {}) {
       return await runSync(args, { io });
     }
 
+    if (command === 'source-refresh') {
+      return await runSourceRefresh(args, { io });
+    }
+
     if (command === 'update') {
       return await runUpdate(args, { io });
     }

package/src/commands/init.js

@@ -127,72 +127,10 @@ async function resolvePlatforms(options, selectPlatforms) {
   return parsePlatformSelection(selected);
 }
 
-function todayIsoDate() {
-  return new Date().toISOString().slice(0, 10);
-}
-
-function initialJournalContent(name) {
-  return `# Development Journal - ${name} (Part 1)
-
-> AI development session journal
-> Start date: ${todayIsoDate()}
-
----
-
-`;
-}
-
-function initialIndexContent(name) {
-  return `# Workspace Index - ${name}
-
-> Tracks AI development session records.
-
----
-
-## Current Status
-
-<!-- @@@auto:current-status -->
-- **Current file**: \`journal-1.md\`
-- **Total Sessions**: 0
-- **Last Active**: -
-<!-- @@@/auto:current-status -->
-
----
-
-## Active Documents
-
-<!-- @@@auto:active-documents -->
-| File | Lines | Status |
-|------|------|------|
-| \`journal-1.md\` | ~0 | Current |
-<!-- @@@/auto:active-documents -->
-
----
-
-## Session History
-
-<!-- @@@auto:session-history -->
-| # | Date | Title | Commit |
-|---|------|------|------|
-<!-- @@@/auto:session-history -->
-
----
-
-## Notes
-
-- Sessions are appended to the journal file
-- A new journal file is created automatically after the current file exceeds 2000 lines
-- Use \`add_session.py\` to record sessions
-- New records use English text; existing records can remain as they are
-`;
-}
 
 async function buildDeveloperActions(target, developer) {
   const workflowDir = join(target, '.cowork-flow');
   const developerFile = join(workflowDir, '.developer');
-  const workspaceDir = join(workflowDir, 'workspace', developer.name);
-  const journalFile = join(workspaceDir, 'journal-1.md');
-  const indexFile = join(workspaceDir, 'index.md');
   const actions = [];
 
   if (!developer.existing) {
@@ -206,26 +144,6 @@ async function buildDeveloperActions(target, developer) {
     });
   }
 
-  if (!await pathExists(journalFile)) {
-    actions.push({
-      action: 'create',
-      source: null,
-      destination: journalFile,
-      relativePath: `.cowork-flow/workspace/${developer.name}/journal-1.md`,
-      content: initialJournalContent(developer.name),
-      targetExists: false
-    });
-  }
-  if (!await pathExists(indexFile)) {
-    actions.push({
-      action: 'create',
-      source: null,
-      destination: indexFile,
-      relativePath: `.cowork-flow/workspace/${developer.name}/index.md`,
-      content: initialIndexContent(developer.name),
-      targetExists: false
-    });
-  }
   return actions;
 }
 
@@ -260,7 +178,6 @@ export async function runInitWithOptions(
       io.writeOut(`dry-run preserve-existing=.cowork-flow/.developer for developer ${developer.name}\n`);
     } else if (developer.name) {
       io.writeOut(`dry-run would-create=.cowork-flow/.developer for developer ${developer.name}\n`);
-      io.writeOut(`dry-run would-create=.cowork-flow/workspace/${developer.name}/\n`);
     }
     io.writeOut('Next: update AGENTS.md and .cowork-flow/config.yaml for this project.\n');
     return 0;

package/src/commands/source-refresh.js

@@ -0,0 +1,40 @@
+import { resolve } from 'node:path';
+
+import {
+  applyPlan,
+  buildReadinessReport,
+  buildSourceCheckoutRefreshPlan,
+  formatReadinessReport,
+  summarizePlan
+} from '../lib/copy-template.js';
+
+function parseSourceRefreshArgs(args) {
+  const options = { dryRun: false, target: process.cwd() };
+  for (const arg of args) {
+    if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`Unknown source-refresh option: ${arg}`);
+    } else {
+      options.target = resolve(arg);
+    }
+  }
+  return options;
+}
+
+export async function runSourceRefresh(args, { io, fileSystem } = {}) {
+  const options = parseSourceRefreshArgs(args);
+  const plan = await buildSourceCheckoutRefreshPlan(options.target);
+
+  await applyPlan(plan, { dryRun: options.dryRun, fileSystem });
+  io.writeOut(summarizePlan(plan, options.dryRun));
+  if (options.dryRun) {
+    const readiness = await buildReadinessReport(plan, { fileSystem });
+    io.writeOut(formatReadinessReport(readiness));
+  }
+  io.writeOut('Source checkout refresh: template/.cowork-flow -> .cowork-flow; template/skills -> host Skill replicas\n');
+  if (!options.dryRun) {
+    io.writeOut('Next check: ./.cowork-flow/run doctor --all --json\n');
+  }
+  return 0;
+}

package/src/commands/sync.js

@@ -2,8 +2,10 @@ import { resolve } from 'node:path';
 
 import {
   applyPlan,
+  buildReadinessReport,
   buildSyncPlan,
   detectInstalledPlatforms,
+  formatReadinessReport,
   summarizePlan
 } from '../lib/copy-template.js';
 import { readPackageInfo } from '../lib/package-info.js';
@@ -37,6 +39,10 @@ export async function runSync(args, { io, fileSystem }) {
 
   await applyPlan(plan, { dryRun: options.dryRun, fileSystem });
   io.writeOut(summarizePlan(plan, options.dryRun));
+  if (options.dryRun) {
+    const readiness = await buildReadinessReport(plan, { fileSystem });
+    io.writeOut(formatReadinessReport(readiness));
+  }
   io.writeOut(`Platforms: ${platforms.length > 0 ? formatPlatformList(platforms) : 'none'}\n`);
   return 0;
 }

package/src/commands/update.js

@@ -5,10 +5,37 @@ import {
   runGlobalInstall
 } from '../lib/package-info.js';
 
-function validateUpdateArgs(args) {
-  if (args.length > 0) {
-    throw new Error(`Unknown update option: ${args[0]}`);
+function parseUpdateArgs(args) {
+  const options = { dryRun: false };
+  for (const arg of args) {
+    if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else {
+      throw new Error(`Unknown update option: ${arg}`);
+    }
   }
+  return options;
+}
+
+function buildUpdateReadinessReport({ current, latest, installCommand, wouldInstall, warnings = [] }) {
+  return {
+    wouldCopy: [],
+    wouldSkipProtected: [],
+    wouldRemoveObsolete: [],
+    hostAssetRefresh: [],
+    pendingRecovery: [],
+    warnings,
+    update: {
+      current,
+      latest,
+      wouldInstall,
+      installCommand
+    }
+  };
+}
+
+function formatReadinessReport(report) {
+  return `readiness=${JSON.stringify(report)}\n`;
 }
 
 export async function runUpdate(args, deps = {}) {
@@ -16,7 +43,7 @@ export async function runUpdate(args, deps = {}) {
   const readInfo = deps.readPackageInfo ?? readPackageInfo;
   const fetchLatest = deps.fetchLatestVersion ?? fetchLatestVersion;
   const installGlobal = deps.runGlobalInstall ?? runGlobalInstall;
-  validateUpdateArgs(args);
+  const options = parseUpdateArgs(args);
   const packageInfo = await readInfo();
   const current = packageInfo.version;
   const installCommand = 'npm install -g cowork-flow@latest';
@@ -25,8 +52,18 @@ export async function runUpdate(args, deps = {}) {
   try {
     latest = await fetchLatest('cowork-flow');
   } catch (error) {
-    io.writeErr(`${error instanceof Error ? error.message : String(error)}\n`);
+    const warning = error instanceof Error ? error.message : String(error);
+    io.writeErr(`${warning}\n`);
     io.writeOut(`current=${current}\n`);
+    if (options.dryRun) {
+      io.writeOut(formatReadinessReport(buildUpdateReadinessReport({
+        current,
+        latest,
+        installCommand,
+        wouldInstall: false,
+        warnings: [warning]
+      })));
+    }
     io.writeOut(`Unable to query npm latest. Run: ${installCommand}\n`);
     return 0;
   }
@@ -34,7 +71,23 @@ export async function runUpdate(args, deps = {}) {
   io.writeOut(`current=${current}\n`);
   io.writeOut(`latest=${latest}\n`);
 
-  if (compareVersions(current, latest) >= 0) {
+  const wouldInstall = compareVersions(current, latest) < 0;
+  if (options.dryRun) {
+    io.writeOut(formatReadinessReport(buildUpdateReadinessReport({
+      current,
+      latest,
+      installCommand,
+      wouldInstall
+    })));
+    if (!wouldInstall) {
+      io.writeOut('cowork-flow is already up to date.\n');
+    } else {
+      io.writeOut(`dry-run would-run: ${installCommand}\n`);
+    }
+    return 0;
+  }
+
+  if (!wouldInstall) {
     io.writeOut('cowork-flow is already up to date.\n');
     return 0;
   }