cowork-flow 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # Changelog
 
+## 1.6.0 - 2026-09-20
+
+### 门禁诚实化（收集一致 / 平台 skip / CI 同门禁）
+
+- **收集一致**：`tests/test_agents_managed_block.py` 的两条断言原为模块级函数，`python -m unittest`（发布门禁与 `test:template` 用的收集器）收集不到它们（实测 `Ran 0 tests`），只有 pytest 能看到。现移入 `unittest.TestCase`，并进入 `CORE_TEMPLATE_TEST_MODULES`（core 套件 176 → 178）。新增 `tests/test_test_collection.py` 守卫：`tests/` 下再出现对 unittest 不可见的模块级 `def test_*` 即失败。
+- **Windows 静默通过**：`test/dsh-home-patch.test.js` 此前在 win32 顶层 `process.exit(0)`，`node --test` 把整个文件记为**通过文件**（不进 skipped、不进 fail）。现改为 7 个用例带 `{ skip: <具体原因> }`，Windows 上如实计入 skipped。
+- **恒真断言**：`tests/test_host_adapters.py` 三处「断言自己刚写死的字面量长度」（`assertEqual(2, len(surfaces))` 等）改为非空断言——不再恒真，也不引入需要同步维护的数字。
+- **CI 与发布同门禁**：ubuntu job 不再分步跑 fast / integration / core，合并为一步 `npm run release:check`（与 publish.yml 完全相同的命令，`setup-python` 前置到它之前）；`test/package.test.js` 新增断言锁定该一致性。此前 `test:node:full` 与 `test:template:full` 两层只在发布时首次执行，PR 侧从不运行。
+
+### 宿主必需集合单源化
+
+- 删除 Python `host_manifest.REQUIRED_CAPABILITY_MATRIX_HOSTS` 与 JS 镜像常量：`capabilityMatrix.hosts` 的必需宿主集合改由 manifest 的 `platforms` 派生（`set(platform_ids)` / `new Set([...platformIds])`）。
+- 删除 `host-assets.schema.json` 中第三处宿主名枚举——它处于漂移状态（要求 5 家、含 `dsh`、缺 `kimi-code`，而数据是 6 家）。schema 只约束结构，宿主覆盖由运行时按数据校验。
+- 新增共享 fixture `tests/fixtures/host-manifest/invalid-missing-matrix-host.json`（平台已声明但矩阵缺条目），Python 与 JS 两侧都拒绝（`capability matrix missing host: codex`），证明常量删除后该规则仍生效。
+- `spec/runtime/index.md` 记录派生规则。
+
+### 死代码与文档漂移清理
+
+- 删除仅测试可达的 skill-path 链：`context_discovery` 的 `detect_installed_platforms`（手写 3 宿主）、`SKILL_REPLICA_DIR_BY_PLATFORM`、`skill_root`、`skill_path`，以及 `adapters/cli/task.py` 的三个未调用别名。该链在生产代码零调用，真实契约由 `infra/skill_manifest` 与 manifest 的 `skillTarget` 承担。
+- 删除 `infra/paths.py` 中 `return` 之后的孤儿 try 块（引用未定义的 `file_path`，为 2026-08-05 移除 journal 流程时遗留）。
+- 删除 `fact_view.STAGE_CONTRACT_STATES`（文件内零引用；活定义在 `workflow_state_hook`）、`lifecycle_checks` 两个零调用的 `*_blockers` 包装、`adapters/review/test_intent` 的恒空校验器 `validate_test_intent` 与三个未被读取的常量，以及断言其返回空的同义用例。
+- 文档对齐：README 保护文件描述与 `syncPolicy` 实际一致（两个 spec 例外文件 + `.developer`）；两处 spec-check 文案 3s → 2.5s；`spec/schemas/index.md` 补列 `host-assets.schema.json`；清理指向已 untrack `docs/` 的历史死链。
+
+### DSH 注入接线覆盖
+
+- `presets/dsh/plugins/workflow-state.js` 的 `apply(ctx)` 此前零测试。新增用例覆盖：四个刷新事件的接线、section 注册（name/order）、无缓存时返回空文本、非编辑调用下 `tools/post-execute` 原样透传 downstream、非 cowork-flow 根目录静默降级——全部在 Windows 上真实执行。「刷新替换而非累积」用例按既有惯例在 Windows skip（宿主解释器限制）。
+
+### Windows 检出与行尾契约
+
+- 根因：`presets/kimi-code/hooks/cowork-flow-inject.mjs` 落在 `* text=auto` 下且未被 `.gitattributes` 钉行尾，Windows 全新检出（Git for Windows 默认 `core.autocrlf=true`，与 `windows-latest` 一致）把它写成 CRLF；`install-kimi-hook` 原样拷贝为全局 hook shim，于是 `test/kimi-hook.test.js` 的 `/^#!\/usr\/bin\/env node\n/` 断言失败，`test:fast` → `windows-core` 确定性红。
+- 修复：`.gitattributes` 为 `*.js`/`*.mjs` 声明 `text eol=lf`（与已钉的 `.py`/`.md`/`.json` 等一致）；`test/package.test.js` 新增行尾契约断言锁定该声明。
+- 为什么只在 Windows CI 可见：开发者工作区与 ubuntu 检出都是 LF，只有 Windows 全新检出是 CRLF。断言保持严格——CRLF shebang 的脚本在 POSIX 上无法直接执行，要修的是检出契约而不是判据。
+- 证据：全新检出实测踩中同一断言失败（`test:fast`）；仅把该文件规范化为 LF → 整条 `npm run test:windows:core` exit 0；Node 20.12.0 / 20.20.2 / 24.14.1 结果一致，与 Node 版本无关。
+
+### 净变化
+
+- 运行时代码（`template/.cowork-flow/scripts` + `src`）：**+4 / −114，净 −110 行**；runtime 模块数 80 不变（行尾修复不涉及运行时代码）。
+- 本次门禁工作：`e262196` **+365 / −200**（含 2 个新文件 +162 行）、`7fa3f8b` +3 / −2，行尾修复为小改动（行尾声明 + 契约守卫 + 记账）；新增集中在 `tests/` 与 `test/`。**AC-006「净行数 ≤ 0」未达成**——三条口径都是新增大于删除。
+- 版本口径参考：自 1.5.0 发版提交 `a4b0bfc` 起，1.6.0 全部提交的净变化由本版本更早的宿主特性主导，不属本次门禁工作。
+- 契约指纹：registry 登记的契约文件与 `spec/runtime/host-assets.json` 均未改动，指纹不变。
+
+### 平台差异与远端确认
+
+- Windows 上 `test:node:full` 的 skipped 明细新增 `dsh-home-patch` 的 7 条；这些用例在 ubuntu 发布门禁中真实执行。
+- POSIX-only：`a session refresh replaces the cached block instead of accumulating` 与既有 DSH 内容用例在本机（Windows）skip，未在本机执行。
+- 远端确认（提交 `e262196`，CI run 35503939861）：ubuntu job 首次执行 `release:check` **通过**——17 条此前只在发布时运行的 `release.test.js` POSIX 用例在 CI 上真实执行并全部通过。
+- 同一 run 的 `windows-core` 失败（步骤 `Run Windows core verification`，exit 1）。该 job 在改动前的 `aa0e34e` 上即为同样的失败，不是本版本的功能改动引入；根因是行尾契约缺失，已在本版本修复（见「Windows 检出与行尾契约」），远端日志无需仓库权限即可复现——全新 `git clone` 即可稳定踩中。
+
+## 1.5.0 - 2026-09-18
+
+### 发版开关 `--no-publish`
+
+- `scripts/release.sh` 新增 `--no-publish`：刷新、self-instance 镜像、双套测试门禁、版本 bump、changelog 校验、提交、tag 全部照常执行，只跳过最后的 `npm publish`，并提示 tag 仍是本地（后续走 `npm publish` 或 `gh release create v<v>` 触发 CI 通道）。不带该 flag 时行为逐项不变。
+- 参数解析改为逐个消费：`--no-publish` 位置无关且可重复；release-type 与 `--version` 仍互斥、最多出现一次，重复被拒。
+- 动机是既有的 CI 发布通道——tag 落地后由 `gh release create` 触发 publish.yml，而脚本此前只能一路 publish 到底。
+
+### 编辑期覆盖扩展（codex / opencode / dsh）
+
+- **codex**：`hooks.json` 注册 `PostToolUse`（matcher `apply_patch|Write|Edit`），编辑后违规经既有 `spec_only_post_tool_use` 通道（stderr + exit 2）反馈；运行时无需新增分支。
+- **opencode**：插件新增 `tool.execute.after` 钩子——`edit`/`write` 命中时调用 `run spec-check --phase edit --file <path> --throttled`，把非空单行结果追加到工具结果文本；2.5 秒超时，运行时不存在的静默且不阻断编辑。
+- **dsh**：预设插件注册 `tools/post-execute` waterfall——`write`/`edit` 命中时调同一 Python 协议（`run_edit_checks`），把单行告警作为 `additionalContexts` 附件送入下一轮请求；2.5 秒超时，无根/无解释器/协议异常一律静默。DSH 的 `tools/result` 只能观察不能回写，故走 post-execute 而非复用刷新监听。
+- **路径提取多形态**：PostToolUse 的路径提取兼容 `file_path`/`filePath`/`path` 与 codex `apply_patch` 补丁文本（`*** Update/Add/Delete File:` 行）；同一路径去重，避免重复消耗节流窗口。
+- **契约诚实化**：`spec-checks.md` 矩阵与 README 从"opencode 降级：无"改为准确表述——五个宿主全部覆盖，其中 zcode 仅主会话、dsh 经预设注入；此前的"降级"是项目未接线，不是宿主能力缺失。
+- **实弹验收项（未在本地执行）**：codex 会话编辑后 stderr 反馈可见（需宿主 hook 信任批准）；opencode 会话 edit 后工具结果含单行警告；dsh 会话编辑后下一轮上下文含 spec-check 通知。
+
+### DSH 预设过期检测
+
+- **版本标记**：`install-dsh-preset` 安装后在预设目录写入 `.cowork-flow-preset.json`（`version` + `installedAt`）；已安装且版本不同时，不带 `--force` 的重复执行输出过期提示与更新命令，而不是仅报 "already installed"。
+- **doctor 检测**：新增只读 advisory 检查 `check_dsh_preset`——预设缺失时不报告；无标记或标记不可读 → `PRESET-UNKNOWN-VERSION`；与项目 `.cowork-flow/.version` 不一致 → `PRESET-STALE`；两者都附 `install-dsh-preset --force` 提示，且不进入 doctor 的 error 集合（`ok` 不受影响）。
+- **背景**：预设不随 `sync`/npm 更新，此前升级路径只存在于 README 散文，用户可能长期停留在旧注入逻辑且没有任何提示；协议失败时该宿主的注入会静默降级为空输出。
+
+### 下游可发现性与文档权威性（spec-check）
+
+- **发现路径补齐**：`run` 帮助列出 `spec-check`；`AGENTS.md` 的 managed block（模板与根同块）加指针行；README 新增「规范挂命令」与「MCP 客户端接入」两节，能力表与常用命令同步。
+- **契约修正**：`spec/contracts/spec-checks.md` 的「归属与 sync 策略」改为与实际一致——`spec/` 是 sync 保护前缀，已安装项目不会被同步改写；具名例外是 `syncPolicy.safeFiles` 中的契约文件。该文件加入 `safeFiles`（同 `workflow-state-templates.md` 先例），使契约修正能到达已安装下游。
+- **fallback 自救路径**：`FALLBACK_BINDING_BLOCKER` 与两处 lifecycle 拒绝文案改为指向 workflow-state 头部的 `session` 属性（`COWORK_FLOW_CONTEXT_ID`），不再给出无任务可传的 `pass <task-dir>` 单一出路。
+- **悬空引用清理**：README 与模板脚本/spec 中指向已 untrack 的 `docs/` 的引用全部改写或内联（MCP 客户端配置要点保留在 README）。
+- **测试**：新增根/模板 managed block 字节相等与指针断言、fallback blocker 文案可执行性断言。
+- **已知合法副作用**：contract fingerprint 由 `d1d0e2536e8fa150` 更新为 `2dc34375d28f8103`（内容派生；`host-assets.json` 的 `safeFiles` 条目变更）。
+
 ## 1.4.0 - 2026-09-14
 
 ### Hook 会话身份绑定（fix(runtime)）
@@ -107,7 +187,7 @@
 
 > **版本内容错位说明**：npm registry 上的 1.0.0 tarball 发布于 2026-08-26（仅含发版脚本修复之前的代码）。1.0.0 段下述的里程碑描述以本 1.1.0 为其实际发布载体——阶段 0-3 的全部内容自本版本起进入 npm 分发。
 
-### 方向落地（阶段 0-3，详见 1.0.0 段与 docs/direction.md）
+### 方向落地（阶段 0-3，详见 1.0.0 段）
 
 - 阶段 0：README 定位改写为「运行时上下文与协作事实层」；注入协议契约 `spec/contracts/context-injection.md`；契约指纹序列化三线统一 + slim 全覆盖 + 跨 host 一致性测试。
 - 阶段 1：`run state [task] --json` 事实视图；`<workflow-state>` 属性事实头 + `<decision-anchor>` 决策要点注入（三线一致）。

package/README.md

@@ -12,8 +12,9 @@
 |---|---|
 | 任务流程 | `task next --json` 给出下一步 action，`task next --run` 只执行当前 action。 |
 | 事实接入 | `run state [task] --json` 事实视图；`run mcp-state` 无依赖 MCP 只读服务（`task_state` / `task_list` / `task_scope` / `task_specs`）供任何 MCP 客户端查询；`task scope` / `task specs` 为 CLI 同源事实命令。 |
+| 规范挂命令 | spec 首部 frontmatter 声明 `checks:` 命令，按编辑期/收口期执行；`run spec-check` 输出三态门禁（pass / violation / unchecked）。 |
 | 运行健康 | `doctor` 诊断 runtime、host assets、Skill replica 和任务 hygiene，不推进生命周期。 |
-| Host 分发 | Host Asset Manifest 驱动 Codex / OpenCode / Claude Code / ZCode / DeepSeek Harness 资产和 obsolete 清理。 |
+| Host 分发 | Host Asset Manifest 驱动 Codex / OpenCode / Claude Code / ZCode / Kimi Code / DeepSeek Harness 资产和 obsolete 清理。 |
 | 批处理与讨论 | Batch 发布 Host action；Party Mode 只输出 advisory final facts。 |
 | 发布准备 | `release:check`、`CHANGELOG.md`、`pack:check` 固定发布前证据。 |
 
@@ -25,7 +26,7 @@
 | 理解任务如何流转 | [任务流程](#任务流程) |
 | 处理故障或漂移 | [支持与故障诊断](#支持与故障诊断) |
 | 做发布前检查 | [发布](#发布)、[`CHANGELOG.md`](CHANGELOG.md) |
-| 了解项目方向与演进路线 | [`docs/direction.md`](docs/direction.md) |
+| 了解项目演进与版本内容 | [`CHANGELOG.md`](CHANGELOG.md) |
 | 接入到自己项目 | [接入原则](#接入原则) |
 
 ## 适用 / 不适用
@@ -68,14 +69,14 @@ cowork-flow install-dsh-hook
 
 # MCP 客户端接入（可选）：全局注册一次，任意项目查询任务事实；
 # 项目级 opt-in（如 claude-code 的 .mcp.json）与注册健康检测见
-# `run doctor`，各客户端配置样例见 docs/mcp-client-setup.md
+# `run doctor`；各客户端配置样例见下方「MCP 客户端接入」一节
 cowork-flow mcp-state
 
 # 维护者发布前检查
 npm run release:check
 ```
 
-平台选项：`codex` / `opencode` / `claude-code` / `dsh` / `zcode` / `all`（逗号分隔）
+平台选项：`codex` / `opencode` / `claude-code` / `dsh` / `zcode` / `kimi-code` / `all`（逗号分隔）
 
 ## 仓库结构
 
@@ -89,6 +90,7 @@ template/
 ├── .opencode/                 # OpenCode agents / commands / plugins
 ├── .dsh/                      # DeepSeek Harness 标记（sync 检测 + 说明）
 ├── .zcode/                    # ⭐ ZCode 插件（hooks + skills + agents + scaffold instructions）
+├── .kimi-code/                # Kimi Code fixed agents（cowork-implement / check / research）
 └── .cowork-flow/
     ├── config.yaml            # 项目配置
     ├── scripts/               # Python 运行时
@@ -115,6 +117,7 @@ Skills 维护在 `template/skills/` 唯一源码，`init` / `sync` 时按目录
 |---|---|
 | `codex` / `opencode` | `.agents/skills/` |
 | `dsh` | `.agents/skills/` |
+| `kimi-code` | `.agents/skills/` |
 | `claude-code` | `.claude/skills/` |
 | `zcode` | `.cowork-flow/skills/`（内核 owner 解析用；系统提示层仍由 ZCode 插件单源提供，不重复加载） |
 
@@ -130,6 +133,7 @@ Skills 维护在 `template/skills/` 唯一源码，`init` / `sync` 时按目录
 | `install-zcode-plugin` | 安装 ZCode 插件到全局缓存 |
 | `install-dsh-preset` | 安装 DSH agent 预设到 `~/.dsh/.agent-presets/cowork-flow/`（整套 agent，可选） |
 | `install-dsh-hook` | 机器级注册 workflow-state hook 组合行到 `$DSH_HOME/cordis.patch.yml`（当前 DSH 的 agent 提示不收集 host 层 section，实时注入请用预设方式） |
+| `install-kimi-hook [--dry-run] [--force] [--uninstall]` | 机器级注册 UserPromptSubmit hook 到 `$KIMI_CODE_HOME/config.toml`（默认 `~/.kimi-code/`），向每个 Kimi Code 会话实时注入工作流上下文 |
 | `update [--dry-run]` | 升级 CLI 本身 |
 | `mcp-state` | 全局 MCP 事实入口：从 cwd 向上定位项目运行时并透传 `run mcp-state`（全局注册一次，所有 cowork-flow 项目通用） |
 
@@ -137,7 +141,7 @@ Skills 维护在 `template/skills/` 唯一源码，`init` / `sync` 时按目录
 
 | 选项 | 说明 |
 |---|---|
-| `--platform <p>` | 平台：`codex` / `opencode` / `claude-code` / `dsh` / `zcode` / `all` |
+| `--platform <p>` | 平台：`codex` / `opencode` / `claude-code` / `dsh` / `zcode` / `kimi-code` / `all` |
 | `--developer <n>` | 开发者名称 |
 | `--force` | 覆盖已有文件 |
 | `--dry-run` | 预览不写入 |
@@ -146,7 +150,7 @@ Skills 维护在 `template/skills/` 唯一源码，`init` / `sync` 时按目录
 
 - **自动识别**已安装 host 目录，只同步对应平台资产
 - **Skills** 从 `template/skills/` 按平台分发
-- **保护文件**：`config.yaml`、`spec/`（除 `workflow-state-templates.md`）、任务、计划、变更
+- **保护文件**：`config.yaml`、`.developer`、`spec/`（例外：`spec/contracts/workflow-state-templates.md` 与 `spec/contracts/spec-checks.md` 两个契约文件）、任务、计划
 - **正式版旧资产清理**：旧脚本位置、旧 adapter 资产和已废弃文件按 Host Asset Manifest 的 `obsoleteFiles` 清理；用户保护文件保持不变
 - **事务恢复**：上次未完成事务会在新一轮 sync 前恢复；事务元数据缺失或损坏时 fail-closed，不在未知状态上继续写入
 - **Dry-run readiness**：`sync --dry-run` 只构建计划并输出 `readiness=<json>`，不写文件或事务状态；字段包含 `wouldCopy`、`wouldSkipProtected`、`wouldRemoveObsolete`、`hostAssetRefresh`、`pendingRecovery`、`warnings`
@@ -164,6 +168,32 @@ Skills 维护在 `template/skills/` 唯一源码，`init` / `sync` 时按目录
 - 默认查询 npm latest，发现新版本时执行 `npm install -g cowork-flow@latest`
 - `--dry-run` 只输出当前版本、最新版本和 `readiness=<json>`，其中 `update.wouldInstall` 表示是否会执行全局安装，不调用安装命令
 
+## MCP 客户端接入
+
+事实层以只读 MCP 服务（工具 `task_state` / `task_list`）提供给任意客户端。两种入口：
+
+- **全局（推荐）**：`cowork-flow mcp-state`（npm 全局 CLI 透传）。注册一次，所有 cowork-flow 项目通用——项目根由客户端启动时的 cwd 向上解析。
+- **项目级**：`<project>/.cowork-flow/run mcp-state`（不依赖全局安装，每项目一份配置）。
+
+stdio 注册样例：
+
+```toml
+# Codex（~/.codex/config.toml）
+[mcp_servers.cowork-flow]
+command = "cowork-flow"
+args = ["mcp-state"]
+```
+
+```json
+// OpenCode（~/.config/opencode/opencode.json）
+{"mcp": {"cowork-flow": {"type": "local", "command": ["cowork-flow", "mcp-state"], "enabled": true}}}
+```
+
+- **Claude Code**：`claude mcp add -s user cowork-flow -- cowork-flow mcp-state`（项目级 `.mcp.json` 写同构条目）。
+- **ZCode**：客户端设置的 MCP 服务器中添加同构 stdio 条目（命令 `cowork-flow`、参数 `mcp-state`）。
+
+项目级注册的健康检查由 `./.cowork-flow/run doctor` 报告。
+
 ## ZCode 插件
 
 ```bash
@@ -195,7 +225,7 @@ cowork-flow init ./my-project --platform dsh   # 项目资产：AGENTS.md + .age
 cowork-flow install-dsh-hook                   # 机器级：注册 hook 组合行（实时注入见下方说明）
 ```
 
-`install-dsh-hook` 把 `workflow-state.js` 插件作为 `insert:` patch 注册到 `$DSH_HOME/cordis.patch.yml`（未设置 `DSH_HOME` 时默认 `~/.dsh`），组合层面可被 `dsh --dump-config` 验证。经实测（DSH 0.1.1-rc.1），**agent 提示组装不收集 host 层 section**：该组合行不会在会话系统提示中产生 `<workflow-state>` 块。当前 DSH 版本下实时注入仍需预设方式（`install-dsh-preset`）；本命令保留为组合层面的幂等注册能力（卸载见下），待 DSH 支持 agent-scope patch / workspace 级组合后可直接生效（见 `docs/dsh-upstream-proposal.md`）。
+`install-dsh-hook` 把 `workflow-state.js` 插件作为 `insert:` patch 注册到 `$DSH_HOME/cordis.patch.yml`（未设置 `DSH_HOME` 时默认 `~/.dsh`），组合层面可被 `dsh --dump-config` 验证。经实测（DSH 0.1.1-rc.1），**agent 提示组装不收集 host 层 section**：该组合行不会在会话系统提示中产生 `<workflow-state>` 块。当前 DSH 版本下实时注入仍需预设方式（`install-dsh-preset`）；本命令保留为组合层面的幂等注册能力（卸载见下），待 DSH 支持 agent-scope patch / workspace 级组合后可直接生效。
 
 在未安装 cowork-flow 的项目里 hook 完全无感：JS 侧根目录预检直接短路——不注入内容、不启动 Python 进程。全局开关（环境变量）：`COWORK_FLOW_HOOKS=0` / `COWORK_FLOW_DISABLE_HOOKS=1`。卸载：`cowork-flow install-dsh-hook --uninstall`（`--force` 同时删除插件文件）。
 
@@ -213,10 +243,28 @@ cowork-flow install-dsh-preset --dry-run  # 预览不写入
 
 安装到 `~/.dsh/.agent-presets/cowork-flow/`（`DSH_HOME` 存在时以其为准）：`agent.cordis.yml` + `preset.yml` + 全部流程技能。安装后在 DeepSeek Harness 中新建会话并选择 **Cowork Flow** 预设即可使用：persona 携带流程门禁规则，技能目录随预设挂载，不依赖项目本地副本。
 
+预设是**一次性安装的机器级资产**：它不随 `sync` 或 npm 更新。升级 cowork-flow 后需要重跑 `cowork-flow install-dsh-preset --force` 才会刷新（不带 `--force` 的重复执行是空操作，安装器会在版本不同时给出提示）。安装时会在预设目录写入 `.cowork-flow-preset.json` 版本标记；`./.cowork-flow/run doctor` 比对标记与项目 runtime 版本，过期或缺失时输出 warning 与更新命令。
+
 预设组合是部署 `standard` 预设的拷贝 + 最小改动（persona 流程规则、`skill-filesystem` 指向预设自带 `skills/`）；`cowork-flow init --platform dsh` 仍负责项目级资产（`AGENTS.md`、`.agents/skills/`、`.dsh/` 标记）。
 
 预设内置 **workflow-state hook**（`plugins/workflow-state.js`）：DSH 原生等效于 Codex/Claude hook，向系统提示末尾注入与其它宿主同构的 `<workflow-state>` 块，每条用户消息刷新一次，并在生命周期命令（`task`/`subagent`/`resume`）执行完成后立即轮内刷新（替换语义，不累积）。项目无 `.cowork-flow` 根、缺少 Python 或设 `COWORK_FLOW_HOOKS=0` / `COWORK_FLOW_DISABLE_HOOKS=1` 时静默降级，由 AGENTS.md 门禁的运行导航器兜底。
 
+## Kimi Code hook
+
+```bash
+cowork-flow install-kimi-hook             # 安装（无条件覆盖）；--force 与不带旗标同义
+cowork-flow install-kimi-hook --dry-run   # 预览将写入的托管块，不写文件
+cowork-flow install-kimi-hook --uninstall # 卸载托管块、shim 与版本标记
+```
+
+安装写入用户级 Kimi Code home（`KIMI_CODE_HOME`，未设置时默认 `~/.kimi-code/`）：hook 脚本 `hooks/cowork-flow-inject.mjs`、版本标记 `hooks/.cowork-flow-kimi-hook.json`，并在 `config.toml` 追加一段由注释标记包裹的托管块——一条 `[[hooks]]`，`event = "UserPromptSubmit"`、`command`、`timeout = 30`，不写 `matcher`（即匹配每条提交的提示）。配置文件按文本编辑、不做 TOML 重排，托管块以外的用户内容原样保留；卸载只移除这段托管块和上面两个文件，`config.toml` 因此变空时一并删除。
+
+Kimi Code 只注册 `UserPromptSubmit` 一个事件：`SessionStart` / `PostToolUse` 等观察型事件的 stdout 会被宿主丢弃，无法注入内容。hook 的 stdout 就是注入正文，宿主把它追加进提示上下文；shim 在项目根目录预检失败（非 cowork-flow 项目）时直接短路，不启动 Python 进程，全局开关为 `COWORK_FLOW_HOOKS=0` / `COWORK_FLOW_DISABLE_HOOKS=1`。
+
+> 安装或更新后需要**重启 Kimi Code 会话**（或重新加载配置）才会加载 hook。
+
+Kimi Code 的 Bash 工具不导出会话标识环境变量，CLI 侧身份只能取自注入头里的 `session="kimi_<id>"`，需要显式传 `COWORK_FLOW_CONTEXT_ID`（或 `COWORK_FLOW_HOST=kimi-code`）。`./.cowork-flow/run doctor` 把该 hook 的注册情况作为 warning 级项报告（`HOOK-NOT-INSTALLED` / `HOOK-SHIM-MISSING` / `HOOK-UNKNOWN-VERSION` / `HOOK-STALE`），不计入 errors。
+
 ## 任务流程
 
 ```
@@ -254,6 +302,29 @@ flowchart TD
 
 Batch 使用任务图和持久化 Host action：运行 `task next <parent-task> --run --intent batch --auto --approved` 获取 `next_action`；Host 完成真实生命周期动作后继续通过 `task next` 导航，不暴露独立 batch 子命令。
 
+## 规范挂命令（spec-check）
+
+`.cowork-flow/spec/` 下的规范可在文件首部 frontmatter 声明检查命令；机制只执行声明、不解析规范正文——规则随规范同文件更新，天然同步。
+
+```markdown
+---
+checks:
+  - cmd: npm run lint --silent
+    files: "src/"        # 可选：目录前缀或扩展名（"*.ts"），逗号分隔
+    timeout: 60          # 可选：秒，默认 30，硬顶 120
+    when: both           # 可选：edit | lifecycle | both（默认 both）
+---
+```
+
+唯一执行器是 `./.cowork-flow/run spec-check`：
+
+- **三态语义**：`pass`（退出码 0）；`violation` 阻断 `task complete`；`unchecked`（命令缺失、解释器缺失、超时）同样阻断，需显式 `--allow-unchecked` 放行，豁免留痕进 `task.json`。unchecked 永不冒充 pass。
+- **两个相位**：`when: edit` 在编辑期就地执行（超时钳制 2.5 秒，违规输出单行提示；具备编辑期 hook 的宿主均已覆盖，其中 zcode 仅主会话），是 best-effort 提示不是门禁；收口期全量执行，未过项阻断状态推进。
+- **扫描范围**：`.cowork-flow/spec/` 下的 markdown；`contracts/`、`runtime/`、`schemas/` 三个机器自有子树不参与。
+- **模板不带生效声明**：模板无法预知项目命令，而命令缺失会归 `unchecked` 并阻断收口；请把声明写进自建 spec 文件（如 `spec/team-xxx.md`）。
+
+`task start` 后，绑定 spec 的章节索引（h2 标题树）随 stage-contract 注入，规范条目名常驻注意力。完整契约见 `.cowork-flow/spec/contracts/spec-checks.md`。
+
 ## 常用命令
 
 ```bash
@@ -274,6 +345,10 @@ Batch 使用任务图和持久化 Host action：运行 `task next <parent-task>
 ./.cowork-flow/run task next <dir> --run --intent review
 ./.cowork-flow/run task next <dir> --run --intent archive
 
+# 规范检查
+./.cowork-flow/run spec-check
+./.cowork-flow/run spec-check --phase lifecycle --json
+
 # 子代理
 ./.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>
@@ -323,6 +398,7 @@ npm run release:check     # 发布信心门禁；当前等价于 test:all
 npm run release          # patch
 npm run release -- minor # minor
 npm run release -- --version 0.1.0  # 精确发布指定版本（跳过自动 bump）
+npm run release -- minor --no-publish  # 完整流程但跳过 npm publish（tag 留在本地）
 ```
 
 **发布流程：**
@@ -331,9 +407,9 @@ npm run release -- --version 0.1.0  # 精确发布指定版本（跳过自动 bu
 3. `npm version` 升级版本
 4. 同步版本到 `template/.cowork-flow/.version` 和 `template/.zcode/.zcode-plugin/plugin.json`
 5. `git commit` + `git tag`
-6. `npm publish`
+6. `npm publish`——走 CI 发布通道时改用 `--no-publish` 在此止步，交由下一步触发
 
-**CI 发布通道（推荐）：** `scripts/release.sh --version <v>` 打好 tag 后，`gh release create v<v>` 触发 `.github/workflows/publish.yml`——Ubuntu/Windows 双平台全量门禁通过后自动 `npm publish`（需仓库 secret `NPM_TOKEN`，权限：publish）。
+**CI 发布通道（推荐）：** `scripts/release.sh <release-type> --no-publish` 完成提交与打 tag（不本地 publish）后，先 `git push` 分支并 `git push origin v<v>` 把 tag 推上远端，再 `gh release create v<v>` 触发 `.github/workflows/publish.yml`——远端尚无该 tag 时，`gh release create` 会从默认分支最新提交自动建 tag，使门禁与发布落在错误的提交上。Ubuntu/Windows 双平台全量门禁通过后自动 `npm publish`（需仓库 secret `NPM_TOKEN`，权限：publish）。`--no-publish` 只是跳过最后一步，前置的镜像、门禁与版本同步与默认路径完全一致。
 
 - 发布说明维护在 `CHANGELOG.md`；发布前更新当前版本段落，并保留 `release:check` 和 `git diff --check` 证据。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {
@@ -19,7 +19,7 @@
   ],
   "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/package.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/kimi-hook.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",

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

@@ -22,6 +22,7 @@
 // falls back to running the navigator manually.
 
 import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { stat } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 
@@ -82,6 +83,44 @@ print(build_hook_context(
 ))
 `;
 
+// The edit path sits on the finished tool result, so it gets a short leash:
+// a slow checker is dropped rather than delaying the edit the model already
+// made.
+const EDIT_TIMEOUT_MS = 2500;
+const EDIT_EXEC_OPTIONS = {
+  timeout: EDIT_TIMEOUT_MS,
+  windowsHide: true,
+  maxBuffer: 1024 * 1024,
+};
+
+// Editor-phase spec-check protocol: same root discovery, then the shared
+// edit-check entry so DSH sessions receive the single-line violation hint
+// the other hosts get from their PostToolUse hook. Always exits 0.
+const PYTHON_EDIT_PROTOCOL = `\
+import sys
+from pathlib import Path
+
+cwd = sys.argv[1]
+file_path = sys.argv[2]
+current = Path(cwd).resolve()
+root = None
+while True:
+    if (current / ".cowork-flow").is_dir():
+        root = current
+        break
+    if current == current.parent:
+        break
+    current = current.parent
+if root is None:
+    raise SystemExit(0)
+sys.path.insert(0, str(root / ".cowork-flow" / "scripts"))
+try:
+    from services.spec_check import run_edit_checks
+    print(run_edit_checks(root, file_path))
+except Exception:
+    pass
+`;
+
 // The first interpreter that ran the protocol successfully; a missing one is
 // dropped so a later refresh can rediscover (e.g. after a PATH change).
 let workingPython = null;
@@ -234,6 +273,90 @@ export async function runWorkflowState(cwd, full = true) {
 }
 
 
+const EDIT_TOOL_NAMES = new Set(['write', 'edit']);
+
+
+/**
+ * Path of the file a finished tool call edited, or '' for anything else.
+ * DSH's fs tools expose `file_path`; other tool surfaces are ignored.
+ */
+export function editedFilePath(exec) {
+  const name = exec && typeof exec.name === 'string' ? exec.name : '';
+  if (!EDIT_TOOL_NAMES.has(name)) {
+    return '';
+  }
+  const args = exec && exec.arguments;
+  const value = args && typeof args === 'object' ? args.file_path : null;
+  return typeof value === 'string' && value.trim() ? value.trim() : '';
+}
+
+
+/**
+ * Editor-phase spec check for one edited file. Returns the single-line
+ * warning, or '' when there is nothing to say: no root, no interpreter, no
+ * declaration, a clean run, or a timeout. Never throws.
+ */
+export async function runEditSpecCheck(cwd, filePath) {
+  if (hooksDisabled() || !cwd || !filePath) {
+    return '';
+  }
+  const resolved = resolve(cwd);
+  if ((await findCoworkRoot(resolved)) === null) {
+    return '';
+  }
+  const attempt = (candidate) => new Promise((resolvePromise) => {
+    execFile(
+      candidate.command,
+      [...candidate.args, '-c', PYTHON_EDIT_PROTOCOL, cwd, filePath],
+      EDIT_EXEC_OPTIONS,
+      (error, stdout) => {
+        if (error) {
+          resolvePromise({ missing: error.code === 'ENOENT', output: '' });
+          return;
+        }
+        resolvePromise({ missing: false, output: stdout.trim() });
+      },
+    );
+  });
+  if (workingPython !== null) {
+    const result = await attempt(workingPython);
+    if (!result.missing) {
+      return result.output;
+    }
+    workingPython = null;
+  }
+  for (const candidate of discoverCandidates()) {
+    const result = await attempt(candidate);
+    if (result.missing) {
+      continue;
+    }
+    workingPython = candidate;
+    return result.output;
+  }
+  return '';
+}
+
+
+/**
+ * One identified user message carrying a plugin notice. DSH's own
+ * createUserMessage lives in a package this preset deliberately does not
+ * import, so the shape is built here with node's uuid.
+ */
+function specNoticeMessage(text) {
+  return {
+    id: randomUUID(),
+    role: 'user',
+    content: [{ type: 'text', text }],
+    source: {
+      kind: 'plugin',
+      plugin: 'cowork-flow',
+      form: 'notice',
+      summary: 'spec-check',
+    },
+  };
+}
+
+
 export function apply(ctx) {
   // One cache entry per agent: { text, inflight, queued, full }.
   // `full` records the digest shape the next refresh should use: session
@@ -291,6 +414,35 @@ export function apply(ctx) {
     refresh(agent, false);
   });
 
+  // Editor-phase spec-check: the tool already ran, so this only attaches
+  // context for the next request and never blocks the call. Waterfall order
+  // requires awaiting next() before merging downstream decisions.
+  ctx.on('tools/post-execute', async (exec, _result, next) => {
+    const downstream = await next();
+    const agent = exec && exec.agent;
+    const filePath = editedFilePath(exec);
+    if (!agent || !agent.cwd || !filePath) {
+      return downstream;
+    }
+    let warning = '';
+    try {
+      warning = await runEditSpecCheck(agent.cwd, filePath);
+    } catch {
+      warning = '';
+    }
+    if (!warning) {
+      return downstream;
+    }
+    const contexts = [
+      specNoticeMessage(warning),
+      ...((downstream && downstream.additionalContexts) || []),
+    ];
+    if (downstream && downstream.kind === 'block') {
+      return { ...downstream, additionalContexts: contexts };
+    }
+    return { ...(downstream || { kind: 'accept' }), additionalContexts: contexts };
+  });
+
   ctx.effect(() => ctx.systemPrompt.section({
     name: SECTION_NAME,
     order: SECTION_ORDER,

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

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * cowork-flow Kimi Code hook — transport shim.
+ *
+ * Kimi Code appends a UserPromptSubmit hook's stdout to the prompt context
+ * verbatim, so all workflow facts are rendered by the single Python source
+ * (inject.py --host kimi-code, emit_text policy). This shim keeps only
+ * transport duties:
+ *   1. cheap project-root pre-check — a cwd outside any cowork-flow project
+ *      exits 0 without spawning anything, so the user-level hook never
+ *      touches unrelated repositories;
+ *   2. interpreter location (COWORK_FLOW_PYTHON → python3 → python → py -3);
+ *   3. stdin passthrough to inject.py, stdout/exit forwarding.
+ *
+ * Fail-open by construction: a missing interpreter, a missing runtime, or a
+ * broken project copy all exit 0 with empty stdout instead of blocking the
+ * user's prompt (a non-zero exit on UserPromptSubmit aborts the submit).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+const WORKFLOW_DIR = ".cowork-flow";
+const INJECT_RELATIVE = join(
+  WORKFLOW_DIR,
+  "scripts",
+  "adapters",
+  "host",
+  "inject.py"
+);
+const HOST = "kimi-code";
+const SPAWN_TIMEOUT_MS = 20000; // config.toml grants the hook 30s
+
+function readHookInput() {
+  if (process.stdin.isTTY) return { raw: "", parsed: {} };
+  let raw = "";
+  try {
+    raw = readFileSync(0, "utf8").trim();
+  } catch {
+    return { raw: "", parsed: {} };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return { raw, parsed: parsed && typeof parsed === "object" ? parsed : {} };
+  } catch {
+    return { raw: "", parsed: {} };
+  }
+}
+
+function findProjectRoot(startDir) {
+  if (typeof startDir !== "string" || !startDir.trim()) return null;
+  let current = startDir.trim();
+  const root = dirname(current);
+  while (current !== root) {
+    if (existsSync(join(current, INJECT_RELATIVE))) return current;
+    current = dirname(current);
+  }
+  return existsSync(join(current, INJECT_RELATIVE)) ? current : null;
+}
+
+function pythonCandidates() {
+  const list = [];
+  const env = (process.env.COWORK_FLOW_PYTHON || "").trim();
+  if (env) list.push([env]);
+  list.push(["python3"], ["python"]);
+  if (process.platform === "win32") list.push(["py", "-3"]);
+  return list;
+}
+
+function main() {
+  if (
+    process.env.COWORK_FLOW_HOOKS === "0" ||
+    process.env.COWORK_FLOW_DISABLE_HOOKS === "1"
+  ) {
+    process.exit(0);
+  }
+
+  const { raw, parsed } = readHookInput();
+  const cwd =
+    typeof parsed?.cwd === "string" && parsed.cwd.trim()
+      ? parsed.cwd
+      : process.cwd();
+  const root = findProjectRoot(cwd);
+  if (!root) process.exit(0);
+
+  const injectScript = join(root, INJECT_RELATIVE);
+  for (const candidate of pythonCandidates()) {
+    let result;
+    try {
+      result = spawnSync(
+        candidate[0],
+        [...candidate.slice(1), injectScript, "--host", HOST],
+        {
+          input: raw,
+          timeout: SPAWN_TIMEOUT_MS,
+          encoding: "utf8",
+          windowsHide: true,
+        }
+      );
+    } catch {
+      continue;
+    }
+    if (result.error || result.status === null) continue;
+    if (result.stdout) process.stdout.write(result.stdout);
+    process.exit(result.status);
+  }
+  // No interpreter could run the entry: stay silent rather than break the
+  // user's submit (fail-open, same contract as the other host shims).
+  process.exit(0);
+}
+
+main();

package/src/cli.js

@@ -5,6 +5,7 @@ import { createInterface } from 'node:readline/promises';
 import { runInit } from './commands/init.js';
 import { runInstallDshHook } from './commands/install-dsh-hook.js';
 import { runInstallDshPreset } from './commands/install-dsh-preset.js';
+import { runInstallKimiHook } from './commands/install-kimi-hook.js';
 import { runInstallZCodePlugin } from './commands/install-zcode-plugin.js';
 import { runMcpState } from './commands/mcp-state.js';
 import { runSourceRefresh } from './commands/source-refresh.js';
@@ -19,6 +20,7 @@ Usage:
   cowork-flow install-zcode-plugin [--dry-run] [--force] [--prune-old]
   cowork-flow install-dsh-preset [--dry-run] [--force]
   cowork-flow install-dsh-hook [--dry-run] [--force] [--uninstall]
+  cowork-flow install-kimi-hook [--dry-run] [--force] [--uninstall]
   cowork-flow update
   cowork-flow sync [target] [--dry-run] [--force]
   cowork-flow source-refresh [target] [--dry-run]
@@ -201,6 +203,10 @@ export async function main(argv = process.argv.slice(2), options = {}) {
       return await runInstallDshHook(args);
     }
 
+    if (command === 'install-kimi-hook') {
+      return await runInstallKimiHook(args);
+    }
+
     if (command === 'mcp-state') {
       return await runMcpState(args);
     }