cowork-flow 1.1.4 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # 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 约束前移）
+
+用户在 `.cowork-flow/spec/` 定义的行为规范，从"review 才发现"前移为"编码时即约束"：
+
+- **spec frontmatter `checks:` 声明**：每条规范可声明检查命令（`cmd`/`files`/`timeout`/`when`），由唯一执行器 `./.cowork-flow/run spec-check` 按相位执行；机制只消费声明、不解析规范正文，规则变化随 spec 同文件天然同步。`files` 只支持目录前缀与扩展名两种形式（完整 glob 解析为错误且声明不执行，doctor 报告）。契约文档见 `spec/contracts/spec-checks.md`。
+- **三态门禁语义**：`pass` / `violation`（complete 阻断、状态不推进）/ `unchecked`（命令缺失、解释器缺失、超时——阻断并要求显式 `--allow-unchecked`，豁免留痕进 `task.json` `meta.specCheckExempt` 供 review 可见）。unchecked 永不冒充 pass。
+- **收口遥测**：complete 时全量结果写 `meta.specCheckSummary`，为"返工前移"效果提供可对比基线。
+- **三线 digest 注入**：进入 in_progress 后，stage-contract 的 Specs 行升级为 h2 标题树索引（每 spec 最多 6 条、每条截断 24 字符），规范条目名随契约常驻注意力；spec 正文改动不影响 digest，超预算整行让位（Scope/Gates 永不丢）。python/zcode/opencode 输出由 matrix 用例锁定逐字相等，claude 线经 Python 单源自动获得。
+- **编辑期快跑**：zcode（PostToolUse 短路径，spawn 单源 CLI、3.8s 上限）与 claude（PostToolUse 新增 hook 资产，exit 2 单行 stderr 反馈）在编辑命中 `files` 的声明时就地执行，违规单行警告、同文件 10 秒节流（状态在 `.cowork-flow/.runtime/`）、执行器缺失静默不阻断编辑流；opencode 降级为仅 digest + 收口。
+- **doctor 健康项**：`specChecks` 报告声明解析错误与命令入口不存在——"跑不了的声明"在收口前暴露。
+
+配套：spec-check CLI（`--phase/--file/--json/--verbose/--throttled`）、`--allow-unchecked` 收口旗标、架构拓扑保持 services 层无 CLI 关注点。
+
 ## 1.1.4 - 2026-08-31
 
 ### 修复

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.1.4",
+  "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,101 +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.workflow_state_hook import build_hook_context
+    from adapters.host.inject import main as inject_main
 
-    event_name = (
-        hook_input.get("hook_event_name")
-        or hook_input.get("hookEventName")
-        or "UserPromptSubmit"
-    )
-    context = build_hook_context(
-        root,
-        hook_input,
-        host="claude-code",
-        adapter="claude-code.hooks",
-        preamble=(
-            (
-                "<claude-code-runtime>\n"
-                "hooks: UserPromptSubmit, SessionStart\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/.claude/settings.json

@@ -19,6 +19,18 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PROJECT_DIR:-.}/.cowork-flow/run\" python \"${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/inject-workflow-state.py\"",
+            "timeout": 30
+          }
+        ]
+      }
     ]
   }
 }

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.1.4
+1.3.0

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

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""`run spec-check [--phase edit|lifecycle] [--file <path>...] [--json]`.
+
+Executes user-declared spec checks (frontmatter `checks:`) and prints a
+normalized one-line summary unless `--json`/`--verbose` asks for more. See
+services/spec_check.py for the three-state contract (pass/violation/unchecked).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+if __package__:
+    from . import _bootstrap as _bootstrap  # noqa: F401
+else:
+    import _bootstrap  # noqa: F401
+
+from infra.paths import get_repo_root
+from services.spec_check import SpecCheckError, run_checks, summary_has
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="spec-check",
+        description=(
+            "Run user-declared spec checks (frontmatter checks:) for one phase."
+        ),
+    )
+    parser.add_argument(
+        "--phase",
+        choices=("edit", "lifecycle"),
+        default="lifecycle",
+        help="edit: only declarations matching the given files (3s clamp); "
+        "lifecycle: every declaration honoring its files scope.",
+    )
+    parser.add_argument(
+        "--file",
+        action="append",
+        default=None,
+        help="Changed file path to match against declaration files filters; "
+        "repeatable. Drives the edit-phase filter and single-file queries.",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Print full command output per result (query mode only).",
+    )
+    parser.add_argument(
+        "--throttled",
+        action="store_true",
+        help="Editor-phase mode: single-line report for one file, throttled "
+        "per file (empty output when nothing to report).",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        dest="as_json",
+        help="Print the machine-readable report.",
+    )
+    args = parser.parse_args()
+
+    repo_root = get_repo_root()
+
+    if args.throttled:
+        from services.spec_check import run_edit_checks
+
+        files = args.file or []
+        if len(files) != 1:
+            print("Error: --throttled requires exactly one --file", file=sys.stderr)
+            return 2
+        print(run_edit_checks(repo_root, files[0]))
+        return 0
+
+    try:
+        report = run_checks(
+            repo_root,
+            phase=args.phase,
+            changed_files=args.file or [],
+        )
+    except SpecCheckError as error:
+        print(f"Error: {error}", file=sys.stderr)
+        return 2
+
+    if args.as_json:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+        return 0
+
+    if args.verbose:
+        for result in report.get("results", []):
+            print(f"--- {result.get('spec')} :: {result.get('cmd')}")
+            for line in result.get("output", []):
+                print(line)
+            if result.get("reason"):
+                print(f"reason: {result['reason']}")
+
+    from services.spec_check import normalized_one_line
+
+    line = normalized_one_line(report)
+    if line:
+        print(line)
+    else:
+        summary = report.get("summary", {})
+        print(
+            "spec-check: {pass} passed, {violation} violations, "
+            "{unchecked} unchecked".format(
+                **{**{"pass": 0, "violation": 0, "unchecked": 0}, **summary}
+            )
+        )
+
+    if summary_has(report, "violation"):
+        return 1
+    if summary_has(report, "unchecked"):
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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_lifecycle_commands.py

@@ -329,6 +329,7 @@ def cmd_complete(args: argparse.Namespace) -> int:
     result = service.complete(
         task_dir,
         execution_context=execution_context,
+        allow_unchecked_specs=bool(getattr(args, "allow_unchecked", False)),
     )
     if not result.ok:
         if result.code == "LIFECYCLE-TRANSITION-001":

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

@@ -84,6 +84,13 @@ def _add_next_output_options(parser: argparse.ArgumentParser) -> None:
         action="store_true",
         help="Validate task context JSONL without changing task state",
     )
+    parser.add_argument(
+        "--allow-unchecked",
+        dest="allow_unchecked",
+        action="store_true",
+        help="With task completion: allow unchecked spec-check commands "
+        "(missing/timeout) and record the exemption in task.json meta",
+    )
     parser.add_argument(
         "--list",
         dest="list_tasks",
@@ -161,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",
@@ -172,6 +200,8 @@ def build_parser() -> argparse.ArgumentParser:
         help="Commands",
     )
     _add_next_command(subparsers)
+    _add_scope_command(subparsers)
+    _add_specs_command(subparsers)
     return parser