Skip to content

docs(dev,skills): separate wait_for_ci=false from self-merge authority - #9043

Open
loopx-agent wants to merge 1 commit into
mainfrom
codex/clarify-self-merge-ci-boundary-20261119
Open

loopx-agent wants to merge 1 commit into
mainfrom
codex/clarify-self-merge-ci-boundary-20261119

Conversation

@loopx-agent

Copy link
Copy Markdown
Collaborator

Summary

Clarify the boundary between CI waiting policy (pull_request_review.wait_for_ci=false, resolved as ci_policy="not_consulted") and merge / self-merge authority following #9040.

Removing remote CI waiting means reviewers and merge-readiness checks do not poll or wait on asynchronous GitHub Actions CI once required local deterministic verification is complete. It does not grant merge authority or turn ready=true / low-risk PRs into automatic self-merges; leaving completed PRs open for maintainer handoff remains the default unless owner/maintainer authorization is explicitly granted.

Changes

  • docs/development/README.md: update the development loop diagram and bilingual paragraph so maintainer handoff is the default (with separately authorized merge/self-merge noted), explicitly stating that wait_for_ci=false and ready=true never grant merge authority or mean ready PRs auto-self-merge.
  • docs/development/testing-and-quality.md: clarify in Local-First Premerge Gate vs. Asynchronous CI / 本地优先门禁与异步 CI that ci_policy="not_consulted" governs CI waiting once local gates pass while leaving merge and self-merge authority separate (PRs remain open by default for maintainer/owner authorization).
  • skills/loopx-pr-merge/SKILL.md: clarify in Configured CI Waiting and Self-Merge Eligibility And Benchmark Exceptions that wait_for_ci=false avoids waiting on remote CI during review/readiness or when an eligible or explicitly authorized merge/self-merge is executed, and that wait_for_ci=false, ready=true, and GitHub BLOCKED never authorize automatic self-merges without owner/maintainer authorization.
  • skills/loopx-pr-review/SKILL.md: tighten the merge-readiness guidance (189 <= 190 lines) to state that ready=true with wait_for_ci=false clears CI waiting when an authorized merge or maintainer-authorized self-merge runs without implying automatic self-merge, while preserving --check-merge-readiness NUMBER@HEAD_OID and admin bypass may override a readiness or GitHub policy hold.

Verification

  • len(open("skills/loopx-pr-review/SKILL.md").read().splitlines()) == 189 (<= 190 invariant satisfied; no ../../AGENTS.md)
  • git diff --check clean
  • pytest -q --no-cov tests/test_workflow_skill_install.py: 32 passed, 2 skipped (pwsh unavailable on host)
  • pytest -q --no-cov tests/capabilities/test_pr_review_contract.py: 38 passed
  • python3 examples/pr-review-command-smoke.py: passed
  • loopx --format json check --scan-path ... (4 changed files, isolated HOME): ok: true, errors: 0, public_boundary_scan.ok: true
  • loopx --format json canary premerge --from-git-diff --git-diff-base origin/main --tier quick: ok: true, merge_gate_passed: true

Clarify that pull_request_review.wait_for_ci=false (ci_policy=not_consulted) removes remote CI waiting during review, readiness checks, and separately authorized merges, without granting merge authority or turning ready PRs into automatic self-merges. Default PR state remains open for maintainer handoff unless owner/maintainer authorization is explicitly granted.

Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent | Gemini | Google | self_reported (session_not_bound)

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

本次针对 PR #9043(head 278e6b4d6c733729301db7ce794992120593a9bd)执行精确头独立证据评审。

动机 / Motivation

受管 Goal 的开发者、PR 评审 Agent 与维护者在按工作流文档及 skills/loopx-pr-review、skills/loopx-pr-merge 执行评审与合并判断时受到影响。

修改前(如 #9040 合入后基线):文档与技能将 pull_request_review.wait_for_ci=false 写为在准备就绪后立即执行 eligible self-merge,容易导致 Agent 把取消远程 CI 等待误判为授予自动自合并权限;修改后:明确 wait_for_ci=false(ci_policy="not_consulted")仅移除评审、就绪检查以及另行获授权合入时的远程 CI 等待,ready=true 不授予合入权限,默认仍保持 PR 开启交由维护者处理。

在 docs/development/README.md、docs/development/testing-and-quality.md、skills/loopx-pr-merge/SKILL.md 与 skills/loopx-pr-review/SKILL.md 中,CI 等待策略与合入/自合并授权在行为描述上完全解耦,且 skills/loopx-pr-review/SKILL.md 保持 189 行(<= 190 行限制)并保留全部契约短语。

本 PR 不修改 loopx 控制面代码、CLI 参数、Goal 配置持久化格式或 GitHub 分支保护策略,也不更改普通独立调用默认 wait_for_ci=true 的行为。

若不及时修复该措辞边界,后续维护或文档类 PR 仍可能因 wait_for_ci=false 返回 ready=true 而被误判为可自动自合并;本变更仅收敛 4 份相关文档与 skill 指令,范围独立、可直接审阅且可逆。

改动思路 / Approach

本次调整沿用既有的控制面规则架构:核心合入权限与评审门禁的单一权威仍留在仓库根规则 AGENTS.md#merge-authority-and-validation(revision 29c312949b6c26e3b27288234881eea2958ead94)以及能力侧代码 loopx/capabilities/pr_review_queue/,未新增任何运行期状态、CLI 参数或重复配置项。

正向流程上,当受管 Goal 配置 pull_request_review.wait_for_ci=false 并显式传入 --registry 与 --goal-id 时,loopx pr-review 与 --check-merge-readiness 解析出 ci_policy="not_consulted",在本地验证通过后直接完成评审与就绪判定;随后流程默认将 PR 保持 OPEN 交由维护者处理,仅在另行取得所有者或维护者授权时才依据 skills/loopx-pr-merge/SKILL.md 执行合并或自合并且无需等待异步 CI。

负向/未授权路径上,即使 PR 属于低风险文档改动、且 --check-merge-readiness 返回 ready=true(或 GitHub mergeStateStatus 仅因 COMMENTED 自评与未咨询的 CI 处于 BLOCKED),缺少维护者/所有者授权时仍明确禁止自动自合并或使用 --admin 绕过。

具体改动 / Changes

对照契约文档 AGENTS.md#merge-authority-and-validation(基线 commit 29c312949b6c26e3b27288234881eea2958ead94)逐项核对验收标准 SM-CI-1、SM-CI-2 与 SM-CI-3:

关键内容讲解

  1. docs/development/README.md(对应 SM-CI-1、SM-CI-2):将开发闭环图中的 "immediate eligible self-merge or maintainer handoff" 与中文 "满足自合并资格时立即合并或交由维护者合入" 改为 "maintainer handoff by default (or separately authorized merge/self-merge)" 与 "默认交由维护者合入(或在另行取得授权时执行合入/自合并)";并在下方中英文说明中明确 wait_for_ci=false 与 ready=true 仅免除评审、就绪检查或另行获授权合入时的远端 CI 等待,均不授予合入权限或意味着就绪 PR 会自动自合并。
  2. docs/development/testing-and-quality.md(对应 SM-CI-1、SM-CI-2):在 Local-First Premerge Gate vs. Asynchronous CI / 本地优先门禁与异步 CI 中补充中英文界定:ci_policy="not_consulted" 仅在本地测试、loopx canary premerge 与精确头评审通过后免除远端 CI 等待,将 CI 等待策略与合入/自合并授权分离,未授权时默认保持 PR 开启,独立未配置调用仍维持 wait_for_ci=true。
  3. skills/loopx-pr-merge/SKILL.md(对应 SM-CI-1、SM-CI-2):在 Configured CI Waiting 中修正此前容易误解的立即自合并表述,改为在评审/就绪检查或执行符合资格且已获明确授权的合并/自合并时不再轮询远端 CI,否则默认保持开启;同时在 Self-Merge Eligibility And Benchmark Exceptions 的前置条件和 ready=true 说明中补充需具备所有者/维护者授权,wait_for_ci=false、ready=true 与 GitHub BLOCKED 均不将普通/低风险 PR 转为自动自合并。
  4. skills/loopx-pr-review/SKILL.md(对应 SM-CI-1、SM-CI-2、SM-CI-3):收紧 Publish And Read Back 末尾的就绪说明,改为 ready=true 配合 wait_for_ci=false 仅在执行已授权合并或维护者授权的自合并时清除 CI 等待,不暗示无授权自动自合并;同时全文行数由 190 行精简至 189 行(满足 <= 190 预算),原样保留 admin bypass may override a readiness or GitHub policy hold、--check-merge-readiness NUMBER@HEAD_OID 且不包含 ../../AGENTS.md。

对主干的风险 / Risks

本次仅修改 4 个 Markdown 文档与 skill 文件(共 +39 / -27 行,无 Python/TypeScript 逻辑变更),对主干无运行时回退风险,但涉及 Agent 消费的指令文本与受安装契约约束的 skill 预算。

  • 潜在误读/预算边界风险:若 skills/loopx-pr-review/SKILL.md 超过 190 行或遗漏关键契约短语,打包与安装冒烟检查 examples/pr-review-command-smoke.py 和 tests/test_workflow_skill_install.py 会直接失败。当前已于 exact head 278e6b4d6c733729301db7ce794992120593a9bd 实测通过:skills/loopx-pr-review/SKILL.md 为 189 行,tests/test_workflow_skill_install.py 为 32 passed, 2 skipped(宿主机无 pwsh 导致 2 个 PowerShell 用例跳过,其余全部通过),tests/capabilities/test_pr_review_contract.py 为 38 passed,examples/pr-review-command-smoke.py 通过。
  • 公共边界与门禁验证:git diff --check、RFC 双语检查与隔离 HOME 下的 loopx check --scan-path 均通过(errors: 0);loopx canary premerge --from-git-diff --git-diff-base origin/main --tier quick 在 exact head 执行 4 项直接检查、3 项 catalog canary 与 1 项边界扫描全部通过(ok: true、merge_gate_passed: true、failures: 0)。
  • 负向路径确认:已核对独立未绑定 Goal 场景保留 wait_for_ci=true 默认值未变,且已验证无授权时即使 ready=true 也不触发自合并;skills/loopx-pr-merge/SKILL.md 仍保持 repo-only(无 .loopx-skill-scope 且不在 wheel 打包列表中)。

我的整体评价 / Verdict

从长程协作(long_horizon)与开发者体验(user_experience)来看,本 PR 消除了 #9040 后把“免等远程 CI”与“自动自合并授权”混为一谈的隐患,减少了误合入后需人工回滚的返工风险,且不增加任何额外配置轮次或新词汇;渲染视图检查不适用(仅文档与 Markdown skill 文本,未涉及前端 UI,无未验证的视觉范围)。语义对齐方面直接复用已有 AGENTS.md 与 pull_request_review 词表与规则,未引入新状态或兼容性负担,代码/文档体量必要且无冗余,默认关闭与独立路径隔离完整。

本评审已在 exact head 278e6b4d6c733729301db7ce794992120593a9bd 完成全部本地验证与公共边界检查(未咨询远程 GitHub CI,符合目标配置 wait_for_ci=false),无阻塞性发现;按本 PR 明确的规则默认保持 PR 开启交由维护者处理。

English verdict: APPROVE — verified exact head 278e6b4d6c733729301db7ce794992120593a9bd with zero findings; tests/test_workflow_skill_install.py (32 passed, 2 host-unavailable pwsh skipped), tests/capabilities/test_pr_review_contract.py (38 passed), examples/pr-review-command-smoke.py, loopx check, and loopx canary premerge --tier quick all pass locally (wait_for_ci=false policy honored without consulting remote CI).

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant