Skip to content

Commit 02ddb25

Browse files
phernandezphernandez
committed
docs(ci): explain bm bossbot pr flow
Covers the required BM Bossbot Approval status, exact-head-SHA behavior, Tests-before-Bossbot sequencing, review-thread gating (unresolved threads block approval; resolution restores it for the same head SHA), the PR image's content-not-verdict theming, managed PR body blocks, the companion Codex skills, and troubleshooting. Signed-off-by: phernandez <paul@basicmachines.co>
1 parent ca9a4d9 commit 02ddb25

1 file changed

Lines changed: 185 additions & 0 deletions

File tree

‎docs/bm-bossbot-pr-flow.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# BM Bossbot PR Flow
2+
3+
BM Bossbot is the required merge gate for Basic Memory pull requests. It reviews
4+
the latest pull request head SHA after the regular test workflow succeeds, then
5+
sets the `BM Bossbot Approval` commit status for that exact SHA.
6+
7+
The generated PR image is non-gating. It is there to make the PR easier to scan,
8+
not to decide whether the PR can merge.
9+
10+
## Quick Start
11+
12+
1. Work from a feature branch, not `main`.
13+
2. Run the local verification that matches the change.
14+
3. Commit with sign-off:
15+
16+
```bash
17+
git commit -s -m "docs(ci): explain bm bossbot pr flow"
18+
```
19+
20+
4. Push the branch and open a PR with a semantic title.
21+
5. Wait for the `Tests` workflow to pass.
22+
6. Wait for the `BM Bossbot Approval` status to turn green for the current head
23+
SHA.
24+
7. Merge only after normal CI and BM Bossbot are both green.
25+
26+
If a new commit is pushed, the old BM Bossbot approval no longer counts. Wait
27+
for Bossbot to review the new head SHA.
28+
29+
## Using The PR Skill
30+
31+
Codex can run the repo-local PR skill from a feature branch:
32+
33+
```text
34+
$pr-create
35+
$pr-create "Italian movie poster"
36+
$pr-create "80's action movies"
37+
```
38+
39+
Use the plain form when you only want the PR workflow. Pass a theme when you
40+
want the non-gating PR image to use a particular visual direction.
41+
42+
The skill:
43+
44+
- checks branch state, GitHub auth, commit sign-offs, and PR title shape,
45+
- pushes the branch,
46+
- creates or reuses the PR,
47+
- adds an optional image theme block when a theme was supplied,
48+
- watches the `BM Bossbot Approval` status,
49+
- never merges and never enables auto-merge.
50+
51+
The optional theme block is managed in the PR body:
52+
53+
```markdown
54+
<!-- BM_INFOGRAPHIC_THEME:start -->
55+
Italian movie poster
56+
<!-- BM_INFOGRAPHIC_THEME:end -->
57+
```
58+
59+
The theme is creative direction only. It does not affect tests, review, merge
60+
eligibility, or the required status check.
61+
62+
The image depicts the content of the pull request — its title, description,
63+
and change shape (labels, linked issues, commit subjects, changed files) —
64+
never the review outcome. Approval stamps, verdicts, and badges are
65+
deliberately excluded from the imagery.
66+
67+
## What BM Bossbot Does
68+
69+
BM Bossbot runs from trusted repository code on `main`. It does not checkout or
70+
execute untrusted PR head code. Instead, it collects PR metadata and diff context
71+
through the GitHub API, gives that sanitized context to Codex, and validates the
72+
structured review output deterministically.
73+
74+
Bossbot can approve only when all of these are true:
75+
76+
- the `Tests` workflow succeeded for the current PR head SHA,
77+
- the PR is not a draft,
78+
- the PR author is an owner, member, or collaborator,
79+
- Codex returned valid review JSON,
80+
- `reviewed_head_sha` matches the current PR head SHA,
81+
- `review_complete` is true,
82+
- `verdict` is `approve`,
83+
- there are no blocking findings,
84+
- every review thread on the PR is resolved — open inline comments (from
85+
Codex or humans) block approval until they are addressed and resolved.
86+
87+
The required status context is:
88+
89+
```text
90+
BM Bossbot Approval
91+
```
92+
93+
## When Bossbot Runs
94+
95+
The automatic workflow starts after the `Tests` workflow completes successfully
96+
for a PR. This saves review tokens when normal CI is already failing.
97+
98+
You can also rerun it manually from GitHub Actions:
99+
100+
1. Open the `BM Bossbot` workflow.
101+
2. Choose `Run workflow`.
102+
3. Enter the PR number.
103+
104+
Manual runs still require a successful `Tests` workflow for the current head
105+
SHA.
106+
107+
## Review Threads Re-Gate The Approval
108+
109+
Review activity re-evaluates the approval without re-running the full review:
110+
111+
- a new review, inline comment, or unresolved thread flips
112+
`BM Bossbot Approval` to failure for the current head SHA,
113+
- resolving the last open thread restores a previously earned approval for
114+
that same head SHA,
115+
- thread resolution alone can never upgrade a review that did not approve.
116+
117+
This means a PR cannot merge while reviewer feedback is sitting unaddressed,
118+
even if the approval was green when the feedback arrived.
119+
120+
## PR Body Blocks
121+
122+
Bossbot writes a managed review summary into the PR body:
123+
124+
```markdown
125+
<!-- BM_BOSSBOT_SUMMARY:start -->
126+
...
127+
<!-- BM_BOSSBOT_SUMMARY:end -->
128+
```
129+
130+
After approval, the assets job may publish a non-gating PR image and image
131+
provenance:
132+
133+
```markdown
134+
<!-- pr-infographic:start -->
135+
![BM Bossbot image for PR #123](...)
136+
<!-- pr-infographic:end -->
137+
138+
<!-- BM_INFOGRAPHIC_PROVENANCE:start -->
139+
...
140+
<!-- BM_INFOGRAPHIC_PROVENANCE:end -->
141+
```
142+
143+
The image provenance records choices like image mode, theme source, selected
144+
visual direction, model, size, and quality. It intentionally does not dump the
145+
full image prompt into the PR description.
146+
147+
Image generation failures do not block `BM Bossbot Approval`.
148+
149+
## Fixing A PR After Bossbot Runs
150+
151+
If Bossbot requests changes:
152+
153+
1. Read the blocking findings in the PR body.
154+
2. Fix the issue locally.
155+
3. Run targeted verification.
156+
4. Commit with sign-off and push.
157+
5. Reply to and resolve the review threads you addressed.
158+
6. Wait for `Tests` to pass.
159+
7. Wait for Bossbot to approve the new head SHA.
160+
161+
Codex can use the companion skill:
162+
163+
```text
164+
$fix-pr-issues
165+
```
166+
167+
That flow collects review findings, failed checks, and PR comments, applies
168+
fixes, verifies them, pushes the branch, and waits for the new Bossbot review.
169+
170+
## Troubleshooting
171+
172+
- `BM Bossbot Approval` is expected but not reported yet: the `Tests` workflow
173+
may still be running or may have failed.
174+
- Bossbot skipped the PR: check whether the PR is a draft, whether tests passed
175+
for the current head SHA, and whether the author is an owner, member, or
176+
collaborator.
177+
- The image is missing but approval is green: check the `BM Bossbot Assets` job.
178+
The image is non-gating, so this should not block merge.
179+
- The PR changed after approval: push invalidates the old approval. Wait for the
180+
new head SHA to be reviewed.
181+
- A manual Bossbot run will not replace failed tests. It only runs after a
182+
successful `Tests` workflow exists for the current head SHA.
183+
- Approval flipped to failure after a review comment: address the feedback,
184+
then resolve the threads — the approval for the same head SHA is restored
185+
automatically once no unresolved threads remain.

0 commit comments

Comments
 (0)