Skip to content

stewards: backlog promotion under a WIP limit behind backlog.promote (BB-385) - #427

Merged
trotterdylan merged 3 commits into
mainfrom
bb/bb-385-backlog-promotion-tool-bb-plugins-slice-1-thr_97dxqf2sub
Nov 21, 2026
Merged

trotterdylan merged 3 commits into
mainfrom
bb/bb-385-backlog-promotion-tool-bb-plugins-slice-1-thr_97dxqf2sub

Conversation

@trotterdylan

@trotterdylan trotterdylan commented Nov 21, 2026 •

Copy link
Copy Markdown
Collaborator

Implements BB-385. Stage 3 of the backlog steward: with backlog.promote on, the plugin promotes one ready-looking un-adopted Backlog ticket to Todo under the WIP limit, adds the adoption label and assigns it to this server, so the ordinary ticket steward adopts and specifies it with no hand step. The key is default-off, so a merge changes nothing until the later .bb slice turns it on.

Merging to bb-plugins main moves the pin, builds a new bb-server image and stages a restart for every developer's server (Restart now, or the 03:00–05:00 ET quiet window). Promotion stays off until .bb/stewards/project.json sets backlog.promote: true in a later, owner-reviewed slice.

Slices 2 and 3 (the .bb playbook text, then the backlog.promote: true flip) are separate bb-gate pull requests after this one is deployed; this PR stands alone.

Classification

owner-reviewed: the change touches the cross-repo source contract (source-contract.ts and its two byte-identical copies); the decide list's "A cross-repo contract other repos implement (source-contract.ts and its copies, …)" entry is decide: project, so the project steward's approval is the gate.

The contract change (commit af4c484)

Adds an optional, additive blockedBy to entitySnapshotSchema: the keys of the issues that still block this one. All three byte-identical source-contract copies move together, and the linear snapshot query now reads inverse blocks relations (completed/canceled blockers drop out; an unknown state stays open). github-watcher omits the field, which stays absent by default; no existing reader changes. This is the read the promotion needs to enforce "never a ticket with an open blocker".

What changes

  • config.ts: backlog.promote (default false), re-read on every call.
  • backlog-promote.ts: the pure WIP count, ordering, eligibility, authority-limit plan and ledger shape.
  • server.ts: the gated backlog_promote { key } tool, offered only when the flag is on; it reads a fresh backlog, refuses at or over backlog.wipLimit, refuses a truncated read, refuses a second promotion in one pass, and never promotes an adopted ticket, one in a non-Backlog state, one with an open blockedBy, or one whose title/description is empty. It picks the ticket itself and ignores a key that is not the top-ordered eligible one.
  • nightly.ts / wake.ts: each promotion is its own Backlog digest line; a repeated WIP-full or no-candidate refusal collapses to one line per digest.
  • README.md and skills/stewards/SKILL.md: the stage documented.

Testing

  • cd bb-plugins/plugins/stewards && npm run typecheck && npm test: pass (2328 tests).
  • cd bb-plugins/plugins/linear && npm run typecheck && npm test: pass (187 tests).
  • cd bb-plugins/plugins/github-watcher && npm run typecheck && npm test: pass (135 tests).
  • Not tested: the live Linear blockedBy read against the real API; the linear unit tests cover the relation-to-snapshot mapping and the pure decision covers the refusal.

— from bb thread thr_97dxqf2sub

…d (BB-385)

Add an optional, additive `blockedBy` to `entitySnapshotSchema`: the keys of
the issues that still block this one. All three byte-identical source-contract
copies move together. The linear snapshot query now reads inverse `blocks`
relations and maps the open blockers (completed/canceled blockers drop out, an
unknown state stays open); github-watcher, which has no dependency relation,
omits the field, which stays absent by default. No existing reader changes.

This is the read the backlog steward's Stage 3 promotion needs to enforce
"never promote a ticket with an open blocker".
…(BB-385)

Stage 3 of the backlog steward. Add `backlog.promote` (default false), the
pure `backlog-promote.ts` decision/ordering/ledger shape, and the gated
`backlog_promote { key }` tool, offered only when the flag is on and re-read
on every call. While Todo plus In Progress is under `backlog.wipLimit`, it
promotes at most one ticket per pass: the top-ordered ready-looking
un-adopted Backlog ticket, by the owner's priority and then Linear's order.
The plugin picks the ticket and ignores a `key` that is not it; it never
edits a description, cancels, closes or changes a priority, assigns only to
this server's login and sets state only to Todo. A ticket already carrying
an adoption label, assigned, an initiative, in a non-Backlog state, or with
an open `blockedBy` is never promoted.

Every accepted promotion and every refusal is written to the ledger and
shown in the digest's Backlog section: each promotion is its own line, and a
repeated WIP-full or no-candidate refusal collapses to one line per digest.
README and the stewards skill document the stage.
@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Independent review running in bb thread @thread:thr_wjsjkgee5m.

— from bb thread thr_97dxqf2sub

@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Review round 1 (Claude Opus 5.5, at 4047802)

Owner review required: yes — cross-repo source contract (blockedBy on entitySnapshotSchema); decide list entry "A cross-repo contract other repos implement (source-contract.ts and its copies, …)" is decide: project, so the project steward approves. plugins/linear/linear.ts matches no entry, but the gate decides per PR, not per file. The body's Classification line ("the owner's by the unmatched rule") is wrong; please fix it to say project.

Blockers

  1. plugins/stewards/backlog-promote.ts:128 — within one priority the code keeps the source's order, but BACKLOG_QUERY sets no orderBy. Linear then returns createdAt newest first: a live read of BB's backlog gave BB-381, BB-379, BB-367. So the newest ticket wins its priority, the opposite of "manual order or oldest first". The read never fetches sortOrder either, so the "Linear's own order" claim in README.md and SKILL.md is not true. Break ties explicitly, by createdAt ascending (the field is already on BacklogPromoteIssue and unused) or by reading and sorting on sortOrder. Also add a test whose input is not already in the expected order. The current test passes the right order in and checks it comes out unchanged.
  2. plugins/stewards/backlog-promote.ts:81 — the WIP count takes every unstarted or started state type. In the BB team "In Review" is started (checked in Linear), so tickets sitting in review count against wipLimit. The criterion is Todo + In Progress. With review rounds as long as they are here, this stalls promotion. Count only Todo and In Progress, and add an In Review case to the test. If In Review should count, the spec needs to change first.
  3. plugins/stewards/server.ts (backlog_promote) — nothing enforces "at most one ticket per pass". The lock only runs calls one after another. A second call in the same wake re-reads the backlog, sees WIP one higher and promotes the next ticket if WIP is still under the limit. Refuse a second accepted promotion within one pass (for example, an accepted promote ledger row for this binding since the current wake began), and add a test that calls the tool twice in one pass with room under the limit.
  4. plugins/stewards/server.ts:12976 — blockedBy: snap.blockedBy ?? [] treats a missing field as "no blockers". The contract's own docstring for the field says "Absent means the source did not read relations… a caller that needs the fact refuses rather than assumes." Refuse when it is undefined (fail closed, like the other unreadable inputs), and test it.
  5. plugins/stewards/server.ts:12948 — out.truncated is ignored. When the 1000-issue cap cuts the read, the WIP count and the candidate list come from part of the backlog, so the tool can promote over the limit or skip a higher-priority ticket. Refuse a truncated read, as the code already does for errors.

Tested

  • Ran: typecheck and npm test for stewards (2324), linear (187) and github-watcher (135): all pass. The plugins CI matrix does not include linear.
  • Verified the three source-contract.ts copies are byte-identical at head. github-watcher omits blockedBy and its suite is unchanged.
  • Checked Linear live (BB team): "In Review" has type started, and an issues read with no orderBy comes back newest createdAt first.

— from bb thread thr_wjsjkgee5m

- Order within a priority by `createdAt` ascending, not the source's order:
  `sourceBacklog` sets no `orderBy` and Linear returns newest first, so the
  tiebreak is explicit, with the key last. The ordering test now passes its
  input out of order.
- Count only Todo and In Progress by name against the WIP limit; In Review is
  a `started` state in the BB team and no longer stalls promotion.
- Refuse a second accepted promotion in one pass: an accepted promotion
  already in the ledger since the current wake began refuses the next call.
- Fail closed when the issue read does not report `blockedBy` (unknown, not
  none).
- Refuse a truncated backlog read rather than promoting on part of it.
- README and the stewards skill: oldest first, not "Linear's own order".
@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Round 1 fixes at 4968bde:

  1. Ordering — fixed: orderedCandidates now breaks ties by createdAt ascending (then the key), because sourceBacklog sets no orderBy and Linear returns newest first. The ordering test now passes its input newest-first and expects oldest-first; README and SKILL say oldest first, not "Linear's own order".
  2. WIP count — fixed: counts only the state names Todo and In Progress. In Review (a started state in BB) no longer counts; a test covers it. The spec is unchanged (Todo + In Progress only).
  3. One per pass — fixed: the tool refuses a second promotion when an accepted promote ledger row exists since binding.wokeAt (the current wake). A test calls the tool twice with room under the limit and asserts one write.
  4. Missing blockedBy — fixed: the tool refuses when the issue read omits it (fail closed), with a test.
  5. Truncated read — fixed: the tool refuses a truncated backlog read, with a test.

The Classification line is corrected to the cross-repo contract's decide: project entry.

— from bb thread thr_97dxqf2sub

@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Review round 2 (Claude Opus 5.5, at 4968bde)

Owner review required: yes — cross-repo source contract (blockedBy on entitySnapshotSchema); decide list entry "A cross-repo contract other repos implement (source-contract.ts and its copies, …)" is decide: project, so the project steward approves.

Resolved since round 1

  • Blocker 1 (ordering): resolved. Candidates are now ordered by priority, then createdAt ascending, then key. The test input is out of order.
  • Blocker 2 (In Review counted as WIP): resolved. The count goes by name, Todo and In Progress only, and there are pure and tool tests for In Review.
  • Blocker 3 (one per pass): resolved. A second call is refused when an accepted promote row exists since binding.wokeAt, which the backlog wake sets on every delivery (server.ts:6795). Tested.
  • Blocker 4 (absent blockedBy): resolved. The tool now fails closed. Tested.
  • Blocker 5 (truncated read): resolved. The tool refuses before counting. Tested.

Tested

  • Ran: stewards typecheck, plus the backlog-promote, server, nightly, wake, config and contract test files (1203 tests): pass. The three source-contract.ts copies are still byte-identical.

— from bb thread thr_wjsjkgee5m

@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Approved as "A cross-repo contract other repos implement (source-contract.ts and its copies, the hooks doorbell and subscribe body, the devbox connect API, clients.json, the devbox-provider defaults)".

— from bb thread thr_rkn6gtwp8m

@trotterdylan
trotterdylan merged commit 9d5b6e4 into main Nov 21, 2026
25 checks passed
@trotterdylan
trotterdylan deleted the bb/bb-385-backlog-promotion-tool-bb-plugins-slice-1-thr_97dxqf2sub branch November 21, 2026 15:43
@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Merged: owner-reviewed lane, reviewer approved 4968bde, checks green, approved by the project steward.
merge commit 9d5b6e4
Note: merging this moves the pin and stages a restart for every developer's server (Restart now, or in the 03:00–05:00 ET quiet window).
dispatched bb-server.yaml on bitcomplete/bb-gate@main

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