Agent-System-Documents/docs/proposals/2026-10-14-merge-queue-manual-phase2-implementation-plan.md

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 设计，Documents PR #104（合入 8e3b5b0d2838f89430683ec731a15b32b4fa5eae）；首轮报告与 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 先排除。

  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 快照 回放对账口径：#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 decision and stop rule

2026-10-14，负责人 weichen 在本任务会话中对 Documents 草稿 PR #105 的计划稿 28c4ceb17315e1bb06f8e39c8407eb525effb8fe 回复“通过阶段 5”，并选择由当前智能体逐项实施。批准覆盖本计划的阶段 6 候选编制与自检，不替代阶段 6–7 的人工结论，也不等于 #518 第二轮 active。任何实施中发现原子互斥、角色隔离或执行端 fencing 被要求为通过条件，应停止扩围并回到阶段 4 重设计，不能靠文字提升 manual 能力。