merge: feature/coordination-db-daemon-impl-plan-2026-09-23 (undertaking plan docs)

2026-09-23 14:16:36 +08:00
parent 1f2f3d6a58 dad5556181
commit 51f82d5d4f
4 changed files with 268 additions and 0 deletions
@@ -18,6 +18,7 @@

 | owner | task | branch | worktree | mutex | status |
 |---|---|---|---|---|---|
+| Cursor | coordination-db-daemon-impl-plan-2026-09-23 | feature/coordination-db-daemon-impl-plan-2026-09-23 | .worktrees/coordination-db-daemon-impl-plan-2026-09-23 | coordination-db-daemon-impl-plan | in_progress |
 | Cursor | coordination-db-daemon-2026-09-23 | feature/coordination-db-daemon-2026-09-23 | .worktrees/coordination-db-daemon-2026-09-23 | coordination-db-daemon | done |
 | Cursor | integrate-pi-runner-response-size-r2-2026-09-23 | feature/integrate-pi-runner-response-size-2026-09-23 | .worktrees/integrate-pi-runner-response-size-2026-09-23 | git:dev | done |
 | Cursor | modular-decouple-residual-b-2026-09-23 | feature/modular-decouple-residual-2026-09-23 | .worktrees/modular-decouple-residual-2026-09-23 | modular-decouple-residual | done |
@@ -0,0 +1,66 @@
+---
+title: "协调库与 daemon：实施承接计划落地"
+task_id: coordination-db-daemon-impl-plan-2026-09-23
+status: in_progress
+created: 2026-09-23
+updated: 2026-09-23
+owner: Cursor
+task_type: research
+task_tier: multi_stage
+policy_revision: "agent-governance-2026-09-21-r1 @ 1f2f3d6a58d153e6a7809943d2f3383b9c620085"
+branch: feature/coordination-db-daemon-impl-plan-2026-09-23
+worktree: .worktrees/coordination-db-daemon-impl-plan-2026-09-23
+base_dev_sha: "1f2f3d6a58d153e6a7809943d2f3383b9c620085"
+write_scope: [".doc"]
+allowed_environments: []
+head_sha: ""
+mutex: coordination-db-daemon-impl-plan
+review_state: pending
+integration_state: pending
+deployment: not_required
+cleanup: pending
+cleanup_owner: "独立维护者"
+cleanup_trigger: "合入 local_dev 且无进程占用后复查"
+remote_sync: not_requested
+---
+
+# 协调库与 daemon：实施承接计划落地
+
+## 用户目标与授权
+
+- 用户目标：为协调库/daemon 设计方案制定可直接开工的实施承接计划（工作包预填）。
+- 授权：docs-only；不实施 U1r–U6 代码；不 push。
+- 交付终点：承接计划 + 本任务文 + INDEX；合入 local_dev。
+- 禁止：装载 daemon、改 FEATURE-MATRIX 状态值、跨机实施、晋升 test/main。
+
+## 范围与非目标
+
+- 允许写入：`.doc`（remediation / ops/short-term / INDEX / CURRENT 本人行）。
+- 非目标：七包代码实施（各包另立 short-term 并满足承接计划开工准入）。
+
+## 步骤与验收
+
+1. [x] 创建 worktree 并登记 — `base_dev_sha=1f2f3d6a…`
+2. [x] CURRENT 认领 — `docs apply` request `…-claim-1`
+3. [x] 写承接计划 — [2026-09-23-coordination-db-daemon-implementation-undertaking-plan.md](../../remediation/2026-09-23-coordination-db-daemon-implementation-undertaking-plan.md)
+4. [ ] 更新 remediation INDEX
+5. [ ] docs-only 验收（链接/锚点抽查/frontmatter）
+6. [ ] 候选 validate + integrate
+
+## 验证与证据
+
+| 范围 / 被测 SHA | 命令与环境 | 预期 | 实际 / 判定 | 证据 |
+|---|---|---|---|---|
+| 承接计划文档 | 相对链接 + 锚点行号抽查 | 可解析；`SHARED_DOCS`/Lease/recover/docs_project 行号匹配 | pending | 合入前脚本 |
+| 设计方案回链 | INDEX + 正文链接 | 指向既有 plan/research | pending | |
+
+## 收口与交接
+
+- 剩余：INDEX、验收、集成、cleanup。
+- deployment=not_required；remote_sync=not_requested。
+
+## 相关链接
+
+- [实施承接计划](../../remediation/2026-09-23-coordination-db-daemon-implementation-undertaking-plan.md)
+- [设计方案](../../remediation/2026-09-23-coordination-db-daemon-plan.md)
+- [研究](../research/2026-09-23-coordination-db-daemon-research.md)
@@ -0,0 +1,200 @@
+---
+title: "协调库与 daemon · 实施承接计划（工作包预填）"
+status: planned
+created: 2026-09-23
+updated: 2026-09-23
+owner: Cursor
+task_id: coordination-db-daemon-impl-plan-2026-09-23
+task_type: research
+task_tier: multi_stage
+policy_revision: "agent-governance-2026-09-21-r1 @ 1f2f3d6a58d153e6a7809943d2f3383b9c620085"
+branch: feature/coordination-db-daemon-impl-plan-2026-09-23
+worktree: .worktrees/coordination-db-daemon-impl-plan-2026-09-23
+base_dev_sha: "1f2f3d6a58d153e6a7809943d2f3383b9c620085"
+write_scope: [".doc"]
+allowed_environments: []
+mutex: coordination-db-daemon-impl-plan
+review_state: pending
+integration_state: pending
+deployment: not_required
+cleanup: pending
+cleanup_owner: "独立维护者"
+remote_sync: not_requested
+---
+
+# 协调库与 daemon · 实施承接计划（工作包预填）
+
+## 1. 目的、输入依赖与非目标
+
+### 1.1 目的
+
+为 [协调库与 daemon 方案](./2026-09-23-coordination-db-daemon-plan.md) 的 L1 七单元提供**可直接开工的承接框架**：三波次门禁、七个工作包预填登记（符号级锚点 + 真实并发验收）、防重复施工、开工准入、集成与收口分项。每包另立 short-term 实施时复制本表字段，不得缺项编码。
+
+### 1.2 输入依赖（本机均可见）
+
+| 输入 | 路径 | 状态 |
+|---|---|---|
+| 设计方案 | [./2026-09-23-coordination-db-daemon-plan.md](./2026-09-23-coordination-db-daemon-plan.md) | planned；已合入 local_dev |
+| 研究依据 | [../ops/research/2026-09-23-coordination-db-daemon-research.md](../ops/research/2026-09-23-coordination-db-daemon-research.md) | done（调研可审） |
+| 既有锁方案 | [./2026-09-21-agent-lock-coordination-plan.md](./2026-09-21-agent-lock-coordination-plan.md) | planned；本机 SQLite 权威 |
+| 操作规范 | [../ops/2026-09-21-agent-worktree-workflow.md](../ops/2026-09-21-agent-worktree-workflow.md) | active |
+| 验证契约 | [../ops/2026-09-21-validation-contract.md](../ops/2026-09-21-validation-contract.md) | active；本批适用「治理脚本」行 |
+| 平台深化 HA 边界 | [./2026-09-23-platform-deepening-reliability-ha-concurrency-plan.md](./2026-09-23-platform-deepening-reliability-ha-concurrency-plan.md) §0 | 单宿主机；跨机需 ADR |
+
+### 1.3 非目标
+
+- 本文件**不实施** U1r–U6 任何代码、不装载 launchd/systemd、不改 FEATURE-MATRIX 状态值。
+- L2 跨机 PostgreSQL / 中央 daemon **不入波次**；无 ADR + 二次授权不得开跨机代码。
+- 不把 L1 宣称为 OS 沙箱；协调不依赖产品容器；不接触业务数据库。
+- 不 push、不操作 test/main（除非另获授权）。
+
+## 2. 已落地基线盘点（本机实测）
+
+编制日：**2026-09-23**。基线 tip：`1f2f3d6a58d153e6a7809943d2f3383b9c620085`（本任务 `base_dev_sha`；各包开工时以当时 `dev` tip 重测）。
+
+| 检查项 | 依据 | 结果 |
+|---|---|---|
+| queue 子解析器重复注册 | 合入 `63e66c6fb35d6b4dd9f3ed92e15acc9933aeb344` | **已修复**；`scripts/agentctl.py` 仅一处 `add_parser('queue')`（`:1613`） |
+| 权威库 | `.locks/state.sqlite` | 11 表；scope/lease/CAS/收据/候选准入/`--ff-only` 已 enforced（相对受控入口） |
+| queue/jobs 行数 | 活库采样 | `queue_items`/`jobs` 仍可为 0（运维闭环待用）；parser 已可用 |
+| 策略 YAML | `configs/agent-governance.yaml` | **不存在** |
+| automation 分叉 | `scripts/agentctl_automation.py` | 零导入；schema 含活库无的 `operations`/`doc_registry` |
+| 常驻服务 | `*.service` / `*.plist` / compose 协调服务 | **0 个** |
+| FEATURE-MATRIX 治理行 | 「Agent worktree 治理自动化」 | `partial`；W4 landed；仍 deferred：PI 源码镜像、跨机隔离、automation/w4 收敛 |
+| CURRENT 矛盾 | `:5` vs `:15` | macOS 租约可用/不可用并存；操作规范 `:3` 仍写「Linux 本机」 |
+
+**含义**：方案 U1 的 queue 缺陷已落地；剩余工作包默认 `incremental` 或 `net_new`（有检索证据），禁止重复施工覆盖已 PASS 的 L1/W4 证据。
+
+## 3. 波次 → 门禁表
+
+```mermaid
+flowchart LR
+  subgraph W1 [W1 认领与策略基础]
+    U1R[U1r automation归一]
+    U2[U2 governance.yaml]
+    U3[U3 长期claim]
+  end
+  subgraph W2 [W2 执行代理与CURRENT]
+    U7[U7 quarantine交接]
+    U4[U4 常驻入口]
+    U5[U5 CURRENT投影]
+  end
+  subgraph W3 [W3 矩阵迁移]
+    U6[U6 MATRIX record id]
+  end
+  U2 --> U4
+  U3 --> U4
+  U3 --> U5
+  U4 --> U5
+  U5 --> U6
+  U7 --> U4
+```
+
+| 波次 | 包 | 准入 | 完成判据 | 验证契约适用行 |
+|---|---|---|---|---|
+| W1 | U1r, U2, U3 | 本承接计划已合入；mutex 无冲突 | 三包各自 short-term 验收 PASS 并合入 | 治理脚本 |
+| W2 | U7, U4, U5 | W1-U2/U3 done；U7 可与 U4 并行编码 | daemon 单实例 + CURRENT 投影 PASS；操作规范/CURRENT 矛盾已修正 | 治理脚本；涉文档追加纯文档核对 |
+| W3 | U6 | W2-U5 done | MATRIX 稳定 ID + done 证据门禁不回退 | 治理脚本 + 纯文档 |
+
+编码/隔离测试可并行（mutex 不重叠）；**dev 集成串行**（`git:dev`）。
+
+## 4. 工作包登记表（全部预填）
+
+### 4.1 必填字段约定
+
+| 字段 | 要求 |
+|---|---|
+| `wp_id` | 唯一；与 short-term `task_id` 可映射 |
+| `phase` | W1 / W2 / W3 |
+| `relation_to_baseline` | `incremental` / `regression_gate` / `net_new`（须检索证据） |
+| `code_anchors` | 文件路径 + 符号；禁止只写包名 |
+| `deps` | 依赖 `wp_id` / 已合入 tip / ADR |
+| `mutex` | 与 CURRENT 认领一致 |
+| `write_scope` | 允许写路径 |
+| `test_scenarios` | Given/When/Then；临时 Git 仓库真实并发/拒绝；stub/SKIP 不算 PASS |
+| `rollback` | 单批 revert；迁移 additive |
+
+### 4.2 登记表
+
+| wp_id | phase | title | relation_to_baseline | code_anchors | deps | mutex | write_scope | test_scenarios | rollback |
+|---|---|---|---|---|---|---|---|---|---|
+| **W1-U1r** | W1 | automation 归一与 state.db 清理 | `incremental`（MATRIX 已记 deferred automation/w4 收敛） | `scripts/agentctl_automation.py`（整文件）；活库无 `operations`/`doc_registry`；`.locks/state.db`（0 字节孤儿，代码无引用） | queue 修复 tip `63e66c6f` | `agentctl-automation-converge` | `scripts` | (1) `rg` 无导入引用后删除或合并到 `agentctl_w4`；(2) `unittest discover` 全绿；(3) 确认无代码引用后清理运行态 `state.db`（不入 Git） | 单批 revert；若已删文件则恢复提交 |
+| **W1-U2** | W1 | 治理策略外部化 | `net_new`（检索：`configs/` 无 `agent-governance.yaml`） | `scripts/agentctl.py:27` `SHARED_DOCS`；`scripts/agentctl_w4.py:64` `JOB_KINDS`；`:75` `PROJECTABLE_DOCS`；`:80` `PROJECTABLE_PREFIXES`；新建 `configs/agent-governance.yaml` | — | `agent-governance-config` | `scripts`, `configs` | 临时仓库：(1) 策略缺失拒写；(2) YAML 损坏拒写；(3) protocol 版本过低拒写；(4) 合法加载后 `docs apply`/`with` 行为不变 | revert 配置+加载代码；硬编码常量可作紧急回退 |
+| **W1-U3** | W1 | 显式长期认领 claim | `incremental`（基于既有 scope/lease） | `scripts/agentctl.py:553` `check_resources`；`:589` `class Lease`；`tasks`/`freezes`/`runs` 表；新 claim 表或等价资源键 | W1-U2 建议先合入（策略版本字段） | `agentctl-claim` | `scripts` | (1) 20 并发抢同一 claim 仅 1 成功；(2) 不同资源并行均成功；(3) 目录/子文件父子重叠冲突；(4) 冻结资源拒写；(5) 重复 `request_id` 幂等；(6) 冲突返回持有者+票据+`retry_after` | additive schema；revert 代码；旧客户端无 claim 列时 fail-closed |
+| **W2-U7** | W2 | quarantine 与安全交接 | `regression_gate`（`recover` 已有三值存活） | `scripts/agentctl.py:993` `recover`；进程层 `alive_status`/`group_status`/`descent_status`；`runs.generation` | —（可与 W1 并行编码） | `agentctl-handoff` | `scripts` | (1) 杀 supervisor 留子进程不得误抢；(2) `unknown` 不回收；(3) TTL/心跳过期只进 suspect/quarantine；(4) 旧 generation renew/write/release 全拒；(5) env/git 未知结果须核验收据 | 单批 revert；不削弱既有 recover 负例 |
+| **W2-U4** | W2 | 常驻协调入口 | `net_new`（检索：仓库 0 个 service/plist） | 新 `deploy/agentctl/` 或 `scripts/systemd/`+`scripts/launchd/` 模板；`.locks/os/manager.lock`（锁方案 §3.1 规划、今日不存在）；复用 `queue schedule` `:1245`、投影路径 | **W1-U2 done**；**W1-U3 done**；**W2-U7** 建议先合入 | `agentctl-daemon` | `scripts`, `deploy`（若放单元模板） | (1) 双实例争 `manager.lock` 仅一存活；(2) daemon 停后受保护写入 fail-closed（非放行）；(3) 前台 CLI 语义不变；(4) daemon 不新增权限（无 register 能力不可越权） | 卸下单元模板；删除 manager.lock 争用代码可 revert；不自动装载本机 |
+| **W2-U5** | W2 | CURRENT 状态输出化 | `incremental`（`docs_project` 已有） | `scripts/agentctl.py:1308` `docs_project`；行模板约 `:1358-1362`；槽位保护 `:903-908`；`.doc/ops/CURRENT.md`；`.doc/ops/2026-09-21-agent-worktree-workflow.md:3` | **W1-U3 done**；**W2-U4** 建议先合入（投影调度） | `current-projection` | `scripts`, `.doc` | (1) 双任务并行投影不丢行；(2) 同行 CAS → `BASE_CHANGED`；(3) 槽位保护不回退；(4) 人工「焦点/受控约束」区块机器不写；(5) 修正 CURRENT `:5`/`:15` 与操作规范「Linux 本机」过时描述 | revert 投影代码+文档；保留人工段落 |
+| **W3-U6** | W3 | FEATURE-MATRIX 稳定 ID | `incremental` | `.doc/status/FEATURE-MATRIX.md` 完成度表约 `:52-78`（27 行）；`docs apply` done 门禁 `:922-928` | **W2-U5 done** | `matrix-record-id` | `scripts`, `.doc` | (1) 无证据升 `done` 被拒；(2) 未知列/历史段落保留；(3) 整文 rewrite 不能夹带 done；(4) 任务 close ≠ 自动升 done；(5) `production_ready` 仍只由发布门禁判定 | revert；记录 ID 映射表保留在 Git 便于回滚对照 |
+
+### 4.3 判定列（开工前填）
+
+每包 short-term 增加列：`判定` = `planned | in_progress | blocked | done | cancelled`。本承接计划合入时全部为 **planned**。
+
+## 5. 防重复施工前置检查
+
+每个工作包开工前，owner 在 short-term 勾选并留证据链接：
+
+1. [ ] 检索 [gap-matrix](./gap-matrix.md)：已有 PASS 覆盖同一缺陷 → 默认 `regression_gate`。
+2. [ ] 检索 FEATURE-MATRIX「Agent worktree 治理自动化」：W4 landed 项不得推倒重来；本包声明与 deferred 项的关系。
+3. [ ] 对照 [设计方案](./2026-09-23-coordination-db-daemon-plan.md) U1–U7：本包范围不越界到 L2。
+4. [ ] 声明 `relation_to_baseline`；`net_new` 列出检索路径（至少含 §4.2 锚点）。
+5. [ ] mutex / write_scope 与 CURRENT / `agentctl task register` 一致。
+6. [ ] 红线：无 ADR 不开跨机；不宣称 OS 沙箱；不碰业务库/产品容器协调。
+7. [ ] 验证契约「治理脚本」行：计划中的并发/拒绝路径均在临时真实 Git/SQLite 执行。
+
+任一项未勾 → 保持 `planned`/`blocked`，不得编码。
+
+## 6. 开工准入（硬条件）
+
+同时满足才可 `agentctl task register` 并编码：
+
+- 本承接计划已为当前 `dev` 祖先；
+- 该包 §4.2 必填字段齐全且 §5 全部勾选；
+- 依赖包（§4.2 `deps`）已 `done` 或显式允许并行；
+- 从**当时 `dev` 完整 SHA** 创建 `feature/<task-id>` / `fix/<task-id>`，不从他人 feature 派生；
+- L2 相关改动另有 ADR + 用户二次授权（本波次不应触发）。
+
+## 7. L2 ADR 前置门（不开工）
+
+跨机 + 独立 PostgreSQL + 中央 daemon + systemd（Linux 中央主机）**仅登记**：
+
+| 门禁 | 要求 |
+|---|---|
+| ADR | 覆盖锁方案 §3.2「跨机锁服务当前不采用」与平台深化 §0「跨机 HA 需先另立 ADR」 |
+| 用户授权 | 二次明确授权；范围/期限/退出条件写入 short-term |
+| 验收登记 | 双主机并发、断网、旧进程存活、重复 request_id、备份恢复——**待执行**，不得冒充已测 |
+
+无上述门禁 → 任何 PR/合入含跨机协调代码一律拒绝。
+
+## 8. 集成、部署与收口
+
+### 8.1 集成
+
+冻结 head → 候选 `merge --no-ff`（第一父 = expected_dev）→ `agentctl validate` → `agentctl integrate --expected-dev <SHA>`（`git:dev` 租约内 `--ff-only`）。CURRENT/MATRIX 变更走 `docs apply` 收据。
+
+### 8.2 部署判定
+
+| 变更 | `deployment` |
+|---|---|
+| 仅 `.doc` / 本承接计划 / 单元模板入库未装载 | `not_required` |
+| `scripts/agentctl*` 行为变更 | 临时仓库治理脚本验收即可；**不**要求产品容器 rebuild |
+| 本机装载 launchd/systemd（若另授权） | 本机装载演练记录；fail-closed 核验 |
+
+### 8.3 收口分项（每包必报）
+
+`review_state` / `integration_state` / `deployment` / `cleanup` / `remote_sync`（默认 `not_requested`）。
+
+## 9. 与本框架任务的关系
+
+- 本文件 `status=planned`：追踪「七包实施队列」，**不是**业务已开工。
+- 编制本框架的 short-term：[../ops/short-term/2026-09-23-coordination-db-daemon-impl-plan.md](../ops/short-term/2026-09-23-coordination-db-daemon-impl-plan.md)。
+- 设计方案保持 planned；各包落地时在方案 U 节回填合入 tip，不代填验收。
+
+## 10. 相关链接
+
+- [设计方案](./2026-09-23-coordination-db-daemon-plan.md)
+- [研究](../ops/research/2026-09-23-coordination-db-daemon-research.md)
+- [锁方案](./2026-09-21-agent-lock-coordination-plan.md)
+- [验证契约](../ops/2026-09-21-validation-contract.md)
+- [操作规范](../ops/2026-09-21-agent-worktree-workflow.md)
+- queue 修复 tip：`63e66c6fb35d6b4dd9f3ed92e15acc9933aeb344`
@@ -2,6 +2,7 @@

 | 文档 | 说明 |
 |------|------|
+| [2026-09-23-coordination-db-daemon-implementation-undertaking-plan.md](./2026-09-23-coordination-db-daemon-implementation-undertaking-plan.md) | 协调库与 daemon **实施承接计划**（工作包预填）：W1–W3 七包（U1r/U2/U3/U7/U4/U5/U6）含符号级锚点、真实并发验收、mutex、开工准入；L2 仅 ADR 前置门。配套 [设计方案](./2026-09-23-coordination-db-daemon-plan.md) · [任务](../ops/short-term/2026-09-23-coordination-db-daemon-impl-plan.md)。planned，不实施代码 |
 | [2026-09-23-coordination-db-daemon-plan.md](./2026-09-23-coordination-db-daemon-plan.md) | 协调库与 daemon 分阶段方案：L1 单宿主机（复用 `.locks/state.sqlite` + claim/常驻入口/文档状态化）；L2 跨机 PostgreSQL 仅 planned（需 ADR）。配套 [研究](../ops/research/2026-09-23-coordination-db-daemon-research.md) · [任务](../ops/short-term/2026-09-23-coordination-db-daemon.md)。U1 queue 子解析器已合入 `63e66c6f`；本文件 planned，不实施 daemon |
 | [2026-09-21-agent-lock-coordination-plan.md](./2026-09-21-agent-lock-coordination-plan.md) | Agent `.locks`、共享文档与并行工作流补充方案：本机 SQLite + 会话/租约/CAS；L1a–L1d 设计。配套 [研究](../ops/research/2026-09-21-agent-lock-coordination-research.md)。planned；跨机锁服务本期不采用 |
 | [2026-09-23-platform-deepening-reliability-ha-concurrency-plan.md](./2026-09-23-platform-deepening-reliability-ha-concurrency-plan.md) | 平台深度完善方案（解耦·通信·总线·可靠性·高可用·高并发）：基于 2026-09-23 四路只读调研，六轨 R1–R6 分批（server 收口/chat 解咬合/bizdev 上收/worker 韧性/并行消费/NOTIFY 唤醒/死信闭环/多副本前置去单点化/PG 本机热备/备份自动化/锁重构/长任务异步化/池调优/app metrics）。planned，不实施代码；HA 边界=单宿主机（用户确认） |