Skip to content

feat(work-ledger): track a PR item until it merges and wake the conductor when it lands - #36914

Closed
iamwhatever wants to merge 1 commit into
mainfrom
feat/pr-land-tracking-phase-a
Closed

iamwhatever wants to merge 1 commit into
mainfrom
feat/pr-land-tracking-phase-a

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A conductor's PR item stays open until its pull request merges, and the conductor is woken when it lands, with no new instruction in its prompt (Decision A of rfc-conductor-pr-land-tracking).

A worker pushes its PR green and reports done; the conductor closes the item at green and never learns whether the PR merged, because the work-ledger probe reads no PR state.

Why it matters

Landed and abandoned work was found late or never (#36540 and #36507 were found merged only by forced floor turns). The repository owner asked for a capability, not more prompt text.

Not a goal

  • Decision B of the RFC (the floor-wake fact digest). It is a later PR.
  • The gateway closing items on a merge. 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)

Part Change
Bar A pr_checks bar with a repo is stored as pr_merged with ready: "pr_checks"; the record reply says acceptance_rewritten. "until": "checks" opts out. A bar with no repo reads land_untracked.
Worker work_brief carries ready_when: "pr_checks", so the worker is done at green.
Awaiting land Open + pr_merged + worker done + verdict pending reads awaiting_land and does not count toward the goal's concurrency cap.
Probe One batched GraphQL read per tick (gh_pr.fetch_states, 20 PRs per query, same transport). Wakes once on merged or closed; for an awaiting item, on a conflict or a red rollup per head. Backs off at the rate-limit floor until the reset.
Evaluator accept_eval pr_merged names an open PR's stage (ready, running, red, conflicting, draft) in its evidence.

Where: the rewrite and awaiting_land in work_ledger_rules.py (exported by src/kiro_crew/work_ledger.py), applied in work_ledger_writes.py; the batched read in probes/gh_pr.py and the wakes in probes/work_ledger.py (wired in probes/__init__.py), their brief in ledger_wake.py; the row flags and record reply in dashboard/handlers/work_ledger_read.py and dashboard/handlers/work_ledger_conductor.py; the tool text in mcp_work.py and work_vocab.py; the evaluator in both builtin_skills/*/scripts/accept_eval.py.

Both conductors get it with no rule change: the bar is rewritten by the store, and Ultra Mode and Bot conductors share the probe, ledger, evaluator and ACCEPTANCE_SHAPES. The goal-conductor skill, docs/work-ledger.md, the session spec and the RFC (now in-progress) describe it. The worker and conductor job-tool budgets in test_job_tools.py rise by 50 for the two new description sentences.

Cost: one GraphQL query per conductor per 300 s tick with a PR item, about 12 points an hour; the operator's gh bucket, not the Actions token.

Backwards compatibility

Breaking: a new pr_checks bar with a repo is stored as pr_merged, so an item written that way no longer passes at green. Writer sweep on origin/main @ 6fa4982: every create and accept through apply_conductor_action / apply_acceptance_update (both conductors' work_ledger_record); create_bound_item (remote peer) stores the hub's already-rewritten bar verbatim; stored items keep their bar. Tests that pinned the verbatim pr_checks shape now use pr_merged or until: "checks".

Removes nothing: no field, route or key is removed; the change adds a stored form and three read flags.

Tests

test/test_work_ledger_land_tracking.py (new): the rewrite and its opt-outs, TBD promotion, ready_when, awaiting_land, the cap count, fetch_states batching, invalid-pair filtering and rate-limit backoff, the four wakes (once per fact, per head), unread and untracked PRs, and that a brief carries no PR text. test/test_accept_eval_pr_merged.py: the new argv, the stage text, and that both skills ship the same evaluator.

Determinism: the new file passed 5 repeats and a reversed-order run.

Related backend tests run locally: 4,783 passed (flock, -n 2). semgrep is not installed on this host, so the diff-scoped scan did not run locally.

Manual verification

The GraphQL shape was run live against #36507 and #36618 for the RFC (#36753). It returned state, mergeable, head and rollup state, with X-Ratelimit-Resource: graphql.

Related Issues

Part of #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
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 1ef5948cd874faa2798bde93f54b33a152075d70 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 1ef5948cd874faa2798bde93f54b33a152075d70 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

No design-level concerns block this. The rewrite happens in the store, a batched read is added to the existing probe, and the change follows the RFC's Decision A.

Notes

  • An item awaiting_land holds no concurrency seat but still counts toward the store's 32-item open bound. If a human sits on merges, a board can fill with PRs nobody is merging and refuse new creates. When that refusal fires, its error text should name the awaiting-land items.
  • A PR that stays open forever keeps its item open forever, and nothing wakes on that. Only merged, closed, conflict and red wake anyone. That gap belongs to Decision B, the floor-wake fact digest, and is worth stating in the RFC.

[DESIGN-REVIEWED] 1ef5948

Description read

[DESCRIPTION-READ] c35b50b25a6adf45cd6632a1273dd494eb39ce2d20dc684c3dcd2fefaa649ac5

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

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 1ef5948cd874faa2798bde93f54b33a152075d70 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks: the accepted base RFC rfc-conductor-pr-land-tracking covers the default rewrite of pr_checks. Two fields of the batched read are never read by anything this PR adds.

Notes

  • Item 6 — zero consumers: _state_facts returns "merged_at" and "draft", but the probe only reads state, mergeable, head and rollup. Grepping the patch for merged_at and "draft" finds 0 readers outside the definition. Their only use is Decision B, which the description says "is a later PR". Subtraction: delete mergedAt, isDraft and the two dict keys from _STATES_FIELDS and _state_facts, and add them back with the floor digest.

What this change ships

Inventory (8 items) — 7 justified

Intent: a conductor learns when a worker's PR actually merges, closes, conflicts or goes red, without extra prompt text. ADDITION.

  1. A pr_checks bar with a repo is now stored as pr_merged + ready: "pr_checks" (changed default; opt out with until: "checks") — justified
  2. The record reply and the tool text say the bar was rewritten (acceptance_rewritten) — justified
  3. The worker's work_brief shows ready_when, so the worker is done at green — justified
  4. Ledger rows show awaiting_land and land_untracked — justified
  5. An awaiting-land item no longer takes a seat under the goal's concurrency cap — justified
  6. The work-ledger watch reads PR state for every tracked item in one batched GraphQL query per tick, backing off at the rate-limit floor — zero consumers for merged_at/draft
  7. The conductor is woken once on merged or closed, and once per head on a conflict or a red rollup — justified
  8. accept_eval pr_merged evidence now names the open PR's stage — justified

[FIRST-PRINCIPLES-REVIEWED] 1ef5948

Description read

[DESCRIPTION-READ] 86c3034a9579c73843f5c9f2c4c7c19a962fd0c90dd4cce21271ddea7af96184

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description 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 1ef5948cd874faa2798bde93f54b33a152075d70 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 1ef5948

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

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 1ef5948cd874faa2798bde93f54b33a152075d70 — this comment is updated in place on each push.

Review details

No findings.

Notes:

  • src/kiro_crew/docs/work-ledger.md:43 still says acceptance is "stored verbatim", and line 342 still says a goal holds "at most concurrency_cap items open at once". Both are now out of date because land_bar rewrites pr_checks bars and items marked is_awaiting_land no longer count toward the cap. The paragraph this PR adds states both exceptions, so a reader sees both versions.

[OPUS-REVIEWED] 1ef5948

Verdict parsed from the review's SHA-scoped output markers for commit 1ef5948cd874faa2798bde93f54b33a152075d70.

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

@iamwhatever
iamwhatever force-pushed the feat/pr-land-tracking-phase-a branch from 6b78ceb to af2c00a Compare November 13, 2026 23:27
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • Second copy of the repo regex — duplicate span=e607583283a0

fixed in af2c00a: gh_pr._REPO_RE is deleted; fetch_states validates with ACCEPTANCE_GH_REPO imported from work_ledger_records, so the ledger and the batched read share one pattern. Test test_fetch_states_uses_the_ledgers_own_repo_pattern pins it.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • One unresolvable PR stops wakes for the board span=70b42392ff93

fixed in af2c00a: on a non-zero exit that is not a rate limit, fetch_states still parses the answer, keeps every alias that resolved and moves on to the next batch; only a rate-limit refusal stops the loop. Test test_an_unresolvable_pr_does_not_blind_the_rest_of_the_board covers a null alias with errors in batch one and a second batch still read.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 13, 2026
@iamwhatever
iamwhatever force-pushed the feat/pr-land-tracking-phase-a branch from af2c00a to 60c002e Compare November 13, 2026 23:39
@iamwhatever

iamwhatever commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor Author
  • Replacement PRs inherit the previous PR’s wake dedupe span=bd25b95e6287

fixed in 60c002e: every land-wake token is keyed on land:<repo>#<pr>, so a bar promoted to a replacement PR wakes on that PR's own merge, close, conflict or red. Test test_a_replacement_pr_closing_wakes_again.

@iamwhatever

iamwhatever commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor Author
  • An oversized PR number invalidates its entire batch span=57012a9f6703

fixed in 60c002e: fetch_states sends only 0 < pr <= MAX_PR (1e9, the ledger's own report bound, under GraphQL's 32-bit Int), so an impossible number never reaches the shared query. test_fetch_states_batches_twenty_per_query_and_skips_invalid_pairs adds 2**31.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 13, 2026
@iamwhatever
iamwhatever force-pushed the feat/pr-land-tracking-phase-a branch from 60c002e to 59b492a Compare November 14, 2026 00:31
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 14, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • Enterprise ledger PRs are polled on the public forge span=57012a9f6703

Rebutted: the github.com pin is the accepted design (rfc-conductor-pr-land-tracking §8 "One forge. GitHub hosts only, as gh_pr is"). An enterprise PR reads unread and wakes no one, so it fails closed while accept_eval still judges it; unpinning would let an ambient GH_HOST re-point a bare owner/name slug at another repository (gh_pr.py transport note), which is the worse failure.

@iamwhatever
iamwhatever force-pushed the feat/pr-land-tracking-phase-a branch from 59b492a to 1ef5948 Compare November 14, 2026 00:54
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • work_ledger_record reply drops acceptance_rewritten span=9ec3bfbb5a00

fixed in 1ef5948: the work_ledger_record reply adds a line when the route reports acceptance_rewritten (stored as pr_merged with ready=pr_checks; send "until": "checks" to keep green as the bar). Test test_a_create_reply_says_the_bar_was_stored_as_a_landed_one.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Nov 14, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Too specific to the case related with PR

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 14, 2026
iamwhatever added a commit that referenced this pull request Nov 15, 2026
The repository owner ruled the PR-specific land-tracking machinery over-engineered and closed its phase A code PR #36914 unmerged. Mark rfc-conductor-pr-land-tracking.md withdrawn so it no longer reads as an accepted decision, and add a withdrawn row to the RFC status vocabulary. Docs only; no behavior change.

Co-authored-by: Joe Guo <zejiangg@amazon.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant