From 7dd947accee91655723999ebf1501deb7881fcce Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 20 May 2026 04:21:31 +0000 Subject: [PATCH] docs: record code queue commander brief --- docs/reference/code-queue-supervision.md | 196 ++++++++++++----------- docs/report/202605/20260520_Commander.md | 117 ++++++++++++++ 2 files changed, 216 insertions(+), 97 deletions(-) create mode 100644 docs/report/202605/20260520_Commander.md diff --git a/docs/reference/code-queue-supervision.md b/docs/reference/code-queue-supervision.md index 13966afb..14cac356 100644 --- a/docs/reference/code-queue-supervision.md +++ b/docs/reference/code-queue-supervision.md @@ -1,154 +1,156 @@ -# Code Queue Supervision Policy +# Code Queue 指挥监督策略 -This document defines the long-term operating model for using Code Queue as a parallel delivery infrastructure under a human or lead-agent supervisor. It is a coordination policy, not a replacement for `docs/reference/microservices.md`, `docs/reference/observability.md`, `docs/reference/user-service-delivery.md`, or the Code Queue runtime contracts. +本文定义在人工或 lead-agent 指挥官监督下，把 Code Queue 作为并行交付基础设施使用的长期运行模型。本文是协同策略，不替代 `docs/reference/microservices.md`、`docs/reference/observability.md`、`docs/reference/user-service-delivery.md` 或 Code Queue runtime 合同。 -## Scope +## 范围 -Use this policy when a delivery goal is too large for one Code Queue task and must be split across multiple queues, services, or infrastructure lanes. +当一个交付目标过大，无法由单个 Code Queue 任务完成，并且必须拆分到多个队列、服务或基础设施 lane 时，使用本策略。 -This policy applies to: +本策略适用于： -- user-service CI/CD rollouts; -- multi-service fixes that need several isolated worktrees; -- infrastructure defects found while user-service work is running; -- follow-up validation, retry, and acceptance coordination; -- manual supervisor work that keeps Code Queue tasks moving without taking over their implementation. +- 用户服务 CI/CD 推广； +- 需要多个隔离 worktree 的跨服务修复； +- 用户服务开发过程中暴露出来的基础设施缺陷； +- 后续验证、retry、验收和任务接力协调； +- 指挥官为了保持 Code Queue 任务推进而做的手动监督工作，但不接管 worker 的具体实现。 -It does not authorize bypassing the normal deployment, Git, or production safety rules. +本文不授权绕过正常部署、Git 或生产安全规则。 -## Operating Principle +## 运行原则 -The supervisor owns the outcome. Code Queue tasks own bounded execution. +指挥官对最终结果负责，Code Queue task 对边界明确的执行负责。 -The supervisor should keep a live map of the delivery goal, active queues, blockers, evidence gaps, and next recovery action. Code Queue workers should receive self-contained prompts with enough context to execute without relying on GitHub issue visibility or chat history. +指挥官应维护交付目标、活跃队列、阻塞点、证据缺口和下一步恢复动作的实时地图。Code Queue worker 应收到自包含 prompt，prompt 中必须有足够上下文，不能依赖 GitHub issue 可见性或聊天历史。 -The goal of central supervision is to increase delivery throughput and availability without turning every defect into a manual one-off fix. +集中指挥的目标是提升交付吞吐和可用性，而不是把每个缺陷都变成一次性的人工修补。 -The supervisor's end goal is to keep the broader development wave moving: track queue progress, correct course early, review completed work for quality, and schedule the next round of tasks so the delivery program keeps compounding instead of stalling after one batch finishes. +指挥官的最终目标是推动整体开发波次持续前进：跟踪队列进展、及时纠偏、审查完成质量，并安排下一轮任务，让交付计划持续复利式推进，而不是一批任务结束后停滞。 -## Task Design +## 任务设计 -Every Code Queue task must have a narrow ownership boundary. +每个 Code Queue task 都必须有清晰且狭窄的 ownership 边界。 -- Assign one service, module, or infrastructure defect per task when possible. -- Give each task its own detached worktree under the shared workspace. -- State the write scope, validation scope, commit/push requirement, and forbidden actions directly in the prompt. -- Include the relevant background in the prompt itself; issue links are supporting references, not required context. -- Prefer existing queues and create new queues only when the existing lanes cannot express the ownership boundary. -- Keep queue concurrency bounded by real execution capacity. A target around five concurrent lanes is the normal operating point; the supervisor should push toward ten concurrent lanes when the active tasks have distinct write scopes, heartbeat/trace evidence is healthy, and the observed success rate stays acceptable. If success quality starts to slip, back off before expanding further. +- 尽量每个任务只负责一个服务、模块或基础设施缺陷。 +- 每个任务使用共享 workspace 下自己的 detached worktree。 +- 在 prompt 中直接写明写入范围、验证范围、提交/推送要求和禁止动作。 +- 相关背景必须写进 prompt；issue 链接只能作为辅助引用，不能作为必要上下文。 +- 优先复用已有队列；只有现有 lane 无法表达 ownership 边界时，才创建新队列。 +- 队列并发必须受真实执行能力约束。通常目标是约 5 条并发 lane；当活跃任务写入范围彼此独立、heartbeat/trace 证据健康、成功率可接受时，指挥官可以把并发提高到约 10。若完成质量下降，应先降并发再继续扩张。 -Prompts for production-adjacent work must explicitly forbid heavy local checks on the master server when those checks are known to risk OOM, and must tell the worker which validation belongs in D601 CI, dev env, or a target service container. +靠近生产的任务 prompt 必须明确禁止在 master server 上跑已知可能 OOM 的重型本地检查，并说明哪些验证应在 D601 CI、dev env 或目标服务容器中执行。 -When one supervisor machine is creating many Code Queue tasks in a burst, submit calls should default to serial or near-serial behavior. A short local lock or delay is acceptable if it prevents the control plane from being flooded faster than it can acknowledge tasks, especially on low-memory hosts. The goal is to keep task creation observable and stable, not to maximize raw enqueue throughput. +当一个指挥机需要突发创建大量 Code Queue 任务时，submit 默认应串行或接近串行。为了避免控制面在确认任务前被打爆，可以使用短本地锁或短延迟，尤其是在低内存主机上。目标是保持任务创建可观测且稳定，而不是最大化瞬时入队吞吐。 -## Monitoring +## 监控 -The supervisor must monitor Code Queue with task-level and queue-level evidence, not with a single status field. +指挥官必须用 task 级和 queue 级证据监控 Code Queue，不能只看单一状态字段。 -Use: +常用入口： -- `bun scripts/cli.ts codex queues` for queue counts, active task ids, unread terminal tasks, and control-plane diagnostics. -- `bun scripts/cli.ts codex task ` for attempt, last assistant message, last error, cancel flag, and current status. -- `bun scripts/cli.ts codex task --trace --limit N` or `codex output` only when the summary is insufficient. -- The liveness rules in `docs/reference/observability.md` when master control-plane state and D601 scheduler state appear split. +- `bun scripts/cli.ts codex queues`：查看队列计数、active task id、完成未读任务和控制面诊断。 +- `bun scripts/cli.ts codex task `：查看 attempt、最后 assistant message、最后错误、cancel flag 和当前状态。 +- 当摘要不足时，再使用 `bun scripts/cli.ts codex task --trace --limit N` 或 `codex output`。 +- 当 master 控制面状态和 D601 scheduler 状态看起来分裂时，使用 `docs/reference/observability.md` 中的活性规则判断。 -`split-brain` in queue diagnostics is a control-plane/execution-plane divergence signal, not automatic evidence that the work is dead. If the task heartbeats are fresh and the trace is still advancing, treat the task as live and keep supervising it rather than interrupting or replacing it. The queue summary should expose this as `effectiveLiveness=live`, `splitBrainLive=true`, and `recommendedAction=continue-supervision`; expired, missing, or stale-recovery heartbeat evidence should instead surface `effectiveLiveness=at-risk`. +队列诊断中的 `split-brain` 表示控制面/执行面观测分裂，不自动证明任务已经死亡。如果任务 heartbeat 新鲜且 trace 仍在推进，应把任务视为 live，继续监督，而不是 interrupt 或替换。队列摘要应显示 `effectiveLiveness=live`、`splitBrainLive=true` 和 `recommendedAction=continue-supervision`；如果 heartbeat expired/missing 或满足 stale-recovery 条件，应显示 `effectiveLiveness=at-risk`。 -Long-running tasks with fresh trace or heartbeat evidence should normally be left alone. Polling every few minutes is preferred over repeated interrupt/retry cycles. +对于 trace 或 heartbeat 新鲜的长任务，通常应保持运行。每几分钟轮询一次优于反复 interrupt/retry。 -For broad CI/CD migration waves, use a fixed supervision cadence unless an incident demands faster action. A five-minute poll loop is the default: read `codex queues`, read terminal or suspect task summaries, then either accept, retry, split a blocker, or leave healthy tasks alone. The loop should keep the supervisor doing useful non-overlapping work, such as documentation or issue triage, but that side work must not take over a worker's assigned implementation. +对于大规模 CI/CD 迁移波次，除非发生事故，否则使用固定监督节奏。默认是 5 分钟轮询循环：读取 `codex queues`，读取 terminal 或可疑任务摘要，然后决定接受、retry、拆分 blocker，或让健康任务继续运行。循环期间指挥官可以做不重叠的有用工作，例如文档或 issue 梳理，但这些辅助工作不能接管 worker 已分配的实现。 -When a task leaves `running` or `judging`, treat the result as unread work until the final response and judge record have been inspected. Only then should the supervisor decide whether to refill the concurrency window. +当任务离开 `running` 或 `judging` 后，其结果仍然是未读工作。指挥官必须检查 final response 和 judge 记录，然后再决定是否补充并发窗口。 -Never use a bulk read action to clear unread terminal tasks before inspection. Each completed task must be reviewed on its own first, then marked read individually so the unread state continues to mean “review still needed.” +禁止在检查前用批量 read 动作清空完成未读任务。每个完成任务必须先单独审阅，再单独标记已读，使未读状态继续代表“仍需审阅”。 -## Supervisor Workflow +## 指挥工作流 -For each active task, evaluate four things in order: +对每个活跃任务，按顺序评估四件事： -1. completion quality: did it actually satisfy the task's acceptance boundary; -2. completion state: is it terminal, retryable, or still making progress; -3. self-blocking risk: is the task stuck on a problem it cannot solve alone; -4. next action: accept, continue, replace with a narrower task, or raise an infrastructure issue. +1. 完成质量：是否真的满足任务验收边界； +2. 完成状态：是否已经终态、可 retry，或仍在推进； +3. 自阻塞风险：任务是否卡在它自己无法解决的问题上； +4. 下一步动作：接受、继续、替换为更窄任务，或上报基础设施问题。 -If the blocker is a reusable infrastructure problem, do not keep re-running the business task blindly. First record the infrastructure defect in an issue, then fix the infrastructure manually if Code Queue cannot move past it, and only then resume the delivery wave. +如果 blocker 是可复用的基础设施问题，不要盲目反复重跑业务任务。应先把基础设施缺陷记录到 issue，再在 Code Queue 无法越过时手动修复基础设施，然后恢复交付波次。 -The supervisor should prefer read-only analysis and new narrowly scoped tasks over local implementation takeover. Manual work is reserved for infrastructure blockers, live recovery, and other cases where the queue cannot safely unblock itself. +指挥官应优先做只读分析和派发新的窄范围任务，而不是本地接管实现。手动工作只保留给基础设施 blocker、live recovery，以及队列无法安全自解的问题。 -## Intervention Rules +## 干预规则 -Intervene only when there is a clear reason. +只有存在明确理由时才干预。 -- If a task is running and trace or scheduler heartbeat is fresh, guide rather than interrupt. -- If a task reaches terminal state but lacks required acceptance evidence, retry the same task with a focused continuation prompt. -- If a task is blocked by a reusable infrastructure defect, assign that defect to an appropriate empty or low-risk queue and keep the original business task waiting or retried after the fix. -- If an infrastructure defect affects Code Queue control-plane availability, the supervisor may apply the smallest controlled deploy needed to restore the queue, then verify the original task can continue. -- If retry, cancel, move, or scheduler behavior is wrong, do not patch PostgreSQL manually as the final fix. Fix the code path, deploy the fix if needed, then recover the affected task through the normal API. +- 如果任务还在运行且 trace 或 scheduler heartbeat 新鲜，应引导而不是 interrupt。 +- 如果任务进入终态但缺少必要验收证据，应使用聚焦 continuation prompt retry 同一任务。 +- 如果任务被可复用基础设施缺陷阻塞，应把该缺陷分配给合适的空闲或低风险队列，让原业务任务等待，或在修复后 retry。 +- 如果基础设施缺陷影响 Code Queue 控制面可用性，指挥官可以执行恢复队列所需的最小受控部署，然后验证原任务能继续。 +- 如果 retry、cancel、move 或 scheduler 行为错误，不要把手动 patch PostgreSQL 当作最终修复。应修复代码路径，必要时部署，然后通过正常 API 恢复受影响任务。 -Manual intervention must preserve the original task identity whenever that helps continuity. Creating duplicate replacement tasks is a fallback, not the default. +手动干预应尽可能保留原任务身份，以保持上下文连续。创建重复替代任务是 fallback，不是默认动作。 -## Completion Criteria +## 完成标准 -A Code Queue task is not complete merely because it pushed code. +Code Queue task 不是只要 push 代码就算完成。 -For CI/CD delivery tasks, acceptance must include the evidence required by the target delivery policy. For user-service artifact delivery this means: +对于 CI/CD 交付任务，验收必须包含目标交付策略要求的证据。对用户服务 artifact 交付，这意味着： -- the CI artifact producer ran from a pushed commit; -- the artifact reference and digest are recorded; -- the dev environment consumed the same artifact; -- production CD consumed the artifact without source rebuild; -- live health and live commit or image label evidence match the requested commit. +- CI artifact producer 从已推送 commit 运行； +- artifact ref 和 digest 已记录； +- dev 环境消费同一个 artifact； +- production CD 消费 artifact，且没有源代码 rebuild； +- live health、live commit 或 image label 证据与请求 commit 匹配。 -For infrastructure tasks, acceptance must prove that the original blocked workflow can proceed, or must state the remaining deployment step needed for the live system to consume the fix. +对于基础设施任务，验收必须证明原本被阻塞的 workflow 可以继续，或明确说明 live 系统消费该修复还缺哪个部署步骤。 -Completed but unread tasks are still supervisor work. They must be read, classified, and either accepted, retried, or turned into a new bounded follow-up task. +完成未读任务仍然是指挥官工作。它们必须被阅读、分类，并被接受、retry，或转成新的窄范围 follow-up task。 -## Infrastructure Defect Handling +## 基础设施缺陷处理 -Infrastructure defects discovered during a delivery program should be split from user-service work when the split improves throughput or reduces confusion. +交付计划中发现的基础设施缺陷，只要拆分后能提高吞吐或减少混乱，就应从用户服务工作中拆出来。 -Examples of infrastructure defects include: +基础设施缺陷示例： -- a retry API that leaves stale cancellation state; -- a healthcheck that no longer matches the runtime image; -- CLI observability that cannot show running, recently completed, or unread terminal tasks; -- a proxy path that differs between WebUI and CLI; -- a deploy job that reports failure even though the service API is healthy. -- a supervisor-side submit burst that can saturate the Code Queue manager or low-memory host before the queue has a chance to acknowledge tasks. -- a Code Queue container missing a basic operator tool or credential path needed for supervision, such as `gh`, `hub`, or a GitHub token injection path. +- retry API 遗留 stale cancellation state； +- healthcheck 不再匹配 runtime image； +- CLI 可观测性无法快速看到 running、最近完成或完成未读任务； +- WebUI 和 CLI 的 proxy 路径不一致； +- deploy job 报失败但服务 API 实际健康； +- 指挥侧突发 submit 打满 Code Queue manager 或低内存主机，导致队列还没确认任务就被压垮； +- Code Queue 容器缺少监督所需的基础工具或凭证路径，例如 `gh`、`hub` 或 GitHub token 注入路径。 -These defects should be assigned to infrastructure queues with prompts that include the concrete observed failure, the expected long-term contract, and the recovery action required for the original delivery task. +这些缺陷应分配给基础设施队列，prompt 中要包含具体观测失败、期望长期合同，以及原交付任务继续所需的恢复动作。 -When the defect is only in the Code Queue execution environment and the service can be safely patched live in dev without touching prod, prefer the smallest temporary live remedy first. Then persist the fix in the relevant Dockerfile, container image, or credential propagation path, and verify the persistent fix in dev before considering the issue closed. +如果缺陷只存在于 Code Queue 执行环境，且服务可以在 dev 中安全热修而不触碰 prod，应先做最小临时 live remedy。然后把修复持久化到相关 Dockerfile、容器镜像或凭证传播路径，并在 dev 验证持久化修复后再关闭问题。 -If a business task discovers this kind of missing tool or missing credential path, the supervisor should split it into a dedicated infra task rather than leaving it buried in the business task prompt. The business task should continue with the bridge in place when possible. +如果业务任务发现缺少工具或凭证路径，指挥官应把它拆成独立 infra task，而不是埋在业务任务 prompt 中。业务任务在 bridge 存在时应继续推进。 -## Supervisor Boundaries +## 指挥边界 -The supervisor may: +指挥官可以： -- read task, queue, health, job, and service status; -- submit, retry, interrupt, or cancel through the normal Code Queue and microservice proxy APIs; -- create self-contained follow-up tasks; -- run controlled production deploys for infrastructure recovery when the user has allowed production repair and the deploy path is already established; -- use a clean detached worktree for documentation or controlled deployment actions when the main worktree has unrelated parallel changes. +- 读取 task、queue、health、job 和 service 状态； +- 通过正常 Code Queue 和 microservice proxy API submit、retry、interrupt 或 cancel； +- 创建自包含 follow-up task； +- 在用户允许生产修复且部署路径已验证时，为基础设施恢复执行受控生产部署； +- 当 main worktree 有无关并行变更时，为文档或受控部署动作使用干净 detached worktree。 -The supervisor's own UniDesk command-and-control repo must stay on the latest `master` checkout in the single root worktree. Do not create extra worktrees for supervision or queue command decisions, so the commander always sees the current repository head and the same live state that production-facing coordination depends on. If an isolated worktree is needed for a worker or a controlled one-off operation, that worktree belongs to the worker or operation, not to the supervisor's standing environment. +指挥官自己的 UniDesk 指挥仓库必须保持在单一根 worktree 的最新 `master` checkout 上。不要为指挥、队列判断或日常监督创建额外 worktree，这样指挥官始终看到当前仓库头和生产协调依赖的同一份实时状态。如果 worker 或受控一次性操作需要隔离 worktree，该 worktree 属于 worker 或具体操作，不属于指挥官的常驻环境。 -The supervisor must not: +每个由指挥官派发的 worker prompt，都必须在 Git 指令前明确写明目标线。`master` 用于主动开发和集成工作；`release/v1` 只用于明确批准的稳定维护修复。worker 的 final response 必须报告实际推送分支、远端 commit hash，以及该 commit 是否可从 `origin/` 获取。如果 final response 引用的 commit 不能被指挥官从声明的目标分支 fetch 到，该任务不得验收为完成。 -- redo a worker's assigned implementation locally unless the user explicitly asks for manual takeover; -- run full check, full e2e, or Playwright on the master server when those checks are known to risk OOM; -- revert unrelated dirty worktree changes; -- treat local deployment state as source of truth when Git remote is the required truth; -- mark a delivery complete without acceptance evidence. +指挥官不得： -## Documentation Feedback Loop +- 本地重做 worker 已分配的实现，除非用户明确要求手动接管； +- 在 master server 上跑已知可能 OOM 的 full check、full e2e 或 Playwright； +- 回滚无关 dirty worktree 变更； +- 在 Git 远端是 source of truth 时，把本地部署状态当作 source of truth； +- 在缺少验收证据时宣布交付完成。 -Every repeated or delivery-blocking failure should feed back into one of: +## 文档反馈回路 -- a Code Queue task that fixes the defect; -- a GitHub issue or issue comment that records the blocking condition and recovery dependency; -- a long-term reference document when the lesson is durable. +每个重复出现或阻塞交付的问题，都应反馈到以下至少一个位置： -Reference docs should capture the reusable rule, not the full incident timeline. Process knowledge should reduce future supervision cost rather than become another one-off log. +- 修复该缺陷的 Code Queue task； +- 记录阻塞条件和恢复依赖的 GitHub issue 或 issue comment； +- 当经验具有长期复用价值时，写入长期参考文档。 + +长期参考文档应记录可复用规则，而不是完整事故流水账。过程知识应降低未来监督成本，而不是变成又一个一次性日志。 diff --git a/docs/report/202605/20260520_Commander.md b/docs/report/202605/20260520_Commander.md new file mode 100644 index 00000000..b0df375e --- /dev/null +++ b/docs/report/202605/20260520_Commander.md @@ -0,0 +1,117 @@ +# 2026-05-20 指挥简报 + +## 范围 + +本文是 Code Queue 指挥官针对 GitHub issue #9、#12、#13、#14、#15、#16 的过程恢复记录。目标是在上下文压缩或指挥交接后，能快速恢复当前态势。 + +当前生效的指挥规则： + +- 指挥官仓库固定使用 `/root/unidesk` 的最新 `master`，不得为指挥工作创建 worktree。 +- 仍有未完成任务时，约每 5 分钟轮询一次。 +- 每轮轮询后视情况追加简报；只有活跃/排队/完成未读、相关 commit、阻塞点或下一步发生变化时才追加。 +- 完成未读任务必须先审阅，再标记已读。 +- 不在 master server 上跑重型 `check`、全量 e2e 或 Playwright。 +- `backend-core` 和 D601 Code Queue 的生产变更默认只在 dev 验证，除非用户明确批准。 +- 简报和长期参考文档使用中文。 + +## 快照 2026-05-20 04:16 UTC + +仓库状态： + +- 指挥官 worktree：`/root/unidesk` +- `origin/master`：`3a5d60140044`（`fix: read k3s artifact labels via root ctr`） +- 写入本简报前，指挥官 worktree 除新简报文件外无其它变更。 + +队列状态： + +- 运行中：2 + - `codex_1779247780398_1`，队列 `code-queue`：#12 后端/API trace 与 STEP 合同。 + - `codex_1779247828759_1`，队列 `frontend`：#12 前端与 dev/prod 部署验证。 +- 排队中：4 + - `codex_1779248021103_1`：#13 后端/API stats。 + - `codex_1779248492207_1`：#15 PR 支持。 + - `codex_1779248052767_1`：#13 前端 stats。 + - `codex_1779248189933_1`：#14 split-brain UI。 +- 完成未读：1 + - `codex_1779248781778_1`，队列 `infra`：#16 CLI 渐进式披露和 skill 注入。 + +诊断： + +- Code Queue 仍报告 live split-brain：PostgreSQL 中存在 active task，但本地 scheduler active slot 为空；同时 scheduler heartbeat 新鲜。 +- 当前推荐动作仍是 `continue-supervision`，不是 stale recovery。 + +## Issue 状态 + +- #12：两条 lane 仍在执行。前端 lane 已经推送并部署过 dev frontend health commit，随后修复了通过 root `ctr` 读取 k3s artifact label 的问题。后端 lane 仍在收口 API/data contract 和类型验证。 +- #13：排在 #12 后面。 +- #14：排在 frontend lane 后面。 +- #15：排在 code-queue lane 后面。 +- #16：Code Queue 终态为 succeeded，但指挥官审阅发现发布风险。 + +## 审阅记录 + +#16 的 Code Queue final response 声称提交了 commit `ed6f8a0586c0423eca4f3763fe0cf4ebd25ab0f6`，提交信息为 `feat: tighten code queue supervision cli`。 + +指挥官在 04:16 UTC 的验证结果： + +- `origin/master` 仍是 `3a5d6014004412d08efe3b83f5b7c7201ec4633c`。 +- 在指挥官仓库中执行 `git cat-file -t ed6f8a0586c0423eca4f3763fe0cf4ebd25ab0f6` 没有找到对象。 +- worker 路径 `/workspace/unidesk/.worktrees/codequeue-16` 在指挥官机器上不可见。 + +判断： + +- 暂不将 #16 标记已读。 +- #16 功能方向看起来有价值，但在 commit 能从 `origin/master` 获取，或 worker 解释 final response 中 commit 不可见的原因之前，不能验收。 + +## 下一步 + +- 持续轮询 #12 后端和前端两条运行 lane。 +- 继续审阅 #16，必要时派一个 follow-up Code Queue 任务恢复/推送缺失 commit，或将发布失败写入 issue。 +- #12 lane 完成后先审阅，再决定是否接受 #13/#14/#15 后续任务结论。 +- 后续轮询如果态势变化，继续向本文追加简报。 + +## 更新 2026-05-20 04:20 UTC + +已检查 #16 commit `ed6f8a0586c0423eca4f3763fe0cf4ebd25ab0f6` 是否推到了其它分支，包括 `release/v1`。 + +结果： + +- `origin/master`：`3a5d60140044` +- `origin/release/v1`：`0cf73d817f14` +- `git branch -r --contains ed6f8a0586c0423eca4f3763fe0cf4ebd25ab0f6`：无结果。 +- `git tag --contains ed6f8a0586c0423eca4f3763fe0cf4ebd25ab0f6`：无结果。 +- `git log --all --grep='tighten code queue supervision cli'`：无结果。 + +结论： + +- #16 仍不能验收/标记已读。final response 引用的 commit 当前不在已拉取的任何远端 ref 中。 +- 下一步继续使用 Code Queue 指挥机制，而不是指挥官本地接手实现：派 follow-up queue task 恢复/推送缺失 commit，或记录 #16 发布失败。 + +不符合预期的 Code Queue 行为： + +- 任务进入 `succeeded` 且 judge 为 `complete`，但其声明的 commit 不能从任何远端分支拉取。 +- 这是指挥官可见的验收缺陷：任务“完成”不能等同于“交付完成”，Git 远端 source-of-truth 缺失时不能接受。 + +长期化建议： + +- 为 Git-backed delivery task 增加 Code Queue 完成后验收门禁： + - 从 worker final response 或结构化元数据解析目标分支和 commit； + - 对 `origin/` 执行 `git ls-remote` / fetch 校验； + - commit 远端不可见时，任务应标记为 `succeeded_unverified`，或至少暴露明确验收告警； + - 在指挥官接受或派出恢复任务之前，保持未读。 +- worker prompt 和 final response 必须包含目标分支、推送 commit、远端可见性证据。 + +## 指挥规则新增 2026-05-20 04:22 UTC + +以后每个 Code Queue 派发任务都必须显式写明目标线： + +- `master`：用于主动开发和集成线。 +- `release/v1`：仅用于明确批准的稳定维护修复。 + +worker prompt 必须包含目标分支，final response 必须报告： + +- 实际推送的分支； +- 远端 commit hash； +- 该 commit 是否可从 `origin/` 获取。 + +“push to master” 或 “push current branch” 这类含糊说法不再满足指挥官派单要求。