cowork-flow 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -4,6 +4,34 @@
 
 ### Added
 
+## [2.2.0] - 2026-10-20
+
+### Changed
+
+- **计划与任务验证段纳入规范门禁检查**：`task-planning` 的计划 `Final Verification`、任务规则与 Self-Review 要求按 `dev_type` 逐条核对 `.cowork-flow/spec/<dev_type>/` 适用规范与项目门禁——改动被规范覆盖时，把决定命令或 `规范核对:` 行写进计划的 Final Verification 与任务简报的 Verification Command，标 `pass` / `not_applicable` 并写理由；`decision-anchor` 契约的 `## 验证命令` 同步要求该检查行，并明确为 review 强提醒而非 `spec-check` 硬门禁，120 字符/10 行限制不变。
+- **模板示例统一展示规范核对行**：`decision-anchor` Schema 的 `## 验证命令` 示例新增 `规范核对:` 行；`task-planning` 任务简报的 `Verification Command` 示例块后补充写法说明，避免新建计划/任务漏写规范检查项。
+
+## [2.1.0] - 2026-10-19
+
+### Added
+
+- **发布前漂移门禁接入 release.sh，测试范围与超时收敛**：发布 pre-flight 在 `source:refresh`（会覆写活副本）之前强制跑 `node scripts/release-gates.js`，自实例漂移即中止并打印修复指引；新增 `pytest.ini`（`testpaths = tests`）把 `python -m pytest -q` 的收集范围钉在 `tests/`，所有 node 测试脚本统一 `--test-timeout=600000`，`test:windows:core` 补上 Windows 全量 `init/sync` 套件（此前只跑两条具名用例）。
+- **发布门禁补"活副本资产漂移"verdict**：`release-gates` 新增 `self-instance-asset-drift`——以 `node bin/cowork-flow.js project sync . --dry-run` 的 readiness 为准，`wouldCopy`/`wouldRemoveObsolete` 非空即 fail 并点名文件（`wouldSkipProtected`/`wouldKeep` 只报告不阻断）。覆盖 `.claude/**`、`.codex/**`、skills 等 `dev refresh` 看不到的活副本，避免发布第 5 步 `sync --force` 静默覆写；`scripts/release.sh` 失败提示补 `node bin/cowork-flow.js project sync .` 修复指引。
+- **doctor 增补 zcode 插件新鲜度检查**：`check_zcode_plugin` 以 payload 盖章清单 `.zcode-plugin/plugin.json` 的版本对比项目 `.cowork-flow/.version` → `PLUGIN-STALE`（hint `cwf host add zcode --force`）；未声明 zcode 静默，声明未安装报 `PLUGIN-NOT-INSTALLED`，清单不可读报 `PLUGIN-UNKNOWN-VERSION`。与 opencode/qoder 同为 advisory，不进 error 级。
+
+### Changed
+
+- **Python 解释器下限统一 3.10，五个宿主 shim 加解释器探针守卫**：`template/.cowork-flow/run`、`run.cmd` 的版本判据与提示从 3.9 升到 3.10（与运行时协议一致）；`presets/{opencode,zcode,qoder,kimi-code,dsh}` 的注入 shim 逐个候选加同源版本探针（`sys.version_info >= (3, 10)`），不可用即跳过、全不可用则 stderr 一行说明并 fail-open（exit 0），探针超时视为无裁决、不跳过。**迁移**：shim 在宿主载荷内，需 `cwf host add <host> --force` 重装。
+- **清理 spec-check 删除后的文档与宿主提示残留**：README（中英）、`docs/{index,hosts,direction}.md`、`context-injection.md` 里"规范检查/规范门禁"的过时措辞改为"同步策略与受保护文件"，并订正机器级 shim 的 fail-open 描述（现为四个机器级 shim；项目级 Edit 期 hook 自 2.0.0 起同样 advisory、恒 exit 0）；15 处宿主 agent 提示（`.claude`/`.codex`/`.kimi-code`/`.opencode` 的 `cowork-*` 与 codex 的 `default`/`explorer`/`worker`）把点名已删子命令的禁令改为"禁止执行任务生命周期转换"。
+- **`assetDriftVerdict` 缺键改为 fail-closed**：readiness 少 `wouldCopy`/`wouldRemoveObsolete`（或给非数组）时不再静默判"无漂移"，改判门禁失效并点名缺失键（`cannot judge drift`），并把逐 key 单钉、e2e fail 断言补进测试。
+- **dsh 候选可用性映射抽为 `candidateUnavailable` 并恢复 Windows 覆盖**：`ENOENT`/退出码 3 → 换下一个候选；其余非零退出（含超时）→ 候选按"可用但协议失败、不注入"处理（语义不变，仅抽函数加注释）；新增跨平台单测钉住四种输入，`test/dsh-hook.test.js` 两条过期的 Windows skip 移除（取证：node 探测 WindowsApps `python3` 别名得 `ENOENT`、回落到真实 `python` 3.12）。
+- **重复工具函数收敛**：`sha256` 只留 `src/lib/asset-plan.js` 的导出，`src/lib/plan-applier.js` 改为复用；`getDshHome` 抽到新增的 `src/lib/dsh-home.js`，两个 dsh 安装器共用。
+
+### Fixed
+
+- **dsh 完整协议 stdout 固定 UTF-8，恢复非 CJK 控制台下的工作流注入**：`<workflow-state>` 块含中文文案，Windows 默认 ANSI 代码页（CI runner 为 cp1252）下 `print()` 抛 `UnicodeEncodeError`，调用方按既有语义读作"解释器能跑但协议失败 → 不注入"，dsh 会话静默丢失整块注入——上面移除 Windows skip 后两条用例在 runner 上暴露的正是这个缺陷（原 skip 注释归因于 WindowsApps `python3` 桩，实测不符）。修法对齐同文件 edit-scope 协议与 `inject.py` 的既有写法，在完整协议开头补 `sys.stdout.reconfigure(encoding="utf-8", errors="replace", newline="")`；新增回归用例在 `PYTHONIOENCODING=ascii` 下钉住该契约（红证：改动前该用例失败）。顺带把 `newline=""` 的 LF 语义带进来，块字节在 Windows 与 POSIX 上一致。
+- **release 编排用例补 `scripts/release-gates.js` 桩**：`0c81b29` 给 `release.sh` 加的首道漂移门禁在 Linux 上必飞——夹具只复制 `release.sh`，`node scripts/release-gates.js` 报 `Cannot find module` 被读作漂移阻断，3 条用例红（was: 该门禁已无任何用例钉住其接线）。夹具补同款 `process.exit(0)` 桩，并在"defaults to patch"用例断言门禁先于 `source:refresh` 运行。
+
 ## [2.0.0] - 2026-10-16
 
 ### Added
@@ -365,7 +393,9 @@
 
 此版本未保留本地条目正文，详情见 [GitHub Release](https://github.com/fishlikewater/cowork-flow/releases/tag/v0.0.47)。
 
-[Unreleased]: https://github.com/fishlikewater/cowork-flow/compare/v2.0.0...HEAD
+[Unreleased]: https://github.com/fishlikewater/cowork-flow/compare/v2.2.0...HEAD
+[2.2.0]: https://github.com/fishlikewater/cowork-flow/compare/v2.1.0...v2.2.0
+[2.1.0]: https://github.com/fishlikewater/cowork-flow/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/fishlikewater/cowork-flow/compare/v1.9.2...v2.0.0
 [1.9.2]: https://github.com/fishlikewater/cowork-flow/compare/v1.9.1...v1.9.2
 [1.9.1]: https://github.com/fishlikewater/cowork-flow/compare/v1.9.0...v1.9.1

package/README.en.md

@@ -169,7 +169,7 @@ The detailed documentation is written in Chinese.
 | Document | Contents |
 |---|---|
 | [Documentation index](docs/index.md) | Entry point for every document |
-| [Architecture and extension](docs/architecture.md) | How the project files are organized, how spec checks work |
+| [Architecture and extension](docs/architecture.md) | How the project files are organized, how the sync policy and protected files work |
 | [Host integration](docs/hosts.md) | Install, restart, troubleshoot, and uninstall for each host |
 | [Release and maintenance](docs/release.md) | Tests, CI, and maintainer commands |
 | [Contributing](CONTRIBUTING.md) | Local setup, commit conventions, and PR checks |

package/README.md

@@ -149,7 +149,7 @@ cwf project sync .
 | 文档 | 内容 |
 |---|---|
 | [文档索引](docs/index.md) | 全部文档入口 |
-| [架构与扩展](docs/architecture.md) | 项目文件如何组织、规范检查如何工作 |
+| [架构与扩展](docs/architecture.md) | 项目文件如何组织、同步策略与受保护文件 |
 | [宿主接入](docs/hosts.md) | 各宿主的安装、重启、排障和卸载方式 |
 | [发布与维护](docs/release.md) | 测试、CI 和维护者命令 |
 | [参与开发](CONTRIBUTING.md) | 本地开发、提交和 PR 检查 |

package/docs/direction.md

@@ -1,6 +1,6 @@
 # cowork-flow 方向规划：Agent 运行时上下文与协作事实层
 
-> 状态：**已批准** · 创建：2026-08-27 · 最近更新：2026-10-13
+> 状态：**已批准** · 创建：2026-08-27 · 最近更新：2026-10-19
 > 本文档是后续阶段立项的权威输入。任何方向的修订必须先更新本文档，再立项。
 > 已完成阶段的实施细节与提交记录见 [CHANGELOG](../CHANGELOG.md)；本文只保留仍然生效的定位、取舍、边界和待决项。
 
@@ -46,7 +46,8 @@
 ## 5. 版本线
 
 - **1.8.x 已发布**：证据化完成（AC 事实化、`evidence.jsonl`、完成门禁）。
-- **1.9.0 主线已实现，待发布**：多执行者协作事实——看板归属可见、依赖边、交接凭证。详见 [CHANGELOG](../CHANGELOG.md) 的 `[Unreleased]` 段。
+- **1.9.x 已发布**：多执行者协作事实——看板归属可见、依赖边、交接凭证。
+- **2.0.0 已发布**：spec-check 机制破坏性删除、编辑期越界警告覆盖各宿主、注入容量放宽（Verify 10 条 / 块预算 3400）。详见 [CHANGELOG](../CHANGELOG.md) 的 `[2.0.0]` 段。
 - 各版本的交付明细一律以 CHANGELOG 为准，本文不重复。
 
 ## 6. 待决项与缓行

package/docs/hosts.md

@@ -51,7 +51,7 @@ cwf host remove <host>
 
 `--force` 只在确认需要覆盖已有安装时使用。安装器遇到不属于自己的文件时默认拒绝覆盖或删除；`--dry-run` 会执行同样的归属检查。
 
-机器级 hook 与项目运行时各自升级，而它会在任何工作区触发——包括运行时比它旧的项目。三个机器级注入 shim（Qoder、ZCode、Kimi Code）因此是 **fail-open** 的：项目运行时失败时只在宿主运行日志留原因并返回 0，不注入，也不把「hook 失败」变成「拒绝你的输入」；保留非零退出的只有项目级 Edit 期规范门禁（Claude Code / Codex），它与所调用的运行时同源。旧项目上注入会静默不生效，跑一次 `cwf project sync .` 即可恢复。
+机器级 hook 与项目运行时各自升级，而它会在任何工作区触发——包括运行时比它旧的项目。四个机器级注入 shim（Qoder、ZCode、Kimi Code、OpenCode）因此是 **fail-open** 的：项目运行时失败时只在宿主运行日志留原因并返回 0，不注入，也不把「hook 失败」变成「拒绝你的输入」；项目级 Edit 期 hook（Claude Code / Codex）自 2.0.0 起同样不再返回非零退出，一律 advisory。旧项目上注入会静默不生效，跑一次 `cwf project sync .` 即可恢复。
 
 ## Codex
 

package/docs/index.md

@@ -8,7 +8,7 @@
 |---|---|---|
 | 安装、初始化项目或开始一个任务 | [README](../README.md) | 最短使用路径、日常命令和常见问题 |
 | 把 cowork-flow 接到某个 AI 编码宿主 | [宿主接入](hosts.md) | 各宿主的安装组件、重启要求、升级、卸载和排障方式 |
-| 了解项目文件如何组织 | [架构与扩展](architecture.md) | 运行时、`template/`、`presets/`、规范检查和扩展边界 |
+| 了解项目文件如何组织 | [架构与扩展](architecture.md) | 运行时、`template/`、`presets/`、同步策略和扩展边界 |
 | 参与项目开发 | [参与开发](../CONTRIBUTING.md) | 本地环境、代码约定、测试和 PR 检查 |
 | 了解测试与发布流程 | [发布与维护](release.md) | 测试分层、CI、版本发布和维护者命令 |
 | 了解项目方向与版本规划 | [方向规划](direction.md) | 定位声明、已拍板取舍、版本主线与待决项 |

package/docs/release.md

@@ -17,7 +17,7 @@
 | `npm run test:windows:core` | 涉及 Windows、路径、换行或发布行为 |
 | `python -m pytest -q` | 改动 `template/.cowork-flow/`、`tests/` 或 Python 契约 |
 | `npm run test:all` | 准备发布时的完整 Node、模板和打包检查 |
-| `npm run release:check` | 发布信心门禁：`test:all` 加上测试表达不了的检查——自实例相对 `template/` 的漂移，以及 `doctor --all` 的 error 级问题 |
+| `npm run release:check` | 发布信心门禁：`test:all` 加上测试表达不了的检查——自实例与活副本资产（`.claude/**`、`.codex/**`、skills）相对 `template/` 的漂移，以及 `doctor --all` 的 error 级问题 |
 
 平台前提不满足时，测试可能明确跳过。跳过项必须原样记录，不能当作通过。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "keywords": [
     "ai-agent",
@@ -48,10 +48,10 @@
   ],
   "scripts": {
     "test": "npm run test:fast",
-    "test:smoke": "node --test test/smoke.test.js test/tarball-install.test.js",
-    "test:fast": "node --test test/asset-plan.test.js test/cli.test.js test/cli-registry.test.js test/claude-code-plugin.test.js test/codex-plugin.test.js test/compliance-e2e.test.js test/contract-fingerprint.test.js test/copy-template.obsolete-safety.test.js test/docs.test.js test/host-assets.test.js test/host-command.test.js test/kimi-hook.test.js test/kimi-installed-registry.test.js test/kimi-plugin.test.js test/opencode-plugin-installer.test.js test/opencode-plugin.test.js test/package.test.js test/plugin-metadata.test.js test/plugin-payload.test.js test/qoder-plugin.test.js test/smoke.test.js test/stage-contract.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:smoke": "node --test --test-timeout=600000 test/smoke.test.js test/tarball-install.test.js",
+    "test:fast": "node --test --test-timeout=600000 test/asset-plan.test.js test/cli.test.js test/cli-registry.test.js test/claude-code-plugin.test.js test/codex-plugin.test.js test/compliance-e2e.test.js test/contract-fingerprint.test.js test/copy-template.obsolete-safety.test.js test/docs.test.js test/host-assets.test.js test/host-command.test.js test/kimi-hook.test.js test/kimi-installed-registry.test.js test/kimi-plugin.test.js test/opencode-plugin-installer.test.js test/opencode-plugin.test.js test/package.test.js test/plugin-metadata.test.js test/plugin-payload.test.js test/qoder-plugin.test.js test/smoke.test.js test/stage-contract.test.js test/template-runner.test.js test/update.test.js test/zcode-plugin.test.js",
+    "test:integration": "node --test --test-timeout=600000 --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-timeout=600000",
     "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",
@@ -61,7 +61,7 @@
     "test:all": "npm run test:node:full && npm run test:template:full && npm run pack:check",
     "release:check": "npm run test:all && node scripts/release-gates.js",
     "release": "sh scripts/release.sh",
-    "test:windows:core": "npm run test:fast && npm run test:integration && node --test test/dsh-home-patch.test.js test/dsh-hook.test.js test/dsh-preset.test.js test/dsh-preset-bundle.test.js test/mcp-client-matrix.test.js test/mcp-state-command.test.js test/tarball-install.test.js && npm run pack:check && npm run test:template"
+    "test:windows:core": "npm run test:fast && npm run test:integration && node --test --test-timeout=600000 test/dsh-home-patch.test.js test/dsh-hook.test.js test/dsh-preset.test.js test/dsh-preset-bundle.test.js test/mcp-client-matrix.test.js test/mcp-state-command.test.js test/tarball-install.test.js && node --test --test-timeout=600000 test/init.test.js test/sync.test.js && npm run pack:check && npm run test:template"
   },
   "engines": {
     "node": ">=20"

package/presets/claude-code/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 Claude Code。",
   "displayName": "Cowork Flow",
   "author": {

package/presets/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 Codex。",
   "author": {
     "name": "fishlikewater",

package/presets/dsh/plugins/workflow-state.js

@@ -52,14 +52,28 @@ const NO_ROOT_MARKER = '__COWORK_FLOW_NO_ROOT__';
 const NO_ROOT_TTL_MS = 30_000;
 const noRootCache = new Map();
 
-// Python 3.9+ protocol reused from the host hook adapters.
+// Python 3.10+ protocol reused from the host hook adapters.
 // It resolves the `.cowork-flow` root from the given cwd,
 // loads the shared workflow_state_hook module, and prints
-// the full hook context block.
+// the full hook context block. The version guard runs first
+// and exits 3 so the caller can tell "interpreter below the
+// floor" (try the next candidate) apart from "the runtime
+// failed" (contribute nothing).
 const PYTHON_PROTOCOL = `\
 import sys
+
+if sys.version_info < (3, 10):
+    raise SystemExit(3)
+
 from pathlib import Path
 
+# The block carries CJK copy, so stdout must be UTF-8 whatever the console
+# codepage says: on a cp1252 console (the CI runner's default) print()
+# raises, and the caller reads the traceback as "interpreter ran, protocol
+# failed" and injects nothing. newline="" keeps the payload bytes identical
+# across platforms, like the edit-scope protocol below.
+sys.stdout.reconfigure(encoding="utf-8", errors="replace", newline="")
+
 cwd = sys.argv[1]
 full_digest = len(sys.argv) > 2 and sys.argv[2] != "0"
 current = Path(cwd).resolve()
@@ -105,9 +119,15 @@ const EDIT_EXEC_OPTIONS = {
 // Editor-phase scope protocol: same root discovery, then the shared
 // edit-scope entry the other hosts reach through their PostToolUse
 // hook, so DSH sessions get the identical single-line advisory. Prints
-// at most one line; exits 0 either way.
+// at most one line; exits 0 either way. The version guard exits 3 (an
+// interpreter below the floor, not a runtime verdict), which the
+// caller treats like a missing binary: try the next candidate.
 const PYTHON_EDIT_SCOPE_PROTOCOL = `\
 import sys
+
+if sys.version_info < (3, 10):
+    raise SystemExit(3)
+
 from pathlib import Path
 
 # The advisory line starts with a character outside the Windows ANSI
@@ -190,6 +210,16 @@ function discoverCandidates() {
 }
 
 
+// ENOENT = the interpreter does not exist, exit code 3 = it is older than
+// the protocol's floor; both mean "try the next candidate". Any other
+// failure — a different non-zero exit or a timeout — means the interpreter
+// ran but the protocol failed: the candidate works, the runtime does not,
+// so it is not skipped. `attempt`'s edit-scope variant shares this mapping.
+export function candidateUnavailable(error) {
+  return error.code === 'ENOENT' || error.code === 3;
+}
+
+
 function tryPython(candidate, cwd, full = true) {
   return new Promise((resolve) => {
     execFile(
@@ -198,11 +228,7 @@ function tryPython(candidate, cwd, full = true) {
       EXEC_OPTIONS,
       (error, stdout) => {
         if (error) {
-          // ENOENT = the interpreter does not exist (try
-          // the next one). Any other failure means the
-          // interpreter ran but the protocol failed — the
-          // candidate works, the runtime does not.
-          resolve({ missing: error.code === 'ENOENT', output: '' });
+          resolve({ missing: candidateUnavailable(error), output: '' });
           return;
         }
         resolve({ missing: false, output: stdout.trim() });
@@ -296,6 +322,13 @@ export async function runWorkflowState(cwd, full = true) {
     workingPython = candidate;
     return normalize(result.output);
   }
+  // Nothing in the candidate list could run the protocol: contribute
+  // nothing, but say why once — a Python below the floor (or none at
+  // all) is a misconfiguration the session owner can fix, and total
+  // silence hides it.
+  process.stderr.write(
+    'cowork-flow dsh hook: no Python 3.10+ interpreter found; skipping workflow-state injection\n'
+  );
   return '';
 }
 
@@ -340,7 +373,7 @@ export async function runEditScopeCheck(cwd, filePath) {
       EDIT_EXEC_OPTIONS,
       (error, stdout) => {
         if (error) {
-          resolvePromise({ missing: error.code === 'ENOENT', output: '' });
+          resolvePromise({ missing: candidateUnavailable(error), output: '' });
           return;
         }
         resolvePromise({ missing: false, output: stdout.trim() });

package/presets/kimi-code/.kimi-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 Kimi Code。",
   "author": {
     "name": "fishlikewater",

package/presets/kimi-code/hooks/cowork-flow-inject.mjs

@@ -34,6 +34,27 @@ const INJECT_RELATIVE = join(
 );
 const HOST = "kimi-code";
 const SPAWN_TIMEOUT_MS = 20000; // config.toml grants the hook 30s
+// The .cowork-flow/run floor, reused here: a candidate that cannot run
+// Python 3.10+ is skipped like a missing binary, so a stale `python3`
+// never hides a working `python` further down the list.
+const MIN_PYTHON_CHECK = "import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)";
+
+function interpreterIsUsable(candidate) {
+  try {
+    const probe = spawnSync(
+      candidate[0],
+      [...candidate.slice(1), "-c", MIN_PYTHON_CHECK],
+      { timeout: SPAWN_TIMEOUT_MS, windowsHide: true }
+    );
+    // A probe killed by its own timeout reached no verdict — a loaded machine,
+    // not a bad interpreter — so let the real spawn decide; it carries the
+    // same timeout and its own diagnostics.
+    if (probe.error && probe.error.code === "ETIMEDOUT") return true;
+    return !probe.error && probe.status === 0;
+  } catch {
+    return false;
+  }
+}
 
 function readHookInput() {
   if (process.stdin.isTTY) return { raw: "", parsed: {} };
@@ -89,6 +110,7 @@ function main() {
 
   const injectScript = join(root, INJECT_RELATIVE);
   for (const candidate of pythonCandidates()) {
+    if (!interpreterIsUsable(candidate)) continue;
     let result;
     try {
       result = spawnSync(
@@ -117,8 +139,12 @@ function main() {
     }
     process.exit(0);
   }
-  // No interpreter could run the entry: stay silent rather than break the
-  // user's submit (fail-open, same contract as the other host shims).
+  // No candidate could run the entry: stay fail-open, but say why once
+  // instead of hiding a misconfiguration (a Python below the floor, or
+  // none at all).
+  process.stderr.write(
+    "cowork-flow kimi-code hook: no Python 3.10+ interpreter found; skipping injection\n"
+  );
   process.exit(0);
 }
 

package/presets/opencode/cowork-flow/plugin-core.js

@@ -16,7 +16,7 @@
 // install, so the adapter's relative import resolves in
 // both.
 
-import { spawn } from "node:child_process"
+import { spawn, spawnSync } from "node:child_process"
 import { existsSync } from "node:fs"
 import { dirname, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
@@ -24,6 +24,27 @@ import { fileURLToPath } from "node:url"
 const DIR_WORKFLOW = ".cowork-flow"
 // One prompt assembly must not wait longer than a host hook event.
 const INJECT_TIMEOUT_MS = 4800
+// The .cowork-flow/run floor, reused here: a candidate that cannot run
+// Python 3.10+ is skipped like a missing binary, so a stale `python3`
+// never hides a working `python` further down the list.
+const MIN_PYTHON_CHECK =
+  "import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)"
+
+function interpreterIsUsable(candidate) {
+  try {
+    const probe = spawnSync(candidate[0], [...candidate.slice(1), "-c", MIN_PYTHON_CHECK], {
+      timeout: INJECT_TIMEOUT_MS,
+      windowsHide: true,
+    })
+    // A probe killed by its own timeout reached no verdict — a loaded machine,
+    // not a bad interpreter — so let the real spawn decide; it carries the
+    // same timeout and its own diagnostics.
+    if (probe.error && probe.error.code === "ETIMEDOUT") return true
+    return !probe.error && probe.status === 0
+  } catch {
+    return false
+  }
+}
 
 // Last-resort repository root: this module lives at
 // <payload>/cowork-flow/plugin-core.js, next to plugins/,
@@ -197,12 +218,18 @@ async function renderViaInject(input, overrides = null) {
     cwd: inputCwd(input) || (root === pluginRoot ? null : root) || process.cwd(),
   }
   for (const candidate of pythonCandidates()) {
+    if (!interpreterIsUsable(candidate)) {
+      continue
+    }
     const result = await runInject(candidate, script, payload)
     if (!result.ran) {
       continue
     }
     return result.stdout.trim()
   }
+  console.error(
+    "cowork-flow opencode plugin: no Python 3.10+ interpreter found; skipping injection"
+  )
   return ""
 }
 

package/presets/qoder/.qoder-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 Qoder。",
   "displayName": "Cowork Flow",
   "author": {

package/presets/qoder/hooks/inject-context.mjs

@@ -33,6 +33,27 @@ const HOST = "qoder";
 const DIR_WORKFLOW = ".cowork-flow";
 // hooks.json grants 30s per event.
 const SPAWN_TIMEOUT_MS = 25000;
+// The .cowork-flow/run floor, reused here: a candidate that cannot run
+// Python 3.10+ is skipped like a missing binary, so a stale `python3`
+// never hides a working `python` further down the list.
+const MIN_PYTHON_CHECK = "import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)";
+
+function interpreterIsUsable(candidate) {
+  try {
+    const probe = spawnSync(
+      candidate[0],
+      [...candidate.slice(1), "-c", MIN_PYTHON_CHECK],
+      { timeout: SPAWN_TIMEOUT_MS, windowsHide: true }
+    );
+    // A probe killed by its own timeout reached no verdict — a loaded machine,
+    // not a bad interpreter — so let the real spawn decide; it carries the
+    // same timeout and its own diagnostics.
+    if (probe.error && probe.error.code === "ETIMEDOUT") return true;
+    return !probe.error && probe.status === 0;
+  } catch {
+    return false;
+  }
+}
 
 function readHookInput() {
   if (process.stdin.isTTY) return { raw: "", parsed: {} };
@@ -113,6 +134,7 @@ function main() {
   if (!existsSync(injectScript)) process.exit(0);
 
   for (const candidate of pythonCandidates()) {
+    if (!interpreterIsUsable(candidate)) continue;
     let result;
     try {
       result = spawnSync(
@@ -142,8 +164,12 @@ function main() {
     }
     process.exit(0);
   }
-  // No interpreter could run the entry: stay silent rather
-  // than break the host's event stream (fail-open).
+  // No candidate could run the entry: stay fail-open, but say why once
+  // instead of hiding a misconfiguration (a Python below the floor, or
+  // none at all).
+  process.stderr.write(
+    "cowork-flow qoder hook: no Python 3.10+ interpreter found; skipping injection\n"
+  );
   process.exit(0);
 }
 

package/presets/zcode/.zcode-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 ZCode。",
   "author": {
     "name": "fishlikewater",

package/presets/zcode/hooks/inject-context.mjs

@@ -35,6 +35,27 @@ const DIR_WORKFLOW = ".cowork-flow";
 const LIFECYCLE_BASH_RE = /\brun(?:\.cmd)?\s+(?:task|subagent|resume)\b/;
 // hooks.json grants 5s per event.
 const SPAWN_TIMEOUT_MS = 4800;
+// The .cowork-flow/run floor, reused here: a candidate that cannot run
+// Python 3.10+ is skipped like a missing binary, so a stale `python3`
+// never hides a working `python` further down the list.
+const MIN_PYTHON_CHECK = "import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)";
+
+function interpreterIsUsable(candidate) {
+  try {
+    const probe = spawnSync(
+      candidate[0],
+      [...candidate.slice(1), "-c", MIN_PYTHON_CHECK],
+      { timeout: SPAWN_TIMEOUT_MS, windowsHide: true }
+    );
+    // A probe killed by its own timeout reached no verdict — a loaded machine,
+    // not a bad interpreter — so let the real spawn decide; it carries the
+    // same timeout and its own diagnostics.
+    if (probe.error && probe.error.code === "ETIMEDOUT") return true;
+    return !probe.error && probe.status === 0;
+  } catch {
+    return false;
+  }
+}
 
 function readHookInput() {
   if (process.stdin.isTTY) return { raw: "", parsed: {} };
@@ -152,6 +173,7 @@ function main() {
   if (!injectScript) process.exit(0);
 
   for (const candidate of pythonCandidates()) {
+    if (!interpreterIsUsable(candidate)) continue;
     let result;
     try {
       result = spawnSync(
@@ -180,9 +202,12 @@ function main() {
     }
     process.exit(0);
   }
-  // No interpreter could run the entry: stay silent rather
-  // than break the host's event stream (fail-open, like
-  // the spec-edit path).
+  // No candidate could run the entry: stay fail-open, but say why once
+  // instead of hiding a misconfiguration (a Python below the floor, or
+  // none at all).
+  process.stderr.write(
+    "cowork-flow zcode hook: no Python 3.10+ interpreter found; skipping injection\n"
+  );
   process.exit(0);
 }
 

package/src/commands/install-dsh-hook.js

@@ -1,7 +1,7 @@
 import { copyFile, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { homedir } from 'node:os';
 
+import { getDshHome } from '../lib/dsh-home.js';
 import { parseInstallArgs, pathExists } from '../lib/install-support.js';
 import { packageRoot } from '../lib/paths.js';
 import { removeManagedBlock, upsertManagedBlock } from '../lib/payload-install.js';
@@ -19,11 +19,6 @@ const MANAGED_MARK = '# cowork-flow: managed workflow-state-hook row. Run "cowor
 export const FLAGS = ['--dry-run', '--force', '--uninstall'];
 
 
-function getDshHome() {
-  return process.env.DSH_HOME || join(homedir(), '.dsh');
-}
-
-
 async function readIfExists(file) {
   try {
     return await readFile(file, 'utf8');

package/src/commands/install-dsh-preset.js

@@ -1,8 +1,8 @@
 import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
 import { pathToFileURL } from 'node:url';
 
+import { getDshHome } from '../lib/dsh-home.js';
 import { parseInstallArgs, pathExists, readJsonFile, writeJsonAtomic } from '../lib/install-support.js';
 import { packageRoot } from '../lib/paths.js';
 import { readPackageInfo } from '../lib/package-info.js';
@@ -34,11 +34,6 @@ const DESKTOP_PERSONA_KEY = /(- id: persona\n(?:.*\n)*? {4})text: /;
 export const FLAGS = ['--dry-run', '--force', '--uninstall'];
 
 
-function getDshHome() {
-  return process.env.DSH_HOME || join(homedir(), '.dsh');
-}
-
-
 function getDshPresetRoot() {
   return join(getDshHome(), '.agent-presets');
 }

package/src/commands/install-zcode-plugin.js

@@ -250,9 +250,8 @@ async function materializePlugin({ pluginSrc, destDir, cacheRoot, manifest, vers
   // folder; keep workflow runtime files out of scaffold.
   await rm(join(destDir, "scaffold", ".cowork-flow"), { recursive: true, force: true });
 
-  // The presets/zcode/hooks/runtime/scripts copy is stale;
-  // overwrite it with the authoritative version from the
-  // template.
+  // The preset ships no runtime payload, so materialize
+  // the authoritative workflow scripts from the template.
   const mainScriptsSrc = join(templateRoot, ".cowork-flow", "scripts");
   const pluginScriptsDest = join(destDir, "hooks", "runtime", "scripts");
   if (await pathExists(mainScriptsSrc)) {

package/src/lib/asset-plan.js

@@ -5,7 +5,7 @@ import { resolve } from 'node:path';
 const VERSION_PATH = '.cowork-flow/.version';
 const MATERIALIZED_ACTIONS = new Set(['create', 'update']);
 
-function sha256(content) {
+export function sha256(content) {
   return createHash('sha256').update(content).digest('hex');
 }
 

package/src/lib/dsh-home.js

@@ -0,0 +1,6 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function getDshHome() {
+  return process.env.DSH_HOME || join(homedir(), '.dsh');
+}

package/src/lib/plan-applier.js

@@ -1,8 +1,7 @@
-import { createHash } from 'node:crypto';
 import * as defaultFileSystem from 'node:fs/promises';
 import { basename, dirname, join, resolve, sep } from 'node:path';
 
-import { planActions } from './asset-plan.js';
+import { planActions, sha256 } from './asset-plan.js';
 
 const MATERIALIZED_ACTIONS = new Set(['create', 'update']);
 const VERSION_PATH = '.cowork-flow/.version';
@@ -15,10 +14,6 @@ const TRANSACTION_STATUSES = new Set([
   'committed'
 ]);
 
-function sha256(content) {
-  return createHash('sha256').update(content).digest('hex');
-}
-
 async function pathExists(fileSystem, path) {
   try {
     await fileSystem.access(path);

package/template/.claude/agents/cowork-check.md

@@ -23,6 +23,6 @@ Execution:
 Rules:
 
 - Do not use the Task tool or invoke subagents.
-- Do not run task start, finish, archive, unscoped resume, commit, or push.
+- Do not run task lifecycle transitions, unscoped resume, commit, or push.
 - Treat backend/frontend natural-language specs as checklist context, not dynamic hard validators.
 - Do not accept shallow tests that would still pass when target behavior breaks.

package/template/.claude/agents/cowork-implement.md

@@ -24,6 +24,6 @@ Execution:
 Rules:
 
 - Do not use the Task tool or invoke subagents.
-- Do not run task start, finish, archive, unscoped resume, commit, or push.
+- Do not run task lifecycle transitions, unscoped resume, commit, or push.
 - Do not create task-local review artifacts, `tdd.jsonl`, or TDD evidence records in `check.jsonl`.
 - Do not claim completion without current verification.

package/template/.claude/agents/cowork-research.md

@@ -19,4 +19,4 @@ Rules:
 
 - Do not use the Task tool or invoke subagents.
 - Do not edit code, specs, task state, or git state.
-- Do not run task start, finish, archive, unscoped resume, commit, or push.
+- Do not run task lifecycle transitions, unscoped resume, commit, or push.

package/template/.codex/agents/cowork-check.toml

@@ -19,7 +19,7 @@ Execution:
 
 Rules:
 - MUST NOT spawn, wait for, list, or close other agents.
-- MUST NOT run task start, finish, archive, unscoped resume, commit, or push.
+- MUST NOT run task lifecycle transitions, unscoped resume, commit, or push.
 - Treat backend/frontend natural-language specs as checklist context, not dynamic hard validators.
 - Do not accept shallow tests that would still pass when target behavior breaks.
 """

package/template/.codex/agents/cowork-implement.toml

@@ -20,7 +20,7 @@ Execution:
 
 Rules:
 - MUST NOT spawn, wait for, list, or close other agents.
-- MUST NOT run task start, finish, archive, unscoped resume, commit, or push.
+- MUST NOT run task lifecycle transitions, unscoped resume, commit, or push.
 - Do not create task-local review artifacts, `tdd.jsonl`, or TDD evidence records in `check.jsonl`.
 - Do not claim completion without current verification.
 """

package/template/.codex/agents/cowork-research.toml

@@ -16,7 +16,7 @@ Execution:
 Rules:
 - MUST NOT spawn, wait for, list, or close other agents.
 - MUST NOT edit code, specs, task state, or git state.
-- MUST NOT run task start, finish, archive, unscoped resume, commit, or push.
+- MUST NOT run task lifecycle transitions, unscoped resume, commit, or push.
 """
 
 [features]

package/template/.codex/agents/default.toml

@@ -15,7 +15,7 @@ constraints only; they are not the task.
 
 Rules:
 - MUST NOT spawn, wait for, list, or close other agents.
-- MUST NOT run task start, task finish, task archive, or unscoped resume.
+- MUST NOT run task lifecycle transitions or unscoped resume.
 - MUST NOT commit or push.
 - Keep edits inside requested scope.
 - Report changed files and exact verification commands.

package/template/.codex/agents/explorer.toml

@@ -16,7 +16,7 @@ constraints only; they are not the task.
 Rules:
 - MUST NOT edit files unless the prompt explicitly allows it.
 - MUST NOT spawn, wait for, list, or close other agents.
-- MUST NOT run task start, task finish, task archive, or unscoped resume.
+- MUST NOT run task lifecycle transitions or unscoped resume.
 - MUST NOT commit or push.
 - Prefer rg for file and text search.
 - Return concise findings with file and line evidence.

package/template/.codex/agents/worker.toml

@@ -16,7 +16,7 @@ constraints only; they are not the task.
 
 Rules:
 - MUST NOT spawn, wait for, list, or close other agents.
-- MUST NOT run task start, task finish, task archive, or unscoped resume.
+- MUST NOT run task lifecycle transitions or unscoped resume.
 - MUST NOT commit or push.
 - Keep edits inside requested scope.
 - Report changed files and exact verification commands.

package/template/.cowork-flow/.version

@@ -1 +1 @@
-2.0.0
+2.2.0

package/template/.cowork-flow/run

@@ -1,8 +1,8 @@
 #!/bin/sh
 set -u
 
-MIN_PYTHON_LABEL="Python 3.9+"
-VERSION_CHECK='import sys; raise SystemExit(0 if sys.version_info >= (3, 9) else 1)'
+MIN_PYTHON_LABEL="Python 3.10+"
+VERSION_CHECK='import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)'
 WORKFLOW_DIR=$(CDPATH= cd "$(dirname "$0")" && pwd) || exit 1
 RUNNER_SCRIPT="$WORKFLOW_DIR/scripts/run.py"
 

package/template/.cowork-flow/run.cmd

@@ -1,8 +1,8 @@
 @echo off
 setlocal EnableExtensions
 
-set "MIN_PYTHON_LABEL=Python 3.9+"
-set "VERSION_CHECK=import sys; raise SystemExit(0 if sys.version_info >= (3, 9) else 1)"
+set "MIN_PYTHON_LABEL=Python 3.10+"
+set "VERSION_CHECK=import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)"
 set "WORKFLOW_DIR=%~dp0"
 set "RUNNER_SCRIPT=%WORKFLOW_DIR%scripts\run.py"
 set "SELECTED_PYTHON="
@@ -46,7 +46,7 @@ if not errorlevel 1 (
 )
 
 echo Error: %ENV_NAME% does not point to a usable %MIN_PYTHON_LABEL% interpreter: %ENV_VALUE% 1>&2
-echo Set %ENV_NAME% to an executable Python 3.9+ interpreter path. 1>&2
+echo Set %ENV_NAME% to an executable Python 3.10+ interpreter path. 1>&2
 exit /b 127
 
 :select_python

package/template/.cowork-flow/spec/contracts/context-injection.md

@@ -49,10 +49,10 @@ ZCode, Kimi Code, OpenCode) are **fail-open**: they run in every workspace, so
 they meet project runtimes older than themselves, and a project-side failure — an
 argparse rejection of the host argument, a crash, a timeout — must not fail the
 event they only decorate. Each keeps the child's message on stderr (the host's
-run log) and completes the event with nothing injected. Exit-status blocking is reserved
-for the project-level edit gate (`spec_only_post_tool_use`, installed by
-`init` / `sync` for claude-code and codex): that wrapper sits next to the
-runtime it calls, so hook and runtime cannot skew.
+run log) and completes the event with nothing injected. Exit-status blocking
+was removed in 2.0.0: the project-level edit hooks (`init` / `sync` install
+them for claude-code and codex next to the runtime they call) are advisory as
+well and always exit 0.
 
 The string block inside every transport follows the same shape: an optional
 runtime preamble, the contract digest (full block or fingerprint line, see

package/template/.cowork-flow/spec/contracts/decision-anchor.md

@@ -33,6 +33,7 @@ translated heading would simply stop being read.
 
 ## 验证命令
 - `<command>` → <expected>
+- 规范核对：逐条核对 `.cowork-flow/spec/<dev_type>/` 适用规范 → pass / not_applicable（附理由）
 ```
 
 ## Section requirements
@@ -44,7 +45,7 @@ translated heading would simply stop being read.
 | `## 被拒方案` | optional | required for brainstorming tasks, so a rejected option is not reconsidered during execution |
 | `## 关键假设` | optional | filled in for complex tasks to surface implicit constraints; not read by the runtime parser |
 | `## 范围边界` | optional | prevents scope creep |
-| `## 验证命令` | optional | filled in for complex tasks, as the basis for automated verification |
+| `## 验证命令` | optional | filled in for complex tasks, as the basis for automated verification; when the changed files are covered by `.cowork-flow/spec/backend/` or `frontend/` rules, it must also carry the spec/gate check for the task's `dev_type` (deciding command, or clause-by-clause `pass` / `not_applicable` with reason) |
 
 ### Machine-readable line formats (for injection)
 
@@ -54,6 +55,11 @@ fact view (`services/fact_view.parse_decision_anchor`). Line-format conventions:
 - `## 验证命令`: one command per line (an optional `- ` prefix), truncated to 120
   characters, at most 10 lines; the implementing agent runs them itself
   (self-declared, self-checked) and the reviewer verifies the execution evidence.
+  When the changed files are covered by `.cowork-flow/spec/<dev_type>/` rules, the
+  section must also carry the spec/gate check for the task's `dev_type`: a deciding
+  command, or a `规范核对:` line reviewed clause by clause (`pass` /
+  `not_applicable` + reason). This is a strong review reminder, not a `spec-check`
+  hard gate.
 - `## 范围边界`: only the first non-empty line is taken, truncated to 160
   characters.
 

package/template/.kimi-code/agents/cowork-check.md

@@ -24,6 +24,6 @@ Execution:
 Rules:
 
 - Do not invoke subagents.
-- Do not run task start, finish, archive, unscoped resume, commit, or push.
+- Do not run task lifecycle transitions, unscoped resume, commit, or push.
 - Treat backend/frontend natural-language specs as checklist context, not dynamic hard validators.
 - Do not accept shallow tests that would still pass when target behavior breaks.

package/template/.kimi-code/agents/cowork-implement.md

@@ -25,6 +25,6 @@ Execution:
 Rules:
 
 - Do not invoke subagents.
-- Do not run task start, finish, archive, unscoped resume, commit, or push.
+- Do not run task lifecycle transitions, unscoped resume, commit, or push.
 - Do not create task-local review artifacts, `tdd.jsonl`, or TDD evidence records in `check.jsonl`.
 - Do not claim completion without current verification.

package/template/.kimi-code/agents/cowork-research.md

@@ -20,4 +20,4 @@ Rules:
 
 - Do not invoke subagents.
 - Do not edit code, specs, task state, or git state.
-- Do not run task start, finish, archive, unscoped resume, commit, or push.
+- Do not run task lifecycle transitions, unscoped resume, commit, or push.

package/template/.opencode/agents/cowork-check.md

@@ -28,6 +28,6 @@ Execution:
 Rules:
 
 - Do not use the `task` tool or invoke subagents.
-- Do not run task start, finish, archive, unscoped resume, commit, or push.
+- Do not run task lifecycle transitions, unscoped resume, commit, or push.
 - Treat backend/frontend natural-language specs as checklist context, not dynamic hard validators.
 - Do not accept shallow tests that would still pass when target behavior breaks.

package/template/.opencode/agents/cowork-implement.md

@@ -29,6 +29,6 @@ Execution:
 Rules:
 
 - Do not use the `task` tool or invoke subagents.
-- Do not run task start, finish, archive, unscoped resume, commit, or push.
+- Do not run task lifecycle transitions, unscoped resume, commit, or push.
 - Do not create task-local review artifacts, `tdd.jsonl`, or TDD evidence records in `check.jsonl`.
 - Do not claim completion without current verification.

package/template/.opencode/agents/cowork-research.md

@@ -26,4 +26,4 @@ Rules:
 
 - Do not use the `task` tool or invoke subagents.
 - Do not edit code, specs, task state, or git state.
-- Do not run task start, finish, archive, unscoped resume, commit, or push.
+- Do not run task lifecycle transitions, unscoped resume, commit, or push.

package/template/.opencode/cowork-flow/plugin-core.js

@@ -16,7 +16,7 @@
 // install, so the adapter's relative import resolves in
 // both.
 
-import { spawn } from "node:child_process"
+import { spawn, spawnSync } from "node:child_process"
 import { existsSync } from "node:fs"
 import { dirname, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
@@ -24,6 +24,27 @@ import { fileURLToPath } from "node:url"
 const DIR_WORKFLOW = ".cowork-flow"
 // One prompt assembly must not wait longer than a host hook event.
 const INJECT_TIMEOUT_MS = 4800
+// The .cowork-flow/run floor, reused here: a candidate that cannot run
+// Python 3.10+ is skipped like a missing binary, so a stale `python3`
+// never hides a working `python` further down the list.
+const MIN_PYTHON_CHECK =
+  "import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)"
+
+function interpreterIsUsable(candidate) {
+  try {
+    const probe = spawnSync(candidate[0], [...candidate.slice(1), "-c", MIN_PYTHON_CHECK], {
+      timeout: INJECT_TIMEOUT_MS,
+      windowsHide: true,
+    })
+    // A probe killed by its own timeout reached no verdict — a loaded machine,
+    // not a bad interpreter — so let the real spawn decide; it carries the
+    // same timeout and its own diagnostics.
+    if (probe.error && probe.error.code === "ETIMEDOUT") return true
+    return !probe.error && probe.status === 0
+  } catch {
+    return false
+  }
+}
 
 // Last-resort repository root: this module lives at
 // <payload>/cowork-flow/plugin-core.js, next to plugins/,
@@ -197,12 +218,18 @@ async function renderViaInject(input, overrides = null) {
     cwd: inputCwd(input) || (root === pluginRoot ? null : root) || process.cwd(),
   }
   for (const candidate of pythonCandidates()) {
+    if (!interpreterIsUsable(candidate)) {
+      continue
+    }
     const result = await runInject(candidate, script, payload)
     if (!result.ran) {
       continue
     }
     return result.stdout.trim()
   }
+  console.error(
+    "cowork-flow opencode plugin: no Python 3.10+ interpreter found; skipping injection"
+  )
   return ""
 }
 

package/template/skills/runtime-health/scripts/doctor.py

@@ -1052,6 +1052,82 @@ def check_qoder_plugin(repo_root: Path) -> list[dict[str, str]]:
     return []
 
 
+_ZCODE_PLUGIN_CONTRACT = "runtime-health:zcode-plugin"
+
+
+def _zcode_warning(code: str, path: Path, message: str, hint: str) -> list[dict[str, str]]:
+    return [
+        _issue(
+            code=code,
+            severity="warning",
+            path=str(path),
+            message=message,
+            command_hint=hint,
+            contract=_ZCODE_PLUGIN_CONTRACT,
+        )
+    ]
+
+
+def _zcode_marketplace_path() -> Path:
+    home = Path(os.environ.get("ZCODE_HOME") or (Path.home() / ".zcode"))
+    return (
+        home
+        / "cli"
+        / "plugins"
+        / "marketplaces"
+        / "cowork-flow-local"
+        / "marketplace.json"
+    )
+
+
+def check_zcode_plugin(repo_root: Path) -> list[dict[str, str]]:
+    """ZCode plugin health. Advisory, and silent while the project never selected
+    the ZCode host: the plugin is a machine-level asset installed once into the
+    ZCode config directory, so it never updates through sync or npm.
+
+    Staleness is judged on the payload's stamped manifest version rather than
+    per file: the payload also carries a materialized copy of the project
+    runtime, and that copy may legitimately differ from this project."""
+    adapter = repo_root / DIR_WORKFLOW / "adapters" / "zcode" / "adapter.yaml"
+    if not adapter.is_file():
+        return []
+
+    marketplace = _zcode_marketplace_path()
+    payload = _machine_plugin_payload("zcode")
+    if payload is None:
+        return _zcode_warning(
+            "PLUGIN-NOT-INSTALLED",
+            marketplace,
+            "this project declares the ZCode host, but no cowork-flow plugin is "
+            "installed in the ZCode config directory, so ZCode sessions inject no "
+            "workflow context",
+            "cwf host add zcode",
+        )
+
+    manifest_relative = _payload_manifest("zcode", repo_root) or ".zcode-plugin/plugin.json"
+    manifest = payload / manifest_relative
+    recorded = _marker_version(manifest)
+    if recorded is None:
+        return _zcode_warning(
+            "PLUGIN-UNKNOWN-VERSION",
+            manifest,
+            "the installed ZCode plugin carries no readable manifest version, so "
+            "its injection logic may predate the current release",
+            "cwf host add zcode --force",
+        )
+    project_version = _project_version(repo_root)
+    if project_version and recorded != project_version:
+        return _zcode_warning(
+            "PLUGIN-STALE",
+            manifest,
+            f"the ZCode plugin was installed from {recorded} but this project "
+            f"runs {project_version}; the plugin does not update with sync or npm, "
+            "so injection may lag the project runtime",
+            "cwf host add zcode --force",
+        )
+    return []
+
+
 _CLAUDE_CODE_PLUGIN_CONTRACT = "runtime-health:claude-code-plugin"
 _CLAUDE_CODE_PLUGIN_NAME = "cowork-flow"
 _CLAUDE_CODE_SKILL = "skills/cowork-flow-bootstrap/SKILL.md"
@@ -1478,15 +1554,7 @@ def _machine_plugin_payload(platform_id: str) -> Path | None:
         payload = Path(str(entry.get("installPath") or "")) if entry else None
         return payload if payload is not None and payload.is_dir() else None
     if platform_id == "zcode":
-        home = Path(os.environ.get("ZCODE_HOME") or (Path.home() / ".zcode"))
-        marketplace = (
-            home
-            / "cli"
-            / "plugins"
-            / "marketplaces"
-            / "cowork-flow-local"
-            / "marketplace.json"
-        )
+        marketplace = _zcode_marketplace_path()
         try:
             data = json.loads(marketplace.read_text(encoding="utf-8"))
         except (OSError, json.JSONDecodeError, ValueError):
@@ -1615,6 +1683,7 @@ def _all_check_result(repo_root: Path) -> dict[str, object]:
     codex_plugin_issues = check_codex_plugin(repo_root)
     claude_code_plugin_issues = check_claude_code_plugin(repo_root)
     opencode_plugin_issues = check_opencode_plugin(repo_root)
+    zcode_plugin_issues = check_zcode_plugin(repo_root)
     kimi_code_plugin_issues = check_kimi_code_plugin(repo_root)
     skill_delivery_issues = check_skill_delivery(repo_root)
     errors: list[dict[str, object]] = []
@@ -1643,6 +1712,7 @@ def _all_check_result(repo_root: Path) -> dict[str, object]:
             "codexPlugin": codex_plugin_issues,
             "claudeCodePlugin": claude_code_plugin_issues,
             "opencodePlugin": opencode_plugin_issues,
+            "zcodePlugin": zcode_plugin_issues,
             "kimiCodePlugin": kimi_code_plugin_issues,
             "skillDelivery": skill_delivery_issues,
         },
@@ -1684,6 +1754,10 @@ def _run_checks(repo_root: Path, *, structured: bool = False) -> int:
         print(f"OpenCode plugin ({issue['code']}): {issue['message']}")
         if issue.get("commandHint"):
             print(f"  fix: {issue['commandHint']}")
+    for issue in result["issues"]["zcodePlugin"]:
+        print(f"ZCode plugin ({issue['code']}): {issue['message']}")
+        if issue.get("commandHint"):
+            print(f"  fix: {issue['commandHint']}")
     for issue in result["issues"]["kimiCodePlugin"]:
         print(f"Kimi Code plugin ({issue['code']}): {issue['message']}")
         if issue.get("commandHint"):

package/template/skills/task-planning/SKILL.md

@@ -45,7 +45,7 @@ Start with a concise brief:
 | **Task Type** | Tiny / Normal / High-risk: <reason> |
 | **Strategy** | Serial / Parallel: <why> |
 | **Success Criteria** | AC-001 / AC-002 / AC-003 |
-| **Final Verification** | `<command>` -> exit 0; `<command>` -> exit 0 |
+| **Final Verification** | `<command>` -> exit 0; clause-by-clause check against applicable `.cowork-flow/spec/<dev_type>/` rules and project gates -> `pass` / `not_applicable` per clause |
 | **Primary Risk** | Low / Medium / High: <one sentence> |
 
 ## Goal
@@ -116,6 +116,8 @@ Then list task briefs, followed by integrated verification and completion checks
   <command>
   ```
 
+  When changed files are covered by `.cowork-flow/spec/<dev_type>/` rules, add the deciding command or a spec/gate check line (`pass` / `not_applicable` with reason; format example in `decision-anchor.md`) here; it is a strong review reminder, not a hard gate.
+
   **Completion Conditions**
   - <2-4 checkable conditions>
 
@@ -128,7 +130,7 @@ Then list task briefs, followed by integrated verification and completion checks
 
 - For Tiny tasks, keep the brief short but still name exact file boundaries, completion conditions, and verification commands.
 - For behavior changes, include a failing test before implementation when behavior can be tested.
-- For implementation tasks whose changed files are covered by `.cowork-flow/spec/` requirements, name the covered spec files in the plan so review can check them clause by clause.
+- For implementation tasks whose changed files are covered by `.cowork-flow/spec/` requirements, name the covered spec files in the plan and add the clause check to the task's `Verification Command` and the plan's `Final Verification`: run the deciding command when one exists, otherwise check clause by clause and record `pass` / `not_applicable` with reason. This is a strong review reminder, not a separate hard gate.
 - Do not add shallow tests just to satisfy process. Avoid tests that only assert existence, mirror implementation details, count mock calls without behavior, or snapshot empty structure.
 - For complex problems, test depth first: business invariants, cross-layer contracts, state transitions, error boundaries, and real regression paths before narrow unit cases.
 - Map behavior-changing tests to stable `decision-anchor.md` acceptance IDs when useful; do not create `tdd.jsonl` or write TDD evidence records into `check.jsonl`.
@@ -190,3 +192,4 @@ Before handoff:
 3. Confirm every Normal or High-risk task has file boundaries, key symbols, implementation notes, test proof, completion conditions, and prohibited drift.
 4. Check names, paths, command syntax, and expected outputs.
 5. Confirm the plan says to stop and report back when code facts conflict with the plan, a plan-external file becomes necessary, or a test fails for an unplanned reason.
+6. Confirm Final Verification carries the applicable `.cowork-flow/spec/<dev_type>/` clause check, or states why no spec file applies.