cowork-flow 1.7.2 → 1.8.0

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

@@ -23,7 +23,7 @@ VERIFY_COMMAND_MAX = 5
 SCOPE_BOUNDARY_TRUNCATE = 160
 ANCHOR_SECTIONS = ("目标", "验收标准", "被拒方案", "验证命令", "范围边界")
 ACCEPTANCE_RE = re.compile(
-    r"^\s*-\s*\[[ xX]?\]\s*(AC-[A-Za-z0-9-]+)\s*[:：]\s*(.+?)\s*$"
+    r"^\s*-\s*(?:\[([ xX])\]?\s*)?(AC-[A-Za-z0-9-]+)\s*[:：]\s*(.+?)\s*$"
 )
 REJECTED_RE = re.compile(r"^\s*-\s*\*\*(.+?)\*\*")
 _HEADING_RE = re.compile(r"^##\s*(.+?)\s*$")
@@ -53,7 +53,11 @@ def parse_decision_anchor(text: str) -> dict[str, Any]:
             match = ACCEPTANCE_RE.match(raw)
             if match:
                 acceptance.append(
-                    {"id": match.group(1), "text": match.group(2)}
+                    {
+                        "id": match.group(2),
+                        "text": match.group(3),
+                        "checked": match.group(1) in ("x", "X"),
+                    }
                 )
         elif section == "被拒方案":
             match = REJECTED_RE.match(raw)
@@ -488,6 +492,15 @@ def build_fact_view(repo_root: Path, task_dir: Path) -> dict[str, Any]:
     else:
         anchor = {"exists": False}
 
+    evidence_coverage: dict[str, Any] | None = None
+    if anchor.get("acceptanceCriteria"):
+        try:
+            from services.ac_evidence import coverage_summary
+
+            evidence_coverage = coverage_summary(task_dir)
+        except Exception:
+            evidence_coverage = None
+
     meta = task.get("meta") if isinstance(task, dict) else None
     plan_file = meta.get("planFile") if isinstance(meta, dict) else None
     plan: dict[str, Any] = {"bound": bool(plan_file)}
@@ -501,6 +514,7 @@ def build_fact_view(repo_root: Path, task_dir: Path) -> dict[str, Any]:
         "taskPath": rel_task,
         "task": task,
         "decisionAnchor": anchor,
+        "evidenceCoverage": evidence_coverage,
         "plan": plan,
         "whitelist": file_scope_whitelist(repo_root, task_dir),
         "sessions": _bound_sessions(repo_root, rel_task),

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

@@ -45,6 +45,7 @@ class LifecycleCheckResult:
     blockers: tuple[str, ...] = ()
     issues: tuple[LifecycleCheckIssue, ...] = ()
     spec_check: dict | None = None
+    evidence_exemption: dict | None = None
 
     def __post_init__(self) -> None:
         if self.issues and not self.blockers:
@@ -96,6 +97,7 @@ class LifecycleCheckRunner:
         *,
         allow_spec_file_modifications: bool | None = None,
         allow_unchecked_specs: bool | None = None,
+        allow_missing_evidence: bool | None = None,
         execution_policy: LifecycleExecutionPolicy | None = None,
     ) -> LifecycleCheckResult:
         spec_report = _spec_check_report(self.repo_root)
@@ -107,6 +109,14 @@ class LifecycleCheckRunner:
                 else _policy_allows_unchecked(execution_policy)
             ),
         )
+        ac_issues, evidence_exemption = _ac_evidence_completion_facts(
+            task_dir,
+            allow_missing_evidence=(
+                bool(allow_missing_evidence)
+                if allow_missing_evidence is not None
+                else _policy_allows_missing_evidence(execution_policy)
+            ),
+        )
         return LifecycleCheckResult(
             stage="complete",
             issues=tuple(
@@ -119,8 +129,10 @@ class LifecycleCheckRunner:
                     ),
                 ))
                 + list(spec_issues)
+                + list(ac_issues)
             ),
             spec_check=spec_report,
+            evidence_exemption=evidence_exemption,
         )
 
 
@@ -139,6 +151,78 @@ def _policy_allows_unchecked(
     return bool(execution_policy is not None and execution_policy.allow_unchecked_specs)
 
 
+def _policy_allows_missing_evidence(
+    execution_policy: LifecycleExecutionPolicy | None,
+) -> bool:
+    return bool(
+        execution_policy is not None
+        and execution_policy.allow_missing_evidence
+    )
+
+
+def _ac_evidence_completion_facts(
+    task_dir: Path,
+    *,
+    allow_missing_evidence: bool,
+) -> tuple[list[LifecycleCheckIssue], dict | None]:
+    """Completion gate over acceptance-criteria evidence.
+
+    The gate only decides existence facts: which AC ids the decision anchor
+    declares, which are checked, and which carry at least one evidence
+    record. Tasks without AC rows are exempt (compatibility path); an
+    unreadable evidence module degrades the same way instead of blocking
+    every legacy task. Returns the issues plus the recorded exemption
+    (missing ids) when --allow-missing-evidence absorbed the gap."""
+    try:
+        from services.ac_evidence import (
+            evidence_coverage,
+            load_acceptance_criteria,
+            read_evidence,
+        )
+    except Exception:  # pragma: no cover - broken runtime copy degrades
+        return [], None
+    acceptance = load_acceptance_criteria(task_dir)
+    if not acceptance:
+        return [], None
+    coverage = evidence_coverage(acceptance, read_evidence(task_dir))
+    unchecked = [item["id"] for item in acceptance if not item["checked"]]
+    unproven = [
+        ac_id for ac_id in coverage["missing"] if ac_id not in unchecked
+    ]
+    issues: list[LifecycleCheckIssue] = []
+    if unchecked:
+        issues.append(
+            LifecycleCheckIssue(
+                code="LIFECYCLE-AC-001",
+                message=(
+                    f"decision-anchor has {len(unchecked)} unchecked "
+                    "acceptance criterion(ies): "
+                    f"{', '.join(unchecked[:5])}; finish them and tick the "
+                    "checkbox, or record evidence in evidence.jsonl"
+                ),
+            )
+        )
+    exemption: dict | None = None
+    if unproven:
+        if allow_missing_evidence:
+            exemption = {"missing": unproven}
+        else:
+            issues.append(
+                LifecycleCheckIssue(
+                    code="LIFECYCLE-AC-002",
+                    message=(
+                        f"{len(unproven)} acceptance criterion(ies) lack "
+                        "evidence records: "
+                        f"{', '.join(unproven[:5])}; append "
+                        "{ac, kind: test|command|manual, ref, note?, "
+                        "recordedAt, by} records to evidence.jsonl, or pass "
+                        "--allow-missing-evidence to record the exemption"
+                    ),
+                )
+            )
+    return issues, exemption
+
+
 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."""

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

@@ -35,6 +35,7 @@ class LifecycleExecutionPolicy:
     execution_scope: str
     allow_spec_file_modifications: bool
     allow_unchecked_specs: bool = False
+    allow_missing_evidence: bool = False
 
 
 def start_readiness_failure(
@@ -93,17 +94,20 @@ def resolve_execution_policy(
     *,
     allow_spec_file_modifications: bool | None = None,
     allow_unchecked_specs: bool | None = None,
+    allow_missing_evidence: bool | None = None,
 ) -> LifecycleExecutionPolicy:
     """Resolve lifecycle scope capability from execution facts."""
     if execution_context is None:
         if (
             allow_spec_file_modifications is not None
             or allow_unchecked_specs is not None
+            or allow_missing_evidence is not None
         ):
             return LifecycleExecutionPolicy(
                 execution_scope="explicit",
                 allow_spec_file_modifications=bool(allow_spec_file_modifications),
                 allow_unchecked_specs=bool(allow_unchecked_specs),
+                allow_missing_evidence=bool(allow_missing_evidence),
             )
         execution_context = ExecutionContext()
 
@@ -117,6 +121,7 @@ def resolve_execution_policy(
         execution_scope=execution_context.mode,
         allow_spec_file_modifications=allowed,
         allow_unchecked_specs=bool(allow_unchecked_specs),
+        allow_missing_evidence=bool(allow_missing_evidence),
     )
 
 

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

@@ -357,9 +357,16 @@ def run_checks(
     if file_filter:
         changed = [file_filter.replace("\\", "/")]
 
+    collected = collect_spec_declarations(repo_root)
+    # Repository-wide declaration count, phase-independent: "no checks
+    # declared" is a property of the repo, not of this phase's result list
+    # (a lifecycle run skips every edit-only declaration and would otherwise
+    # read as "nothing declared").
+    declarations_total = sum(len(spec_decls.decls) for spec_decls in collected)
+
     results: list[CheckResult] = []
     parse_errors: list[dict[str, str]] = []
-    for spec_decls in collect_spec_declarations(repo_root):
+    for spec_decls in collected:
         for message in spec_decls.errors:
             parse_errors.append({"spec": spec_decls.spec, "error": message})
         for decl in spec_decls.decls:
@@ -400,11 +407,14 @@ def run_checks(
         "pass": sum(1 for r in results if r.status == "pass"),
         "violation": sum(1 for r in results if r.status == "violation"),
         "unchecked": sum(1 for r in results if r.status == "unchecked"),
+        "declarations": declarations_total,
     }
     return {
         "schemaVersion": SCHEMA_VERSION,
         "phase": phase,
         "changedFiles": changed,
+        "declarations": declarations_total,
+        "specFiles": len(collected),
         "results": [r.to_json() for r in results],
         "parseErrors": parse_errors,
         "summary": summary,

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

@@ -160,6 +160,7 @@ class TaskLifecycleService:
         completed_at: str | None = None,
         allow_spec_file_modifications: bool | None = None,
         allow_unchecked_specs: bool = False,
+        allow_missing_evidence: bool = False,
         execution_context: object | None = None,
     ) -> LifecycleResult:
         return self.execute(
@@ -168,6 +169,7 @@ class TaskLifecycleService:
             completed_at=completed_at,
             allow_spec_file_modifications=allow_spec_file_modifications,
             allow_unchecked_specs=allow_unchecked_specs,
+            allow_missing_evidence=allow_missing_evidence,
             execution_context=execution_context,
         )
 
@@ -179,6 +181,7 @@ class TaskLifecycleService:
         preflight: Preflight | None = None,
         allow_spec_file_modifications: bool | None = None,
         allow_unchecked_specs: bool = False,
+        allow_missing_evidence: bool = False,
         completed_at: str | None = None,
         execution_context: object | None = None,
         executor: str | None = None,
@@ -191,6 +194,7 @@ class TaskLifecycleService:
             execution_context,
             allow_spec_file_modifications=allow_spec_file_modifications,
             allow_unchecked_specs=allow_unchecked_specs,
+            allow_missing_evidence=allow_missing_evidence,
         )
         prepared = self._prepare_transition(
             stage, task_dir, preflight, executor=executor, takeover=takeover
@@ -590,6 +594,7 @@ class TaskLifecycleService:
                     execution_policy.allow_spec_file_modifications
                 ),
                 allow_unchecked_specs=execution_policy.allow_unchecked_specs,
+                allow_missing_evidence=execution_policy.allow_missing_evidence,
                 execution_policy=execution_policy,
             )
         else:
@@ -678,6 +683,13 @@ class TaskLifecycleService:
                 meta["specCheckSummary"] = dict(
                     spec_report.get("summary") or {}
                 )
+                if getattr(check_result, "evidence_exemption", None):
+                    meta["evidenceExempt"] = {
+                        "at": datetime.now(timezone.utc).strftime(
+                            "%Y-%m-%dT%H:%M:%SZ"
+                        ),
+                        **check_result.evidence_exemption,
+                    }
                 if (
                     execution_policy is not None
                     and execution_policy.allow_unchecked_specs

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

@@ -17,7 +17,7 @@ would make the digest self-referential).
 
 | Host | Transport | Shape |
 |---|---|---|
-| zcode | process hook shim (`inject-context.js`) → `inject.py --host zcode`, stdout JSON | `hookSpecificOutput.{hookEventName, additionalContext}` |
+| zcode | process hook shim (`inject-context.mjs`) → `inject.py --host zcode`, stdout JSON | `hookSpecificOutput.{hookEventName, additionalContext}` |
 | codex | thin wrapper (`inject-workflow-state.py`) → `inject.py --host codex`, stdout JSON | same shape |
 | claude-code | thin wrapper (`inject-workflow-state.py`) → `inject.py --host claude-code`, stdout JSON | same shape |
 | opencode | plugin `experimental.chat.system.transform` + `shell.env` | system-prompt section push / env object |
@@ -233,6 +233,7 @@ means without re-reading the file:
 <decision-anchor task=".cowork-flow/tasks/08-28-demo">
 Goal: <first goal line, max 160 chars>
 Acceptance: AC-001 <text, max 80>; AC-002 <...>   (first 8 items)
+AC evidence: <with evidence>/<total>[ missing=<id,...>, max 5]
 Rejected: <rejected option name>; ...             (first 6 names)
 </decision-anchor>
 ```
@@ -240,9 +241,10 @@ Rejected: <rejected option name>; ...             (first 6 names)
 - Extracted from `decision-anchor.md` with the line-level parser frozen in
   `services/fact_view.py` (`parse_decision_anchor`); the zcode and opencode JS
   lines carry an identical parser shape.
-- Missing anchor file, no extractable essentials, or terminal statuses
-  (`completed`) inject nothing.
-
+- The `AC evidence:` row appears only for tasks that declare AC rows, right
+  after the `Acceptance:` row, and renders byte-identically across the
+  python / zcode-shim / opencode lines (matrix-locked). Schema and gate
+  semantics live in `evidence-completion.md`.
 - Missing anchor file, no extractable essentials, or terminal statuses
   (`completed`) inject nothing.
 

package/template/.cowork-flow/spec/contracts/decision-anchor.md

@@ -66,6 +66,7 @@
 ## Lifecycle Check 联动
 
 - `task next <dir> --run` 启动任务时的 preflight 检查 `decision-anchor.md` 非空，并要求 `## 目标` 和 `## 验收标准` 章节存在。
+- `## 验收标准` 行的勾选状态（`- [ ]` / `- [x]`）与证据记录（任务目录 `evidence.jsonl`）是完成门禁的事实源：存在未勾选 AC（`LIFECYCLE-AC-001`）或已声明 AC 缺证据（`LIFECYCLE-AC-002`）时完成被阻断。schema 与豁免见 `evidence-completion.md`。
 - `cowork-implement` 读取：见 .cowork-flow/spec/contracts/subagent-dispatch.md
 - `cowork-check` 读取：同上
 - `debug.jsonl` 引用：可选，偏差诊断时写入 anchor 锚点差异

package/template/.cowork-flow/spec/contracts/evidence-completion.md

@@ -0,0 +1,48 @@
+# Evidence Completion Contract
+
+**任务完成从"流程走完"升级为"证据齐全"：decision-anchor 的验收标准（AC）是机器可查询的事实，完成门禁校验每个 AC 的证据记录存在性。**
+
+机器只裁决存在性事实（AC 声明、勾选状态、证据条目有无）；一条证据是否真正证明对应 AC，由 review 判断。
+
+## 证据记录：`evidence.jsonl`
+
+任务目录下的追加式 JSONL 文件，由实现方（主会话或子代理）在实现过程中写入，runtime 只读：
+
+```json
+{"ac": "AC-001", "kind": "test", "ref": "tests/test_ac_evidence.py", "note": "覆盖计算三态断言", "recordedAt": "2026-10-06", "by": "cwf-cli-1004"}
+```
+
+| 字段 | 必填 | 含义 |
+|---|---|---|
+| `ac` | 是 | 对应的 AC id（`AC-xxx`，与 decision-anchor 一致） |
+| `kind` | 是 | `test`（自动化测试）、`command`（命令及退出码）、`manual`（手工验证记录） |
+| `ref` | 是 | 证据指向：测试文件/用例、命令、手工记录位置；非空字符串 |
+| `note` | 否 | 核心断言一句话 |
+| `recordedAt` | 否 | ISO 日期 |
+| `by` | 否 | 写入者会话/执行者标识 |
+
+坏行、缺字段、未知 `kind` 的记录被读取端跳过（与 context JSONL 容错一致），门禁只看有效记录。
+
+## 完成门禁
+
+`task next <dir> --run` 的完成动作在直接生命周期检查中追加两条稳定 code：
+
+| code | 触发事实 | 豁免 |
+|---|---|---|
+| `LIFECYCLE-AC-001` | 存在未勾选的 AC 行 | 无——完成工作本身，或勾选已完成的行 |
+| `LIFECYCLE-AC-002` | 存在已声明但无任何有效证据记录的 AC | `--allow-missing-evidence`（记入 task.json `meta.evidenceExempt`，含 `at` 与 `missing`） |
+
+- 两个 code 可同时出现；`--allow-missing-evidence` 只豁免 `LIFECYCLE-AC-002`。
+- **兼容路径**：decision-anchor 缺失或未声明任何 AC 行的任务（全部存量任务）不触发本门禁；ac_evidence 模块不可读时同样降级为不阻断。
+- 豁免留痕 `meta.evidenceExempt` 与 spec-check 的 `specCheckExempt` 同型：重试不累积，最新一次完成结果为准。
+
+## 注入与事实视图
+
+- decision-anchor 注入块：声明了 AC 的任务在 `Acceptance:` 行后追加一行 `AC evidence: <有证据数>/<总数>`，有缺失时附 ` missing=<id 逗号列表，最多 5 个>`；三线（Python / zcode shim / opencode 插件）逐字节同格式，由矩阵测试锁定。
+- `run state <task> --json` / MCP 事实视图：`evidenceCoverage: {total, withEvidence, missing[]}`；未声明 AC 时为 `null`。
+
+## 边界
+
+- runtime 不代写证据，不执行 AC 对应命令"代打"记录。
+- 不解析 AC 正文语义；`AC-xxx` 行的勾选框缺失时按未完成解析。
+- 本契约不改变 spec-check 语义；MCP 写工具仍默认拒绝（`fact-layer-access.md`）。

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

@@ -16,3 +16,4 @@
 - `decision-anchor.md`: 每个 task 的 `decision-anchor.md` schema——目标、验收标准、被拒方案与关键假设。
 - `error-output-as-data.md`: 外部错误输出按数据分析而非指令执行（`ERROR_OUTPUT_AS_DATA_V1`）。
 - `fact-layer-access.md`: 无注入 hook 的宿主与外部工具读取任务事实的通道（`FACT_LAYER_ACCESS_V1`）。
+- `evidence-completion.md`: 证据化完成——`evidence.jsonl` schema、`LIFECYCLE-AC-001/002` 完成门禁、`--allow-missing-evidence` 豁免留痕与注入覆盖行。

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

@@ -1,8 +1,16 @@
 # Spec Check 契约（规范挂命令）
 
-用户规范（`.cowork-flow/spec/` 下 `backend/`、`frontend/`、自建目录）可通过
-frontmatter 的 `checks:` 声明检查命令。机制只执行声明、不解析规范正文——
-规则变化 = 用户改同一个文件里的命令，天然同步。
+## 它做什么
+
+用户规范（`.cowork-flow/spec/` 下 `backend/`、`frontend/`、自建目录）可通过 frontmatter 的
+`checks:` 声明检查命令。机制只执行声明、不解析规范正文——规则变化 = 用户改同一个文件里的命令，天然同步。
+
+## 什么时候挂
+
+条款能用命令退出码判定时（lint / 测试 / 类型检查 / schema 校验）就值得挂 `checks:`。两条硬约束：
+
+- **声明的命令不存在 = `unchecked` = 阻断 `complete`**：挂之前先确认命令在当前仓库能跑通。
+- **edit-only 不是门禁**：`when: edit` 只是编辑期 best-effort 提示——Bash 直写绕过 PostToolUse、无编辑期快跑能力的宿主（见附录 A）都收不到这层反馈，收口期也不补跑；需要硬门禁的检查必须声明 `when: lifecycle` 或默认 `both`。
 
 ## 语法
 
@@ -19,17 +27,12 @@ checks:
 # 规范正文（机制不读）
 ```
 
-- `files` 只支持两种形式：目录前缀（`src/`，以 `/` 结尾或自动补齐）与
-  扩展名（`*.ts`）。完整 glob 形态（`**`、`[]`）解析为错误，声明不执行，
-  doctor 报告——绝不回退为"匹配一切"。多值形态（如 `files: "src/", "lib/"`）
-  每个 token 按同样的引号规则去引号后生效。
-- `when: edit` 的声明在编辑期（PostToolUse）对命中 `files` 的改动文件
-  就地执行，超时被钳制到 2.5 秒（为解释器启动与 cmd 包装留 spawn 预算）；
-  慢命令请声明 `when: lifecycle`。
-- 引号规则：仅值整体为单对引号时去引号；`"python" -c "..."`
-  这类含多对引号的命令值原样保留，由执行器按 shell 规则拆分。
+- `files` 只支持两种形式：目录前缀（`src/`，以 `/` 结尾或自动补齐）与扩展名（`*.ts`）。完整 glob 形态（`**`、`[]`）解析为错误、声明不执行、doctor 报告——绝不回退为"匹配一切"；多值（`files: "src/", "lib/"`）每个 token 按同一引号规则去引号后生效。
+- 引号规则：仅值整体为单对引号时去引号；`"python" -c "..."` 这类含多对引号的命令值原样保留，由执行器按 shell 规则拆分。
+- `when: edit` 在编辑期（PostToolUse）对命中 `files` 的改动文件就地执行，超时被钳制到 2.5 秒（为解释器启动与 cmd 包装留 spawn 预算）；慢命令请声明 `when: lifecycle`。
+- **文件必须 UTF-8 无 BOM**：BOM 开头的 frontmatter 会被解析器静默忽略（声明数 0、无解析错误）——声明无声失效。挂完声明请跑一次 `spec-check` 确认被解析。
 
-## 三态结果（完成门禁语义）
+## 三态与门禁
 
 | 状态 | 含义 | complete 门禁 |
 | --- | --- | --- |
@@ -37,58 +40,26 @@ checks:
 | `violation` | 退出码非 0 | **阻断**（状态不推进） |
 | `unchecked` | 命令不存在/解释器缺失/超时 | **阻断**；显式 `--allow-unchecked` 可放行，豁免留痕进 task.json `meta.specCheckExempt` |
 
-unchecked 永不冒充 pass（"没跑成"不是"通过"）。frontmatter 畸形视该
-spec 为无检查并进 doctor 报告，不炸流程。
-
-解析失败是独立于三态之外的信号：`files` 形态非法等声明解析错误归入
-`parseErrors`，不折进 `pass`/`unchecked`，退出码与 `unchecked` 同为 2。
-文本模式与 `--json` 必须使用同一退出码，且文本模式必须打印解析错误行
-（`spec-check: N parse error(s): <spec>: <error>`）——只打印
-`0 passed, 0 violations, 0 unchecked` 会让畸形声明看起来像干净通过。
-
-退出码契约：`0` 全部 pass；`1` 存在 violation；`2` 存在 unchecked 或
-`parseErrors`。`--allow-unchecked` 只豁免 unchecked 的阻断，不豁免
-解析错误。
-
-## 时机与单行输出
-
-- **编辑期**（zcode/claude）：违规输出单行
-  `spec-check[<spec>] violation: <首个违规行>`；同一文件 10 秒内只报一次
-  （节流状态在 `.cowork-flow/.runtime/spec-edit-throttle.json`，检查完整
-  跑过才写节流——执行器崩溃不消费时间窗，重试仍会执行）；执行器
-  缺失或超时静默，绝不阻断编辑流。delegated 子代理会话同样收到 spec
-  违规反馈（子代理是主力写码者）；scope 警告保持 main-only。zcode 主
-  会话的 hook 身份（对话自身 session id）不会被绑定——激活发生在 Bash
-  侧显式身份下——显示与编辑期警告按最新主会话兜底；claude/codex 保持
-  严格会话身份（其 Bash env 携带同一 session id）。zcode 经
-  shim 转发到单源入口（`inject.py`），scope 警告与 spec 警告合并进同一个
-  additionalContext 载荷；claude 走 exit 2 stderr 反馈。
-- **收口期**（task complete）：全量执行，结果进 `meta.specCheckSummary`
-  遥测；阻断消息只列未过项摘要。
-- 手动查询：`./.cowork-flow/run spec-check [--file <path>] [--json]
-  [--verbose]`（退出码见上）。
-- **edit-only 是 best-effort 提示，不是门禁**：Bash 直写绕过 PostToolUse
-  不会触发编辑期反馈；无编辑期快跑能力的宿主（见能力矩阵）同样没有
-  这层提示，且收口期不会对 `when: edit` 声明补跑。需要硬门禁的检查
-  必须声明 `when: lifecycle` 或默认 `both`。
-- **开放决策**：收口期全量执行没有聚合预算——声明多且慢的仓库 complete
-  会线性变慢；是否给收口加并行/预算上限留给后续产品决策，当前保持
-  简单串行。
-
-## 归属与 sync 策略
-
-- **`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 不触碰，声明随规范正文一起由使用方维护。
-
-## 宿主能力矩阵
+unchecked 永不冒充 pass（"没跑成"不是"通过"）；frontmatter 畸形视该 spec 为无检查并进 doctor 报告，不炸流程。解析失败是独立于三态之外的信号：`files` 形态非法等声明解析错误归入 `parseErrors`，不折进 `pass`/`unchecked`，退出码与 `unchecked` 同为 2。文本模式与 `--json` 必须使用同一退出码，且文本模式必须打印解析错误行（`spec-check: N parse error(s): <spec>: <error>`）——只打印 `0 passed, 0 violations, 0 unchecked` 会让畸形声明看起来像干净通过。
+
+退出码契约：`0` 全部 pass；`1` 存在 violation；`2` 存在 unchecked 或 `parseErrors`。`--allow-unchecked` 只豁免 unchecked 的阻断，不豁免解析错误。
+
+**零声明是合法状态，但必须显式可见**：仓库无任何生效声明时退出码为 `0`，文本模式输出独立事实行 `spec-check: no checks declared (<N> spec files scanned)`，与"有声明且全过"的 `spec-check: <n> passed, 0 violations, 0 unchecked` 可区分；`--json` 顶层含 `specFiles`、summary 含 `declarations`。零声明 ≠ 干净通过——它意味着规范链上当前没有可机检约束，是需要被看见的事实，而不是可冒充通过的绿色。
+
+## 时机与输出
+
+- **编辑期**（PostToolUse）：仅 `when: edit`/`both` 且改动命中 `files` 时执行，违规输出单行 `spec-check[<spec>] violation: <首个违规行>`；执行器缺失或超时静默，绝不阻断编辑流。宿主差异与节流细节见附录 A。
+- **收口期**（task complete）：全量执行，结果进 `meta.specCheckSummary` 遥测；阻断消息只列未过项摘要。
+- **手动查询**：`./.cowork-flow/run spec-check [--file <path>] [--json] [--verbose]`（退出码见上）。
+
+## 声明归使用方维护
+
+- **模板不预置声明**：模板自带的 spec 文件不含生效的 `checks:` 声明——模板无法预知项目命令，而命令缺失会归 `unchecked` 并阻断 `complete`。请把声明写进自建 spec 文件（如 `spec/team-xxx.md` 或自建子目录），sync 不触碰，声明随规范正文一起由使用方维护。
+- **sync 保护前缀与具名例外**：`spec/` 整体是 sync 保护前缀，已存在的 spec 文件不会被 `sync` 覆盖（模板里 spec 的更新只对 `init` 新装生效）；唯一具名例外是 `spec/contracts/` 下列入 `spec/runtime/host-assets.json` `syncPolicy.safeFiles` 的条目（本文件与 `workflow-state-templates.md`），它们随 sync 更新，使契约修正能到达已安装项目。
+- **识别并挂声明是主会话 AI 的职责**：声明归项目所有。review / 规范维护时，主会话 AI 负责识别可机检条款并补 `checks:` 声明（条款正文不擅自改——发现条款与实现冲突时按 review 流程提出，由用户决策）；仅主会话写入 spec，delegated 子代理只上报候选、不越 scope。完整职责见 `task-review` 与 `spec-sync` Skill。
+- **质量纪律四条**：① 在干净树上跑出 `pass`；② 用一个反例证明该检查确实能报错（不是恒过的装饰）；③ 用 `files` 限定适用范围；④ 挂后跑一次 `spec-check` 确认声明被解析（防 BOM / `files` 形态错误静默失效）；并在 review 报告列出「条款 → 命令」清单。
+
+## 附录 A 宿主能力矩阵
 
 | 宿主 | digest 注入 | 编辑期快跑 | 收口强制 |
 | --- | --- | --- | --- |
@@ -102,27 +73,23 @@ spec 为无检查并进 doctor 报告，不炸流程。
 
 zcode / codex / claude-code 经 Python 单源共享 `run_edit_checks`；opencode 在插件内以 CLI 拉取同一执行器（`run spec-check --phase edit --throttled`），dsh 经预设插件的 `tools/post-execute` 调同一 Python 协议，qoder 经插件 hook 的 `PostToolUse` 调同一执行器（该事件在 Qoder 不可阻断，告警以 `additionalContext` 随 exit 0 返回，而非 claude-code/codex 的 stderr + exit 2）——具备编辑期快跑的六家共享同一节流状态与三态语义，不各自实现检查逻辑；kimi-code 只走收口强制与子代理自查。
 
-**delegated 子代理编辑期缺口（zcode 实测，2026-09-09 两轮）**：ZCode 的插件
-hook 只在主会话工具流上派发（事件模型七事件均挂主会话；子代理是独立内部
-会话流 `sess_subagent_agent_*`），Agent 子代理的 Edit/Write 收不到
-`spec-check[...] violation` 行——runtime 绑定与检查逻辑均正常，缺的是宿主
-派发。补偿机制（subagent-dispatch.md 契约固化）：
+编辑期节流：同一文件 10 秒内只报一次；节流状态在 `.cowork-flow/.runtime/spec-edit-throttle.json`，检查完整跑过才写节流——执行器崩溃不消费时间窗，重试仍会执行。delegated 子代理会话同样收到 spec 违规反馈（子代理是主力写码者）；scope 警告保持 main-only。zcode 主会话的 hook 身份（对话自身 session id）不会被绑定——激活发生在 Bash 侧显式身份下——显示与编辑期警告按最新主会话兜底；claude/codex 保持严格会话身份（其 Bash env 携带同一 session id）。zcode 经 shim 转发到单源入口（`inject.py`），scope 警告与 spec 警告合并进同一个 additionalContext 载荷；claude 走 exit 2 stderr 反馈。
+
+## 附录 B delegated 编辑期缺口与补偿
 
-1. 子代理完成前自查：`./.cowork-flow/run spec-check` 全量并修复（拉取路径，
-   实测有效）；
+**delegated 子代理编辑期缺口（zcode 实测，2026-09-09 两轮）**：ZCode 的插件 hook 只在主会话工具流上派发（事件模型七事件均挂主会话；子代理是独立内部会话流 `sess_subagent_agent_*`），Agent 子代理的 Edit/Write 收不到 `spec-check[...] violation` 行——runtime 绑定与检查逻辑均正常，缺的是宿主派发。补偿机制（subagent-dispatch.md 契约固化）：
+
+1. 子代理完成前自查：`./.cowork-flow/run spec-check` 全量并修复（拉取路径，实测有效）；
 2. 父会话验收前再查：violation 视为验收阻塞（反馈时点从收口提前到返回）；
 3. 实现类任务 Verify 命令默认含 spec-check 自查；
 4. 收口硬门禁兜底不变（violation 阻断 complete）。
 
-治理方向：向宿主提需求扩展子代理工具流的 hook 派发；落地后第 1 条自动
-退化为冗余保险。
+治理方向：向宿主提需求扩展子代理工具流的 hook 派发；落地后第 1 条自动退化为冗余保险。
+
+## 附录 C digest 注入
+
+进入 in_progress 后，stage-contract 的 Specs 行升级为 `Specs: <spec>(<h2 标题树>); …`：最多 6 个 h2 条目、每条截断 24 字符、剔除 `();` 字符；文件缺失不加注解。digest 是条目名索引不是正文，受 scope-rules.json `stageContract.budget` 硬顶，超预算整行让位（Scope/Gates 行永不丢）。python/zcode 输出同源于单一 Python 入口，opencode 镜像与它逐字相等由 matrix 用例锁定（`test/stage-contract.test.js` matrix）。
 
-## digest 注入
+## 附录 D 开放决策
 
-进入 in_progress 后，stage-contract 的 Specs 行升级为
-`Specs: <spec>(<h2 标题树>); …`：最多 6 个 h2 条目、每条截断 24 字符、剔除
-`();` 字符；文件缺失不加注解。digest 是条目名索引不是正文，受
-scope-rules.json `stageContract.budget` 硬顶，超预算整行让位
-（Scope/Gates 行永不丢）。python/zcode 输出同源于单一 Python 入口，
-opencode 镜像与它逐字相等由 matrix 用例锁定
-（`test/stage-contract.test.js` matrix）。
+**收口期聚合预算**：收口期全量执行没有聚合预算——声明多且慢的仓库 complete 会线性变慢；是否给收口加并行/预算上限留给后续产品决策，当前保持简单串行。

package/template/.cowork-flow/spec/runtime/contract-registry.json

@@ -115,6 +115,19 @@
         "when changing task start readiness",
         "when changing resume context for active tasks"
       ]
+    },
+    {
+      "id": "SPEC_CHECKS_V1",
+      "path": ".cowork-flow/spec/contracts/spec-checks.md",
+      "digest": [
+        "Specs may declare `checks:` commands in frontmatter; the mechanism runs declarations, never prose.",
+        "A declared command that cannot be found counts as unchecked and blocks completion."
+      ],
+      "readWhen": [
+        "before adding or editing spec files",
+        "when a spec clause can be judged by a command exit code",
+        "when spec-check reports violations or unchecked"
+      ]
     }
   ],
   "references": [