Skip to content

armgit / mwmbl

Public Imported from GitHub
0

An open source, non-profit web search engine

Let the run own the pipeline, and keep in shell only what it cannot claim

Daoud Clarke64a56a377f83
diff --git a/.github/claude/finalise-pull-request.md b/.github/claude/finalise-pull-request.md
deleted file mode 100644
index 76f84bf..0000000
--- a/.github/claude/finalise-pull-request.md
+++ /dev/null
@@ -1,94 +0,0 @@
-# Push the branch and open or update the pull request
-
-You are Claude Code running in GitHub Actions, at the end of a pipeline. A build step
-committed a change on this branch and a review step may have committed more on top. You
-are the only step that is allowed to push.
-
-`ISSUE_NUMBER` is in the prompt; `$N` below means that number.
-
-## 1. Read what the earlier steps reported
-
-Each step of this pipeline is a fresh session, so the only thing you know about the two
-before you is what they wrote down. `BUILD_SUMMARY` and `REVIEW_SUMMARY` in the prompt are
-the paths of their final messages — the build step's, and the review step's. Read both.
-
-That is what the body describes, and it is the only honest source for it. An empty file
-means that step left no final message; write that it reported nothing rather than
-inventing what it might have found. Their claims about the gates are theirs, not yours:
-section 2 is where you measure that for yourself.
-
-## 2. Verify before you publish
-
-Nothing on this branch has been checked since the last commit landed, so check it:
-
-```
-make check
-uv run pytest
-```
-
-Both must pass. If either fails, **push nothing** — say exactly what fails in your final
-message and stop. A pull request that does not build blocks every later part of the issue,
-and a branch that was never pushed costs nothing to redo.
-
-## 3. Check the size budget
-
-```
-git diff --numstat origin/main...HEAD
-```
-
-Sum the added lines, ignoring `uv.lock`, `poetry.lock`, `devdata/`, `front-end/` build
-output and `docs/plans/`. Over 500 is a problem to report in the body, not to fix by
-rewriting the change at this stage — say so plainly so the reviewer can decide.
-
-## 4. Check the plan bookkeeping
-
-If `docs/plans/issue-$N-*.md` exists, the build step should have either appended ` (Done)`
-to exactly one section heading, or `git rm`-ed the file when it built the last section. If
-neither happened and this branch does implement a section, make that change now and commit
-it — otherwise the next run rebuilds the same section.
-
-A plan branch (`claude/issue-$N-plan`) adds the plan file and changes nothing else.
-
-## 5. Push
-
-```
-git push -u origin $(git branch --show-current)
-```
-
-If the build step said it rebased the branch, use `--force-with-lease` instead — a rebase
-cannot fast-forward. Otherwise never force-push.
-
-## 6. Open or update the pull request
-
-```
-gh pr list --head "$(git branch --show-current)" --state open --json number
-```
-
-**No open pull request:** create one.
-
-```
-gh pr create --title "<section title>" --body "<body>"
-```
-
-The body says what changed and why, how it was verified — quote the `make check` and
-`uv run pytest` results *you* just measured, not what an earlier step reported — what the
-review step changed and what it found and left alone, and ends with `Part of #$N`, or
-`Closes #$N` when this was the last section of the plan.
-
-For a plan branch, the title is `Plan: <issue title>` and the body is one paragraph on the
-approach and why it is split this way, then the sections with their line estimates, then
-`Part of #$N`. Merging it is what starts implementation, so make the trade-offs easy to
-review.
-
-**A pull request already open:** the push updated it. Comment on it instead, saying what
-these commits change, which piece of feedback each one answers, and anything raised that
-was deliberately not done and why. Do not rewrite the original body — a reviewer coming
-back wants to see what moved since they left, not a description that quietly changed under
-them.
-
-## Rules
-
-- Do not merge anything, do not close the issue, do not change labels.
-- Never write code here. If the gates fail, report it — fixing it is the build step's job
- on the next run, with a clean context and a proper budget.
-- Never describe a run as green when it is not.
diff --git a/.github/claude/implement-issue.md b/.github/claude/implement-issue.md
index ae4349b..8725b6c 100644
--- a/.github/claude/implement-issue.md
+++ b/.github/claude/implement-issue.md
@@ -4,9 +4,9 @@ You are Claude Code running in GitHub Actions on a fresh checkout of `main`, wit
project installed and a test database running. Your job is **one** commit: the next
unbuilt part of one issue, verified green.
-`ISSUE_NUMBER` is in the prompt; `$N` below means that number. Later steps in this job
-review what you commit and open the pull request, so commit and stop — see
-`.github/claude/coordinate.md` for the pipeline.
+`ISSUE_NUMBER` is in the prompt; `$N` below means that number. You are inside the run
+described by `.github/claude/run.md`: come back to its section 4 when you have committed,
+which is where the change is reviewed and handed to the publish step. Commit and stop.
## 1. Decide what to build
@@ -63,10 +63,10 @@ remainder rather than silently dropping the work.
git commit -m "<section title>"
```
-Stop there — do not push, do not open a pull request. Leave the finalise step what it
-needs for the body in your final message: what changed and why, how you verified it (the
-actual `make check` and `uv run pytest` results), and whether this was the last section of
-the plan, which decides between `Part of #$N` and `Closes #$N`.
+Stop there — do not push, do not open a pull request. Return to section 4 of
+`.github/claude/run.md`, which has the change reviewed and writes the pull request body.
+You need to carry this into it: what changed and why, how you verified it, and whether this
+was the last section of the plan, which decides between `Part of #$N` and `Closes #$N`.
## Rules
@@ -75,6 +75,6 @@ the plan, which decides between `Part of #$N` and `Closes #$N`.
maintainer merges the pull request — never part-way through this run.
- One section per run. Never bundle two sections into one pull request.
- Never `git push`, never `gh pr create`, do not merge anything, do not change labels.
-- If you cannot finish, commit nothing and explain in your final message. The review and
- finalise steps are skipped when there is no new commit, and a half-finished branch that
- reaches a pull request blocks every later part of the issue.
+- If you cannot finish, commit nothing and explain in your final message. Nothing is
+ published when there is no new commit, and a half-finished branch that reaches a pull
+ request blocks every later part of the issue.
diff --git a/.github/claude/plan-issue.md b/.github/claude/plan-issue.md
index 256dbc6..7cf4e11 100644
--- a/.github/claude/plan-issue.md
+++ b/.github/claude/plan-issue.md
@@ -4,9 +4,9 @@ You are Claude Code running in GitHub Actions on a fresh checkout of `main`. You
to turn one issue into a written plan: one commit adding exactly one file.
**Write no application code in this run.**
-`ISSUE_NUMBER` is in the prompt; `$N` below means that number. Later steps in this job
-review the plan and open the pull request, so commit and stop — see
-`.github/claude/coordinate.md` for the pipeline.
+`ISSUE_NUMBER` is in the prompt; `$N` below means that number. You are inside the run
+described by `.github/claude/run.md`: come back to its section 4 when you have committed,
+which is where the plan is reviewed and handed to the publish step. Commit and stop.
## 1. Understand the issue
@@ -56,10 +56,11 @@ git add docs/plans/issue-$N-<slug>.md
git commit -m "Plan issue #$N: <issue title>"
```
-Stop there — do not push, do not open a pull request. Leave the finalise step what it
-needs for the body in your final message: one paragraph on the approach and why it is
-split this way, then the sections with their line estimates. Merging that pull request is
-what starts implementation, so make the trade-offs easy to review.
+Stop there — do not push, do not open a pull request. Return to section 4 of
+`.github/claude/run.md`, which has the plan reviewed and writes the pull request body. You
+need to carry this into it: one paragraph on the approach and why it is split this way,
+then the sections with their line estimates. Merging that pull request is what starts
+implementation, so make the trade-offs easy to review.
## Rules
diff --git a/.github/claude/review-changes.md b/.github/claude/review-changes.md
index b4e7394..82371e3 100644
--- a/.github/claude/review-changes.md
+++ b/.github/claude/review-changes.md
@@ -1,8 +1,14 @@
# Review what was just committed
-You are Claude Code running in GitHub Actions, in a fresh context. Another run built the
-change on this branch; you have no memory of it and no stake in it. Your job is to find
-what is wrong with it and fix that, before a human ever sees it.
+You are a subagent, spawned by the run that built the change on this branch. You started
+cold: nothing of that run's reasoning reached you, and the prompt that spawned you is
+fixed text it was not allowed to add to. So you have no memory of the change and no stake
+in it, and the only account of it you are given is the diff itself. That is deliberate —
+it is the whole reason you exist as a separate context rather than as a second look by the
+run that wrote the code.
+
+Your job is to find what is wrong with the change and fix that, before a human ever sees
+it. You commit your own fixes: they do not need the agreement of the run that spawned you.
`ISSUE_NUMBER` is in the prompt; `$N` below means that number.
@@ -55,19 +61,20 @@ useful — a pointless commit costs a reviewer more than it saves.
## 4. Hand over
-Your final message is quoted in the pull request body. Say what you changed and why, and
-list anything you found but deliberately left alone — a real problem outside this
-section's scope belongs in the body as a note for the reviewer, or in the plan as a later
-section, not in this commit.
+Your final message is the only thing that reaches the run that spawned you, and through it
+the pull request body. Say what you changed and why, whether you committed, and list
+anything you found but deliberately left alone — a real problem outside this section's
+scope belongs in the body as a note for the reviewer, or in the plan as a later section,
+not in this commit.
## Rules
-- Never `git push`, never `gh pr create`, never merge. The finalise step pushes.
+- Never `git push`, never `gh pr create`, never merge. The publish step pushes.
- Never amend, rebase or reorder the commit you are reviewing. Add commits on top, so the
reviewer can see what the build did and what the review changed.
- Never weaken, skip or delete a test to make a gate pass. If a test is wrong, fix the
test and say so explicitly; if the code is wrong, fix the code.
-- Never touch the plan file. The build step already updated it, and changing it here would
- make the automation rebuild or skip a section.
+- Never touch the plan file. The run that built the change already updated it, and changing
+ it here would make the automation rebuild or skip a section.
- Stay inside the scope of the change you are reviewing. A refactor you would like is not
a review finding.
diff --git a/.github/claude/coordinate.md b/.github/claude/run.md
similarity index 56%
rename from .github/claude/coordinate.md
rename to .github/claude/run.md
index cc01b95..c24fea5 100644
--- a/.github/claude/coordinate.md
+++ b/.github/claude/run.md
@@ -1,26 +1,28 @@
-# Decide what this issue needs, and do it
+# Work on one issue
You are Claude Code running in GitHub Actions on a checkout of `main`, with the project
-installed and a test database up.
+installed and a test database up. You are the whole run: you decide what this issue needs,
+do it, have it reviewed, and leave the branch ready to publish.
-You are the **first step of a pipeline**. You commit your work on a `claude/issue-<N>-*`
-branch and stop there. A review step then reads what you committed in a fresh context and
-fixes what it finds, and a finalise step pushes the branch and opens or updates the pull
-request. So: **never `git push`, and never run `gh pr create`.**
+A shell step publishes afterwards — it re-runs both gates, pushes, and opens or updates the
+pull request from what you leave behind. **Never `git push`, and never run `gh pr create`.**
+That step is not a formality: it checks your work rather than taking your word for it, and
+it refuses to publish a branch you did not have reviewed.
-Committing is not the only thing you can do, though, and it is often not the useful one.
-Answering a question, saying what you could not work out, recording what you learnt on the
-issue and filing what you found but should not fix here are all first-class outcomes —
-section 2 lists them alongside the ones that write code.
+Committing is not the only thing you can do, and it is often not the useful one. Answering
+a question, saying what you could not work out, recording what you learnt on the issue and
+filing what you found but should not fix here are all first-class outcomes.
The prompt carries:
- `ISSUE_NUMBER` — `$N` below.
- `ITEM_KIND` — `plan`, `implement` or `respond`. This is what the selector read off
repository state. Treat it as the likely answer, not an order: it knows about labels,
- plan files, reviews and check results, and nothing at all about what the issue says.
+ plan files, reviews and check results, and nothing at all about what the issue says. If
+ the state calls for something else, say so in your final message and do the right thing.
- `PULL_REQUEST` — the open pull request's number for a `respond` item, `0` otherwise.
-- `REASON` — why a `respond` item was selected.
+- `REASON` — why the selector woke you.
+- `REPORT_DIR` — where section 4 writes the two files the publish step reads.
## 1. Read the state before choosing
@@ -39,8 +41,7 @@ For a `respond` item, also read everything said on the pull request:
## 2. Choose one action
-One action per run. Pick the one the state actually calls for — if that is not what
-`ITEM_KIND` suggested, say so in your final message and do the right thing anyway.
+One action per run. Pick the one the state actually calls for.
**Write a plan.** No plan file, and the issue is too big for one pull request. Follow
`.github/claude/plan-issue.md`.
@@ -67,9 +68,9 @@ the environment — say so on the pull request with the evidence and commit noth
than committing a change that pretends to fix it.
**Rebase onto main.** The branch conflicts. `gh pr checkout $PULL_REQUEST`, then
-`git rebase origin/main`, resolve, re-run both gates. Say in your final message that the
-branch was rebased, so the finalise step force-pushes rather than failing on a non-fast
--forward.
+`git rebase origin/main`, resolve, re-run both gates. Write `rebased: true` in the report
+file described in section 4, so the publish step force-pushes rather than failing on a
+non-fast-forward.
**Answer the question, and commit nothing.** The feedback asks about the change rather
than asking for a change to it: why it was done this way, whether something was
@@ -77,7 +78,9 @@ considered, what a test actually covers. Work the answer out from the code — n
the pull request body claims — and post it on the thread it was asked on:
```
-gh pr comment $PULL_REQUEST --body "..."
+gh pr comment $PULL_REQUEST --body "...
+
+<!-- claude-run: answer -->"
gh api repos/$REPOSITORY/pulls/comments/<comment-id>/replies -f body="..." # inline thread
```
@@ -104,19 +107,22 @@ not.
you noticed while reading the code, a request from a reviewer that belongs to a different
change. Search for it first with `gh issue list --search "<terms>" --state all`, then
`gh issue create`: say what you saw, where, and how you noticed it, and link this issue
-and the pull request. Leave it unlabelled. An issue reaches these queues only when
-someone with write access labels it, and an automation that could label its own would be
-feeding itself. At most one per run, and never for a style preference, for something a
-plan section already covers, or for anything you could simply have fixed here.
+and the pull request. Leave it unlabelled. An issue reaches these queues only when someone
+with write access labels it, and an automation that could label its own would be feeding
+itself. At most one per run, and never for a style preference, for something a plan
+section already covers, or for anything you could simply have fixed here.
+
+**Any comment you post on a pull request must end with an HTML comment starting
+`<!-- claude-run:`.** That is how the selector recognises its own voice, and how it knows
+this commit has already had its turn; without it the same red checks would wake a run on
+every trigger from here to eternity.
-Committing nothing is a valid outcome. The review and finalise steps are skipped when the
-run leaves no new commit, and on a pull request the workflow then comments to say the run
-changed nothing — which is also what stops the same red checks or the same unanswered
-review selecting this pull request on every trigger from here to eternity. Nothing else
-happens until a new commit lands or someone says something new, so whatever you post
-before you stop is all a human has to go on: make it specific.
+Committing nothing is a valid outcome. Nothing is published, and on a pull request the
+workflow comments to say the run changed nothing. Nothing else happens until a new commit
+lands or someone says something new, so whatever you post before you stop is all a human
+has to go on: make it specific.
-## 3. Both gates must pass before you stop
+## 3. Both gates must pass
Any action that changes code has to leave the branch green:
@@ -125,23 +131,55 @@ make check
uv run pytest
```
-`DATABASE_URL` and `DJANGO_SETTINGS_MODULE` are already set. Iterate until both pass. If
-something is genuinely beyond this change to fix, say exactly what fails and why in your
-final message — never describe a run as green when it is not.
+`DATABASE_URL` and `DJANGO_SETTINGS_MODULE` are already set. Iterate until both pass. The
+publish step runs them again and will not push if they fail, so a branch you leave red is
+simply a wasted run. If something is genuinely beyond this change to fix, say exactly what
+fails and why — never describe a run as green when it is not.
+
+## 4. Have the change reviewed, in a fresh context
+
+**If you committed anything, this section is not optional.** The publish step refuses to
+push a branch with no review report, so skipping it throws the run away.
+
+Spawn a subagent with the Agent tool and this prompt, verbatim, with `$N` substituted and
+nothing added:
+
+```
+Follow the instructions in .github/claude/review-changes.md exactly.
+
+ISSUE_NUMBER: $N
+```
+
+Nothing else. Do not tell it what you built, what you found hard, what you already
+checked, or what you would like it to conclude. It reads the diff cold, the way a reviewer
+does, and everything you add is you reviewing your own work through it. It has `Edit` and
+`Bash`, and it commits its own fixes: its findings do not need your agreement to land.
+
+When it returns, write two files under `$REPORT_DIR`:
+
+**`review.md`** — what the review reported, in its own terms: what it changed, what it
+found and left alone, and whether it committed. Where you think it was wrong, say so here
+and say why; do not quietly drop it. If it reported nothing, write that. Start the file
+with `rebased: true` on its own line if section 2 rebased the branch.
+
+**`pr-body.md`** — the pull request body, ready to post. What changed and why, how it was
+verified, what the review changed and what it left alone, what you deliberately did not
+do. End with `Part of #$N`, or `Closes #$N` when this finished the last section of the
+plan. For a plan branch, one paragraph on the approach and why it is split this way, then
+the sections with their line estimates, then `Part of #$N` — merging it is what starts
+implementation, so make the trade-offs easy to review.
-## 4. Hand over
+Do not claim a gate is green in `pr-body.md`. The publish step measures that itself and
+appends what it measured.
-Your final message is what the finalise step writes the pull request body from. Say which
-action you took and why, what changed, what you deliberately did not do, and the actual
-results of the two gates.
+## 5. Hand over
-If you committed nothing, no later step runs and nobody reads that message. Everything a
-human needs has to be in what you posted on the issue or the pull request before you
-stopped.
+Your final message goes in the job log, not the pull request. Say which action you took
+and why, what changed, what you deliberately did not do, and the results of both gates.
## Rules
-- Never `git push`. Never `gh pr create`. The finalise step does both.
+- Never `git push`. Never `gh pr create`. The publish step does both.
- Do not merge anything, and do not close the issue — the pull request closes it, by
saying `Closes #$N` when it finishes the last section of the plan.
- Do not add or remove labels, on this issue or on one you file. Labels are how a human
diff --git a/.github/scripts/classify-claude-run.sh b/.github/scripts/classify-claude-run.sh
index d21e7a6..b989dd2 100755
--- a/.github/scripts/classify-claude-run.sh
+++ b/.github/scripts/classify-claude-run.sh
@@ -12,6 +12,11 @@
# Any other failure belongs to this run. Repeating it every hour would spend the budget on
# the same mistake, so the issue is labelled "claude: stuck" and the selector skips it
# until a human removes the label or reruns that issue alone with workflow_dispatch.
+#
+# A publish step that refused counts as this run's failure too, and it is the one failure
+# the run log cannot show: publish-branch.sh rejects a branch whose gates fail or that has
+# no review report, both of which are the run's doing however cleanly the Claude step
+# ended. $PUBLISH_OUTCOME carries it in, as steps.publish.outcome.
set -euo pipefail
@@ -32,6 +37,10 @@ steps_matching() {
broken=$(steps_matching "($never_reached_model) | not")
out_of_credit=$(steps_matching "$never_reached_model")
+if [[ ${PUBLISH_OUTCOME:-} == failure ]]; then
+ broken="${broken:+$broken }publish"
+fi
+
if [[ -n $broken ]]; then
echo "::error::Claude failed in: $broken. Labelling issue #$issue '$stuck_label' so the" \
"scheduled runs stop retrying it; remove the label, or rerun this issue alone with" \
diff --git a/.github/scripts/publish-branch.sh b/.github/scripts/publish-branch.sh
new file mode 100755
index 0000000..d1e6812
--- /dev/null
+++ b/.github/scripts/publish-branch.sh
@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+#
+# Push the branch the run left behind, and open or update its pull request.
+#
+# This is the only thing that pushes, and it is a shell script rather than a Claude step
+# for two reasons.
+#
+# The first is that it is mechanical: verify, push, create or comment. The run that did
+# the work already knows everything a pull request body needs, so there is nothing left
+# here for a model to work out — it writes the body to a file in $REPORT_DIR and this
+# posts it.
+#
+# The second is the point. Everything after the run starts is the run's own account of
+# itself, and the two things that must be true before a change reaches a human are exactly
+# the two a self-report cannot establish: that the gates pass, and that somebody other than
+# the author looked at it. So this measures the gates itself rather than believing the
+# summary, and refuses to push at all unless the run left a review report — which only
+# .github/claude/review-changes.md, running as its own subagent, produces. A run that skips
+# the review does not get a shortcut; it gets nothing published.
+#
+# Nothing to publish is the ordinary outcome, not a failure: a run that answered a
+# question, asked one, or found the work already done leaves the branch exactly as it
+# found it, and this exits green having said so.
+
+set -euo pipefail
+
+readonly report_dir="${CLAUDE_REPORT_DIR:?}"
+readonly review_report="$report_dir/review.md"
+readonly body_file="$report_dir/pr-body.md"
+
+# Whether a pull request now carries this run's work. The workflow reads it to decide
+# whether to leave the "this run changed nothing" comment that bounds the retries.
+published() {
+ printf 'published=%s\n' "$1" >>"${GITHUB_OUTPUT:-/dev/stdout}"
+}
+
+branch=$(git branch --show-current)
+
+if [[ $branch != claude/* ]]; then
+ echo "::notice::Not on a claude/* branch; nothing to publish."
+ published false
+ exit 0
+fi
+
+# Measured against the branch's own published tip rather than against the commit the job
+# checked out. A respond run starts with `gh pr checkout`, which moves HEAD to commits that
+# are already pushed and already reviewed: comparing against where the job started would
+# call every one of those runs a build.
+published_tip="origin/$branch"
+if ! git rev-parse --verify --quiet "$published_tip" >/dev/null; then
+ published_tip=origin/main
+fi
+if [[ $(git rev-parse HEAD) == $(git rev-parse "$published_tip") ]]; then
+ echo "::notice::$branch is unchanged from $published_tip; nothing to publish."
+ published false
+ exit 0
+fi
+
+# The attestation. Not a formality: the review is a separate context precisely so that its
+# verdict is not the author's, and a report that does not exist is a review that did not
+# happen. Refusing here is what stops "I reviewed it" from being a claim the run can simply
+# make about itself.
+if [[ ! -s $review_report ]]; then
+ echo "::error::$branch has commits but no review report at $review_report." \
+ "Section 4 of .github/claude/run.md is not optional: a change is published only" \
+ "once a review subagent has read it in a fresh context. Pushing nothing."
+ exit 1
+fi
+if [[ ! -s $body_file ]]; then
+ echo "::error::$branch has commits but no pull request body at $body_file." \
+ "Section 4 of .github/claude/run.md writes it. Pushing nothing."
+ exit 1
+fi
+
+# The Claude GitHub App's token, as the Claude step's github_token output. Not the workflow
+# token: a push made with GITHUB_TOKEN does not trigger workflows, so the pull request this
+# opens would sit with no checks on it, forever, and the automation would never see CI go
+# red on its own branch. Unset means the app authentication the whole workflow assumes did
+# not happen, which is worth failing on rather than working around — but only once there is
+# something to push, so that a run with nothing to publish stays green regardless.
+readonly token="${GH_TOKEN:?}"
+# git prints the remote it failed to reach, and from here that remote carries the token.
+echo "::add-mask::$token"
+
+# Nothing on this branch has been checked since the last commit landed, and the run's own
+# account of the gates is the run's, not ours.
+echo "::group::make check"
+make check
+echo "::endgroup::"
+echo "::group::uv run pytest"
+uv run pytest
+echo "::endgroup::"
+
+# `grep -v` exits 1 when it filters everything out, which under pipefail would end the
+# script — and a plan branch, whose only file is under docs/plans/, hits that every time.
+added=$(git diff --numstat "origin/main...HEAD" \
+ | { grep -vE $'\t(uv\\.lock|poetry\\.lock|devdata/|front-end/|docs/plans/)' || true; } \
+ | awk '{ total += $1 } END { print total + 0 }')
+
+verified=$(cat <<EOF
+---
+\`make check\` and \`uv run pytest\` both pass, measured by the publish step after the
+review, on $(git rev-parse --short HEAD). Added lines outside lockfiles, \`devdata/\`,
+\`front-end/\` and \`docs/plans/\`: $added.
+EOF
+)
+
+# Reported rather than acted on: the change has already been reviewed, and cutting it back
+# now would mean republishing work nobody has looked at.
+if ((added > 500)); then
+ verified+=$'\n\n**This is over the 500-line budget.** Reported rather than trimmed here,'
+ verified+=$' because trimming it now would republish unreviewed work.'
+fi
+
+body=$(cat "$body_file")$'\n\n'"$verified"
+
+# actions/checkout leaves behind an http.extraheader carrying the workflow token, and it
+# takes precedence over every other credential git could find, so the app token has to
+# replace it rather than sit alongside it.
+# --unset-all exits 5 when the key is not there, which is the state it is trying to reach.
+git config --local --unset-all 'http.https://github.com/.extraheader' || true
+git remote set-url origin \
+ "https://x-access-token:${token}@github.com/${GITHUB_REPOSITORY:?}.git"
+
+# A rebase cannot fast-forward. The run says so on the first line of the review report,
+# which is the only place it is allowed to speak to this step.
+if head -1 "$review_report" | grep -qx 'rebased: true'; then
+ git push --force-with-lease -u origin "$branch"
+else
+ git push -u origin "$branch"
+fi
+
+existing=$(gh pr list --head "$branch" --state open --json number --jq '.[0].number // empty')
+
+if [[ -z $existing ]]; then
+ # The commit subject already names the work: an implementing run commits the plan
+ # section's title, a planning run commits "Plan issue #<N>: <title>".
+ gh pr create --title "$(git log -1 --format=%s)" --body "$body"
+else
+ # A reviewer coming back wants to see what moved since they left, not a description
+ # that quietly changed under them, so the original body stands and the update is a
+ # comment.
+ gh pr comment "$existing" --body "$body
+
+<!-- claude-run: update -->"
+fi
+
+published true
diff --git a/.github/scripts/record-claude-run.sh b/.github/scripts/record-claude-run.sh
index deb1ea7..7d6a245 100755
--- a/.github/scripts/record-claude-run.sh
+++ b/.github/scripts/record-claude-run.sh
@@ -1,26 +1,18 @@
#!/usr/bin/env bash
#
-# Append one Claude step's outcome and its result message to $CLAUDE_RUN_LOG, and leave
-# its final message where a later step can read it.
+# Append one Claude step's outcome and its result message to $CLAUDE_RUN_LOG.
#
-# claude-code-action writes every step's messages to the same path under $RUNNER_TEMP and
-# overwrites it, so a step's result has to be copied out before the next step runs. The
-# log this builds is what tells a step that never reached the model from one where Claude
-# ran and genuinely failed; see classify-claude-run.sh.
+# claude-code-action writes the step's messages to a path under $RUNNER_TEMP; the log this
+# builds pulls out just the result, which is what tells a step that never reached the model
+# from one where Claude ran and genuinely failed. See classify-claude-run.sh.
#
-# The final message is copied out for a second reason. Each step is a fresh session that
-# can see nothing of the one before it, and the finalise step is asked to write a pull
-# request body describing what the build and the review did — which it can only do if it
-# is handed what they said. Its prompt points at these files.
-#
-# $OUTCOME and $EXECUTION_FILE come from the step being recorded, as
-# steps.<id>.outcome and steps.<id>.outputs.execution_file.
+# $OUTCOME and $EXECUTION_FILE come from the step being recorded, as steps.<id>.outcome and
+# steps.<id>.outputs.execution_file.
set -euo pipefail
step="$1"
log="${CLAUDE_RUN_LOG:?}"
-summary_dir="${CLAUDE_SUMMARY_DIR:?}"
# A step that was skipped, or one that died before Claude produced anything, leaves no
# execution file. An empty result is how the classifier sees "nothing to go on".
@@ -32,8 +24,3 @@ fi
jq -nc --arg step "$step" --arg outcome "$OUTCOME" --argjson result "$result" \
'{step: $step, outcome: $outcome, result: $result}' | tee -a "$log"
-
-# An empty file rather than a missing one: the step that reads it should see that this
-# step reported nothing, not have to guess whether the path is right.
-mkdir -p "$summary_dir"
-jq -r '.result // ""' <<<"$result" >"$summary_dir/$step.md"
diff --git a/.github/scripts/report-no-change.sh b/.github/scripts/report-no-change.sh
index bc9e4d2..92dbea0 100755
--- a/.github/scripts/report-no-change.sh
+++ b/.github/scripts/report-no-change.sh
@@ -6,21 +6,37 @@
# functions of repository state, so a run that ends without committing leaves exactly the
# state that selected it: the same red checks, the same unanswered review. Without a record
# that the automation has already had its turn at this commit, the item would be selected
-# again on the next trigger and on every scheduled run after that, at three Opus steps a
-# time, for as long as the reason stood.
+# again on the next trigger and on every scheduled run after that, for as long as the
+# reason stood.
#
# So this is what bounds the retries: select-claude-work.sh stops counting failing checks
-# and conflicts once a report is newer than the last commit, and counts feedback only from
-# after it. A new commit, or a human replying, is what starts the pull request moving
-# again.
+# and conflicts once the automation has spoken about the current commit, and counts
+# feedback only from after that. A new commit, or a human replying, is what starts the pull
+# request moving again.
#
-# The marker string has to stay in step with the one select-claude-work.sh looks for.
+# A run that answered a question or asked one has already spoken, with a comment carrying
+# the same marker, so this stays quiet rather than saying it twice. The marker prefix has
+# to stay in step with the one select-claude-work.sh looks for.
set -euo pipefail
pull_request="${PULL_REQUEST:?}"
reason="${REASON:?}"
-readonly marker='<!-- claude-run: no change -->'
+readonly marker='<!-- claude-run:'
+
+# Piped through jq rather than gh's own --jq, which takes the expression alone and
+# rejects the --arg the marker needs.
+already_spoken=$(gh pr view "$pull_request" --json commits,comments \
+ | jq -r --arg marker "$marker" '
+ (.commits | last | .committedDate) as $commit
+ | [.comments[] | select(.body | contains($marker)) | .createdAt]
+ | max
+ | . != null and . > $commit')
+
+if [[ $already_spoken == true ]]; then
+ echo "::notice::The run already commented on #$pull_request; not saying it twice."
+ exit 0
+fi
gh pr comment "$pull_request" --body "This run looked at the pull request and left the
branch as it found it.
@@ -30,4 +46,4 @@ It was woken because: $reason.
It will not try again by itself at this commit — pushing a commit here, or replying, is
what wakes it.
-$marker"
+$marker no change -->"
diff --git a/.github/scripts/select-claude-work.sh b/.github/scripts/select-claude-work.sh
index a5a6ad3..c050179 100755
--- a/.github/scripts/select-claude-work.sh
+++ b/.github/scripts/select-claude-work.sh
@@ -1,29 +1,31 @@
#!/usr/bin/env bash
#
-# Pick the work items the Claude issue-automation workflow should act on.
+# Pick the issues the Claude automation should act on, and in what order.
#
-# An item is one issue plus the kind of attention it needs. The kinds are ordered so
-# that finishing something always beats starting something:
+# This is a cost gate, not an instruction. It answers one question — is it worth spending
+# a run on this issue at all — because deciding that needs to be cheap, and everything a
+# run does after that point costs Opus turns. What it works out about *what* an issue
+# needs is a hint: the run re-derives it from the thread, which the selector has never
+# read, and .github/claude/run.md tells it to overrule this when the two disagree.
#
-# respond an open claude/issue-<N>-* pull request needs a change: someone with
-# write access left feedback after the last commit, its checks are red, or
-# it no longer merges cleanly
-# implement the issue has a plan under docs/plans/ with a section not marked (Done),
-# or it is labelled "ready to code" and has no plan at all
+# So the kinds below order the queues and name the job; they do not direct the work.
+#
+# respond an open claude/issue-<N>-* pull request has something outstanding
+# implement a plan under docs/plans/ has a section not marked (Done), or the issue is
+# labelled "ready to code" and has no plan at all
# plan the issue is labelled "ready to plan" and has no plan yet
#
-# The queues are derived entirely from repository and issue state, never from a label the
-# automation has to remember to set, so a rerun after a failed job is harmless and a human
-# can redirect the work by editing a plan file or leaving a review.
+# Finishing beats starting, so respond items come first. The queues are derived entirely
+# from repository and issue state, never from a label the automation has to remember to
+# set, so a rerun after a failed job is harmless and a human can redirect the work by
+# editing a plan file or leaving a review.
#
-# Still one pull request at a time per issue: an issue with an open claude/issue-<N>-*
-# pull request can only produce a "respond" item, never a new branch. What changed is that
-# such an issue is no longer simply skipped — an unanswered review is the most valuable
-# thing the automation can pick up, because it is what a human is waiting on.
+# One pull request at a time per issue: an issue with an open claude/issue-<N>-* pull
+# request can only produce a "respond" item, never a new branch.
#
-# Pull requests from forks are not the automation's to work on and are ignored throughout,
-# branch name notwithstanding: a fork's branch is code nobody here has reviewed, and the
-# workflow could not check it out with a working token even if it wanted to.
+# Pull requests from forks are not the automation's to work on and are ignored throughout:
+# a fork's branch is code nobody here has reviewed, and the workflow could not check it
+# out with a working token even if it wanted to.
#
# The one label the automation writes is "claude: stuck", added by the workflow when a run
# fails for a reason that is not a usage limit. Items on a stuck issue are skipped so a
@@ -31,8 +33,7 @@
# reruns that issue alone with workflow_dispatch, which ignores it.
#
# Each kind is ordered by the "priority: high|medium|low" label before the queue is
-# truncated to CLAUDE_MAX_ITEMS, so raising an issue's priority moves it up. Issues without
-# a priority label sort last, behind "priority: low".
+# truncated to CLAUDE_MAX_ITEMS. Issues without a priority label sort last.
#
# Writes items_matrix (and has_items) to $GITHUB_OUTPUT, or to stdout when that is unset,
# so the selection can be dry-run locally with:
@@ -45,17 +46,20 @@ readonly plan_dir="docs/plans"
readonly max_items="${CLAUDE_MAX_ITEMS:-3}"
readonly only_issue="${CLAUDE_ONLY_ISSUE:-}"
+# Every comment the automation posts on a pull request carries this, so recognising its
+# own voice is a string test on text it wrote rather than a guess about authorship. That
+# matters: GraphQL hands a Bot actor a login without the "[bot]" suffix, so the obvious
+# test against gh's projection silently matches nothing and the automation reads its own
+# comments as a maintainer's. Kept in step with .github/scripts/report-no-change.sh and
+# .github/claude/run.md, which write it.
+readonly marker='<!-- claude-run:'
+
open_issues=$(gh issue list --state open --limit 200 --json number,title,labels)
open_pull_requests=$(gh pr list --state open --limit 200 \
--json number,headRefName,isCrossRepository \
--jq '[.[] | select(.isCrossRepository | not)]')
-# What a run that changed nothing leaves behind, so that it is not asked the same question
-# on the next trigger and every scheduled run after it. Written by
-# .github/scripts/report-no-change.sh — the two strings have to stay in step.
-readonly no_change_marker='<!-- claude-run: no change -->'
-
-# What needs answering on one open pull request, if anything.
+# Why one open pull request is worth waking a run for, or nothing if it is not.
#
# Feedback counts only from an OWNER, MEMBER or COLLABORATOR — a drive-by comment on a
# public repository must not be able to steer a run — and only when it is newer than the
@@ -63,59 +67,36 @@ readonly no_change_marker='<!-- claude-run: no change -->'
# carrying inline comments and no body still arrives as a review with a timestamp, so
# inline-only feedback is caught too.
#
-# The last thing a run said about the current commit bounds the retries. A run that ends
-# without committing changes nothing the queues are derived from, so failing checks it
-# could not fix, or a question it could not answer without guessing, would select this
-# pull request again on every trigger for as long as they stood. Once it has reported on a
-# commit, the mechanical reasons stop counting for that commit and only something said
-# after the report counts as feedback — a new commit, or a human replying, is what starts
-# it again.
-#
-# Comments and reviews come from the REST API rather than from `gh pr view`, which is the
-# only one of the two that says whether an author is a bot: GraphQL gives a Bot actor a
-# login without the "[bot]" suffix, so a suffix test against gh's projection silently
-# matches nothing and the automation reads its own comments as a maintainer's.
-#
-# Asked per pull request rather than across the list: `gh pr list --json commits` walks
-# every author of every commit of every open pull request, which exceeds GitHub's GraphQL
-# node limit on a repository this size.
-readonly reason_filter='
-def is_maintainer:
- (.author_association | . == "OWNER" or . == "MEMBER" or . == "COLLABORATOR")
- and (.user.type != "Bot");
-
-($state.commits | last | .committedDate) as $last_commit
-| ([ $comments[]
- | select(.user.type == "Bot")
- | select(.body | contains($marker))
- | .created_at ] | max) as $reported
-| ([ ($reviews[] | select(is_maintainer) | .submitted_at),
- ($comments[] | select(is_maintainer) | .created_at) ] | max) as $feedback
-| ($reported != null and $reported > $last_commit) as $already_reported
-| [ (if $feedback != null and $feedback > $last_commit
- and ($reported == null or $feedback > $reported)
- then "unanswered feedback" else empty end),
- (if $already_reported then empty
- else ([ $state.statusCheckRollup[] | select(.conclusion == "FAILURE") | .name ]
- | if length > 0 then "failing checks: " + join(", ") else empty end)
- end),
- (if $state.mergeable == "CONFLICTING" and ($already_reported | not)
- then "conflicts with main" else empty end) ]
-| join("; ")
+# The last thing the automation said about the current commit bounds the retries. A run
+# that ends without committing changes nothing the queues are derived from, so failing
+# checks it could not fix, or a question it could not answer without guessing, would
+# select this pull request again on every trigger for as long as they stood. Once it has
+# spoken about a commit, the mechanical reasons stop counting for that commit, and only
+# something said afterwards counts as feedback. A new commit, or a human replying, is what
+# starts it moving again.
+readonly wake_filter='
+def ours: (.body // "") | contains($marker);
+def maintainer:
+ (["OWNER", "MEMBER", "COLLABORATOR"] | index(.authorAssociation) != null)
+ and (.author.is_bot != true);
+def failing: [.statusCheckRollup[] | select(.conclusion == "FAILURE") | .name];
+
+(.commits | last | .committedDate) as $commit
+| ([.comments[] | select(ours) | .createdAt] | max) as $spoken
+| ([ (.comments[] | select(ours | not) | select(maintainer) | .createdAt),
+ (.reviews[] | select(maintainer) | .submittedAt) ] | max) as $feedback
+| if $feedback != null and $feedback > $commit
+ and ($spoken == null or $feedback > $spoken)
+ then "feedback nobody has answered"
+ elif $spoken != null and $spoken > $commit then empty
+ elif (failing | length) > 0 then "failing checks: " + (failing | join(", "))
+ elif .mergeable == "CONFLICTING" then "conflicts with main"
+ else empty end
'
-# `gh api --paginate` prints one JSON document per page, which jq -s puts back together.
-whole_of() {
- gh api "$1" --paginate | jq -s 'add // []'
-}
-
-reason_to_respond() {
- local state comments reviews
- state=$(gh pr view "$1" --json mergeable,statusCheckRollup,commits)
- comments=$(whole_of "repos/{owner}/{repo}/issues/$1/comments")
- reviews=$(whole_of "repos/{owner}/{repo}/pulls/$1/reviews")
- jq -nr --argjson state "$state" --argjson comments "$comments" \
- --argjson reviews "$reviews" --arg marker "$no_change_marker" "$reason_filter"
+reason_to_wake() {
+ gh pr view "$1" --json mergeable,statusCheckRollup,commits,comments,reviews \
+ | jq -r --arg marker "$marker" "$wake_filter"
}
pull_request_for() {
@@ -135,7 +116,7 @@ plan_file_for() {
}
# A plan is unfinished while it still has a "## PR <k>: ..." heading without the (Done)
-# suffix that the implementing PR appends.
+# suffix that the implementing pull request appends.
has_pending_section() {
local total done_count
total=$(grep -cE '^## PR [0-9]+:' "$1" || true)
@@ -171,7 +152,6 @@ while IFS=$'\t' read -r number title labels; do
fi
rank=$(priority_rank "$labels")
- plan_file=$(plan_file_for "$number")
emit() {
printf '%s\t%s' "$rank" "$(jq -nc \
@@ -181,9 +161,10 @@ while IFS=$'\t' read -r number title labels; do
}
pull_request=$(pull_request_for "$number")
+ plan_file=$(plan_file_for "$number")
if [[ -n $pull_request ]]; then
- reason=$(reason_to_respond "$pull_request")
+ reason=$(reason_to_wake "$pull_request")
if [[ -n $reason ]]; then
respond_items+=("$(emit respond "$pull_request" "$reason")")
else
diff --git a/.github/workflows/claude-issues.yml b/.github/workflows/claude-issues.yml
index c307d94..725f7dc 100644
--- a/.github/workflows/claude-issues.yml
+++ b/.github/workflows/claude-issues.yml
@@ -4,19 +4,26 @@ name: Claude issue automation
#
# A run picks up one issue and decides what it needs — write a plan, build the next part,
# answer a review, fix red checks, rebase, answer a question, ask one, or file what it
-# found and should not fix here — then builds it, reviews it in a fresh context, and opens
-# or updates the pull request. Changing no code is a normal outcome, and one a run says out
-# loud rather than ending in silence. The three Claude steps below are that pipeline;
-# .github/scripts/select-claude-work.sh decides what to point it at and .github/claude/*.md
-# is what each step is told. See docs/plans/README.md for the plan format the queues are
-# derived from.
+# found and should not fix here — then does it, has it reviewed in a fresh context, and
+# leaves a branch for the publish step. Changing no code is a normal outcome, and one a run
+# says out loud rather than ending in silence.
+#
+# There is one Claude step. It spawns the review as a subagent, which starts cold and
+# commits its own findings, so the fresh-context review costs a briefing rather than a
+# second action invocation. What is left in shell is only what a run cannot credibly say
+# about itself: which issues are worth spending a run on at all
+# (.github/scripts/select-claude-work.sh, before any model runs), and whether the gates
+# actually pass and a review actually happened (.github/scripts/publish-branch.sh, which is
+# the only thing that pushes). Everything between those two is the run's to decide, and
+# .github/claude/run.md is what it is told. See docs/plans/README.md for the plan format
+# the queues are derived from.
#
# Only one claude/issue-<N>-* pull request is ever open per issue. It no longer blocks the
# issue, though: while it is open the only thing the automation may do to that issue is
# answer what is holding the pull request up, which is what a human is actually waiting on.
#
-# Every step authenticates with the CLAUDE_CODE_OAUTH_TOKEN secret, a one-year token from
-# `claude setup-token`. It runs against a Claude subscription rather than API credit, so
+# The Claude step authenticates with the CLAUDE_CODE_OAUTH_TOKEN secret, a one-year token
+# from `claude setup-token`. It runs against a Claude subscription rather than API credit, so
# these runs share the usage windows of an interactive session, and the token has to be
# regenerated when it expires. A run that finds the window spent ends green and stays
# queued; see .github/scripts/classify-claude-run.sh.
@@ -141,7 +148,7 @@ jobs:
needs: select
if: needs.select.outputs.has_items == 'true'
runs-on: ubuntu-latest
- # Three Claude steps and up to four runs of a 67-second test suite.
+ # One Claude run, the review subagent inside it, and one run of a 67-second test suite.
timeout-minutes: 120
strategy:
fail-fast: false
@@ -152,7 +159,7 @@ jobs:
cancel-in-progress: false
name: "#${{ matrix.item.issue }} ${{ matrix.item.kind }}"
- # Claude has to get the same gates green before it opens a pull request as CI runs
+ # Claude has to get the same gates green before its branch is published as CI runs
# afterwards, so it needs the same database and toolchain as ci.yml's test job. The
# planning run gets it too: a plan is only as good as the facts behind it, and this
# lets it count lint violations and see what actually breaks rather than estimating.
@@ -172,21 +179,26 @@ jobs:
env:
ISSUE_NUMBER: ${{ matrix.item.issue }}
+ # The publish step runs the gates itself rather than believing the run's account of
+ # them, so it needs the same environment the run had.
+ DATABASE_URL: postgres://postgres:postgres@localhost:5432/test_mwmbl
+ DJANGO_SETTINGS_MODULE: mwmbl.settings_test
steps:
- # Both of these live outside the checkout. The review and finalise steps run git with
- # an unrestricted Bash tool and are asked to commit; a file sitting untracked in the
- # working tree is one `git add -A` away from being part of the pull request.
+ # These live outside the checkout. The run holds an unrestricted Bash tool and is
+ # asked to commit; a report file sitting untracked in the working tree is one
+ # `git add -A` away from being part of the pull request.
#
# They are set here rather than in the job's `env` above because the `runner` context
# does not exist at job level: a `${{ runner.temp }}` there is not an empty string but
# a workflow that fails to validate, which is what broke every run from 2f0de72 on.
- - name: Point the run log outside the checkout
+ - name: Point the run log and reports outside the checkout
run: |
echo "CLAUDE_RUN_LOG=$RUNNER_TEMP/claude-runs.jsonl" >>"$GITHUB_ENV"
- echo "CLAUDE_SUMMARY_DIR=$RUNNER_TEMP/claude-summaries" >>"$GITHUB_ENV"
- # Full history: every step diffs the branch against main, and the step below
- # compares HEAD against the branch's own remote tip.
+ echo "CLAUDE_REPORT_DIR=$RUNNER_TEMP/claude-reports" >>"$GITHUB_ENV"
+ mkdir -p "$RUNNER_TEMP/claude-reports"
+ # Full history: the run and the publish step both diff the branch against main, and
+ # the publish step compares HEAD against the branch's own remote tip.
#
# The ref is pinned because `pull_request` hands github.ref as refs/pull/<n>/merge:
# a ref GitHub stops guaranteeing once the pull request closes, and a snapshot of a
@@ -201,19 +213,16 @@ jobs:
- name: Set up the project
uses: ./.github/actions/setup-project
- # No github_token input on any Claude step: the action then authenticates as the
- # Claude GitHub App, which sets GH_TOKEN and the git credentials for Claude and,
- # unlike the workflow token, lets CI run on the pull requests it pushes.
+ # No github_token input: the action then authenticates as the Claude GitHub App,
+ # which sets GH_TOKEN and the git credentials for Claude and, unlike the workflow
+ # token, lets CI run on the pull requests this pushes.
#
- # continue-on-error throughout, so that the last step can classify how the run ended
- # rather than the job dying at the first red step with no explanation.
- - name: Decide what the issue needs and do it
- id: coordinate
+ # continue-on-error, so that the last step can classify how the run ended rather than
+ # the job dying here with no explanation. The publish step guards itself.
+ - name: Work on the issue
+ id: run
uses: anthropics/claude-code-action@v1
continue-on-error: true
- env:
- DATABASE_URL: postgres://postgres:postgres@localhost:5432/test_mwmbl
- DJANGO_SETTINGS_MODULE: mwmbl.settings_test
with:
# A subscription token from `claude setup-token`, not a Console API key: these
# runs draw on the same subscription as an interactive session, so they share
@@ -225,7 +234,7 @@ jobs:
allowed_bots: claude
display_report: true
prompt: |
- Follow the instructions in .github/claude/coordinate.md exactly.
+ Follow the instructions in .github/claude/run.md exactly.
ISSUE_NUMBER: ${{ matrix.item.issue }}
ISSUE_TITLE: ${{ matrix.item.title }}
@@ -233,119 +242,50 @@ jobs:
PULL_REQUEST: ${{ matrix.item.pr }}
REASON: ${{ matrix.item.reason }}
REPOSITORY: ${{ github.repository }}
+ REPORT_DIR: ${{ runner.temp }}/claude-reports
+ # Agent is the subagent tool section 4 of run.md needs; Task is what older
+ # releases of the CLI called it, and a name that matches nothing is inert.
claude_args: |
--model claude-opus-5
- --max-turns 120
- --allowedTools "Read,Glob,Grep,Edit,Write,TodoWrite,Bash"
- - name: Record the coordinate step
+ --max-turns 150
+ --allowedTools "Read,Glob,Grep,Edit,Write,TodoWrite,Bash,Agent,Task"
+ - name: Record the run
if: always()
env:
- OUTCOME: ${{ steps.coordinate.outcome }}
- EXECUTION_FILE: ${{ steps.coordinate.outputs.execution_file }}
- run: .github/scripts/record-claude-run.sh coordinate
+ OUTCOME: ${{ steps.run.outcome }}
+ EXECUTION_FILE: ${{ steps.run.outputs.execution_file }}
+ run: .github/scripts/record-claude-run.sh run
- # Derived from git state rather than from anything a step has to remember to set, so
- # a rerun is as harmless as the selector's queues are. A run that committed nothing —
- # it asked a question, answered one, or found the work already done — skips the rest
- # of the job.
- #
- # Measured against the branch's own published tip rather than against the commit this
- # job checked out. A `respond` run starts with `gh pr checkout`, which moves HEAD to
- # commits that are already pushed and already reviewed: comparing against where the
- # job started would call every one of those runs a build.
- - name: Did the run commit anything?
- id: built
- run: |
- branch=$(git branch --show-current)
- if [[ $branch != claude/* ]]; then
- echo "built=false" >>"$GITHUB_OUTPUT"
- echo "::notice::Not on a claude/* branch; nothing to review or push."
- exit 0
- fi
- published="origin/$branch"
- if ! git rev-parse --verify --quiet "$published" >/dev/null; then
- published=origin/main
- fi
- if [[ $(git rev-parse HEAD) == $(git rev-parse "$published") ]]; then
- echo "built=false" >>"$GITHUB_OUTPUT"
- echo "::notice::$branch is unchanged from $published; nothing to review or push."
- else
- echo "built=true" >>"$GITHUB_OUTPUT"
- fi
-
- # A fresh context is the whole point: this step has no memory of the reasoning that
- # produced the change, so it reads the diff the way a reviewer would. It is also why
- # the build step above is not simply told to check its own work.
- - name: Review the change
- id: review
- if: steps.built.outputs.built == 'true' && steps.coordinate.outcome == 'success'
- uses: anthropics/claude-code-action@v1
+ # The only step that pushes, and the only check on the run that is not the run's own
+ # account of itself: it re-runs both gates and refuses a branch with no review report.
+ # Skipped when the run itself failed — a run that died part-way through leaves a tree
+ # nobody has finished with, and republishing that is what this exists to prevent.
+ - name: Publish the branch
+ id: publish
continue-on-error: true
+ if: steps.run.outcome == 'success'
env:
- DATABASE_URL: postgres://postgres:postgres@localhost:5432/test_mwmbl
- DJANGO_SETTINGS_MODULE: mwmbl.settings_test
- with:
- claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
- allowed_bots: claude
- display_report: true
- prompt: |
- Follow the instructions in .github/claude/review-changes.md exactly.
+ # The Claude GitHub App's token, not the workflow token: a push made with
+ # GITHUB_TOKEN does not trigger workflows, so the pull request would open with no
+ # checks on it and CI could never go red on a branch the automation owns.
+ GH_TOKEN: ${{ steps.run.outputs.github_token }}
+ run: .github/scripts/publish-branch.sh
- ISSUE_NUMBER: ${{ matrix.item.issue }}
- ISSUE_TITLE: ${{ matrix.item.title }}
- REPOSITORY: ${{ github.repository }}
- claude_args: |
- --model claude-opus-5
- --max-turns 40
- --allowedTools "Read,Glob,Grep,Edit,Write,TodoWrite,Bash"
- - name: Record the review step
- if: always()
- env:
- OUTCOME: ${{ steps.review.outcome }}
- EXECUTION_FILE: ${{ steps.review.outputs.execution_file }}
- run: .github/scripts/record-claude-run.sh review
-
- # The only step allowed to push. It re-runs both gates first, so the pull request
- # body describes the code as it stands after the review rather than before it.
- #
- # The review step is continue-on-error, so a review that ran out of turns part-way
- # through a fix ends red having left the branch mid-change. Publishing that is the
- # "opens a pull request nobody reviewed" failure the review step exists to prevent,
- # so its outcome gates this step exactly as the build's does. When review is skipped
- # this step is skipped too: both are guarded on the same build.
- - name: Open or update the pull request
- id: finalise
+ # A run that changes nothing leaves the repository exactly as the selector found it,
+ # so the same red checks or the same unanswered review would select this pull request
+ # again on the next trigger, and on every scheduled run after that. This comment is
+ # the record that stops it; select-claude-work.sh reads it as "this commit has
+ # already had its turn".
+ - name: Say on the pull request that nothing changed
if: >-
- steps.built.outputs.built == 'true'
- && steps.coordinate.outcome == 'success'
- && steps.review.outcome == 'success'
- uses: anthropics/claude-code-action@v1
- continue-on-error: true
- env:
- DATABASE_URL: postgres://postgres:postgres@localhost:5432/test_mwmbl
- DJANGO_SETTINGS_MODULE: mwmbl.settings_test
- with:
- claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
- allowed_bots: claude
- display_report: true
- prompt: |
- Follow the instructions in .github/claude/finalise-pull-request.md exactly.
-
- ISSUE_NUMBER: ${{ matrix.item.issue }}
- ISSUE_TITLE: ${{ matrix.item.title }}
- REPOSITORY: ${{ github.repository }}
- BUILD_SUMMARY: ${{ runner.temp }}/claude-summaries/coordinate.md
- REVIEW_SUMMARY: ${{ runner.temp }}/claude-summaries/review.md
- claude_args: |
- --model claude-opus-5
- --max-turns 30
- --allowedTools "Read,Glob,Grep,Edit,Write,TodoWrite,Bash"
- - name: Record the finalise step
- if: always()
+ matrix.item.kind == 'respond'
+ && steps.run.outcome == 'success'
+ && steps.publish.outputs.published == 'false'
env:
- OUTCOME: ${{ steps.finalise.outcome }}
- EXECUTION_FILE: ${{ steps.finalise.outputs.execution_file }}
- run: .github/scripts/record-claude-run.sh finalise
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ PULL_REQUEST: ${{ matrix.item.pr }}
+ REASON: ${{ matrix.item.reason }}
+ run: .github/scripts/report-no-change.sh
- name: Upload the run log
if: always()
@@ -355,24 +295,9 @@ jobs:
path: ${{ runner.temp }}/claude-runs.jsonl
if-no-files-found: ignore
- # A run that changes nothing leaves the repository exactly as the selector found
- # it, so the same red checks or the same unanswered review would select this pull
- # request again on the next trigger, and on every scheduled run after that, at three
- # Opus steps a time. This comment is the record that stops it; select-claude-work.sh
- # reads it as "this commit has already had its turn".
- - name: Say on the pull request that nothing changed
- if: >-
- matrix.item.kind == 'respond'
- && steps.coordinate.outcome == 'success'
- && steps.built.outputs.built != 'true'
- env:
- GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- PULL_REQUEST: ${{ matrix.item.pr }}
- REASON: ${{ matrix.item.reason }}
- run: .github/scripts/report-no-change.sh
-
- name: Report how the run ended
if: always()
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ PUBLISH_OUTCOME: ${{ steps.publish.outcome }}
run: .github/scripts/classify-claude-run.sh