cowork-flow 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 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)）

package/README.md

@@ -12,6 +12,7 @@
 |---|---|
 | 任务流程 | `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 清理。 |
 | 批处理与讨论 | Batch 发布 Host action；Party Mode 只输出 advisory final facts。 |
@@ -25,7 +26,7 @@
 | 理解任务如何流转 | [任务流程](#任务流程) |
 | 处理故障或漂移 | [支持与故障诊断](#支持与故障诊断) |
 | 做发布前检查 | [发布](#发布)、[`CHANGELOG.md`](CHANGELOG.md) |
-| 了解项目方向与演进路线 | [`docs/direction.md`](docs/direction.md) |
+| 了解项目演进与版本内容 | [`CHANGELOG.md`](CHANGELOG.md) |
 | 接入到自己项目 | [接入原则](#接入原则) |
 
 ## 适用 / 不适用
@@ -68,7 +69,7 @@ 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
 
 # 维护者发布前检查
@@ -164,6 +165,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 +222,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,6 +240,8 @@ 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 门禁的运行导航器兜底。
@@ -254,6 +283,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 秒，违规输出单行提示；五个宿主均已覆盖，其中 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 +326,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 +379,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 +388,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.5.0",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {

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/src/commands/install-dsh-preset.js

@@ -1,10 +1,12 @@
-import { cp, mkdir, rm, access } from 'node:fs/promises';
+import { cp, mkdir, rm, access, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 
 import { packageRoot, templateRoot } from '../lib/paths.js';
+import { readPackageInfo } from '../lib/package-info.js';
 
 const PRESET_ID = 'cowork-flow';
+const MARKER_FILE = '.cowork-flow-preset.json';
 const PRESET_SRC = join(packageRoot, 'presets', 'dsh');
 const SKILLS_SRC = join(templateRoot, 'skills');
 
@@ -33,6 +35,17 @@ function getDshPresetRoot() {
 }
 
 
+async function readInstalledVersion(destDir) {
+  try {
+    const raw = await readFile(join(destDir, MARKER_FILE), 'utf8');
+    const parsed = JSON.parse(raw);
+    return typeof parsed.version === 'string' ? parsed.version : null;
+  } catch {
+    return null;
+  }
+}
+
+
 export async function runInstallDshPreset(args = []) {
   const { dryRun, force } = parseArgs(args);
 
@@ -53,9 +66,25 @@ export async function runInstallDshPreset(args = []) {
     return;
   }
 
+  const { version } = await readPackageInfo();
+
   if (!force && (await pathExists(destDir))) {
+    const installedVersion = await readInstalledVersion(destDir);
     console.log(`cowork-flow DSH preset already installed at ${destDir}`);
-    console.log('Use --force to overwrite.');
+    if (installedVersion === null) {
+      console.log(
+        `Installed version unknown (no ${MARKER_FILE}); current version is ${version}.`
+      );
+      console.log('Refresh it with: cowork-flow install-dsh-preset --force');
+    } else if (installedVersion !== version) {
+      console.log(
+        `Installed version ${installedVersion} differs from current version ${version}.`
+      );
+      console.log('The preset does not update with sync or npm; refresh it with:');
+      console.log('  cowork-flow install-dsh-preset --force');
+    } else {
+      console.log('Use --force to overwrite.');
+    }
     return;
   }
 
@@ -66,6 +95,11 @@ export async function runInstallDshPreset(args = []) {
 
   await cp(PRESET_SRC, destDir, { recursive: true });
   await cp(SKILLS_SRC, skillsDest, { recursive: true, force: true });
+  await writeFile(
+    join(destDir, MARKER_FILE),
+    `${JSON.stringify({ version, installedAt: new Date().toISOString() }, null, 2)}\n`,
+    'utf8'
+  );
 
   console.log(`✓ cowork-flow DSH preset installed to ${destDir}`);
   console.log('  Start a new DSH session and pick the "Cowork Flow" preset.');

package/template/.codex/hooks.json

@@ -10,6 +10,18 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "apply_patch|Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".cowork-flow/run python .codex/hooks/inject-workflow-state.py",
+            "timeout": 5
+          }
+        ]
+      }
     ]
   }
 }

package/template/.cowork-flow/.version

@@ -1 +1 @@
-1.4.0
+1.5.0

package/template/.cowork-flow/scripts/adapters/cli/state.py

@@ -4,7 +4,7 @@
 
 Assembles one machine-readable fact view per task (task.json, decision-anchor
 essentials, plan binding, bound sessions, trusted snapshot). See
-services/fact_view.py and docs/direction.md stage 1.
+services/fact_view.py and the fact-layer stage 1 design.
 """
 
 from __future__ import annotations

package/template/.cowork-flow/scripts/adapters/cli/task_lifecycle_commands.py

@@ -82,7 +82,9 @@ def _resolve_status_task_dir(
             print(
                 colored(
                     "Error: Session binding is process-fallback (shared); "
-                    "pass a task dir explicitly.",
+                    "set COWORK_FLOW_CONTEXT_ID to the session value shown "
+                    "in the workflow-state header, or pass a task dir "
+                    "explicitly.",
                     Colors.RED,
                 ),
                 file=sys.stderr,
@@ -368,7 +370,8 @@ def cmd_finish(args: argparse.Namespace) -> int:
         print(
             colored(
                 "Error: Refusing to clear a session binding resolved from "
-                "process-fallback identity; archive the task to clear it.",
+                "process-fallback identity; archive the task to clear it, or "
+                "set COWORK_FLOW_CONTEXT_ID to your own session identity.",
                 Colors.RED,
             ),
             file=sys.stderr,

package/template/.cowork-flow/scripts/adapters/host/workflow_state_hook.py

@@ -435,6 +435,41 @@ def _stage_contract_block(
         return None
 
 
+_APPLY_PATCH_FILE_RE = re.compile(
+    r"^\*\*\* (?:Update|Add|Delete) File: (.+?)\s*$", re.MULTILINE
+)
+
+
+def _extract_edited_paths(tool_input: Any) -> list[str]:
+    """Best-effort edited file paths from a PostToolUse tool_input payload.
+
+    Hosts differ: claude-code and zcode pass file_path, while codex's
+    apply_patch carries the paths inside the patch text. Returning every
+    extractable path keeps a multi-file patch from silently skipping
+    checks; deduplication keeps one edit from burning the throttle window
+    on the same file twice."""
+    if not isinstance(tool_input, dict):
+        return []
+    paths: list[str] = []
+    for key in ("file_path", "filePath", "path"):
+        value = tool_input.get(key)
+        if isinstance(value, str) and value.strip():
+            paths.append(value.strip())
+    for key in ("input", "patch", "patchText"):
+        text = tool_input.get(key)
+        if isinstance(text, str):
+            paths.extend(
+                match.strip() for match in _APPLY_PATCH_FILE_RE.findall(text)
+            )
+    seen: set[str] = set()
+    unique: list[str] = []
+    for path in paths:
+        if path not in seen:
+            seen.add(path)
+            unique.append(path)
+    return unique
+
+
 def spec_edit_warning(
     root: Path,
     hook_input: dict[str, Any],
@@ -461,16 +496,17 @@ def spec_edit_warning(
         return ""
     if not task_path or status not in STAGE_CONTRACT_STATES:
         return ""
-    tool_input = hook_input.get("tool_input")
-    file_path = (
-        tool_input.get("file_path") if isinstance(tool_input, dict) else None
-    )
-    if not isinstance(file_path, str) or not file_path.strip():
+    paths = _extract_edited_paths(hook_input.get("tool_input"))
+    if not paths:
         return ""
     try:
         from services.spec_check import run_edit_checks
 
-        return run_edit_checks(root, file_path)
+        for path in paths:
+            warning = run_edit_checks(root, path)
+            if warning:
+                return warning
+        return ""
     except Exception:
         return ""
 

package/template/.cowork-flow/scripts/adapters/mcp/state_server.py

@@ -2,7 +2,7 @@
 # -*- coding: utf-8 -*-
 """Read-only MCP stdio server exposing the cowork-flow fact layer.
 
-Stage 3 of docs/direction.md: any MCP client can query task facts without
+Fact-layer stage 3: any MCP client can query task facts without
 pulling the workflow into a prompt. Deliberately dependency-free — the MCP
 stdio transport is newline-delimited JSON-RPC 2.0, small enough to serve on
 the standard library while the ecosystem settles (see

package/template/.cowork-flow/scripts/run.py

@@ -50,6 +50,7 @@ Common commands:
   resume
   task
   state
+  spec-check
   get-context
   get-developer
   init-developer

package/template/.cowork-flow/scripts/runtime/session_state.py

@@ -25,8 +25,9 @@ PROVENANCE_HOST_SESSION = "host_session"
 PROVENANCE_PROCESS_FALLBACK = "process_fallback"
 PROVENANCE_MISSING = "missing"
 FALLBACK_BINDING_BLOCKER = (
-    "session identity is process-fallback (shared); pass <task-dir> explicitly "
-    "or set COWORK_FLOW_CONTEXT_ID to a trusted session id"
+    "session identity is process-fallback (shared); set COWORK_FLOW_CONTEXT_ID "
+    "to the session value shown in the workflow-state header (or pass "
+    "<task-dir> explicitly when acting on an existing task)"
 )
 RUNTIME_CONTEXT_PROMPT_RE = re.compile(
     r"(?im)^\s*cowork_runtime_context_id\s*:\s*([A-Za-z0-9._-]+)\s*$"

package/template/.cowork-flow/scripts/services/fact_view.py

@@ -3,7 +3,7 @@
 """Task fact view: one machine-readable aggregate of everything a session
 needs to know about a task.
 
-This is the fact-layer read entry (docs/direction.md, stage 1): task.json,
+This is the fact-layer read entry (fact-layer stage 1): task.json,
 decision-anchor essentials, plan binding, bound sessions, and the trusted
 state snapshot — assembled once so hosts, hooks, and tools stop re-deriving
 them from file conventions.

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

@@ -180,7 +180,9 @@ Verify: npm run test:fast; python3 -m pytest tests/ -q
   (`Bash|Edit|Write|MultiEdit`) is asserted by template tests but depends on
   the ZCode runtime's tool names — there is no external runtime contract to
   verify them against, so a runtime rename would silently disable the
-  warning; the matcher is the single switch.
+  warning; the matcher is the single switch. This bullet covers the scope
+  warning only; the spec-check violation line is a separate channel that
+  also reaches codex and opencode sessions (see spec-checks.md).
 - Budget: the whole block stays ≤ 1200 characters. Over-budget inputs
   degrade by dropping Verify, then Specs, then shrinking Scope entries
   (min 1) — the closing tag and the Gates row always survive; tests assert

package/template/.cowork-flow/spec/contracts/fact-layer-access.md

@@ -2,7 +2,7 @@
 
 How external tools (MCP clients today, other ecosystem protocols as they
 converge) and agents on hosts without injection hooks read cowork-flow task
-facts. Stage 3 of `docs/direction.md`.
+facts. Fact-layer stage 3.
 
 ## Three channels, one fact layer
 

package/template/.cowork-flow/spec/contracts/spec-checks.md

@@ -67,10 +67,16 @@ spec 为无检查并进 doctor 报告，不炸流程。
 
 ## 归属与 sync 策略
 
-- **模板自带 spec**（`spec/backend/` 等随包分发）的 check 声明由
-  cowork-flow 上游维护，属 sync safe 资产——本地修改会被 sync 覆盖。
-- **用户自定义规范**请放自建 spec 文件（如 `spec/team-xxx.md` 或自建
-  子目录），sync 不触碰；check 声明随规范正文一起由用户维护。
+- **`spec/` 整体是 sync 保护前缀**：已存在的 spec 文件不会被 `sync`
+  覆盖——模板里 spec 的更新只对 `init` 新装生效，已安装项目的本地
+  内容不会被同步任务改写。
+- **具名例外**：`spec/contracts/` 下列入 `spec/runtime/host-assets.json`
+  的 `syncPolicy.safeFiles` 条目（本文件与 `workflow-state-templates.md`）
+  随 sync 更新，使契约修正能到达已安装项目；其余 spec 文件保持保护。
+- **声明由使用方维护**：模板自带的 spec 文件不含生效的 `checks:` 声明
+  ——模板无法预知项目命令，而命令缺失会归 `unchecked` 并阻断
+  `complete`。请把声明写进自建 spec 文件（如 `spec/team-xxx.md` 或
+  自建子目录），sync 不触碰，声明随规范正文一起由使用方维护。
 
 ## 宿主能力矩阵
 
@@ -78,7 +84,11 @@ spec 为无检查并进 doctor 报告，不炸流程。
 | --- | --- | --- | --- |
 | zcode | 有（Specs 行 h2 digest） | 有（PostToolUse 短路径；**仅主会话**） | 有 |
 | claude-code | 有（Python 单源） | 有（PostToolUse，exit 2 反馈） | 有 |
-| opencode | 有 | **降级：无**（插件无 PostToolUse 短路径） | 有 |
+| codex | 有 | 有（PostToolUse，`apply_patch\|Write\|Edit` → exit 2 stderr） | 有 |
+| opencode | 有 | 有（插件 `tool.execute.after` 单行追加到工具结果） | 有 |
+| dsh | 有（预设注入） | 有（预设插件 `tools/post-execute` → `additionalContexts`） | 有 |
+
+zcode / codex / claude-code 经 Python 单源共享 `run_edit_checks`；opencode 在插件内以 CLI 拉取同一执行器（`run spec-check --phase edit --throttled`），dsh 经预设插件的 `tools/post-execute` 调同一 Python 协议——五家共享同一节流状态与三态语义，不各自实现检查逻辑。
 
 **delegated 子代理编辑期缺口（zcode 实测，2026-09-09 两轮）**：ZCode 的插件
 hook 只在主会话工具流上派发（事件模型七事件均挂主会话；子代理是独立内部

package/template/.cowork-flow/spec/runtime/host-assets.json

@@ -289,6 +289,7 @@
       ".cowork-flow/.version",
       ".cowork-flow/run",
       ".cowork-flow/run.cmd",
+      ".cowork-flow/spec/contracts/spec-checks.md",
       ".cowork-flow/spec/contracts/workflow-state-templates.md"
     ],
     "safePrefixes": [

package/template/.opencode/plugins/cowork-flow.js

@@ -1,3 +1,4 @@
+import { spawn } from "node:child_process"
 import { createHash } from "node:crypto"
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { dirname, resolve } from "node:path"
@@ -721,6 +722,81 @@ function buildInjectedDigest(input) {
   return `<contract-fingerprint value="${contractFingerprint(root, contracts)}"/>`
 }
 
+// Editor-phase spec-check: opencode sessions get the same single-line
+// violation hint zcode and claude-code already receive. Best-effort — a
+// missing runtime, a timeout, or any error stays silent and never blocks
+// the edit that already happened.
+const EDIT_TOOL_NAMES = new Set(["edit", "write"])
+const EDIT_CHECK_TIMEOUT_MS = 2500
+
+function editedFilePath(input) {
+  const tool = typeof input?.tool === "string" ? input.tool : ""
+  if (!EDIT_TOOL_NAMES.has(tool)) {
+    return ""
+  }
+  const args = input?.args
+  const candidate = args && typeof args === "object" ? args.filePath : null
+  return typeof candidate === "string" && candidate.trim() ? candidate.trim() : ""
+}
+
+function runEditSpecCheck(root, filePath) {
+  return new Promise((resolvePromise) => {
+    let settled = false
+    const finish = (value) => {
+      if (!settled) {
+        settled = true
+        resolvePromise(value)
+      }
+    }
+    const entry = resolve(
+      root,
+      ".cowork-flow",
+      process.platform === "win32" ? "run.cmd" : "run"
+    )
+    if (!existsSync(entry)) {
+      finish("")
+      return
+    }
+    let child
+    try {
+      child = spawn(
+        entry,
+        ["spec-check", "--phase", "edit", "--file", filePath, "--throttled"],
+        {
+          cwd: root,
+          stdio: ["ignore", "pipe", "ignore"],
+          shell: process.platform === "win32",
+        }
+      )
+    } catch {
+      finish("")
+      return
+    }
+    const timer = setTimeout(() => {
+      try {
+        child.kill()
+      } catch {
+        // the edit must not be held up by a stuck checker
+      }
+      finish("")
+    }, EDIT_CHECK_TIMEOUT_MS)
+    let stdout = ""
+    if (child.stdout) {
+      child.stdout.on("data", (chunk) => {
+        stdout += String(chunk)
+      })
+    }
+    child.on("error", () => {
+      clearTimeout(timer)
+      finish("")
+    })
+    child.on("close", () => {
+      clearTimeout(timer)
+      finish(stdout.trim())
+    })
+  })
+}
+
 export const CoworkFlowPlugin = async () => {
   return {
     "shell.env": async (input, output) => {
@@ -729,6 +805,16 @@ export const CoworkFlowPlugin = async () => {
     "experimental.chat.system.transform": async (input, output) => {
       output.system.push([buildInjectedDigest(input), buildRuntimeWorkflowState(input)].filter(Boolean).join("\n\n"))
     },
+    "tool.execute.after": async (input, output) => {
+      const filePath = editedFilePath(input)
+      if (!filePath) {
+        return
+      }
+      const warning = await runEditSpecCheck(findRepoRoot(input), filePath)
+      if (warning) {
+        output.output = [output.output, warning].filter(Boolean).join("\n")
+      }
+    },
   }
 }
 

package/template/.zcode/.zcode-plugin/plugin.json

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

package/template/AGENTS.md

@@ -143,4 +143,5 @@
 
 <!-- COWORK-FLOW:START -->
 项目流程以 `task next`、runtime gate、Skill command manifests 和 `.cowork-flow/spec/` 硬契约为准；不要维护第二套流程文档或 Skill 注册控制面。
+规范声明的检查以 `.cowork-flow/spec/contracts/spec-checks.md` 为准；交付或收口前运行 `./.cowork-flow/run spec-check`。
 <!-- COWORK-FLOW:END -->

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

@@ -5,6 +5,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
@@ -28,7 +29,7 @@ from adapters.host.host_manifest import (
     load_host_manifest,
     validate_host_assets,
 )
-from infra.paths import get_repo_root
+from infra.paths import DIR_WORKFLOW, get_repo_root
 from infra.skill_manifest import SkillManifestError, action_owners, load_skill_manifests
 from infra.storage.operation_log import OperationLog
 from infra.storage.state_store import DEFAULT_STALE_LOCK_SECONDS, StateStore
@@ -727,6 +728,77 @@ def check_mcp_registration(repo_root: Path) -> list[dict[str, str]]:
     return issues
 
 
+def _dsh_preset_dir() -> Path:
+    base = os.environ.get("DSH_HOME") or str(Path.home() / ".dsh")
+    return Path(base) / ".agent-presets" / "cowork-flow"
+
+
+def check_dsh_preset(repo_root: Path) -> list[dict[str, str]]:
+    """DSH preset freshness. Advisory only, and silent when the preset is
+    absent: it is a machine-level asset installed once, so it does not
+    update with npm or sync. Report an unknown or stale installed version
+    instead of assuming the injection logic matches this project."""
+    preset_dir = _dsh_preset_dir()
+    if not preset_dir.is_dir():
+        return []
+    marker = preset_dir / ".cowork-flow-preset.json"
+    if not marker.is_file():
+        return [
+            _issue(
+                code="PRESET-UNKNOWN-VERSION",
+                severity="warning",
+                path=str(marker),
+                message=(
+                    "DSH preset is installed without a version marker; its "
+                    "injection logic may predate the current release"
+                ),
+                command_hint="cowork-flow install-dsh-preset --force",
+                contract="runtime-health:dsh-preset",
+            )
+        ]
+    recorded: object = None
+    try:
+        recorded = json.loads(marker.read_text(encoding="utf-8")).get("version")
+    except (OSError, json.JSONDecodeError, ValueError, AttributeError):
+        recorded = None
+    if not isinstance(recorded, str) or not recorded:
+        return [
+            _issue(
+                code="PRESET-UNKNOWN-VERSION",
+                severity="warning",
+                path=str(marker),
+                message=(
+                    "DSH preset version marker is unreadable; its injection "
+                    "logic may predate the current release"
+                ),
+                command_hint="cowork-flow install-dsh-preset --force",
+                contract="runtime-health:dsh-preset",
+            )
+        ]
+    try:
+        project_version = (
+            repo_root / DIR_WORKFLOW / ".version"
+        ).read_text(encoding="utf-8").strip()
+    except OSError:
+        return []
+    if not project_version or recorded == project_version:
+        return []
+    return [
+        _issue(
+            code="PRESET-STALE",
+            severity="warning",
+            path=str(marker),
+            message=(
+                f"DSH preset was installed from {recorded} but this project "
+                f"runs {project_version}; the preset does not update with "
+                "sync or npm, so injection may lag the project runtime"
+            ),
+            command_hint="cowork-flow install-dsh-preset --force",
+            contract="runtime-health:dsh-preset",
+        )
+    ]
+
+
 def _all_check_result(repo_root: Path) -> dict[str, object]:
     host_issues = _host_issues(repo_root)
     runtime_errors = check_runtime(repo_root)
@@ -736,6 +808,7 @@ def _all_check_result(repo_root: Path) -> dict[str, object]:
     session_hygiene_issues = check_session_hygiene(repo_root)
     spec_check_issues = check_spec_checks(repo_root)
     mcp_issues = check_mcp_registration(repo_root)
+    dsh_preset_issues = check_dsh_preset(repo_root)
     errors: list[dict[str, object]] = []
     for issue in host_issues:
         errors.append({"kind": "host_adapter", **issue})
@@ -758,6 +831,7 @@ def _all_check_result(repo_root: Path) -> dict[str, object]:
             "sessionHygiene": session_hygiene_issues,
             "specChecks": spec_check_issues,
             "mcpRegistration": mcp_issues,
+            "dshPreset": dsh_preset_issues,
         },
     }
 
@@ -773,6 +847,10 @@ def _run_checks(repo_root: Path, *, structured: bool = False) -> int:
     _print_session_hygiene_issues(result["issues"]["sessionHygiene"])
     for issue in result["issues"]["mcpRegistration"]:
         print(f"MCP ({issue['status']}): {issue['message']}")
+    for issue in result["issues"]["dshPreset"]:
+        print(f"DSH preset ({issue['code']}): {issue['message']}")
+        if issue.get("commandHint"):
+            print(f"  fix: {issue['commandHint']}")
     if errors:
         for error in errors:
             print(f"ERROR: {error['message']}", file=sys.stderr)