diff --git a/docs/bm-bossbot-pr-flow.md b/docs/bm-bossbot-pr-flow.md new file mode 100644 index 00000000..9130c6eb --- /dev/null +++ b/docs/bm-bossbot-pr-flow.md @@ -0,0 +1,184 @@ +# BM Bossbot PR Flow + +BM Bossbot is the required merge gate for Basic Memory pull requests. It reviews +the latest pull request head SHA after the regular test workflow succeeds, then +sets the `BM Bossbot Approval` commit status for that exact SHA. + +PR images are generated on demand only (see `scripts/generate_pr_infographic.py`); +the automated per-PR image job was removed because it consumed API tokens on +every Bossbot run. Images are never part of merge eligibility. + +## Quick Start + +1. Work from a feature branch, not `main`. +2. Run the local verification that matches the change. +3. Commit with sign-off: + + ```bash + git commit -s -m "docs(ci): explain bm bossbot pr flow" + ``` + +4. Push the branch and open a PR with a semantic title. +5. Wait for the `Tests` workflow to pass. +6. Wait for the `BM Bossbot Approval` status to turn green for the current head + SHA. +7. Merge only after normal CI and BM Bossbot are both green. + +If a new commit is pushed, the old BM Bossbot approval no longer counts. Wait +for Bossbot to review the new head SHA. + +## Using The PR Skill + +Codex can run the repo-local PR skill from a feature branch: + +```text +$pr-create +$pr-create "Italian movie poster" +$pr-create "80's action movies" +``` + +Use the plain form when you only want the PR workflow. Pass a theme when you +want an on-demand PR image to use a particular visual direction. + +The skill: + +- checks branch state, GitHub auth, commit sign-offs, and PR title shape, +- pushes the branch, +- creates or reuses the PR, +- adds an optional image theme block when a theme was supplied, +- watches the `BM Bossbot Approval` status, +- never merges and never enables auto-merge. + +The optional theme block is managed in the PR body: + +```markdown + +Italian movie poster + +``` + +The theme is creative direction only. It does not affect tests, review, merge +eligibility, or the required status check. + +The image depicts the content of the pull request — its title, description, +and change shape (labels, linked issues, commit subjects, changed files) — +never the review outcome. Approval stamps, verdicts, and badges are +deliberately excluded from the imagery. + +## What BM Bossbot Does + +BM Bossbot runs from trusted repository code on `main`. It does not checkout or +execute untrusted PR head code. Instead, it collects PR metadata and diff context +through the GitHub API, gives that sanitized context to Codex, and validates the +structured review output deterministically. + +Bossbot can approve only when all of these are true: + +- the `Tests` workflow succeeded for the current PR head SHA, +- the PR is not a draft, +- the PR author is an owner, member, or collaborator, +- Codex returned valid review JSON, +- `reviewed_head_sha` matches the current PR head SHA, +- `review_complete` is true, +- `verdict` is `approve`, +- there are no blocking findings, +- every review thread on the PR is resolved — open inline comments (from + Codex or humans) block approval until they are addressed and resolved. + +The required status context is: + +```text +BM Bossbot Approval +``` + +## When Bossbot Runs + +The automatic workflow starts after the `Tests` workflow completes successfully +for a PR. This saves review tokens when normal CI is already failing. + +You can also rerun it manually from GitHub Actions: + +1. Open the `BM Bossbot` workflow. +2. Choose `Run workflow`. +3. Enter the PR number. + +Manual runs still require a successful `Tests` workflow for the current head +SHA. + +## Review Threads Re-Gate The Approval + +Review activity re-evaluates the approval without re-running the full review: + +- a new review, inline comment, or unresolved thread flips + `BM Bossbot Approval` to failure for the current head SHA, +- resolving the last open thread restores a previously earned approval for + that same head SHA, +- thread resolution alone can never upgrade a review that did not approve. + +This means a PR cannot merge while reviewer feedback is sitting unaddressed, +even if the approval was green when the feedback arrived. + +## PR Body Blocks + +Bossbot writes a managed review summary into the PR body: + +```markdown + +... + +``` + +If an image was generated on demand, it is published with provenance: + +```markdown + +![BM Bossbot image for PR #123](...) + + + +... + +``` + +The image provenance records choices like image mode, theme source, selected +visual direction, model, size, and quality. It intentionally does not dump the +full image prompt into the PR description. + +Images and their provenance never affect `BM Bossbot Approval`. + +## Fixing A PR After Bossbot Runs + +If Bossbot requests changes: + +1. Read the blocking findings in the PR body. +2. Fix the issue locally. +3. Run targeted verification. +4. Commit with sign-off and push. +5. Reply to and resolve the review threads you addressed. +6. Wait for `Tests` to pass. +7. Wait for Bossbot to approve the new head SHA. + +Codex can use the companion skill: + +```text +$fix-pr-issues +``` + +That flow collects review findings, failed checks, and PR comments, applies +fixes, verifies them, pushes the branch, and waits for the new Bossbot review. + +## Troubleshooting + +- `BM Bossbot Approval` is expected but not reported yet: the `Tests` workflow + may still be running or may have failed. +- Bossbot skipped the PR: check whether the PR is a draft, whether tests passed + for the current head SHA, and whether the author is an owner, member, or + collaborator. +- No PR image: expected — images are on-demand only and never block merge. +- The PR changed after approval: push invalidates the old approval. Wait for the + new head SHA to be reviewed. +- A manual Bossbot run will not replace failed tests. It only runs after a + successful `Tests` workflow exists for the current head SHA. +- Approval flipped to failure after a review comment: address the feedback, + then resolve the threads — the approval for the same head SHA is restored + automatically once no unresolved threads remain.