diff --git a/docs/development/README.md b/docs/development/README.md index 616e105bb5..3787d551a0 100644 --- a/docs/development/README.md +++ b/docs/development/README.md @@ -88,15 +88,15 @@ issue or regression -> focused implementation -> focused tests, durable smoke, and catalog-selected canary (`loopx canary premerge`) -> Goal-bound exact-head review (`loopx pr-review --goal-id GOAL`, respecting `wait_for_ci=false` without polling remote CI) - -> immediate eligible self-merge or maintainer handoff + -> maintainer handoff by default (or separately authorized merge/self-merge) -> release outcome observation when needed ``` -通常闭环为:问题或回归 -> 确定性刻画 -> 聚焦实现 -> 单测、durable smoke 与 catalog 选择的 canary(`loopx canary premerge`)-> 绑定 Goal 的精确头评审(`loopx pr-review --goal-id GOAL`,遵守 `wait_for_ci=false`,不等待也不轮询远端 CI)-> 满足自合并资格时立即合并或交由维护者合入 -> 必要时观察发布结果。 +通常闭环为:问题或回归 -> 确定性刻画 -> 聚焦实现 -> 单测、durable smoke 与 catalog 选择的 canary(`loopx canary premerge`)-> 绑定 Goal 的精确头评审(`loopx pr-review --goal-id GOAL`,遵守 `wait_for_ci=false`,不等待也不轮询远端 CI)-> 默认交由维护者合入(或在另行取得授权时执行合入/自合并)-> 必要时观察发布结果。 -When the owning Goal sets `pull_request_review.wait_for_ci=false`, deterministic local checks plus Goal-bound exact-head review and readiness (`--registry /.loopx/registry.json --goal-id `) form the complete pre-merge gate; never wait for or poll asynchronous GitHub Actions CI before finishing review or eligible self-merge. +When the owning Goal sets `pull_request_review.wait_for_ci=false`, deterministic local checks plus Goal-bound exact-head review and readiness (`--registry /.loopx/registry.json --goal-id `) remove remote CI waiting during review, readiness checks, or when a merge/self-merge is separately authorized; `wait_for_ci=false` and `ready=true` never grant merge authority or mean ready PRs auto-self-merge (leaving PRs open for maintainer handoff remains the default). -当所属 Goal 配置了 `pull_request_review.wait_for_ci=false` 时,本地确定性验证加上显式绑定 Goal 的精确头评审与就绪检查(`--registry /.loopx/registry.json --goal-id `)即构成完整合入前门禁;不得为等待或轮询异步 GitHub Actions CI 而阻塞评审结论或符合条件的自合并。 +当所属 Goal 配置了 `pull_request_review.wait_for_ci=false` 时,本地确定性验证加上显式绑定 Goal 的精确头评审与就绪检查(`--registry /.loopx/registry.json --goal-id `)可在评审、就绪检查以及另行获授权执行合入或自合并时免除对远端异步 GitHub Actions CI 的等待或轮询;`wait_for_ci=false` 与 `ready=true` 均不授予合入权限,也不意味着就绪 PR 会自动自合并(默认仍保持开启并交由维护者处理)。 ## Engineering Scope And Refactoring diff --git a/docs/development/testing-and-quality.md b/docs/development/testing-and-quality.md index de05097fd2..41f005948d 100644 --- a/docs/development/testing-and-quality.md +++ b/docs/development/testing-and-quality.md @@ -67,14 +67,20 @@ sets `pull_request_review.wait_for_ci=false`, callers pass `--registry` and `--goal-id GOAL` to `loopx pr-review` and `--check-merge-readiness`, resolving `ci_policy="not_consulted"` so local `pytest`/`ruff`/`mypy` checks, `loopx canary premerge --from-git-diff --git-diff-base "$PR_BASE_REF"`, and -exact-head review complete merge readiness without waiting on or polling CI. -Standalone or unconfigured callers keep the safe default `wait_for_ci=true`. +exact-head review complete merge readiness without waiting on or polling remote CI +once local gates pass. `ci_policy="not_consulted"` separates CI waiting from +merge and self-merge authority: it never authorizes merging or auto-self-merging +ready PRs, and the default remains leaving PRs open for maintainer/owner +authorization. Standalone or unconfigured callers keep the safe default +`wait_for_ci=true`. 当本地确定性验证已完整通过时,远端 CI 作为异步安全兜底,而不应成为串行阻塞点。对于配置了 `pull_request_review.wait_for_ci=false` 的受管 Goal,调用 `loopx pr-review` 与 `--check-merge-readiness` 时须显式传入 `--registry` 与 `--goal-id GOAL`(解析为 -`ci_policy="not_consulted"`),以本地测试、`loopx canary premerge` 和精确头评审直接完成 -就绪判断与合入,不再等待或轮询远端 CI;未配置 Goal 的独立调用保持默认 `wait_for_ci=true`。 +`ci_policy="not_consulted"`),在本地测试、`loopx canary premerge` 与精确头评审等本地 +门禁通过后即可完成就绪判断,不再等待或轮询远端 CI。`ci_policy="not_consulted"` 仅控制 +CI 等待策略,合入与自合并授权仍保持独立:它不会自动批准或触发自合并,默认仍保持 PR 开启等待 +维护者或所有者授权;未配置 Goal 的独立调用保持默认 `wait_for_ci=true`。 Tests first judge whether the state and rule are correct, then whether the implementation conforms. Expected outcomes come from an independently reviewed diff --git a/skills/loopx-pr-merge/SKILL.md b/skills/loopx-pr-merge/SKILL.md index 1a7d8ca92a..4a82084906 100644 --- a/skills/loopx-pr-merge/SKILL.md +++ b/skills/loopx-pr-merge/SKILL.md @@ -53,14 +53,18 @@ Pass `--registry` (when running outside the primary repo root, such as a worktree) and `--goal-id GOAL` for managed merges and follow resolved `wait_for_ci`. Omitting `--registry` or `--goal-id` silently falls back to the unconfigured default (`wait_for_ci=true`) and reports false CI waits. When -`wait_for_ci=false` (`ci_policy=not_consulted`), never query, poll, or wait for -CI; complete required local validation (`canary premerge`, targeted tests, -`check_rfc_bilingual.py` when RFCs change) and exact-head review/thread checks, -and run eligible self-merges or maintainer-authorized merges immediately with -`--match-head-commit HEAD_OID --admin` when branch protection holds only on -author-owned `COMMENTED` approvals or unconsulted status checks. GitHub -`BLOCKED` alone never grants merge authority; it only documents why admin bypass -applies once readiness and authorization both hold. +`wait_for_ci=false` (`ci_policy=not_consulted`), do not query, poll, or wait on +remote CI during review/readiness or when an eligible or explicitly authorized +merge/self-merge is executed: complete required local validation (`canary +premerge`, targeted tests, `check_rfc_bilingual.py` when RFCs change) and +exact-head review/thread checks, then leave the PR open for maintainer handoff +by default, or run `--match-head-commit HEAD_OID --admin` only when owner or +maintainer merge/self-merge authorization is separately held and branch +protection blocks solely on author-owned `COMMENTED` approvals or unconsulted +status checks. `wait_for_ci=false`, `ready=true`, and GitHub `BLOCKED` never +grant merge authority or turn ordinary/low-risk PRs into automatic self-merges +without owner/maintainer authorization; `BLOCKED` only documents why admin +bypass applies once readiness and authorization both hold. ## Decision Workflow @@ -100,8 +104,9 @@ authorization rule; without it, leave the merge to the maintainer. Bypass never replaces exact-head review, validation, thread/finding resolution or merge authority. -Maintainers may self-merge single-purpose, low-risk public-doc, contributor -metadata, test, example or narrow-cleanup PRs when all these conditions hold: +With owner/maintainer authorization, maintainers may self-merge single-purpose, +low-risk public-doc, contributor metadata, test, example or narrow-cleanup PRs +when all these conditions hold: - none of the protected behavior surfaces above is changed; - the diff is easy to review and required checks/focused smokes passed; @@ -109,7 +114,9 @@ metadata, test, example or narrow-cleanup PRs when all these conditions hold: `uv run --extra test loopx pr-review --check-merge-readiness NUMBER@HEAD_OID` returned `ready=true` for that unchanged head (always pass `--registry` and `--goal-id GOAL` for already Goal-managed work so `wait_for_ci=false` is - honored without waiting on remote CI; standalone delivery requires no Goal); + honored without waiting on remote CI; `ready=true` clears CI waiting only and + never turns ordinary/low-risk PRs into automatic self-merges without + owner/maintainer authorization; standalone delivery requires no Goal); - no private state, raw benchmark evidence, credentials, local paths or generated logs are included; - no runtime behavior, benchmark adapter, permission, destructive Git or public diff --git a/skills/loopx-pr-review/SKILL.md b/skills/loopx-pr-review/SKILL.md index 56e3ce3964..3ff42ee593 100644 --- a/skills/loopx-pr-review/SKILL.md +++ b/skills/loopx-pr-review/SKILL.md @@ -134,14 +134,13 @@ owner/GitHub authority, preserving discussion and unresolved reviews. Merge rout `loopx-pr-merge`; `APPROVE` is not merge authority; a public blocker belongs on the PR. Immediately before every merge, run `loopx --format json pr-review --repo OWNER/REPO ---check-merge-readiness NUMBER@HEAD_OID` (pass explicit `--registry` and -`--goal-id GOAL` on Goal-managed work so `wait_for_ci=false` is honored without -waiting on remote CI; standalone work needs no Goal). `ready=true` permits -immediate merge (including `--admin` for author-owned `COMMENTED` approvals or -unconsulted status checks when `wait_for_ci=false`); explicit maintainer -authorization means admin bypass may override a readiness or GitHub policy hold, -never missing exact-head review, validation, unresolved threads, a changed head, -an unmergeable conflict, or absent merge authority. +--check-merge-readiness NUMBER@HEAD_OID` (pass explicit `--registry` and `--goal-id GOAL` on +Goal-managed work so `wait_for_ci=false` is honored without waiting on remote CI; standalone work +needs no Goal). `ready=true` with `wait_for_ci=false` clears CI waiting when an authorized merge or +maintainer-authorized self-merge runs (never implying automatic self-merge without authorization); +explicit maintainer authorization means admin bypass may override a readiness or GitHub policy hold, +never missing exact-head review, validation, unresolved threads, a changed head, an unmergeable +conflict, or absent merge authority. ## Full PR Review And Bilingual Format