ECC 2.0 Progress Sync Contract：跨 GitHub、Linear、本地交接与仓库路线图的状态同步契约实践

本文以 docs/architecture/progress-sync-contract.md 为主线，系统讲解 ECC（Agent Harness 性能优化系统）在多执行面（GitHub、Linear、本地交接、仓库路线图）之间维护"进度状态单一可信"的契约设计与落地方式。读完本文，你将掌握 ECC 2.0 定义的四类真相来源（Sources of Truth）及其当前适用规则、八条流程泳道（Flow Lanes）、显著合并批次（Significant Merge Batch）后的状态更新协议，以及如何通过 scripts/work-items.js、scripts/status.js 等命令行工具与 SQLite 状态库打通"本地实时路径（Realtime Boundary）"，从而在不依赖任何托管遥测的情况下完成可审计、可交接、可发布守门的状态同步。

为什么需要一份进度同步契约

ECC 2.0 的日常执行分散在多个表面：GitHub 上的 PR/issue/discussion 是公开队列与评审状态，Linear 项目承载高层路线图与干系人状态更新，本地交接文件保证操作者连续性，仓库内路线图文档是规划的可审计镜像。任何一个表面单独"看起来最新"都不代表整体状态可信——只有在更新一条泳道（Lane）的进度之前，先满足契约规定的最小证据要求，这个状态更新才有资格声称"该泳道是当前的（current）"。

契约原文的定位非常明确：它定义的是在状态更新声称某条泳道"当前"之前必须存在的最小证据。换句话说，这份契约不是"如何写周报"，而是一套针对多执行面 Agent 进度跟踪的可验证边界。

四类真相来源：各自的角色与当前规则

契约用一张表规定了每个表面在整个系统中的职责边界。这张表是整套机制的地基，逐项展开如下：

Surface（表面）	Role（角色）	Current rule（当前规则）
GitHub PRs/issues/discussions	公开队列与评审状态	在每一次显著合并批次之前、以及发布审批之前，必须重新检查实时数量（Recheck live counts）
Linear project	高管路线图与干系人状态更新	因该工作区禁用了 project status updates，改用 project documents 与 project/issue comments；为持久执行泳道创建/复用 issue
Local handoff（本地交接）	持久的操作者连续性	每次合并批次、队列清空、跳过的发布门禁或受阻的外部动作之后，都要更新当前交接文件
Repo roadmap（仓库路线图）	可审计的规划镜像	保持 docs/ECC-2.0-GA-ROADMAP.md 与已合并 PR 证据、未解决门禁保持一致
scripts/work-items.js	本地跟踪桥	将 GitHub PR/issues 同步进 SQLite work-items 存储，用于状态快照与受阻后续跟进

可以从源码验证每条规则的具体含义：

• GitHub 实时复核在 scripts/work-items.js 的 syncGithubWorkItems 中实现：它通过 gh pr list --state open 与 gh issue list --state open 拉取当前开启的 PR/issue，再 upsert 进本地 store，并在同一批次里把已不在活动集合中的旧条目自动 close（closeStaleGithubItems），这就把"合并批次前必须拿到活计数"变成了一个可重复执行的本地命令。
• Repo roadmap 是"合并证据 + 未解门禁"的镜像：docs/ECC-2.0-GA-ROADMAP.md 开篇即声明自己是活跃 Linear 项目的持久镜像，并明确"实时执行真相"分散在 Linear 项目文档/issue 泳道/依赖/里程碑、本仓库文档、已合并 PR 证据、以及 ~/.cluster-swarm/handoffs/ 下的交接文件中，这说明 roadmap 只作为审计镜像、而非执行真相本身。

流程泳道：避免 ECC 工作坍缩成单一巨型积压

契约要求在仓库镜像中划分出八条流程泳道，避免所有工作坍缩成一个不可区分的积压（backlog）：

1. 队列卫生与过期工作抢救（Queue hygiene and stale-work salvage）
2. 发布、命名、插件发布与公告（Release, naming, plugin publication, and announcements）
3. Harness 适配合规（Harness adapter compliance）
4. 本地可观测性、HUD/状态与会话控制（Local observability, HUD/status, and session control）
5. Evaluator/RAG 与自我改进 harness 循环（Evaluator/RAG and self-improving harness loops）
6. AgentShield 企业安全平台
7. ECC Tools 计费、PR 风险检查、深度分析与 Linear 同步
8. 遗留工件审计与 translator/manual-review 收尾

契约对每条泳道提出了一个强约束：

每条流程泳道需要且仅需要：一个 owner artifact、一个当前证据来源、一个下一步动作（next action）。这三者任一缺失，该泳道即不处于 current 状态。

这一规则的价值在于把"看起来在推进"和"确实是当前的"分开——泳道是否 current 不再是主观感受，而是可判定的三字段完整性检查。与它遥相呼应的是本地工作项的"泳道/状态"模型：在 scripts/lib/control-pane/work-item-mutations.js 中，Kanban 看板的 ready/running/blocked/done 四条泳道被映射为 open/running/blocked/done 四个规范状态，任何 move 操作都只能走这四条合法泳道，任何 claim 都要求 owner 必须是 agent 或 human（VALID_ASSIGNEE_KINDS），从而在本地工作项层面同样保证"每项工作必须有归属与明确状态"。

显著合并批次后的更新协议

契约规定了在完成一次显著合并批次后，需要在 Linear 与交接文件中更新的五项最小内容：

1. 受跟踪 GitHub 仓库的当前公开队列计数（Current public queue counts）；
2. 已合并的 PR 编号、commit ID 与验证证据（Merged PR numbers, commit IDs, and validation evidence）；
3. 若发生变更，发布门禁的变更点（Changed release gates, if any）；
4. 被推迟或跳过的工作及其明确原因（Deferred or skipped work and the explicit reason）；
5. 接下来的一到两个实现切片（The next one or two implementation slices）。

第 1、2 项可直接借助本地工具产出，而不是靠人工在浏览器里数：执行一次 scripts/work-items.js 的 sync-github 子命令即可得到 Open PRs、Open issues、Closed stale items 三个计数，并以 --json 输出完整对象。从源码看，每个 GitHub 工作项拥有确定性的本地 ID 形态 github-<repo>-pr-<number> / github-<repo>-issue-<number>（见 githubWorkItemId，scripts/work-items.js），并携带 syncedBy: 'ecc-work-items-sync-github' 元数据标记，供后续的过期清理逻辑精确识别本次同步来源的条目。

第 4 项尤其重要——"被推迟/跳过的工作"必须带有显式原因，这是整个契约"证据驱动"哲学的最小体现，防止跳过动作在交接中变成无声损耗。

Linear 的使用纪律：证据优先于占位

契约专门处理了一个工作区约束：该 Linear workspace 禁用了 project status updates。因此在 ECC 2.0 的实际执行中，高层路线图状态改用 project document 加 project/issue comments 来表达，而不是试图去开启被禁用的能力。

同时契约划出了一条清晰的边界，防止系统被滥用：

• issue 容量（issue capacity）可用于持久的执行泳道（durable execution lanes）；
• 但不得用占位 issue 替代"有证据支撑的项目状态"（evidence-backed project status）；
• 仅当某条泳道需要一个持久执行 owner 时，才创建或复用精确同名（exact-title）的 issue，且必须把这些 issue 链接到仓库证据上。

这条纪律保证了：Linear 上的 issue 永远指向"确实有人/Agent 在推进的执行单元"，而不是充当状态面板的替代品。状态本身仍然来自合并 PR 证据与交接记录。

实时路径边界：文件优先、无托管遥测即可发布

契约最务实的部分莫过于 Realtime Boundary 的默认设计——本地实时路径默认由文件支撑（file-backed）：

# 将当前 GitHub PR/issue 状态导入 SQLite work-items 存储
node scripts/work-items.js sync-github --repo <owner/repo>

# 为 HUD、交接或后续 Linear 同步暴露本地状态
node scripts/status.js --json
node scripts/work-items.js list --json

关于第一条命令，源码对它的约束比文档更细：

• --repo <owner/repo> 在 sync-github 子命令下等价于 --github-repo <owner/repo>，二者均可指定目标仓库（scripts/work-items.js）；
• 该命令必须能够调用 gh CLI；为便于无 gh 的测试/CI 环境，它还支持通过环境变量 ECC_GH_SHIM 注入一个 node shim 来替代真实的 gh 可执行文件（scripts/work-items.js）；
• 同步逻辑会把开启的 PR 映射为 needs-review（若为 draft 或 mergeStateStatus === 'DIRTY' 则标记为 blocked 并提升优先级为 high），把开启的 issue 映射为 needs-review（scripts/work-items.js）；
• 每次同步后自动关闭"不再活跃"的旧条目，并记录 sourceClosedAt，使本地镜像不会无限累积僵尸任务。

sync-github 的完整可复现用法如下（更完整的选项清单见 scripts/work-items.js 的 help 输出）：

node scripts/work-items.js sync-github --repo affaan-m/ECC --json
# 输出包含 repo、syncedAt、prCount、issueCount、closedCount、items、closedItems

关于 SQLite 存储本身，可以从迁移脚本确认其结构。work_items 表由 schema migration 002_work_items 创建（scripts/lib/state-store/migrations.js），核心字段包括：

字段	说明
id	稳定本地工作项 ID，主键
source	来源系统，如 linear、github-pr、github-issue、handoff、manual
source_id	来源侧标识，如 ECC-20 或 PR 编号
title / status / priority	标题、状态（open/in-progress/blocked/done…）、优先级标签
url / owner / repo_root / session_id	来源 URL、owner 标签、关联仓库根路径、ECC 会话 ID
metadata	JSON 元数据，带 json_valid 检查约束
created_at / updated_at	创建与更新时间

表上还建立了 (status, updated_at DESC)、(source, source_id)、(session_id, updated_at DESC) 三组索引，分别服务于"按状态快照"、"按来源去重/查询"与"按会话回溯"三种典型访问模式。metadata 必须为合法 JSON，这保证了同步时写入的 repo、mergeStateStatus、labels、syncedBy 等扩展信息不会污染表结构——事件模型是稳定的，扩展全靠元数据列承载。

而 node scripts/status.js --json 侧（scripts/status.js）则把整份状态汇总成 HUD 可消费的视角：活跃会话、近期 skill 运行、安装健康、待处理治理事件与关联工作项。它还提供 --markdown（与 --json 二选一）、--write <path>（落盘）、以及 --exit-code（就绪度需要关注时退出码为 2）等选项，适合直接接入本地监控或交接流程。如果只需要某一项的完整细节，还可以用 node scripts/work-items.js show <id> --json 单独查看。

upsert、claim、close、move 这些本地变更逻辑并非各写一份：CLI 与 control-pane 本地看板服务器共用 scripts/lib/control-pane/work-item-mutations.js 中同一份 claimWorkItem / moveWorkItem / selectClaimTarget 实现（文件头注释明确写着"两个表面永不漂移"）。例如 claim 在未指定 ID 时会走 JIT 领取队列：自动挑选优先级最高且无人认领的 open 工作项（selectClaimTarget），然后把状态置为 running——这与契约中"泳道必须有 owner"的要求完全同构。

最后一点原则：Linear 仍是外部状态表面，但仓库不要求任何托管遥测即可达到可发布状态。像 PostHog 这样的托管遥测可以在未来接入，但它必须消费同一套事件模型，而不是演变成第二个真相来源（second source of truth）。也就是说，文件优先 + SQLite 本地镜像这条链路本身就是完整的、可独立工作的实时状态路径，外部遥测只是它的可选投影。

发布门禁：契约本身不能作为发布依据

契约在结尾给出了一个容易被忽略但极其重要的边界声明：

不得仅依据本契约就进行发布、打 tag、公告、提交 marketplace 包或宣称插件可用。发布就绪仍然要求：发布就绪性证据文档、新鲜的队列检查、包检查、插件检查，以及维护者的明确批准。

这实际上把"进度同步"与"发布守门"解耦了：进度契约只回答"各泳道状态是否当前且可交接"，而 release-ready 是一个需要独立证据链的更强主张。在执行上，"跳过某道发布门禁"这一动作本身就要回写本地交接（见真相来源表中 Local handoff 的 current rule），也就是说连"门禁被跳过"这个事实都必须进入状态系统，而不是悄悄消失。

把它串起来：一份典型的"合并批次后收尾"动作序列

综合契约全部章节，一次显著合并批次之后的状态收敛可以落到如下可执行动作（对应关系均为仓库内可验证路径）：

1. 执行 node scripts/work-items.js sync-github --repo <owner/repo>，把 GitHub 活计数与最新 PR/issue 状态刷进 SQLite work-items 存储（桥接 docs/architecture/progress-sync-contract.md 中的 GitHub + work-items.js 两行规则）；
2. 执行 node scripts/status.js --json（或 --markdown --write <path>）生成状态快照供 HUD/交接消费；
3. 核对八条流程泳道，逐条确认 owner artifact、当前证据来源、next action 三项齐全，缺失即先补齐再宣称 current；
4. 更新 docs/ECC-2.0-GA-ROADMAP.md，使其与已合并 PR 证据、未解决门禁一致（保持 roadmap 的可审计镜像属性）；
5. 在 Linear 中通过 project document / issue comments 记录五项更新内容（队列计数、合并证据、门禁变更、跳过项及原因、下一两个切片），绝不拿占位 issue 冒充证据状态；
6. 更新本地交接（~/.cluster-swarm/handoffs/），覆盖合并批次、队列清空、跳过的发布门禁或受阻外部动作；
7. 若要发布，则另行走发布就绪性证据 + 包/插件检查 + 维护者批准的独立守门流程，而非仅凭本契约放行。

这套动作把契约中分散在各小节的要求，压缩成一条可重复、可由 Agent 或人工执行的收尾路径。只要每一步的产物都能被上述 SQLite 表、roadmap 文档与交接文件记录并链接回仓库证据，"某条泳道是否 current"就始终是一个可审计、可判定的问题，而不是一个凭印象的断言。这正是 ECC 2.0 在多 harness、多表面协作场景下保持进度可信的核心工程实践。