cowork-flow 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 1.3.0 - 2026-09-09
+
+### 跨宿主适配通用化（注入单源化 + MCP 重定位）
+
+注入事实逻辑收拢到单一 Python 源，MCP 定位收口为"外部/无 hook 宿主的通用 pull 通道"：
+
+- **宿主中立入口 `inject.py`**：zcode shim、claude-code、codex 全部走同一入口（`--host` 选择信封与形状），wrapper 瘦身为 ≤20 行委托。digest policy 措辞、registry-warning 抑制（zcode）、preamble、信封缩进全部按 host 参数化，仍由 context-injection.md 契约锁定。
+- **zcode shim 化**：`inject-context.js` 从 ~1000 行事实镜像降为 ~140 行传输层——事件路由、PostToolUse(Bash) 廉价过滤（非生命周期命令零 spawn）、解释器定位（项目 runtime 优先、插件缓存副本兜底）、stdin/stdout 转发。删除 `inject-context.selfcheck.mjs`。matrix 逐字相等测试中的 zcode 线改为经 shim 驱动单源。
+- **每宿主策略模块**：`adapters/host` 拆出 zcode/claude_code/codex policy（digest 措辞、警告静默、rebind 提示、essential-files、PostToolUse 传输、emit 格式化），共享层与入口零 `host ==` 分支；无模块宿主（dsh）走中立默认。字节级契约不变（fingerprint、stage-contract matrix 绿）。
+- **JS-only 行为移植进 Python 单源**：`formatRebindHints`（zcode 无任务体补活动任务列表）、`editScopeWarning`（逐文件 scope 白名单警告，与 spec 警告合并进同一载荷）、missing-task 统一文案（原 "stale" 通用回退改为明确指向任务目录不存在 + 建任务指引，全宿主生效）、`checkEssentialFiles` 缺文件警告（zcode）、无会话身份时的 newest-session 显示回退（zcode，仅显示不改写绑定语义）。
+- **MCP 重定位**：`task_scope` / `task_specs` 补 CLI 同源事实命令（`task scope` / `task specs`），MCP 不再有独占能力；contract-registry 注册 `FACT_LAYER_ACCESS_V1` 契约（digest 行注入"MCP 优先查询事实，CLI 兜底"）；doctor 新增 MCP 注册健康项（项目级 .mcp.json 存在性 / 全局+项目双重注册提示 / 缺失提示），只读 advisory 不阻断；README 增加两档注册说明（全局受支持默认 + 项目 opt-in 地图）。
+- **修复（1.2.0 遗留，Windows）**：`spec_check._run_command` 三处——含引号命令经 list2cmdline 转义后 cmd.exe 解析失败；`text=True` 未显式 `encoding="utf-8", errors="replace"`，中文 Windows cmd GBK 输出致解码线程崩溃、输出丢失；命令入口缺失在 Windows 被误分类为 violation（现经 `shutil.which` 归 unchecked，契约三态语义恢复一致）。
+- **修复**：legacy runtime context 文件（缺 `runtime_context_id` 字段）注入显示回退到检测到的 id。
+
+**行为变更**：delegated 绑定写语义统一为 Python（zcode 注入时新增 bind 写，原 JS 为只读）；zcode missing-task 文案与全宿主统一；digest/fingerprint 因注册 `FACT_LAYER_ACCESS_V1` 而变化（预期内，change guard 允许）。
+
+### 实弹修正与 delegated 自检协议化（fix）
+
+实弹验证（zcode 插件 live proof）暴露四个缺陷并修复：
+
+- **未绑定会话的编辑期警告可达**：zcode hook 会话携带对话自身 id、从不绑定（激活发生在 Bash CLI 的显式身份下），empty-session 此前跳过 newest-session 回退——主会话的编辑期 spec/scope 警告完全静默。回退现覆盖 empty-session，`spec_edit_warning` 的 zcode 路由经它放行（claude-code/codex 保持严格身份）。
+- **scope 路径相对化**：`edit_scope_warning` 此前拿原始绝对路径与仓库相对白名单比对，所有编辑都被误标越界；现与 spec 路径同样归一为仓库相对，警告行显示相对路径。
+- **编辑期预算与节流加固**：edit 钳制 3s→2.5s（子进程预算余量）；节流只在跑完一次后写入（执行器崩溃不再吞掉节流窗口）；`files` 多值列表逐 token 剥引号。
+- **delegated 子代理收到 spec 反馈**：编辑期 spec 警告的静默范围此前在 Python/JS 两侧不一致，现统一为 delegated 会话可达（scope 警告保持仅主会话）。
+
+配套协议化（文档与 skill）：实弹两轮证实宿主 PostToolUse 只覆盖主会话流——Agent 子代理收不到编辑期反馈。按已验证的 CLI 拉取路径固化：子代理报告前跑 `run spec-check` 自检修复（subagent-dispatch.md、agent-dispatch SKILL）；父侧验收把 violation 作为验收阻断项（task-review SKILL，delegated 工作最早的可靠检查点）；task-planning 的实现 Verify 命令默认含 spec-check 自检；spec-checks.md 记录缺口、四部分补偿与治理方向（向宿主请求；原生的那一环降级为冗余保险）。
+
+**已知合法副作用**：contract fingerprint 更新为 `d1d0e2536e8fa150`（内容派生；Python 与 JS 镜像重算一致）。
+
+### 发布门禁加固（release.sh）
+
+- 同步 `--force` 自实例镜像时带 AGENTS.md 定制守卫（脏树预检、sync 后从 HEAD 还原）；pytest services 门禁前置到 `test:all` 之前；`.gitattributes` 将 `*.version` 钉为 LF（fingerprint 字节比对前提）。
+
 ## 1.2.0 - 2026-09-08
 
 ### 规范挂命令（spec 约束前移）

package/README.md

@@ -11,7 +11,7 @@
 | 领域 | 当前能力 |
 |---|---|
 | 任务流程 | `task next --json` 给出下一步 action，`task next --run` 只执行当前 action。 |
-| 事实接入 | `run state [task] --json` 事实视图；`run mcp-state` 无依赖 MCP 只读服务（`task_state` / `task_list`）供任何 MCP 客户端查询。 |
+| 事实接入 | `run state [task] --json` 事实视图；`run mcp-state` 无依赖 MCP 只读服务（`task_state` / `task_list` / `task_scope` / `task_specs`）供任何 MCP 客户端查询；`task scope` / `task specs` 为 CLI 同源事实命令。 |
 | 运行健康 | `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。 |
@@ -66,8 +66,9 @@ cowork-flow install-dsh-preset
 # 机器级安装实时 workflow-state 注入（推荐：不换预设，任意 DSH 会话生效）
 cowork-flow install-dsh-hook
 
-# MCP 客户端接入（可选）：全局注册一次，任意项目查询任务事实
-# 各客户端配置样例见 docs/mcp-client-setup.md
+# MCP 客户端接入（可选）：全局注册一次，任意项目查询任务事实；
+# 项目级 opt-in（如 claude-code 的 .mcp.json）与注册健康检测见
+# `run doctor`，各客户端配置样例见 docs/mcp-client-setup.md
 cowork-flow mcp-state
 
 # 维护者发布前检查

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {

package/template/.claude/hooks/inject-workflow-state.py

@@ -1,114 +1,28 @@
 #!/usr/bin/env python3
-"""Emit cowork-flow workflow context for Claude Code hooks."""
+"""Claude Code hook: thin delegate to the host-neutral injection entry.
+
+All workflow facts and host shaping (preamble, envelope, exit codes) live in
+adapters/host/inject.py — this file only locates the project runtime next to
+itself (.claude/hooks/ → project root) and forwards with --host claude-code.
+"""
 
 from __future__ import annotations
 
-import json
-import os
 import sys
 from pathlib import Path
-from typing import Any
-
-
-def _configure_stdio() -> None:
-    for stream in (sys.stdout, sys.stderr):
-        if hasattr(stream, "reconfigure"):
-            stream.reconfigure(encoding="utf-8", errors="replace")
-
-
-def _read_input() -> dict[str, Any]:
-    raw = sys.stdin.buffer.read()
-    if not raw.strip():
-        return {}
-    try:
-        data = json.loads(raw.decode("utf-8-sig"))
-    except (UnicodeDecodeError, json.JSONDecodeError, ValueError):
-        return {}
-    if not isinstance(data, dict):
-        return {}
-    if "claude_session_id" not in data:
-        session_id = data.get("session_id")
-        if isinstance(session_id, str) and session_id.strip():
-            data["claude_session_id"] = session_id
-    return data
-
-
-def _find_root(start: Path) -> Path | None:
-    current = start.resolve()
-    while True:
-        if (current / ".cowork-flow").is_dir():
-            return current
-        if current == current.parent:
-            return None
-        current = current.parent
 
 
 def main() -> int:
-    if (
-        os.environ.get("COWORK_FLOW_HOOKS") == "0"
-        or os.environ.get("COWORK_FLOW_DISABLE_HOOKS") == "1"
-    ):
-        return 0
-    hook_input = _read_input()
-    cwd_value = hook_input.get("cwd")
-    cwd = (
-        Path(cwd_value)
-        if isinstance(cwd_value, str) and cwd_value.strip()
-        else Path.cwd()
-    )
-    root = _find_root(cwd)
-    if root is None:
+    project_root = Path(__file__).resolve().parents[2]
+    scripts_dir = project_root / ".cowork-flow" / "scripts"
+    if not scripts_dir.is_dir():
+        # Outside any cowork-flow project: stay silent like the entry does.
         return 0
-    scripts_dir = root / ".cowork-flow" / "scripts"
     sys.path.insert(0, str(scripts_dir))
+    from adapters.host.inject import main as inject_main
 
-    event_name = (
-        hook_input.get("hook_event_name")
-        or hook_input.get("hookEventName")
-        or "UserPromptSubmit"
-    )
-    if event_name == "PostToolUse":
-        # Editor-phase spec-check short path: at most one advisory line on
-        # stderr (exit 2 surfaces it to the model; the edit itself has
-        # already happened). Nothing to report exits 0 silently.
-        from adapters.host.workflow_state_hook import spec_edit_warning
-
-        warning = spec_edit_warning(root, hook_input)
-        if warning:
-            print(warning, file=sys.stderr)
-            return 2
-        return 0
-
-    from adapters.host.workflow_state_hook import build_hook_context
-
-    context = build_hook_context(
-        root,
-        hook_input,
-        host="claude-code",
-        adapter="claude-code.hooks",
-        preamble=(
-            (
-                "<claude-code-runtime>\n"
-                "hooks: UserPromptSubmit, SessionStart, PostToolUse\n"
-                "</claude-code-runtime>"
-            ),
-        ),
-        session_start=(event_name == "SessionStart"),
-    )
-    print(
-        json.dumps(
-            {
-                "hookSpecificOutput": {
-                    "hookEventName": event_name,
-                    "additionalContext": context,
-                }
-            },
-            ensure_ascii=False,
-        )
-    )
-    return 0
+    return inject_main(["--host", "claude-code"])
 
 
 if __name__ == "__main__":
-    _configure_stdio()
     raise SystemExit(main())

package/template/.codex/hooks/inject-workflow-state.py

@@ -1,105 +1,29 @@
 #!/usr/bin/env python3
-"""Emit cowork-flow workflow context for Codex hooks."""
+"""Codex hook: thin delegate to the host-neutral injection entry.
+
+All workflow facts and host shaping (dispatch-mode preamble, envelope,
+session-probe digest semantics) live in adapters/host/inject.py — this file
+only locates the project runtime next to itself (.codex/hooks/ → project
+root) and forwards with --host codex.
+"""
 
 from __future__ import annotations
 
-import json
-import os
 import sys
 from pathlib import Path
-from typing import Any
-
-
-def _configure_stdio() -> None:
-    for stream in (sys.stdout, sys.stderr):
-        if hasattr(stream, "reconfigure"):
-            stream.reconfigure(encoding="utf-8", errors="replace")
-
-
-def _read_input() -> dict[str, Any]:
-    raw = sys.stdin.buffer.read()
-    if not raw.strip():
-        return {}
-    try:
-        data = json.loads(raw.decode("utf-8-sig"))
-    except (UnicodeDecodeError, json.JSONDecodeError, ValueError):
-        return {}
-    return data if isinstance(data, dict) else {}
-
-
-def _find_root(start: Path) -> Path | None:
-    current = start.resolve()
-    while True:
-        if (current / ".cowork-flow").is_dir():
-            return current
-        if current == current.parent:
-            return None
-        current = current.parent
 
 
 def main() -> int:
-    if (
-        os.environ.get("COWORK_FLOW_HOOKS") == "0"
-        or os.environ.get("COWORK_FLOW_DISABLE_HOOKS") == "1"
-    ):
-        return 0
-    hook_input = _read_input()
-    cwd_value = hook_input.get("cwd")
-    cwd = (
-        Path(cwd_value)
-        if isinstance(cwd_value, str) and cwd_value.strip()
-        else Path.cwd()
-    )
-    root = _find_root(cwd)
-    if root is None:
+    project_root = Path(__file__).resolve().parents[2]
+    scripts_dir = project_root / ".cowork-flow" / "scripts"
+    if not scripts_dir.is_dir():
+        # Outside any cowork-flow project: stay silent like the entry does.
         return 0
-    scripts_dir = root / ".cowork-flow" / "scripts"
     sys.path.insert(0, str(scripts_dir))
-    from adapters.host.workflow_state_hook import (
-        build_hook_context,
-        codex_dispatch_mode,
-    )
+    from adapters.host.inject import main as inject_main
 
-    dispatch_mode = codex_dispatch_mode(root)
-    event_name = (
-        hook_input.get("hook_event_name")
-        or hook_input.get("hookEventName")
-        or "UserPromptSubmit"
-    )
-    context = build_hook_context(
-        root,
-        hook_input,
-        host="codex",
-        adapter="codex.spawn_agent",
-        preamble=(
-            f"<codex-dispatch-mode>{dispatch_mode}</codex-dispatch-mode>",
-            (
-                "<codex-runtime>\n"
-                "dispatch_mode_meaning: workflow dispatch hint, not current "
-                "thread role\n"
-                "runtime_context_identity: formal subagent sessions bind "
-                "before workflow-state injection\n"
-                "</codex-runtime>"
-            ),
-        ),
-        # Codex registers UserPromptSubmit only, so event_name carries no
-        # session-start signal; build_hook_context falls back to the session
-        # state file probe (full on first injection, slim afterwards).
-    )
-    print(
-        json.dumps(
-            {
-                "hookSpecificOutput": {
-                    "hookEventName": event_name,
-                    "additionalContext": context,
-                }
-            },
-            ensure_ascii=False,
-        )
-    )
-    return 0
+    return inject_main(["--host", "codex"])
 
 
 if __name__ == "__main__":
-    _configure_stdio()
     raise SystemExit(main())

package/template/.cowork-flow/.version

@@ -1 +1 @@
-1.2.0
+1.3.0

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

@@ -26,7 +26,6 @@ from services.task_context import (
     is_skill_path as _is_skill_path,
     iter_jsonl_lines as _iter_jsonl_lines,
     skill_path as _skill_path,
-    use_claude_skill_context as _use_claude_skill_context,
     write_jsonl as _write_jsonl,
 )
 from adapters.cli.task_archive_commands import cmd_archive
@@ -35,6 +34,8 @@ from adapters.cli.task_context_commands import (
     cmd_add_context,
     cmd_init_context,
     cmd_list_context,
+    cmd_scope,
+    cmd_specs,
     cmd_validate,
 )
 from adapters.cli.task_create_command import cmd_create, ensure_tasks_dir
@@ -124,6 +125,8 @@ WORKER_BLOCKED_COMMANDS = frozenset()
 
 COMMANDS = {
     "next": cmd_next,
+    "scope": cmd_scope,
+    "specs": cmd_specs,
 }
 
 

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

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import argparse
+import json
 from pathlib import Path
 
 from services.task_context import (
@@ -244,3 +245,67 @@ def cmd_list_context(args: argparse.Namespace) -> int:
             print(f"     {colored('->', Colors.YELLOW)} {reason}")
         print()
     return 0
+
+
+def _resolve_fact_task_dir(
+    task_dir_arg: str | None, repo_root: Path
+) -> Path | None:
+    """Explicit dir wins; otherwise the session-bound active task. Returns
+    None when nothing is resolvable (the caller reports no-active-task)."""
+    if task_dir_arg:
+        return resolve_task_dir(task_dir_arg, repo_root)
+    from runtime.session_state import get_active_task
+
+    active = get_active_task(repo_root)
+    if not active.task_path:
+        return None
+    return repo_root / active.task_path
+
+
+def _print_fact_json(payload: dict) -> None:
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+def cmd_scope(args: argparse.Namespace) -> int:
+    """File-scope whitelist for a task (read-only fact query, MCP task_scope
+    parity). With --path, prints the per-file inScope verdict instead."""
+    repo_root = get_repo_root()
+    task_dir = _resolve_fact_task_dir(getattr(args, "dir", None), repo_root)
+    if task_dir is None or not task_dir.is_dir():
+        _print_fact_json({"error": "no-active-task"})
+        return 1
+    from services.fact_view import file_scope_whitelist, path_in_scope
+
+    whitelist = file_scope_whitelist(repo_root, task_dir)
+    if getattr(args, "path", None):
+        payload = {"taskDir": task_dir.name, **path_in_scope(whitelist, args.path)}
+    else:
+        payload = {
+            "taskDir": task_dir.name,
+            "whitelist": whitelist,
+            "count": len(whitelist),
+        }
+    _print_fact_json(payload)
+    return 0
+
+
+def cmd_specs(args: argparse.Namespace) -> int:
+    """Spec/skill reading list dispatched by task dev_type (read-only fact
+    query, MCP task_specs parity)."""
+    repo_root = get_repo_root()
+    task_dir = _resolve_fact_task_dir(getattr(args, "dir", None), repo_root)
+    if task_dir is None or not task_dir.is_dir():
+        _print_fact_json({"error": "no-active-task"})
+        return 1
+    from services.fact_view import spec_entries_for_task
+
+    dev_type, specs = spec_entries_for_task(repo_root, task_dir)
+    _print_fact_json(
+        {
+            "taskDir": task_dir.name,
+            "devType": dev_type,
+            "specs": specs,
+            "count": len(specs),
+        }
+    )
+    return 0

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

@@ -168,6 +168,27 @@ def _add_next_command(subparsers: argparse._SubParsersAction) -> None:
     _add_next_create_inputs(next_parser)
     _add_next_runtime_inputs(next_parser)
 
+
+def _add_scope_command(subparsers: argparse._SubParsersAction) -> None:
+    scope_parser = subparsers.add_parser(
+        "scope",
+        help="File-scope whitelist for a task (read-only fact query)",
+    )
+    _add_optional_task_dir(scope_parser)
+    scope_parser.add_argument(
+        "--path",
+        help="Check one repo-relative path and print the inScope verdict",
+    )
+
+
+def _add_specs_command(subparsers: argparse._SubParsersAction) -> None:
+    specs_parser = subparsers.add_parser(
+        "specs",
+        help="Spec/skill reading list dispatched by task dev_type "
+        "(read-only fact query)",
+    )
+    _add_optional_task_dir(specs_parser)
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         description="Task workflow router for cowork-flow",
@@ -179,6 +200,8 @@ def build_parser() -> argparse.ArgumentParser:
         help="Commands",
     )
     _add_next_command(subparsers)
+    _add_scope_command(subparsers)
+    _add_specs_command(subparsers)
     return parser
 
 

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

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""claude-code host policy: the claude-code-specific behaviors of the
+workflow hook.
+
+Rendering stays in workflow_state_hook.py; this module owns only the
+claude-code transport specifics — the session alias ported from the claude
+wrapper, the runtime preamble block, and the PostToolUse spec-advisory path
+(stderr + exit 2, shared with codex via the neutral helper).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from adapters.host.workflow_state_hook import HostPolicy
+
+CLAUDE_PREAMBLE = (
+    (
+        "<claude-code-runtime>\n"
+        "hooks: UserPromptSubmit, SessionStart, PostToolUse\n"
+        "</claude-code-runtime>"
+    ),
+)
+
+
+def claude_session_alias(data: dict[str, Any]) -> dict[str, Any]:
+    # Ported from the claude-code wrapper: bare session_id must resolve as a
+    # claude session, not fall through to the codex session_id rule.
+    if "claude_session_id" not in data:
+        session_id = data.get("session_id")
+        if isinstance(session_id, str) and session_id.strip():
+            data["claude_session_id"] = session_id
+    return data
+
+
+def preamble(root: Path) -> tuple[str, ...]:
+    return CLAUDE_PREAMBLE
+
+
+def post_tool_use(root: Path, hook_input: dict[str, Any]) -> tuple[str, int]:
+    from adapters.host.workflow_state_hook import spec_only_post_tool_use
+
+    return spec_only_post_tool_use(root, hook_input, POLICY)
+
+
+POLICY = HostPolicy(
+    host="claude-code",
+    session_alias=claude_session_alias,
+    preamble=preamble,
+    post_tool_use=post_tool_use,
+)

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

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""codex host policy: the codex-specific behaviors of the workflow hook.
+
+Rendering stays in workflow_state_hook.py; this module owns only the codex
+transport specifics — the dispatch-mode preamble (config-driven, the codex
+wrapper surfaces it above every injection) and the probe-based session-start
+detection (codex registers UserPromptSubmit only, so the digest shape derives
+from the session state file probe). PostToolUse reuses the neutral spec-only
+stderr path shared with claude-code.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+from adapters.host.workflow_state_hook import HostPolicy
+
+
+def codex_dispatch_mode(root: Path) -> str:
+    from adapters.host.workflow_state_hook import _load_common
+
+    _load_common(root)
+    try:
+        from infra.config import get_codex_dispatch_mode
+    except Exception:
+        return "sub-agent"
+    try:
+        return get_codex_dispatch_mode(root)
+    except Exception:
+        return "sub-agent"
+
+
+def preamble(root: Path) -> tuple[str, ...]:
+    dispatch_mode = codex_dispatch_mode(root)
+    return (
+        f"<codex-dispatch-mode>{dispatch_mode}</codex-dispatch-mode>",
+        (
+            "<codex-runtime>\n"
+            "dispatch_mode_meaning: workflow dispatch hint, not current "
+            "thread role\n"
+            "runtime_context_identity: formal subagent sessions bind "
+            "before workflow-state injection\n"
+            "</codex-runtime>"
+        ),
+    )
+
+
+def post_tool_use(root: Path, hook_input: dict[str, Any]) -> tuple[str, int]:
+    from adapters.host.workflow_state_hook import spec_only_post_tool_use
+
+    return spec_only_post_tool_use(root, hook_input, POLICY)
+
+
+POLICY = HostPolicy(
+    host="codex",
+    session_start_event=None,  # probe the session state file instead
+    preamble=preamble,
+    post_tool_use=post_tool_use,
+)