cowork-flow 1.1.4 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 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/package.json

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

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

@@ -61,13 +61,26 @@ def main() -> int:
         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
 
     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,
@@ -76,7 +89,7 @@ def main() -> int:
         preamble=(
             (
                 "<claude-code-runtime>\n"
-                "hooks: UserPromptSubmit, SessionStart\n"
+                "hooks: UserPromptSubmit, SessionStart, PostToolUse\n"
                 "</claude-code-runtime>"
             ),
         ),

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/.cowork-flow/.version

@@ -1 +1 @@
-1.1.4
+1.2.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_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",

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

@@ -252,12 +252,14 @@ def _stage_contract_block(
             build_stage_contract,
             file_scope_whitelist,
             parse_decision_anchor,
+            spec_digest_items,
             spec_pointer_files,
         )
 
         task_dir = root / task_path
         whitelist = file_scope_whitelist(root, task_dir)
         spec_files = spec_pointer_files(task_dir)
+        digests = spec_digest_items(root, spec_files) if spec_files else {}
         rules = load_scope_rules(root)
         anchor_path = task_dir / "decision-anchor.md"
         try:
@@ -280,12 +282,45 @@ def _stage_contract_block(
             parsed,
             mutable=status != "delegated_subtask",
             rules=rules,
+            digests=digests,
         )
     except Exception as error:
         sys.stderr.write(f"stage-contract degraded: {error}\n")
         return None
 
 
+def spec_edit_warning(root: Path, hook_input: dict[str, Any]) -> str:
+    """Editor-phase spec-check single-line warning (PostToolUse short path).
+
+    Silence rules match the zcode JS mirror (editScopeWarning family): only
+    an active in_progress/review main-session task gets advisories —
+    no_task, planning, completed, and delegated sessions stay silent. Empty
+    string means silent. Never raises — the editor path must not break
+    edits.
+    """
+    try:
+        task_path, status, _source = _get_active_task(root, hook_input)
+    except Exception:
+        return ""
+    if not task_path or status not in STAGE_CONTRACT_STATES:
+        return ""
+    tool_name = hook_input.get("tool_name")
+    tool_input = hook_input.get("tool_input")
+    if tool_name not in {"Edit", "Write", "MultiEdit"}:
+        return ""
+    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():
+        return ""
+    try:
+        from services.spec_check import run_edit_checks
+
+        return run_edit_checks(root, file_path)
+    except Exception:
+        return ""
+
+
 def _load_breadcrumbs(root: Path) -> dict[str, str]:
     path = (
         root

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

@@ -31,6 +31,7 @@ COMMAND_SCRIPTS = {
     "state": "adapters/cli/state.py",
     "mcp-state": "adapters/mcp/state_server.py",
     "subagent": "adapters/cli/subagent.py",
+    "spec-check": "adapters/cli/spec_check.py",
 }
 RESERVED_COMMAND_NAMES = (*COMMAND_SCRIPTS, "python", "help", "-h", "--help")
 

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

@@ -277,6 +277,7 @@ def _stage_contract_lines(
     scope_limit: int = STAGE_CONTRACT_SCOPE_LIMIT,
     spec_limit: int = STAGE_CONTRACT_SPECS_LIMIT,
     verify_limit: int = STAGE_CONTRACT_VERIFY_LIMIT,
+    digests: dict[str, str] | None = None,
 ) -> list[str]:
     """Assemble the stage-contract body lines. Byte-for-byte mirrored by the
     zcode and opencode JS implementations — keep the formatting identical."""
@@ -285,8 +286,13 @@ def _stage_contract_lines(
     scope_items = [entry["file"] for entry in whitelist[:scope_limit]]
     lines.append(_scope_row(scope_items, len(whitelist), scope_suffix))
     if spec_files:
+        digest_map = digests or {}
         spec_items = spec_files[:spec_limit]
-        specs_text = "; ".join(spec_items)
+        parts = []
+        for item in spec_items:
+            digest = digest_map.get(item)
+            parts.append(f"{item}({digest})" if digest else item)
+        specs_text = "; ".join(parts)
         spec_more = len(spec_files) - len(spec_items)
         if spec_more > 0:
             specs_text += f" (+{spec_more} more)"
@@ -315,6 +321,7 @@ def build_stage_contract(
     anchor: dict[str, Any],
     mutable: bool = True,
     rules: dict | None = None,
+    digests: dict[str, str] | None = None,
 ) -> str:
     """Assemble the stage-contract block. Byte-for-byte mirrored by the zcode
     and opencode JS implementations — keep the formatting identical. Over-
@@ -322,7 +329,8 @@ def build_stage_contract(
     closed block. `mutable=False` renders the parent scope as a read-only
     reference for delegated subtasks. `rules` comes from
     scope-rules.json (load_scope_rules) and carries budget and limits; None
-    falls back to the module constants."""
+    falls back to the module constants. `digests` maps spec pointer entries
+    to their h2 heading digest (spec_digest_items)."""
     stage_contract = (rules or {}).get("stageContract") or {}
     budget = stage_contract.get("budget", STAGE_CONTRACT_BUDGET)
     scope_limit = stage_contract.get("scopeLimit", STAGE_CONTRACT_SCOPE_LIMIT)
@@ -338,6 +346,7 @@ def build_stage_contract(
             scope_limit=scope_limit,
             spec_limit=spec_limit,
             verify_limit=verify_limit,
+            digests=digests,
         )
     )
     lines.append("</stage-contract>")
@@ -348,6 +357,50 @@ def build_stage_contract(
     return "\n".join(fitted)
 
 
+# Spec digest: the h2 heading tree of each bound spec — the "entry-name"
+# index injected with the contract so the rules exist in the agent's
+# attention without reading full spec bodies. Format is pinned byte-for-byte
+# across the Python source and the zcode/opencode JS mirrors (contract
+# fingerprint tests): path(h2a/h2b), at most 6 headings, each truncated to
+# 24 chars after stripping "();" characters.
+SPEC_DIGEST_MAX_HEADINGS = 6
+SPEC_DIGEST_MAX_CHARS = 24
+
+
+def _clean_digest_heading(raw: str) -> str:
+    cleaned = (
+        raw.replace("(", "").replace(")", "").replace(";", "").strip()
+    )
+    return cleaned[:SPEC_DIGEST_MAX_CHARS]
+
+
+def spec_heading_digest(path: Path) -> str | None:
+    """Extract the h2 heading digest of one spec file, or None."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    headings: list[str] = []
+    for line in text.splitlines():
+        if line.startswith("## ") and not line.startswith("###"):
+            cleaned = _clean_digest_heading(line[3:])
+            if cleaned:
+                headings.append(cleaned)
+                if len(headings) >= SPEC_DIGEST_MAX_HEADINGS:
+                    break
+    return "/".join(headings) if headings else None
+
+
+def spec_digest_items(root: Path, spec_files: list[str]) -> dict[str, str]:
+    """Digest map for spec pointer entries; missing files stay unannotated."""
+    digests: dict[str, str] = {}
+    for item in spec_files:
+        digest = spec_heading_digest(root / item)
+        if digest:
+            digests[item] = digest
+    return digests
+
+
 def _normalize_rel(path_value: str) -> str | None:
     value = path_value.strip().replace("\\", "/")
     while value.startswith("./"):

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

@@ -44,6 +44,7 @@ class LifecycleCheckResult:
     stage: str
     blockers: tuple[str, ...] = ()
     issues: tuple[LifecycleCheckIssue, ...] = ()
+    spec_check: dict | None = None
 
     def __post_init__(self) -> None:
         if self.issues and not self.blockers:
@@ -96,18 +97,27 @@ class LifecycleCheckRunner:
         allow_spec_file_modifications: bool | None = None,
         execution_policy: LifecycleExecutionPolicy | None = None,
     ) -> LifecycleCheckResult:
+        spec_report = _spec_check_report(self.repo_root)
+        spec_issues = _spec_check_completion_issues(
+            spec_report,
+            allow_unchecked_specs=_policy_allows_unchecked(
+                execution_policy,
+            ),
+        )
         return LifecycleCheckResult(
             stage="complete",
             issues=tuple(
-                _review_completion_issues(
+                list(_review_completion_issues(
                     self.repo_root,
                     task_dir,
                     allow_spec_file_modifications=_policy_allows_spec_changes(
                         execution_policy,
                         allow_spec_file_modifications,
                     ),
-                ),
+                ))
+                + list(spec_issues)
             ),
+            spec_check=spec_report,
         )
 
 
@@ -120,6 +130,69 @@ def _policy_allows_spec_changes(
     return bool(allow_spec_file_modifications)
 
 
+def _policy_allows_unchecked(
+    execution_policy: LifecycleExecutionPolicy | None,
+) -> bool:
+    return bool(execution_policy is not None and execution_policy.allow_unchecked_specs)
+
+
+def _spec_check_report(repo_root: Path) -> dict | None:
+    """Run the lifecycle-phase spec checks. A structural failure degrades to
+    an unchecked report — never to a silently passing gate."""
+    try:
+        from services.spec_check import run_checks
+    except Exception:  # pragma: no cover - import surface must stay lazy
+        return {"schemaVersion": 1, "phase": "lifecycle", "results": [],
+                "parseErrors": [], "summary": {"pass": 0, "violation": 0,
+                "unchecked": 1, "executorError": 1}}
+    try:
+        return run_checks(repo_root, phase="lifecycle")
+    except Exception as error:  # fail closed: unchecked, not pass
+        return {"schemaVersion": 1, "phase": "lifecycle", "results": [],
+                "parseErrors": [], "summary": {"pass": 0, "violation": 0,
+                "unchecked": 1, "executorError": 1, "error": str(error)}}
+
+
+def _spec_check_completion_issues(
+    spec_report: dict | None,
+    *,
+    allow_unchecked_specs: bool,
+) -> list[LifecycleCheckIssue]:
+    if not spec_report:
+        return []
+    summary = spec_report.get("summary") or {}
+    issues: list[LifecycleCheckIssue] = []
+    violation = int(summary.get("violation") or 0)
+    unchecked = int(summary.get("unchecked") or 0)
+    if violation:
+        first_lines = []
+        for item in spec_report.get("results") or []:
+            if item.get("status") == "violation":
+                detail = item.get("firstViolationLine") or item.get("reason") or ""
+                first_lines.append(f"{item.get('spec')}: {detail}")
+        issues.append(
+            LifecycleCheckIssue(
+                code="SPEC-CHECK-VIOLATION",
+                message=(
+                    "spec checks report "
+                    f"{violation} violation(s): {'; '.join(first_lines[:3])}"
+                ),
+            )
+        )
+    if unchecked and not allow_unchecked_specs:
+        issues.append(
+            LifecycleCheckIssue(
+                code="SPEC-CHECK-UNCHECKED",
+                message=(
+                    f"spec checks report {unchecked} unchecked command(s) "
+                    "(missing/timeout); rerun spec-check, or pass "
+                    "--allow-unchecked to complete with the exemption recorded"
+                ),
+            )
+        )
+    return issues
+
+
 
 def _baseline_changed_paths(
     repo_root: Path, task_dir: Path

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

@@ -34,6 +34,7 @@ class LifecycleExecutionPolicy:
 
     execution_scope: str
     allow_spec_file_modifications: bool
+    allow_unchecked_specs: bool = False
 
 
 def start_readiness_failure(
@@ -91,13 +92,18 @@ def resolve_execution_policy(
     execution_context: ExecutionContext | None = None,
     *,
     allow_spec_file_modifications: bool | None = None,
+    allow_unchecked_specs: bool | None = None,
 ) -> LifecycleExecutionPolicy:
     """Resolve lifecycle scope capability from execution facts."""
     if execution_context is None:
-        if allow_spec_file_modifications is not None:
+        if (
+            allow_spec_file_modifications is not None
+            or allow_unchecked_specs is not None
+        ):
             return LifecycleExecutionPolicy(
                 execution_scope="explicit",
-                allow_spec_file_modifications=allow_spec_file_modifications,
+                allow_spec_file_modifications=bool(allow_spec_file_modifications),
+                allow_unchecked_specs=bool(allow_unchecked_specs),
             )
         execution_context = ExecutionContext()
 
@@ -110,6 +116,7 @@ def resolve_execution_policy(
     return LifecycleExecutionPolicy(
         execution_scope=execution_context.mode,
         allow_spec_file_modifications=allowed,
+        allow_unchecked_specs=bool(allow_unchecked_specs),
     )