diff --git a/docs/proposals/2026-10-14-merge-queue-manual-phase2-implementation-plan.md b/docs/proposals/2026-10-14-merge-queue-manual-phase2-implementation-plan.md new file mode 100644 index 0000000..ea4c247 --- /dev/null +++ b/docs/proposals/2026-10-14-merge-queue-manual-phase2-implementation-plan.md @@ -0,0 +1,113 @@ +# Dev main 第二轮 manual 合入调度实施与测试计划 + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 让第二轮三个已授权真实任务在同一人工窗口中按序完成最终同步、审核、CI 与智能体合入,同时把所有已知 Dev main 写入及失败退出记录在唯一调度 Issue;正常排队推进不使等待分支反复重跑最终 CI。 + +**Architecture:** 保留现有 Gitea 分支保护、三项 PR 检查和 `task-sync`;Dev `policy/` 仅说明项目采纳、写者覆盖、记录字段及停止条件。Issue #518 是动态窗口唯一来源,原任务卡保留授权与阶段结论。只读对账从实际 main PR/合入列表反查 #518 的先前领取与事后释放;无原子锁、无自动调度服务。 + +**Tech Stack:** Git/Gitea 1.27 API、Dev `make precheck`/`make evidence`/`make task-sync`、Markdown 规范与 JSON 收据、现有 `.gitea/workflows/ci.yaml`。 + +**Spec:** [已批准的阶段 4 设计](2026-10-14-merge-queue-manual-phase2.md),Documents PR #104(合入 `8e3b5b0d2838f89430683ec731a15b32b4fa5eae`);[首轮报告](../records/2026-10-14-merge-queue-trial.md)与 Dev #518 是历史与动态证据,不能以本计划代替实时回读。 + +## Global Constraints + +- 范围仅为 Dev 仓库 ID=29、`refs/heads/main`;普通、闭卡、紧急和机器人目标写入都纳入同一记录。组件仓按自身目标协调。 +- 第二轮样本为**随后实际就绪的三个已授权真实任务**;闭卡单列。#482、#512、#537 不因本计划自动取得接管或合入授权。 +- 现有 Gitea 保护、必需检查、CI workflow 和 runner 全局配置保持不变;最终 PR HEAD 的 `test`、`test-pg`、`svc-realcombo` 均须取得真实 GATE。 +- 采用单一协调者维护的 `manual` 窗口。Issue 编辑、评论、`content_version` 和本地锁都不是平台原子互斥;旧执行者未确认退出时不得接管。 +- 无进展 20 分钟、单窗口 90 分钟、已知基础设施失败最多额外重试一次、队列每 30 分钟复核;领取前当场核对 runner 容量。 +- 阶段 5–7 依 `policy/delivery.md` 分别取得人工结论;阶段 8–9 由智能体审阅、核验精确 HEAD 与平台准入并合入。阶段 5 批准不等于第二轮已启用。 +- 所有通过断言区分 GATE、REPLAY、SELF;本地输出经 `make evidence` 写入,固定后收据置于源码外;未知结果先读回,不盲目重复副作用请求。 + +## Review Focus + +1. **已知写者仍从另一入口推进 main:**任务 2 的对账应查到实际合入但缺先前领取,暂停新领取并标记受影响候选失效。 +2. **Issue 中只有事后补记:**任务 2 的对账应区分先前领取与事后释放;#539 不能被算作合格覆盖。 +3. **候选固定后内容或 base 变化:**任务 3 的核验应建立新尝试,并拒用旧 Review/CI;同基线重复 `task-sync` 应保持 HEAD 不变。 +4. **合入响应未知或协调者失联:**任务 3 应先回读 PR/main 并保持 `reconciling`,确认前执行者退出后才释放/交接。 +5. **没有三个已就绪任务:**任务 4 应保持 `waiting`,不接管 #482/#512 或制造生产 PR,不把缺样本写为通过。 + +| 设计验收 | 计划中的主要验证 | +|---|---| +| M2-1 | 任务 2 入队字段、任务 4 三个真实任务与等待期间最终 CI 清单 | +| M2-2 | 任务 2 的逐合入只读对账、任务 4 每次 main 推进后的覆盖核对 | +| M2-3 | 任务 3 的同基线无变更与变更后新尝试重放 | +| M2-4 | 任务 3 的精确 HEAD 三项 GATE/智能体合入、任务 4 的每任务对象记录 | +| M2-5 | 任务 4 对正常排队造成的最终 CI 废弃数和所有 CI 成本分类 | +| M2-6 | 任务 2/3 的异常决策表与任务 4 的自然退出/`NOT_RUN` 记录 | + +--- + +### Task 1: 固定实施范围与 Dev 规范入口(M2-1、M2-3) + +**Files:** +- Modify: Dev `policy/merge-queue.md` 的状态、项目调度记录、启动与同步、采纳顺序及验收表。 +- Modify: Dev `policy/adoption.md` 中合入调度采纳行。 +- Modify: Dev `policy/tool-adaptation-matrix.md` 的 A10/A11 行。 +- Read only: Dev `AGENTS.md`、`policy/delivery.md`、`policy/governance.md`、Guidelines 固定版 `standards/merge-queue.md`。 + +**Interfaces:** 仅细化已固定通用规范,不改 `task-sync`、`make evidence` 或 CI 接口。规范链接指向 Documents 阶段 4 设计和 #518;`policy/adoption.md` 区分“规范已合入”“第二轮待启用”“manual 能力”;A10 说明 Issue 协作与平台准入的不同强度。 + +- [ ] 在 Dev 当前 main 创建未占用收据路径,运行下列启动门禁并确认 READY;按输出读必读规范。新任务用同一收据建独立工作区,记录 R0 与写者归属;若任务已登记则在原 worktree 改用 `make task-resume PRECHECK_RECEIPT="$mq_receipt"`,不重复开卡。BUSY、SYNC_REQUIRED、REMOTE_UNVERIFIED 先排除。 + + ```bash + mq_receipt="/tmp/mq-phase2-stage6-precheck-$(date -u +%Y%m%dT%H%M%SZ)-$$.json" + RECEIPT="$mq_receipt" CMD='make precheck' make evidence + make task-start NAME=feature/merge-queue-manual-phase2 PRECHECK_RECEIPT="$mq_receipt" + ``` +- [ ] 对照当前 Dev main、Guidelines gitlink、#518 与已合入设计。把 `policy/merge-queue.md` 首轮“本轮三个任务待完成”“本分支”等已过期时态改为历史结果,把第二轮规则明确标为 `approved/pending-activation`,并逐项写明 `ready_at`、`queue_entered_at`、`attempt_id`、`initial_base_sha`、`source_head_sha`、`sync_base_sha`、`frozen_head_sha`、组件/检查定义、Review 与 GATE、实际合入/释放。动态值只在 #518,不复制静态队列表。 +- [ ] 在 `policy/adoption.md` 与 A10/A11 中指向同一设计及项目规则:保留首轮原始证据范围;第二轮标 `manual`、`pending-activation`,不可升级成 `enforced` 或声称自动互斥;现有源码外收据能力保持原样。 +- [ ] 检查 `AGENTS.md` 与 `policy/delivery.md` 对合入窗口及阶段 7–9 的指向。若现有入口已覆盖,只记录无需修改;若确有入口断链,按文档范围补链接并将变化列入 Review。 +- [ ] 运行 `git diff --check`、Markdown 相对链接检查和规则一致性检查:阶段 5 批准后尚未启用、缺写者覆盖时必须保持 waiting、三个必需检查没有删减。若动到治理脚本或任务卡模板,另运行 `CMD='make test-governance' make evidence`;纯文档不制造新脚本测试。 +- [ ] 将本单元源码与 SELF 检查收据写入原任务卡并提交;阶段 6 人工评审前不把 #518 标为第二轮 active。 + +### Task 2: 建立 #518 入队模板与只读覆盖对账(M2-1、M2-2、M2-6) + +**Files:** +- Modify: Dev `policy/merge-queue.md` 的记录示例、写者覆盖、异常与暂停规则。 +- Prepare then update after Stage 6 approval: Gitea Dev Issue #518 正文的第二轮入口与追加式评论模板;不建立第二份队列状态文件。 +- Save outside source: 每次只读 Gitea API 对账的原始脱敏 JSON/`make evidence` 收据;必要结论只引用对象和链接。 + +**Interfaces:** #518 条目至少包含 `entry_id`、目标、PR/任务卡、owner/协调者、授权与阶段版本、依赖、`queue_entered_at`、`ready_at`、状态;领取评论补 Task 1 的 attempt 字段;释放评论补实际 PR/main SHA、合入结果及 GATE 链接。`ready_at` 未知标 `NOT_MEASURED`,不足条件标 `blocked`。 + +- [ ] 只读查询 Dev 当前 main SHA、开放 PR、仓库协作者、可写工作区 owner、机器人/webhook/workflow 入口、#518 正文与评论,生成带观察时间和对象 SHA 的 SELF 清单;无法查到的写者类别标“未核验”,不推断不存在。 +- [ ] 在 Task 1 规范中给出普通、闭卡、紧急、机器人共同的入队/领取/释放字段,规定 `blocked` 不占窗口;跨仓组件未就绪不占 Dev 窗口。未知来源与旧执行者未退出必须暂停或 `reconciling`,不得靠 20 分钟超时接管。 +- [ ] 固定只读对账步骤:枚举观察区间内实际合入 Dev main 的 PR/merge SHA;逐个在 #518 找**合入前**同目标同 attempt 的领取和**合入后**释放;同时反查 Issue 中仍占用但 PR 已关闭/合入的窗口。分列“合格、仅事后补记、未找到、结果不明”,保留 API 原始响应与分页范围。 +- [ ] 用 [阶段 4 SELF 快照](../records/2026-10-14-manual-phase2-source-audit.json) 回放对账口径:#539 属“仅事后补记”,#540/#542 能找到领取/释放,其余七个仅可记“在该次 #518 观察中未找到”;不得倒推出其他渠道绝无协调。源记录更新后另取实时快照,不用历史快照证明当前覆盖。 +- [ ] 将模板与覆盖清单先作为 Dev PR/任务卡可审附件;Stage 6 人工确认后才更新 #518 的**待启用**入口。写入前读回 `content_version` 与活动窗口,遇到别人更新先重算差异;请求结果未知先 GET 对账,不重复 PATCH/POST。 +- [ ] 当场向每位**已知目标写者**核实采用同一窗口的确认;未确认类别逐项留记录。没有全体已知写者覆盖,不转 active、不领取三个样本。人工确认不等于 Gitea 执行端隔离。 + +### Task 3: 用现有门禁交付 Dev 规则并验证异常边界(M2-3、M2-4) + +**Files:** +- Modify: Task 1/2 的 Dev 规则差异及原任务卡(仅在候选固定前)。 +- Save outside source: 最终 precheck、task-sync、直接相关检查、Review 和 CI 的原始收据及对象索引。 + +**Interfaces:** 复用 `make task-sync`、`make evidence`、Gitea PR/Actions 与现有分支保护;不新增自动队列或跳过 CI 的入口。 + +- [ ] 在阶段 6 人工通过后,正式测试前对 Dev 规则 PR 执行一次 `make task-sync`,处理真实冲突、确认组件不回退,先写完任务卡和需提交证据,再固定并推送 PR HEAD。若有脚本/模板改动跑 `make test-governance`,Dev 组合按变更影响跑 `make test`/`make build`,由 `make evidence` 保存完整 SELF 输出。 +- [ ] 在临时真实 Git 场景复核同 base/head 重复 `task-sync` 的 HEAD、索引和组件不变;目标前进或候选内容变时,新 attempt 的 base/head 与旧 CI/Review 不同,旧结果不能放行。若本增量未改同步脚本,引用现有治理回归并做最小重放,不重复整个历史试行。 +- [ ] 用只读或隔离模拟验证异常决策表:未登记 main 推进→暂停及候选失效;合入 API 超时/断连→`reconciling` 并先读 PR/main;代码/Review 失败→当前条目 blocked 并安全释放;未发生真实生产故障的路径只标模拟或 `NOT_RUN`。 +- [ ] 阶段 7 人工审阅固定候选与测试映射后,由智能体完成阶段 8 Review 与影响重放;阶段 9 合入前再次同步核对最新 base/head/组件及当次要求的 GATE 身份、SHA、三项结果。合入请求固定 `head_commit_id` 且 `force_merge=false`,回读 PR/main 树与合入 SHA。若候选改变,重新测试及受影响评审,不沿用旧绿灯。 +- [ ] 把实际阶段 6/7/8/9 结果及 GATE/REPLAY/SELF 来源写入原任务记录;规则 PR 合入并不自动启用第二轮任务窗口。 + +### Task 4: 第二轮启用、三任务试行与收口(M2-1–M2-6) + +**Files:** +- Update dynamically: Gitea Dev Issue #518 与每个**原任务**的任务卡/PR。 +- Create after actual observation: Documents `docs/records/<实际日期>-merge-queue-manual-phase2-trial.md`;与 #518 互链,不复制动态队列状态。 +- Update only after result review: Dev `policy/adoption.md`、`policy/tool-adaptation-matrix.md` 的实际能力和状态(若有变化)。 + +**Interfaces:** Task 2 的 #518 模板;每个任务原有人工阶段与接管授权;固定 PR HEAD 的三项 GATE;智能体合入入口。此任务不承担其他任务业务代码实现。 + +- [ ] 在规则 PR 合入、#518 模板已登记、已知目标写者确认覆盖、无活动/未知窗口、runner 容量当场核验后,由负责人审阅启用条件与当前清单,再把第二轮从 `pending-activation` 切为 `manual active`。缺任何条件保持 `waiting`,继续独立局部开发。 +- [ ] 只让三个**实际就绪且已有自身实施/合入授权**的任务依 `queue_entered_at`/`ready_at` 顺序入队;协调者在领取前核对原卡阶段结论、PR head、依赖、组件与其他写者退出。#482/#512 只有重新满足这些条件才可参与,不能因本计划自动接管。 +- [ ] 每次领取后按 Task 3 固定并通过当前 HEAD 必需检查、Review 与人工阶段结论,智能体串行合入并释放;闭卡 PR 使用独立窗口,成本单列。每 30 分钟复查等待队列,记录 runner 等待与人的依赖/准备等待;时间缺失记 `NOT_MEASURED`。 +- [ ] 每次 main 实际推进后运行 Task 2 只读覆盖对账;发现未登记合入、并行窗口、对象不符、旧执行者未退出接管或来源伪造时立即暂停新领取,先核清受影响候选和写者。未知合入结果不重发 POST。已合入成果不自动回退。 +- [ ] 三项完成或触发停止条件时,按 M2-1–M2-6 列每个真实任务的最终 base/head、同步/新尝试原因、Review、GATE、合入树、开发/最终/main push/组件/闭卡 CI 次数与耗时、废弃原因;仅正常已登记顺序推进造成的最终 CI 废弃数作为目标指标。没有可比历史基线时不报告节省百分比,未发生的退出路径记 `NOT_RUN`。 +- [ ] 用户评审第二轮报告后决定继续 manual、调整预算、停止或另立自动准入;仅实际合入与经核验的能力可更新 Dev 采纳/矩阵。阶段 10 的安全回收按工作区 owner 和 `task-finish` 现场检查执行,任务闭合经有授权的 `task-close` 与智能体 PR 合入;保留所有原始收据。 + +## Stage 5 review and stop rule + +本计划当前仅供阶段 5 人工评审;PR/文件合入不等于 Dev 规则实施获批,也不等于 #518 第二轮 active。请核对四项工作顺序、写者覆盖的实际确认方式、Issue 写入时点、三个真实任务的接管边界及 M2 指标。任何实施中发现原子互斥、角色隔离或执行端 fencing 被要求为通过条件,应停止扩围并回到阶段 4 重设计,不能靠文字提升 `manual` 能力。