cowork-flow 1.7.3 → 1.8.0

package/CHANGELOG.md

@@ -5,6 +5,13 @@
 ### Added
 
 
+## [1.8.0] - 2026-10-08
+
+### Added
+
+- **spec-check 采纳闭环（1.8.x 主线）**：让 spec-check 机制从"存在但沉默"变为可遵循。① 零声明可见性：仓库无生效声明时 `spec-check` 文本模式输出显式事实行 `spec-check: no checks declared (<N> spec files scanned)`（与"有声明且全过"可区分），`--json` 顶层新增 `specFiles`、summary 新增 `declarations`——"没挂声明"不再与"干净通过"同形（零声明保持退出码 0：不挂命令是合法状态，但必须被看见）。② 注入契约 `SPEC_CHECKS_V1`：`contract-registry.json` 新增第 10 条（digest 2 条 + readWhen 3 条），python/zcode/opencode 三线渲染在 digest 块输出 `- SPEC_CHECKS_V1: .cowork-flow/spec/contracts/spec-checks.md`。③ `spec-checks.md` 重排为使用者核心区（何时挂 / 语法含 UTF-8 无 BOM 注意点 / 三态与门禁含零声明语义 / 时机与输出 / 归属）+ 维护者附录（宿主能力矩阵 / delegated 缺口与补偿 / digest 注入 / 开放决策），零信息丢失由独立复核逐项清点确认。④ AI 挂命令职责三处一致：契约归属段、`task-review`（User specs 逐条问"可机检吗、已挂吗" + `user_spec_review` 列「条款 → 命令」清单）、`spec-sync`（同次维护挂/刷新声明）；质量纪律四条（干净树跑出 pass / 反例能报错 / `files` 限定 / 挂后跑 spec-check 确认解析）获测试锁（`test_review_contract.py` markers）。不新增硬门禁——放权语义：主会话 AI 主动挂声明，review 报告留痕。
+- **证据化完成（1.8.0 主线）**：任务完成从"流程走完"升级为"证据齐全"。decision-anchor 的验收标准（AC）成为机器可查询事实——`services/ac_evidence.py` 解析 `## 验收标准` 的勾选状态并读取任务目录 `evidence.jsonl`（追加式，`{ac, kind: test|command|manual, ref, note?, recordedAt, by}`）；完成动作新增两条稳定门禁 code：存在未勾选 AC 阻断（`LIFECYCLE-AC-001`）、已声明 AC 缺有效证据记录阻断（`LIFECYCLE-AC-002`），新旗标 `--allow-missing-evidence` 豁免后者并把 `meta.evidenceExempt`（含 `at` 与 `missing`）留在任务记录；decision-anchor 注入块在 `Acceptance:` 行后追加 `AC evidence: n/m`（缺失时附 `missing=` 列表），三线（Python / zcode shim / opencode 插件）逐字节同格式并由矩阵测试锁定；`run state --json` 与 MCP 事实视图新增 `evidenceCoverage`。无 AC 的存量任务零影响（兼容路径有测试锁定），契约见 `.cowork-flow/spec/contracts/evidence-completion.md`。
+
 ## [1.7.3] - 2026-10-06
 
 ### Fixed
@@ -289,7 +296,8 @@
 
 此版本未保留本地条目正文，详情见 [GitHub Release](https://github.com/fishlikewater/cowork-flow/releases/tag/v0.0.47)。
 
-[Unreleased]: https://github.com/fishlikewater/cowork-flow/compare/v1.7.3...HEAD
+[Unreleased]: https://github.com/fishlikewater/cowork-flow/compare/v1.8.0...HEAD
+[1.8.0]: https://github.com/fishlikewater/cowork-flow/compare/v1.7.3...v1.8.0
 [1.7.3]: https://github.com/fishlikewater/cowork-flow/compare/v1.7.2...v1.7.3
 [1.7.2]: https://github.com/fishlikewater/cowork-flow/compare/v1.7.1...v1.7.2
 [1.7.1]: https://github.com/fishlikewater/cowork-flow/compare/v1.7.0...v1.7.1

package/docs/direction.md

@@ -17,6 +17,9 @@
 | 1.5→1.7 宿主广度 + 发布链（七宿主） | ✅ 完成 | CHANGELOG 1.5.0-1.7.2 | — |
 | 1.7.3 维护：ZCode shim .mjs + 项目根查找修复 | ✅ 完成 | 10-04-zcode-shim-mjs（d0716a9） | — |
 | 1.8.0 立项：证据化完成 | 🔄 立项完成，待启动 | 10-05-direction-1-8-0 / 10-05-evidence-completion | 在宿主会话启动主线任务 |
+| 1.8.0 主线实现：证据化完成 | ✅ 完成 | 10-05-evidence-completion（baa386d，CI test + windows-core 全绿） | 真实宿主冒烟后发布 1.8.0 |
+| 1.8.x 收尾：Skill 证据补课 | 🔄 进行中 | 10-06-skill-evidence-training | 合入后与冒烟共同构成 1.8.0 发布判据 |
+| 1.9.0 前置：task adopt 命令 | 📋 立项 | 10-06-task-adopt-command | 下一会话实现（agent-teams 就绪的地基） |
 
 **当前结论**：方向路线图阶段 0-3 全部落地。项目当前形态：「多主机 Agent 协作的运行时上下文与协作事实层」——事实视图（CLI + MCP）、结构化注入、跨宿主一致性治理、执行者归属与证据位均已就绪并有测试锁定。后续演进见「不做什么」边界与观察期事项。
 
@@ -156,6 +159,14 @@
 
 5. **采用**：npm 周下载与激活项目数——1.8.0 之后用数字验证"深度路线"是否兑现。
 
+### 10.5 2026-10-06 增补：1.8.x 收尾与 1.9.0 排期
+
+- **1.8.0 主线已实现**（10-05-evidence-completion，baa386d）：AC 事实化、`evidence.jsonl`、完成门禁 `LIFECYCLE-AC-001/002`、三线注入覆盖行、`evidenceCoverage` 事实视图；主线任务自身以新门禁完成（四 AC 证据齐全，无豁免）。
+- **1.8.0 发布判据**：CI 双平台（已绿）+ 真实宿主冒烟（维护者：带 AC 任务在 ZCode/Qoder 实跑一轮，观察覆盖行与门禁体验）+ Skill 证据补课合入。
+- **1.9.0 主线候选：agent-teams 就绪**，按 10.3 排期；前置小任务 = **task adopt 命令**（孤儿任务收养：显式重绑执行者 + 陈旧基线降级 + 审计留痕）。需求证据：2026-10-06 归档两个滞留任务时，takeover 只重绑执行者，陈旧基线需手改 task.json meta 才能走降级归档——该操作目前无运行时命令承载。10.5 增补时立项（10-06-task-adopt-command），设计注意"基线永不覆盖"不变量与显式收养语义的边界。
+- **Skill 证据补课**（10-06-skill-evidence-training）：1.8.0 只改了运行时与契约，教 agent 写证据的目前只有门禁报错文案；task-review 等 Skill 正文需补 evidence.jsonl 约定。
+- **维持**：文档英文化待维护者拍板（与 AGENTS.md 文档语言约定冲突）；缓行清单不变。**观察项**：1.8.0 的机器可解析 AC 是与 Spec Kit / OpenSpec 互操作的第一块砖（spec 制品 ↔ decision-anchor 映射），符合"SDD 工具之下的状态层"定位，待 agent-teams 排期落定后议。
+
 ## 11. 修订记录
 
 - 2026-08-27：创建。基于三路只读探查（注入层/状态模型/治理层）+ 大模型趋势分析；用户拍板方案 A；落库任务 08-27-direction-doc。
@@ -165,3 +176,4 @@
 - 2026-08-29：阶段 3 完成并更新状态追踪——路线图阶段 0-3 全部落地。`run mcp-state` 无依赖 MCP stdio 只读服务（task_state / task_list）、`spec/contracts/fact-layer-access.md` 接入契约（只读保证 + 薄 adapter 立场）（a88474e）。观察期事项：AGNTCY 等跨 agent 协议收敛后按薄壳接入；MCP 写工具默认拒绝，提案须先重开 fact-layer-access 契约。
 - 2026-08-29：MCP 全局入口补充——npm CLI 新增 `cowork-flow mcp-state` 透传命令（cwd 向上定位项目运行时、stdio inherit、退出码透传），MCP 客户端全局注册一次即可服务所有项目，消除逐项目 `.mcp.json` 配置（9a1fa86）。
 - 2026-08-29：后续方向 P0-P3 执行完毕。**P0**：1.1.0 发布——dev→master 合并、CHANGELOG 1.1.0 段（含 1.0.0 载体错位注明）、tag v1.1.0 与 GitHub Release 创建；publish CI 首跑曝光 node:full 存量问题（dsh-hook 依赖 gitignored 运行时、Windows 无法 exec shebang 脚本、test runner IPC 崩溃）并全部修复——双平台门禁现已全绿。**发布确认：npm registry `cowork-flow@1.1.0` 已上线（dist-tag latest），AC-004 闭合，发版任务归档。** **P1**：`docs/mcp-client-setup.md`（codex/opencode/claude-code/zcode 真实注册格式）+ `test/mcp-client-matrix.test.js` 客户端等效启动验证。**P1'**：publish.yml 链路实测核对并写入 README 发布节。**P2**：flaky 组合复跑 5 轮未复现（记录为单次现象）；doctor 会话卫生无残留。**P3**：观察期边界维持——MCP 写工具默认拒绝，AGNTCY 等协议收敛后按薄壳接入。- 2026-10-05：2026-10 修订落库（任务 10-05-direction-1-8-0）。1.7.3 维护完成（10-04-zcode-shim-mjs，d0716a9：ZCode shim 改 .mjs、findWorkflowRoot off-by-one 修复）；1.8.0 主线定为**证据化完成**，主线任务 10-05-evidence-completion 立项（planning 就绪待启动）；候选 B（agent-teams 就绪）列为 1.9.0 候选主线；文档英文化列为待决项，待维护者拍板。方向文档自本次起恢复版本控制（087ef72 untrack 后首次入库）。
+- 2026-10-06：10.5 增补落库（任务 10-06-direction-post-1-8-0）。1.8.0 主线实现完成（10-05-evidence-completion，baa386d，CI 双平台全绿）；立项 10-06-skill-evidence-training（1.8.0 收尾）与 10-06-task-adopt-command（1.9.0 前置）；1.8.0 发布判据 = CI + 真实宿主冒烟 + Skill 补课。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "1.7.3",
+  "version": "1.8.0",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "keywords": [
     "ai-agent",

package/presets/claude-code/.claude-plugin/plugin.json

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

package/presets/codex/.codex-plugin/plugin.json

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

package/presets/kimi-code/.kimi-plugin/plugin.json

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

package/presets/opencode/cowork-flow/plugin-core.js

@@ -574,8 +574,14 @@ function parseDecisionAnchor(text) {
     if (section === "目标") {
       if (line) goalLines.push(line)
     } else if (section === "验收标准") {
-      const match = raw.match(/^\s*-\s*\[[ xX]?\]\s*(AC-[A-Za-z0-9-]+)\s*[:：]\s*(.+?)\s*$/)
-      if (match) result.acceptanceCriteria.push({ id: match[1], text: match[2] })
+      const match = raw.match(/^\s*-\s*(?:\[([ xX])\]?\s*)?(AC-[A-Za-z0-9-]+)\s*[:：]\s*(.+?)\s*$/)
+      if (match) {
+        result.acceptanceCriteria.push({
+          id: match[2],
+          text: match[3],
+          checked: match[1] === 'x' || match[1] === 'X',
+        })
+      }
     } else if (section === "被拒方案") {
       const match = raw.match(/^\s*-\s*\*\*(.+?)\*\*/)
       if (match) result.rejectedOptions.push(match[1].trim())
@@ -836,6 +842,36 @@ function withStageFacts(block, root, taskPath, status, readonly = false) {
   return parts.length > 0 ? `${parts.join("\n\n")}\n\n${block}` : block
 }
 
+// Evidence coverage for the anchor block: one read of the task's
+// evidence.jsonl, tolerating noise exactly like the python line. Returns
+// null when the file is absent so the coverage line degrades silently.
+function readEvidenceCoverage(root, taskPath) {
+  let text = ''
+  try {
+    text = readFileSync(resolve(root, taskPath, 'evidence.jsonl'), 'utf8')
+  } catch {
+    return null
+  }
+  const covered = new Set()
+  for (const raw of text.split('\n')) {
+    const line = raw.trim()
+    if (!line) continue
+    let record
+    try {
+      record = JSON.parse(line)
+    } catch {
+      continue
+    }
+    if (!record || typeof record !== 'object' || Array.isArray(record)) continue
+    const ac = typeof record.ac === 'string' ? record.ac.trim() : ''
+    const ref = typeof record.ref === 'string' ? record.ref.trim() : ''
+    if (ac && ref && ['test', 'command', 'manual'].includes(record.kind)) {
+      covered.add(ac)
+    }
+  }
+  return covered
+}
+
 function decisionAnchorBlock(root, taskPath, status) {
   if (!taskPath) {
     return null
@@ -868,6 +904,17 @@ function decisionAnchorBlock(root, taskPath, status) {
     lines.push(
       `Acceptance: ${parsed.acceptanceCriteria.slice(0, 8).map((item) => `${item.id} ${item.text.slice(0, 80)}`).join("; ")}`
     )
+    const covered = readEvidenceCoverage(root, taskPath)
+    if (covered) {
+      const total = parsed.acceptanceCriteria.length
+      const missing = parsed.acceptanceCriteria
+        .map((item) => item.id)
+        .filter((id) => !covered.has(id))
+      const detail = missing.length
+        ? ` missing=${missing.slice(0, 5).join(',')}`
+        : ''
+      lines.push(`AC evidence: ${total - missing.length}/${total}${detail}`)
+    }
   }
   if (parsed.rejectedOptions.length > 0) {
     lines.push(`Rejected: ${parsed.rejectedOptions.slice(0, 6).join("; ")}`)
@@ -1073,5 +1120,6 @@ export {
   runEditSpecCheck,
   contractFingerprint,
   stableStringify,
-  stageContractBlock
+  stageContractBlock,
+  decisionAnchorBlock
 }

package/presets/qoder/.qoder-plugin/plugin.json

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

package/presets/zcode/.zcode-plugin/plugin.json

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

package/template/.cowork-flow/.version

@@ -1 +1 @@
-1.7.3
+1.8.0

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

@@ -108,13 +108,22 @@ def _print_text_report(report: dict, *, verbose: bool) -> None:
         print(_parse_error_line(parse_errors))
         return
 
+    summary = report.get("summary", {})
+    if not parse_errors and summary.get("declarations") == 0:
+        # Zero declarations is a fact, not a pass: name it so a missing or
+        # silently ignored declaration block cannot look like a clean run.
+        print(
+            "spec-check: no checks declared "
+            f"({report.get('specFiles', 0)} spec files scanned)"
+        )
+        return
+
     from services.spec_check import normalized_one_line
 
     line = normalized_one_line(report)
     if line:
         print(line)
         return
-    summary = report.get("summary", {})
     print(
         "spec-check: {pass} passed, {violation} violations, "
         "{unchecked} unchecked".format(

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

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

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

@@ -86,6 +86,7 @@ def _add_next_output_options(parser: argparse.ArgumentParser) -> None:
     )
     parser.add_argument(
         "--allow-unchecked",
+        "--allow-missing-evidence",
         dest="allow_unchecked",
         action="store_true",
         help="With task completion: allow unchecked spec-check commands "

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

@@ -382,12 +382,33 @@ def _decision_anchor_block(
             for item in parsed["acceptanceCriteria"][:8]
         )
         lines.append(f"Acceptance: {items}")
+        coverage = _acceptance_evidence_coverage(root, task_path)
+        if coverage:
+            detail = ""
+            if coverage["missing"]:
+                detail = f" missing={','.join(coverage['missing'][:5])}"
+            lines.append(
+                f"AC evidence: {coverage['withEvidence']}/{coverage['total']}{detail}"
+            )
     if parsed["rejectedOptions"]:
         lines.append("Rejected: " + "; ".join(parsed["rejectedOptions"][:6]))
     lines.append("</decision-anchor>")
     return "\n".join(lines)
 
 
+def _acceptance_evidence_coverage(root: Path, task_path: str | None):
+    """AC evidence coverage facts for the anchor block; a supplementary fact
+    that degrades to absence on any failure instead of degrading injection."""
+    if not task_path:
+        return None
+    try:
+        from services.ac_evidence import coverage_summary
+
+        return coverage_summary(root / task_path)
+    except Exception:
+        return None
+
+
 def _stage_contract_block(
     root: Path, task_path: str | None, status: str
 ) -> str | None:

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

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Acceptance-criteria evidence facts for task completion.
+
+Single read entry for the completion gate, the fact view, and injection:
+which AC ids the decision anchor declares, which are checked, and which
+have at least one evidence record in the task's evidence.jsonl. Judgment
+about whether a record really proves an AC stays with review; the machine
+only decides existence facts.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from services.fact_view import parse_decision_anchor
+
+EVIDENCE_FILE = "evidence.jsonl"
+EVIDENCE_KINDS = ("test", "command", "manual")
+
+
+def read_decision_anchor(task_dir: Path) -> str | None:
+    path = Path(task_dir) / "decision-anchor.md"
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+    return text or None
+
+
+def load_acceptance_criteria(task_dir: Path) -> list[dict[str, Any]]:
+    """AC rows (id / text / checked) declared by the task's decision anchor.
+
+    Empty list when the anchor is missing or declares no AC rows — the
+    compatibility path that keeps pre-existing tasks exempt from the gate."""
+    text = read_decision_anchor(task_dir)
+    if not text:
+        return []
+    return list(parse_decision_anchor(text)["acceptanceCriteria"])
+
+
+def read_evidence(task_dir: Path) -> list[dict[str, Any]]:
+    """Valid evidence records appended by the implementer.
+
+    Bad lines and malformed records are skipped, never fatal: the gate
+    blocks on missing coverage, not on file noise."""
+    path = Path(task_dir) / EVIDENCE_FILE
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return []
+    records: list[dict[str, Any]] = []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            record = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(record, dict) and _valid_record(record):
+            records.append(record)
+    return records
+
+
+def _valid_record(record: dict[str, Any]) -> bool:
+    ac = record.get("ac")
+    ref = record.get("ref")
+    kind = record.get("kind")
+    return (
+        isinstance(ac, str)
+        and bool(ac.strip())
+        and isinstance(ref, str)
+        and bool(ref.strip())
+        and kind in EVIDENCE_KINDS
+    )
+
+
+def evidence_coverage(
+    acceptance: list[dict[str, Any]],
+    evidence: list[dict[str, Any]],
+) -> dict[str, Any]:
+    """Coverage facts over declared AC ids: total, covered, missing ids."""
+    covered = {
+        record["ac"].strip()
+        for record in evidence
+    }
+    ids = [item["id"] for item in acceptance]
+    missing = [ac_id for ac_id in ids if ac_id not in covered]
+    return {
+        "total": len(ids),
+        "withEvidence": len(ids) - len(missing),
+        "missing": missing,
+    }
+
+
+def coverage_summary(task_dir: Path) -> dict[str, Any] | None:
+    """End-to-end coverage facts for one task.
+
+    None when the task declares no acceptance criteria — consumers treat
+    that as "gate not applicable" instead of a fake zero."""
+    acceptance = load_acceptance_criteria(task_dir)
+    if not acceptance:
+        return None
+    return evidence_coverage(acceptance, read_evidence(task_dir))

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

@@ -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": [

package/template/.opencode/cowork-flow/plugin-core.js

@@ -574,8 +574,14 @@ function parseDecisionAnchor(text) {
     if (section === "目标") {
       if (line) goalLines.push(line)
     } else if (section === "验收标准") {
-      const match = raw.match(/^\s*-\s*\[[ xX]?\]\s*(AC-[A-Za-z0-9-]+)\s*[:：]\s*(.+?)\s*$/)
-      if (match) result.acceptanceCriteria.push({ id: match[1], text: match[2] })
+      const match = raw.match(/^\s*-\s*(?:\[([ xX])\]?\s*)?(AC-[A-Za-z0-9-]+)\s*[:：]\s*(.+?)\s*$/)
+      if (match) {
+        result.acceptanceCriteria.push({
+          id: match[2],
+          text: match[3],
+          checked: match[1] === 'x' || match[1] === 'X',
+        })
+      }
     } else if (section === "被拒方案") {
       const match = raw.match(/^\s*-\s*\*\*(.+?)\*\*/)
       if (match) result.rejectedOptions.push(match[1].trim())
@@ -836,6 +842,36 @@ function withStageFacts(block, root, taskPath, status, readonly = false) {
   return parts.length > 0 ? `${parts.join("\n\n")}\n\n${block}` : block
 }
 
+// Evidence coverage for the anchor block: one read of the task's
+// evidence.jsonl, tolerating noise exactly like the python line. Returns
+// null when the file is absent so the coverage line degrades silently.
+function readEvidenceCoverage(root, taskPath) {
+  let text = ''
+  try {
+    text = readFileSync(resolve(root, taskPath, 'evidence.jsonl'), 'utf8')
+  } catch {
+    return null
+  }
+  const covered = new Set()
+  for (const raw of text.split('\n')) {
+    const line = raw.trim()
+    if (!line) continue
+    let record
+    try {
+      record = JSON.parse(line)
+    } catch {
+      continue
+    }
+    if (!record || typeof record !== 'object' || Array.isArray(record)) continue
+    const ac = typeof record.ac === 'string' ? record.ac.trim() : ''
+    const ref = typeof record.ref === 'string' ? record.ref.trim() : ''
+    if (ac && ref && ['test', 'command', 'manual'].includes(record.kind)) {
+      covered.add(ac)
+    }
+  }
+  return covered
+}
+
 function decisionAnchorBlock(root, taskPath, status) {
   if (!taskPath) {
     return null
@@ -868,6 +904,17 @@ function decisionAnchorBlock(root, taskPath, status) {
     lines.push(
       `Acceptance: ${parsed.acceptanceCriteria.slice(0, 8).map((item) => `${item.id} ${item.text.slice(0, 80)}`).join("; ")}`
     )
+    const covered = readEvidenceCoverage(root, taskPath)
+    if (covered) {
+      const total = parsed.acceptanceCriteria.length
+      const missing = parsed.acceptanceCriteria
+        .map((item) => item.id)
+        .filter((id) => !covered.has(id))
+      const detail = missing.length
+        ? ` missing=${missing.slice(0, 5).join(',')}`
+        : ''
+      lines.push(`AC evidence: ${total - missing.length}/${total}${detail}`)
+    }
   }
   if (parsed.rejectedOptions.length > 0) {
     lines.push(`Rejected: ${parsed.rejectedOptions.slice(0, 6).join("; ")}`)
@@ -1073,5 +1120,6 @@ export {
   runEditSpecCheck,
   contractFingerprint,
   stableStringify,
-  stageContractBlock
+  stageContractBlock,
+  decisionAnchorBlock
 }

package/template/skills/spec-sync/SKILL.md

@@ -33,6 +33,7 @@ Keep each update concrete:
 - Show the contract or command shape.
 - Include good/bad cases when useful.
 - State tests or checks that protect the behavior.
+- When a clause is machine-checkable (可机检), add or refresh its `checks:` declaration in the same pass (main session only — never rewrite the clause text): the command must pass on a clean tree, a negative case must prove it can fail, `files` must narrow the scope, and a `spec-check` run after writing must confirm the declaration parses.
 - Update the matching `index.md` when adding a new topic.
 - Check for duplicate guidance and remove stale wording before finishing.
 

package/template/skills/task-review/SKILL.md

@@ -37,7 +37,8 @@ Read only what is needed for the current task:
 - **Scope**: every changed file is planned or justified; no unrelated cleanup sneaks in.
 - **Behavior**: acceptance criteria are satisfied through observable behavior, not implementation-shaped assertions.
 - **Tests**: test intent is explicit; tests fail for meaningful regressions, reject shallow tests such as existence/mock/snapshot-only checks, and cover boundary/error paths when relevant.
-- **User specs**: every applicable backend/frontend requirement is verified against the diff and marked `pass`, `finding`, or `not_applicable` with reason. Every `finding` is fixed during review; an unfixed spec violation blocks completion and is never accepted as-is or deferred to the user.
+- **Evidence coverage**: when the decision anchor declares acceptance criteria (`AC-xxx`), verify each one has an evidence record in `<task>/evidence.jsonl` — or a recorded `meta.evidenceExempt` exemption from an explicit `--allow-missing-evidence` completion. Schema and gate codes (`LIFECYCLE-AC-001/002`) are defined in `.cowork-flow/spec/contracts/evidence-completion.md`. A record must point at real proof (test, command output, or manual verification note); a record that restates the AC without evidence is a finding.
+- **User specs**: every applicable backend/frontend requirement is verified against the diff and marked `pass`, `finding`, or `not_applicable` with reason. Every `finding` is fixed during review; an unfixed spec violation blocks completion and is never accepted as-is or deferred to the user. For each requirement, also ask whether it is machine-checkable (可机检) and already declared with `checks:`; identifying checkable clauses and adding or refreshing declarations is a main-session duty (never rewrite the clause text — raise a conflict through the review instead), and a declared check must earn its place: the command passes on a clean tree, a negative case proves it can fail, `files` narrows the scope, and a `spec-check` run after declaring confirms the declaration parses. Delegated subagents do not edit specs; they report candidates up.
 - **Specs**: project specs are updated when behavior/contracts changed, or the review states why no spec update is needed.
 - **Code quality**: naming, layering, error handling, state boundaries, security-sensitive paths, and complexity are reviewed against applicable user specs.
 - **Lifecycle blockers**: state/scope blockers are fixed before acceptance; review does not invent hard blockers for natural-language specs.
@@ -61,7 +62,7 @@ Return a concise review result with:
 - `status`: `pass`, `needs_fix`, or `blocked`.
 - `findings`: severity, file, line/scope, impact, and fix.
 - `test_intent_review`: why tests prove the intended behavior or what is missing.
-- `user_spec_review`: applicable spec files, per-requirement result, and findings.
+- `user_spec_review`: applicable spec files, per-requirement result, findings, and the "clause → command" list for every `checks:` declaration added or refreshed in this review (`none` when nothing became machine-checkable).
 - `lifecycle_check_review`: lifecycle commands run, blocker status, and resolution.
 - `verification`: exact commands run from this checkout.
 - `specUpdates`: files updated or reason no update was needed.

package/template/skills/test-first/SKILL.md

@@ -39,6 +39,10 @@ If red-first is skipped, state the reason before or with the implementation summ
 
 Do not write TDD evidence objects to `check.jsonl`, do not create `tdd.jsonl`, and do not create TDD exemption records. Report the exact red/green commands in the agent response or task review narrative when useful; the workflow does not validate them as separate evidence artifacts.
 
+## Evidence records
+
+When the task's decision anchor declares acceptance criteria, a green test from a red-green cycle is the canonical completion evidence for the mapped AC: append one record to the task's `evidence.jsonl` — `{"ac": "AC-xxx", "kind": "test", "ref": "<test file>::<case>", "note": "<core assertion>", "recordedAt": "<date>", "by": "<session>"}`. This is task-level completion evidence governed by `.cowork-flow/spec/contracts/evidence-completion.md`; it is a different artifact from the forbidden `tdd.jsonl` above, and this skill still does not require or validate it — recording it as you go simply spares the completion gate a block later.
+
 ## Anti-Rationalization
 
 Do not use these excuses to skip meaningful behavior tests: