Skip to content

docs(rfc): track a PR item until it lands and give the forced floor wake live facts - #36753

Merged
bolichen97 merged 1 commit into
mainfrom
docs/rfc-pr-land-tracking
Nov 13, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
docs/rfc-pr-land-tracking

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record the design that keeps a conductor's PR item open until the pull request merges, wakes the conductor when it lands, and gives a forced floor wake live facts to act on.

A worker pushes its PR green and reports done. The conductor closes the item at green and never learns whether the PR merged: the work-ledger probe reads no PR state. A quiet-floor wake re-sends the same patrol text with no facts, so the forced turn has nothing to check or correct with. On 2026-11-13 items for #36529 and #36302 were closed at green, and #36540 and #36507 were found merged only by floor turns.

Why it matters

The repository owner asked for a capability, not more instructions. Without it, every conductor relies on prompt text to remember to re-check merges, and finds landed work late or never.

Not a goal

  • Any code or skill change. The code follows in three phase PRs that rebase onto this document.
  • The gateway closing items on its own; the conductor stays the only verdict writer.
  • A webhook, a new tool, status, item state, event kind or config key.

What changed (motivation → approach → change)

One new RFC, docs/request-for-change/rfc-conductor-pr-land-tracking.md, with its row in docs/request-for-change/README.md.

Part Decision
A. Bar pr_merged is the landed bar with an optional ready: "pr_checks": the worker reports done at green, the item passes only on merge. pr_checks with a repo is stored this way by default (opt-out until: "checks").
A. Awaiting land Open + pr_merged + worker done + pending, derived at read time. Leaves the goal's concurrency_cap, keeps the 32-item store bound.
A. Probe One batched GraphQL read per tick through gh_pr's transport. Wakes on merged, closed, conflicting or red, once per fact. About 12 queries an hour per conductor; backs off on rate-limit headers.
B. Floor digest A floor turn on a work-ledger watch carries one line per open item: PR state, worker running or idle, minutes since last report, transcript moved, and a fixed hint. Gateway facts only, at most 20 lines and 4,000 characters, reusing A's read.

It covers Ultra Mode and Bot conductors (same probe, ledger and evaluator), lists the tests each phase carries, the GitHub cost, known limits, and a phased rollout with A first. It links rfc-work-ledger-resource-pressure.md, rfc-conductor-drift-check.md and #36507.

Backwards compatibility

Compatible: docs only; no code reads the new document.

Removes nothing: the diff adds one file and one index row.

Tests

Proof: not provable -- docs or config only

./scripts/docs-lint.sh passes locally ("All documentation checks passed").

Manual verification

The batched GraphQL shape in §3.4 was run live against #36507 and #36618: it returned state, mergeable, head and checkRunCountsByState, with X-Ratelimit-Resource: graphql headers.

Related Issues

Closes #36751

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality (N/A: docs only)
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 13, 2026 16:58
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 13, 2026
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 083451078433f2753d51e25864cb8d3b7ec96705 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 083451078433f2753d51e25864cb8d3b7ec96705 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 083451078433f2753d51e25864cb8d3b7ec96705 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Docs-only RFC with a bounded, phased, revertible design; nothing blocks.

Notes

  • §3.2 rewrites a pr_checks bar to pr_merged by default. Together with the 24 h pending_overdue path in §3.3, an item whose PR waits more than a day for human review gets re-armed and then closed abandoned. Phase 2 should either exclude awaiting-land items from that budget or state that this is intended.
  • §8 accepts that the rollup counts non-required checks, so land:red can fire on a PR that is mergeable. The digest's -> reseed hint then points at the wrong action. Consider giving red the wait/decide hint when mergeable is MERGEABLE, until the required-contexts upgrade lands.

[DESIGN-REVIEWED] 0834510

Description read

[DESCRIPTION-READ] 449a48ca82c5cd394ff52984626694af607d91042aa4b734cda6f8302a381558

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 083451078433f2753d51e25864cb8d3b7ec96705 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 0834510

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 083451078433f2753d51e25864cb8d3b7ec96705 false-positive: <reason, 20 to 500 characters>

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: Approve

Why: the decider estimates a 10% chance that this change introduces a defect, within the 12% limit for approving on its own, and every check passes.

Docs-only RFC plus one index row. I checked its claims about current code against repo/ and they hold: _pr_merged exists in both accept_eval.py copies; ACCEPTANCE_READ_FIELDS["pr_merged"] is ("pr","repo") and the concreteness check reads only those fields, so extra ready metadata is ignored; is_stale treats a done-with-pending item as the conductor's move; PENDING_BUDGET_SECS, MAX_ITEMS_PER_CONDUCTOR, MAX_WAKE_BRIEF_CHARS, _RATE_LIMIT_FLOOR and the quiet floors match; WorkLedgerProbe.observe reads no PR state; _work_ledger_wake_text returns "" when nothing is owed; _spend gives the once-per-token dedupe the design relies on; gh_pr._Transport handles rate-limit headers and calls GitHub through run_gh. Trust: wakes and the digest carry only ids, enums and numbers, keep the documented pointer-not-board rule, never ride a steer, and the conductor stays the only verdict writer. Lifecycle, restart, rollout/revert and rate-limit handling are covered. Front matter and the index row follow the sibling drift-check RFC's accepted-on-owner-request pattern.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit e5bd1c0901 · 344 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 083451078433f2753d51e25864cb8d3b7ec96705 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 0834510

Verdict parsed from the review's SHA-scoped output markers for commit 083451078433f2753d51e25864cb8d3b7ec96705.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 083451078433f2753d51e25864cb8d3b7ec96705 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 13, 2026
@bolichen97

Copy link
Copy Markdown
Contributor

Review brief. I read the whole diff (the new RFC and its README row). It is docs only, and all 96 checks are green. I am leaving this as a comment, not an approval, because it is a design decision for the maintainer to sign.

  • What: (A) a PR item's bar becomes "merged": pr_checks with a repo is stored as pr_merged with a ready stage, the worker still reports done at green, and an awaiting_land item leaves the concurrency cap. The work-ledger probe reads every open PR item in one batched GraphQL call per tick and wakes the conductor on merged, closed, conflicting or red. (B) A forced floor wake carries a bounded per-item digest of gateway facts (ids, enums, numbers, times only, at most 20 lines and 4,000 characters), so the turn has something to act on. Three phases, A first.
  • Pros: a conductor learns when a PR lands without a new instruction, a worker stops polling through the merge, and a floor turn can close, re-seed or drift-read from facts. The conductor stays the only verdict writer. Wake text holds no PR-authored or worker-authored prose, so it adds no prompt-injection surface.
  • Cons: the default acceptance bar for new items moves from green to merged, so an item stays open until someone merges (opt-out until: "checks", and 24 h pending is still re-armed once, then closed). The rollup counts every check, so a red non-required lane wakes once per head. One extra GitHub query per conductor per tick, about 12 an hour.
  • Tech debt: two named shortcut: limits (no repo means no watch, rollup state instead of required checks), and an in-memory digest and transcript length that reset on restart.
  • Recommendation: merge once the maintainer signs the direction. I found no security change: it is read-only GraphQL with the operator's existing gh login, with repo and pr validated before the query.

I did not check the code references against main at the stated audit sha.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Approving. This is the same head I read in full earlier, and all 96 checks are green. It is docs only: the new RFC and its README row. It changes no code and adds no security surface.

Condition for the implementation PR (phase 2, the default bar): items that already exist with a pr_checks bar keep their current meaning and are not rewritten. Only items created after the change default to "merged". The opt-out until: "checks" must be documented in the goal-conductor skill, next to the two lines that now call pr_checks the common case. The RFC's section 7 already says phase 2 rewrites only new writes, so this pins that sentence in the code PR and its tests.

Direction signed by maintainer (bolichen97).

@iamwhatever
iamwhatever force-pushed the docs/rfc-pr-land-tracking branch from e5bd1c0 to 218e043 Compare November 13, 2026 19:27
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/request-for-change/README.md since this head went green (ee52eac -> 39fd360); CI re-running.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Nov 13, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Approving again on the new head. The author rebased onto main after my first approval, and I compared the two saved diffs: the RFC file is the same, and only the neighbouring rows of the README table moved. Checks on this head are still starting and none is red.

The condition from my first approval stands for the implementation PR: items that already exist with a pr_checks bar keep their current meaning and are not rewritten, only items created after the change default to "merged", and the opt-out until: "checks" is documented in the goal-conductor skill.

Direction signed by maintainer (bolichen97).

@bolichen97
bolichen97 enabled auto-merge (squash) November 13, 2026 19:28
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Coverage Gate red on 218e043 is main's, not this docs-only PR: 75.7% src/kiro_crew/agent_ipc_client.py (87/115), a file this PR does not touch. Fixed by #36804 (open); this PR rebases onto it once it merges.

@iamwhatever
iamwhatever force-pushed the docs/rfc-pr-land-tracking branch from 218e043 to 0834510 Compare November 13, 2026 20:26
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased onto af8d570, which carries the Coverage Gate fix #36804 (39fd360 -> af8d570); docs unchanged, CI re-running.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 13, 2026
@bolichen97
bolichen97 merged commit 7b455df into main Nov 13, 2026
154 of 159 checks passed
@bolichen97
bolichen97 deleted the docs/rfc-pr-land-tracking branch November 13, 2026 22:27
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 13, 2026
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.

Conductor: track a PR item until it merges, and give the forced floor wake live facts

3 participants