Skip to content

docs(pm-dispatch): read mergeable_state on every look at a watched PR - #26627

Merged
os-zhuang merged 1 commit into
mainfrom
claude/project-thread-kkdhb4
Oct 27, 2026
Merged

os-zhuang merged 1 commit into
mainfrom
claude/project-thread-kkdhb4

Conversation

@objectstack-fleet

Copy link
Copy Markdown
Contributor

Requested by Tesla · project thread

No card: the maintainer authorized this .claude/ tooling PR directly in the project chat, replying 「同意」 to the proposal "update the pm-dispatch skill so any agent watching or landing a PR checks mergeable state on every look, not only CI checks, merges main itself when conflicted, and never reports nothing-needed-from-you without confirming mergeability".

维护者速读

  • 改了什么:pm-dispatch 看护 PR 时,每看一眼都同时读 CI 与 mergeable_state;冲突(dirty)当即合 main;未确认可合并不报「无需你做」。
  • 为什么改:一个 PR 冲突了好几个小时,线程只看 CI、一直说「在等 CI」,冲突通知没到,是你先发现的。
  • 风险与回滚:只改四个 .claude/ 文件的规则文字,每个文件行数不变;回滚 = revert 本 PR。
  • 先看:landing-operations.md B 节新增两行,coordinator.md 第七节新增一行。
  • 两分钟验证:读 diff 的 5 行增改;pnpm check:pm-skill-ratchet 绿。
  • 需要你做的:os-zhuang 批准即可,批准后由本线程合入。

What changes

  • references/landing-operations.md §B (the watch from PR open to MERGED) gains two rules:
    • every look at a PR (event wake, patrol, before a report) reads mergeable_state beside the checks, and unknown is re-read;
    • dirty ⇒ merge origin/main and push a new commit at once, without waiting for a conflict notice; no "nothing needed from you" report without a settled non-dirty reading.
  • references/coordinator.md §七: before relaying a thread's "this PR needs nothing from you", the coordinator reads that PR's mergeable_state itself; dirty ⇒ send it back to the thread to merge main instead of relaying.
  • references/dispatch-runbook.md card-thread section: the thread drives CI and mergeability.
  • references/execution-duties.md collect section: the subscribe-on-report line now points at landing-operations §B for how the watch reads a PR.

behind is deliberately left alone: platform-readings.md already rules that a PR behind main still enters the queue and owes no pr_update_branch, so only dirty asks for a merge.

Why

A cleanup PR sat in merge conflict while its thread said it was watching CI. Two PRs had landed on main that edited the same skill files. Conflict notices are best effort and often never arrive, and the existing mergeable_state reads in the skill fire only at arming time and when an enqueue fails. The maintainer noticed the conflict before any agent did.

Ratchet funding (line-neutral per file, no ceiling moved)

Every file sits at headroom 0, so each added line is paid by deleting a line whose content another text already carries:

  • landing-operations.md −「信任 suite/check 事件前先重读 PR 对象取 head…」: carried by platform-readings.md's last queue-section line (check_suite.completed names a stale head ⇒ re-read the current head before use).
  • landing-operations.md −「确认 MERGED 要两个读数…」: carried by AGENTS.md Multi-agent §7 ("Always read two things: the queue branch and origin/main") and platform-readings.md (「落地检查恒两个读数」).
  • coordinator.md −「按派发令所写的 model 与 effort 开线程…」: carried by dispatch-runbook.md's card-thread section (「档位与 effort 席位自推导 ⛔ 不等维护者原话」 and 「派发令写两者与推导…协调者照令开线程;常设原话有则作 reason:」).
  • dispatch-runbook.md and execution-duties.md: edited in place, same line count, every line ≤ 120 bytes.

Verification

Derived gate list (node scripts/pm/dispatch-gates.mjs --commands, 17 commands) run on head 08225fc; results are in the review comment below.

Clause-②: no
Metadata-protocol: none

Human Minimum

  • 1. Schemas start as Zod; packages/spec holds no runtime logic. (n/a, no spec change)
  • 2. Every name I added uses the casing for its kind. (n/a)
  • 3. No formatter ran (markdown-only diff; eslint reads none of these files).
  • 4. One issue, one branch off an up-to-date main, one pull request.
  • 5. A change that publishes carries a changeset. (publishes nothing: skip-changeset)
  • 6. packages/spec touched: its generated artifacts are regenerated and committed. (n/a)
  • 7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
  • 8. Title, body and comments are in English (the 维护者速读 block and the verbatim ruling quotes excepted, per AGENTS.md Communication).
  • The Before Submitting list in CONTRIBUTING.md is done.

🤖 Generated with Claude Code

https://claude.ai/code/session_01L9qibvepenMLGwN7rQgFH4


Generated by Claude Code

A PR sat in merge conflict while its thread reported it was only waiting
on CI: conflict notices are best effort and often never arrive. Every look
at an open PR now reads mergeable_state beside the checks, a dirty PR is
merged with origin/main at once, and nobody (thread or coordinator) reports
"nothing needed from you" without a settled non-dirty reading.

Line-neutral per file: two landing-operations lines whose facts
platform-readings.md and AGENTS.md already carry, and one coordinator line
that dispatch-runbook.md carries, pay for the additions.

Claude-Session: https://claude.ai/code/session_01L9qibvepenMLGwN7rQgFH4
Co-authored-by: Claude <noreply@anthropic.com>
@objectstack-fleet objectstack-fleet Bot added the skip-changeset PR has no user-facing published change; bypasses the changeset gate label Oct 27, 2026
@github-actions github-actions Bot added size/s documentation Improvements or additions to documentation labels Oct 27, 2026
@objectstack-fleet

Copy link
Copy Markdown
Contributor Author

Local gates on head 08225fc1 — the full derived list from node scripts/pm/dispatch-gates.mjs --commands (17 commands), each run to completion after pnpm install --frozen-lockfile and pnpm --filter '@objectstack/lint...' build:

node scripts/check-closing-keyword-parity.mjs :: exit 0
node scripts/check-closing-keyword-parity.mjs --self-test :: exit 0
node scripts/check-comment-mask-corpus.mjs :: exit 0
node scripts/pm/check-harness-current.mjs --self-test :: exit 0
pnpm --filter @objectstack/lint run check:doc-formula-expressions :: exit 0
pnpm check:agent-test-spelling :: exit 0
pnpm check:cross-package-test-inputs :: exit 0
pnpm check:doc-authoring :: exit 0
pnpm check:driver-memory-census :: exit 0
pnpm check:gitlink-declared :: exit 0
pnpm check:nul-bytes :: exit 0
pnpm check:pm-governed-merges :: exit 0
pnpm check:pm-skill-id-lint :: exit 0
pnpm check:pm-skill-ratchet :: exit 0
pnpm check:refd-timer-probe :: exit 0
pnpm check:skill-frame-sync :: exit 0
pnpm check:watch-hint-literal :: exit 0

17/17 exit 0. git merge-tree against open PR #26598 (which also edits dispatch-runbook.md) writes a clean tree.


Generated by Claude Code

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

Labels

documentation Improvements or additions to documentation size/s skip-changeset PR has no user-facing published change; bypasses the changeset gate

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants