diff --git a/.doc/ops/CURRENT.md b/.doc/ops/CURRENT.md index d45af241..c989103d 100644 --- a/.doc/ops/CURRENT.md +++ b/.doc/ops/CURRENT.md @@ -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 | diff --git a/.doc/ops/short-term/2026-09-23-coordination-db-daemon-impl-plan.md b/.doc/ops/short-term/2026-09-23-coordination-db-daemon-impl-plan.md new file mode 100644 index 00000000..d5c36561 --- /dev/null +++ b/.doc/ops/short-term/2026-09-23-coordination-db-daemon-impl-plan.md @@ -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) diff --git a/.doc/remediation/2026-09-23-coordination-db-daemon-implementation-undertaking-plan.md b/.doc/remediation/2026-09-23-coordination-db-daemon-implementation-undertaking-plan.md new file mode 100644 index 00000000..d7acb0ac --- /dev/null +++ b/.doc/remediation/2026-09-23-coordination-db-daemon-implementation-undertaking-plan.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/` / `fix/`，不从他人 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 `（`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` diff --git a/.doc/remediation/INDEX.md b/.doc/remediation/INDEX.md index 57df818b..1fe90ce8 100644 --- a/.doc/remediation/INDEX.md +++ b/.doc/remediation/INDEX.md @@ -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 边界=单宿主机（用户确认） |