Skip to content

stewards: mark a project-steward merge ask as a workaround (BB-386) - #429

Merged
trotterdylan merged 2 commits into
mainfrom
bb/bb-386-fix-4-project-steward-cannot-invent-an-ow-thr_wci4qipgwv
Nov 22, 2026
Merged

trotterdylan merged 2 commits into
mainfrom
bb/bb-386-fix-4-project-steward-cannot-invent-an-ow-thr_wci4qipgwv

Conversation

@trotterdylan

Copy link
Copy Markdown
Collaborator

Implements BB-386 fix 4. When the project steward asks the owner to merge a pull request whose prGate is already met and whose decide list routes it to the project steward, the plugin marks the item as a workaround and attaches the gate's verdict, so the owner sees "gate met: no binding can merge" instead of a made-up reason. The item is never refused: the owner still receives it, marked. It covers a forwarded escalation and the project steward's own ask.

A merge to bb-plugins moves the BB_PLUGINS_REF pin, builds a new bb-server image, and stages a restart for every developer's server. The server restarts when the developer presses Restart now, or in the 03:00–05:00 quiet window.

Sibling PR: fixes 1–3 landed in #428.

Classification

owner-reviewed: the change is in the stewards plugin's escalation routing — it changes what reaches the user from the project steward. It touches no lane, gate rule or approval handling.

What changes

  • need-parts.ts: mergeWorkaroundParts builds the marker and the gate verdict, or null when the gate is not met or the decide list routes the pull request to the user.
  • server.ts: mergeWorkaroundFor finds the named pull request in the binding's snapshot, reads its gate through the single assessedGate site, and attaches the marker to the forwarded question (and the project steward's own ask).

Testing

  • npm run typecheck: pass.
  • npx vitest run: pass (2347 tests; the stewards suite is not in CI's matrix).
  • New tests in server.test.ts cover fix 4: the forwarded item is still delivered to the owner and carries the marker and verdict; no marker when the gate is not met; no marker when the decide list routes it to the user; and the project steward's own ask is marked too.
  • readability.test.ts guards the shown why/details.

Implements [BB-386](https://linear.app/bit-complete/issue/BB-386) fix 4: when
the project steward asks the owner to merge a pull request whose `prGate` is
already met and whose decide list routes it to the project steward, the plugin
marks the item as a workaround and attaches the gate's verdict, so the owner
sees "gate met: no binding can merge" instead of a made-up reason. The item is
never refused: the owner still receives it, marked. It covers a forwarded
escalation and the project steward's own `ask`.

> A merge to `bb-plugins` moves the `BB_PLUGINS_REF` pin, builds a new
> `bb-server` image, and stages a restart for every developer's server. The
> server restarts when the developer presses Restart now, or in the
> 03:00–05:00 quiet window.

Sibling PR: fix 1-3 landed in #428.

## Classification
owner-reviewed: the change is in the stewards plugin's escalation routing —
it changes what reaches the user from the project steward. It touches no
lane, gate rule or approval handling.

## What changes
- `need-parts.ts`: `mergeWorkaroundParts` builds the marker and the gate
  verdict, or null when the gate is not met or the decide list routes the
  pull request to the user.
- `server.ts`: `mergeWorkaroundFor` finds the named pull request in the
  binding's snapshot, reads its gate through the single `assessedGate` site,
  and attaches the marker to the forwarded question (and the project
  steward's own `ask`).

## Testing
- `npm run typecheck`: pass.
- `npx vitest run`: pass (2347 tests; the stewards suite is not in CI's matrix).
- New tests in `server.test.ts` cover fix 4: the forwarded item is still
  delivered to the owner and carries the marker and verdict; no marker when
  the gate is not met; no marker when the decide list routes it to the user;
  and the project steward's own `ask` is marked too.
- `readability.test.ts` guards the shown `why`/`details`.
@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Independent review running in bb thread @thread:thr_igp4um8r89.

— from bb thread thr_wci4qipgwv

@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Review round 1 (Claude Opus 5.5, at a13aad9)

Owner review required: yes. This changes what reaches the user from the project steward. The BB-386 spec approval (limit 3) puts it under "The stewards plugin's roles parsing, ready gate and escalation routing", which is decide: user, even though the paths match only the project stewards entry. @trotterdylan, this one needs your approval. The escalation is binding: a project-steward bb-approval will not meet the gate, and your unsigned approval will.

Blockers

  1. plugins/stewards/server.ts:14152 (mergeWorkaroundFor), used at :14311 and :14722. The marker goes on any question or forwarded escalation whose url is a gate-met, project-routed PR, not only on a request to merge it. The ticket and the task limit fix 4 to "asking the owner to merge". Take a blocked, scope or decision escalation about a gate-met PR that has nothing to do with the merge, such as "add the repo secret before this deploys" or "the requester also wants X, include it?". The forward replaces its why (and drops forwardWhy(entry)) with "Workaround: … the owner's merge is not the gate" and "no owner approval or merge is needed". A secret ask with the PR url gets the same text. That is the made-up-reason problem turned around: the plugin now tells the owner something false about a legitimate ask. Fix: mark only a merge ask. Two signals would do it: a stuck escalation with data.pullStuck === "gate-met", or a question or choice that names a merge (the incident's "Merge PR stewards: retry a lost adoption wake for an unthreaded binding (BB-92) #119?", and your test's ["Merge", "Close"]). Add a test showing that a non-merge question about the same gate-met PR stays unmarked and keeps its original why.

Suggestions

  • need-parts.ts:151: the "verdict" is a fixed string plus the lane, and nothing checks the claim "no binding can merge". In your own forward test, ENG-12 is open and bound, so it can merge. Build the verdict from the gate you already read: the head sha it was met at, the lane and the decide mark. Point at the real path (bb stewards merge <key>) rather than asserting no binding can.
  • The ask path is marked only when the project steward passes url. The incident's ask ("Merge PR stewards: retry a lost adoption wake for an unthreaded binding (BB-92) #119?") may well have had none. Fall back to a PR key in the question text that matches one of the binding's observed pulls, so the case the ticket was filed for is caught.

Tested

  • Ran: stewards npm run typecheck and npm test (56 files, 2347 tests, pass). CI's matrix job for stewards was still running when I posted.

— from bb thread thr_igp4um8r89

…round 1)

Address the reviewer's round 1:
- Only mark an ask to merge. A gate-met `stuck` escalation, or a question or
  choice that names a merge, is a merge ask; an unrelated question about the
  same gate-met pull request keeps its own why.
- Build the verdict from the gate (head sha, lane, decide mark) and point at
  the real path (`bb stewards merge <key>`) instead of asserting no binding
  can merge.
- Find the pull request by a key in the question when the ask carries no url.
- Add tests for the non-merge question staying unmarked and for the
  url-less ask.
@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Round 1 addressed at 19e465b.

Blocker 1 — mark only a merge ask: fixed. asksToMerge gates the marker: a stuck escalation with data.pullStuck === "gate-met", or a question or choice that names a merge. An unrelated question about the same gate-met pull request keeps its own why. New test: "leaves an unrelated question about the same gate-met pull request unmarked and keeps its why" — a forwarded decision escalation "Add the repo secret before this deploys?" keeps forwardWhy(entry).

Suggestion — verdict from the gate, point at the real path: fixed. mergeWorkaroundParts now takes the head sha and builds gate met at <short-sha> (<lane>), decide: <mark>; the why and details point at bb stewards merge <key> rather than claiming no binding can merge.

Suggestion — fall back to a PR key in the question: fixed. referencedPull matches the url, a key or url in the question text, or a bare #N when exactly one observed pull has that number. New test: the url-less ask "Merge acme/web#7?" is marked.

Tested: npm run typecheck pass; npx vitest run pass (2349 tests; the stewards suite is not in CI's matrix).

— from bb thread thr_wci4qipgwv

@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Review round 2 (Claude Opus 5.5, at 19e465b)

Owner review required: yes. This changes what reaches the user from the project steward. The BB-386 spec approval (limit 3) puts it under "The stewards plugin's roles parsing, ready gate and escalation routing", which is decide: user. @trotterdylan, this one needs your approval. The escalation is binding: a project-steward bb-approval will not meet the gate, and your unsigned approval will.

Resolved since round 1

  • Blocker 1 (the marker went on non-merge asks) is resolved by 19e465b. asksToMerge limits it to a gate-met stuck escalation or a question or choice that names a merge. The new test shows an unrelated question about the same gate-met PR stays unmarked and keeps its entry why.
  • Both suggestions were taken. The verdict now comes from the gate (head sha, lane, decide mark) and names bb stewards merge <key>. The PR is also found by a key in the question text, with a test for an ask that has no url.

Tested

  • Ran: stewards npm run typecheck and npm test (56 files, 2349 tests, pass; not in CI's matrix).

— from bb thread thr_igp4um8r89

@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Approved 19e465b from the Stewards page

@trotterdylan
trotterdylan merged commit 5840d83 into main Nov 22, 2026
25 checks passed
@trotterdylan
trotterdylan deleted the bb/bb-386-fix-4-project-steward-cannot-invent-an-ow-thr_wci4qipgwv branch November 22, 2026 00:17
@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Merged: owner-reviewed lane, reviewer approved 19e465b, checks green, approved by the owner, escalated by the reviewer to the owner.
merge commit 5840d83
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