|
|
|
@@ -131,9 +131,10 @@ and watch the check fail.
|
|
|
|
|
|
|
|
|
|
**Do not push `main` to `gh/main`.** Each agent's work reaches GitHub as its own
|
|
|
|
|
branch and its own pull request, and lands on `main` by being merged there, once
|
|
|
|
|
CI is green and an adversarial review agent has passed the PR's head SHA. The
|
|
|
|
|
orchestrator does not integrate agent branches locally: its `main` only
|
|
|
|
|
fast-forwards to `gh/main` after a merge. The procedure is
|
|
|
|
|
CI is green and an adversarial review agent has passed the PR's head SHA. An ADR
|
|
|
|
|
PR also needs the user's explicit approval, and nothing else stands in for it:
|
|
|
|
|
"ADR pull requests" below. The orchestrator does not integrate agent branches
|
|
|
|
|
locally: its `main` only fast-forwards to `gh/main` after a merge. The procedure is
|
|
|
|
|
`.agents/skills/wave/SKILL.md`, "Shepherding". `origin` and `gitea` are mirrors
|
|
|
|
|
and take `main` directly.
|
|
|
|
|
|
|
|
|
@@ -184,8 +185,8 @@ earlier head, and the finding may already be fixed — verify rather than assume
|
|
|
|
|
in either direction.
|
|
|
|
|
|
|
|
|
|
Reviews arrive **as the owner's quota allows**, so absence is not evidence.
|
|
|
|
|
Wait where a review is plausible, and when one is found, answer it on the
|
|
|
|
|
thread even if the PR has already merged: that is where the next reader looks.
|
|
|
|
|
Wait where a review is plausible. How a review is answered once found, by the
|
|
|
|
|
author and by a reviewer, is `.agents/skills/wave/agent-rules.md`, "GitHub".
|
|
|
|
|
|
|
|
|
|
**Copilot is not reviewing this repository, and the request is a silent no-op.**
|
|
|
|
|
Measured 2026-09-20: PRs #12, #21 and #27 carry 2, 8 and 4 Copilot reviews; #61,
|
|
|
|
@@ -231,8 +232,8 @@ normally.)
|
|
|
|
|
|
|
|
|
|
Across four PRs Copilot has found genuine bugs and no false positives, so its
|
|
|
|
|
findings are worth the loop. **But judge each one against the repo's doctrine
|
|
|
|
|
rather than applying it reflexively**, and when you decline, reply on the thread
|
|
|
|
|
with the reason. The distinction that has mattered: a finding can be *correct*
|
|
|
|
|
rather than applying it reflexively**. How a declined finding is answered is
|
|
|
|
|
agent-rules, "GitHub". The distinction that has mattered: a finding can be *correct*
|
|
|
|
|
and still be wrong to fix in that PR. On #12, a non-ASCII `truncate` panic was
|
|
|
|
|
applied (byte-identical on ASCII, so it cost no evidence) while a hint-line
|
|
|
|
|
padding bug in the same file was declined — fixing it would have rewritten the
|
|
|
|
@@ -251,21 +252,30 @@ is to branch from `gh/main`, cherry-pick, open a follow-up PR, and delete the
|
|
|
|
|
stray re-creation. Check `gh pr view <n> --json state` *before* pushing a fix to
|
|
|
|
|
a PR you have not looked at in a few minutes, rather than after.
|
|
|
|
|
|
|
|
|
|
Merge only once a review has passed — an adversarial agent's while Copilot is
|
|
|
|
|
absent, and it must name the head SHA it reviewed. Prefer a **merge commit** —
|
|
|
|
|
Merge only once a review of the PR's current head has passed — an adversarial
|
|
|
|
|
agent's while Copilot is absent. What a review must state is agent-rules,
|
|
|
|
|
"GitHub". Prefer a **merge commit** —
|
|
|
|
|
`AGENTS.md` says merges over rebases, and a PR's commits are individually
|
|
|
|
|
meaningful.
|
|
|
|
|
|
|
|
|
|
### ADR pull requests
|
|
|
|
|
|
|
|
|
|
An ADR (`context/adr/`) merges on the user's approval, not on a review. The
|
|
|
|
|
steps, modelled on PR #122 (ADR 004):
|
|
|
|
|
**Only the user's explicit approval accepts an ADR (`context/adr/`), and only
|
|
|
|
|
it lets an ADR PR merge.** "An ADR isn't approved until I say it is" (the
|
|
|
|
|
user). Green CI, every review answered and a passing adversarial review
|
|
|
|
|
("Shipping a wave") are still required. They are gates, never approval: an ADR
|
|
|
|
|
PR that passes all of them is still unapproved and does not merge. The steps,
|
|
|
|
|
modelled on PR #122 (ADR 004):
|
|
|
|
|
|
|
|
|
|
1. The PR proposes the ADR with its **open questions numbered**.
|
|
|
|
|
2. The user answers them on the PR.
|
|
|
|
|
3. The answers are folded into the ADR, in a section headed **"What the user
|
|
|
|
|
decided"**.
|
|
|
|
|
4. The PR merges only after the user comments **"Approved"**.
|
|
|
|
|
4. The PR merges only after the user comments **"Approved"**, and only while
|
|
|
|
|
the gates above still hold. Nobody else's comment or review stands in for
|
|
|
|
|
it. "Read the PR's reviews before merging it" still
|
|
|
|
|
applies after the approval. On #122 the user's own review landed as the PR
|
|
|
|
|
merged.
|
|
|
|
|
|
|
|
|
|
### Never hand-edit `.beads/issues.jsonl`
|
|
|
|
|
|
|
|
|
@@ -296,7 +306,7 @@ bd show $(cat /tmp/bd-audit-ids.txt) 2>&1 \
|
|
|
|
|
|
|
|
|
|
`git ls-files` picks the files, and grep only reads them. The file list is the
|
|
|
|
|
tracked files plus the untracked ones, minus anything git ignores. That leaves
|
|
|
|
|
out three things a `grep -r` over the same roots reads:
|
|
|
|
|
out two things a `grep -r` over the same roots reads:
|
|
|
|
|
|
|
|
|
|
- **Build output.** After `./harness/build.sh`, `harness/serve/` holds
|
|
|
|
|
rendered copies of `context/`, and `grep -r` reported three dead ids from them
|
|
|
|
@@ -304,9 +314,16 @@ out three things a `grep -r` over the same roots reads:
|
|
|
|
|
- **Other agents' worktrees.** In the orchestrator's checkout
|
|
|
|
|
`.claude/worktrees/` holds every agent's worktree, dozens of copies of the
|
|
|
|
|
repository with their unpushed work.
|
|
|
|
|
- **The skills twice.** `.claude/skills/*` are symlinks to directories under
|
|
|
|
|
`.agents/skills/`. `-d skip` passes over them, so the skills are read once,
|
|
|
|
|
through `.agents`.
|
|
|
|
|
|
|
|
|
|
`-d skip` is there for the skills' symlinks, and it changes no answer. The
|
|
|
|
|
`.claude/skills/*` entries are symlinks to directories under `.agents/skills/`,
|
|
|
|
|
and `git ls-files` lists each one, so each reaches grep as a command-line
|
|
|
|
|
operand. The grep has no `-r`, so it never reads a directory operand. It prints
|
|
|
|
|
`grep: <path>: Is a directory` on stderr instead, and `-d skip` only silences
|
|
|
|
|
those lines. The output goes through `sort -u`, so a duplicate could not change
|
|
|
|
|
the answer anyway. Measured with BSD grep 2.6.0 and GNU grep 3.12: 3092 matches
|
|
|
|
|
with or without the flag, 462 distinct ids. Do not add `-r`: GNU grep then
|
|
|
|
|
follows those symlinks and reads the skills a second time (3107 matches).
|
|
|
|
|
|
|
|
|
|
Plain `git grep` is not a substitute: on macOS its `-E` silently ignores `\b`
|
|
|
|
|
and finds a fraction of the ids.
|
|
|
|
@@ -346,8 +363,10 @@ real defect through:
|
|
|
|
|
added to the exclusion list in the same commit**, or it arrives as a dead id
|
|
|
|
|
that no amount of `bd` archaeology explains.
|
|
|
|
|
|
|
|
|
|
Note the recipe's own prose deliberately spells no live or dead id: a document
|
|
|
|
|
that lists ids as examples makes itself a source of audit noise.
|
|
|
|
|
The recipe's own prose spells no id as an *example*, because a document that
|
|
|
|
|
lists example ids makes itself a source of audit noise. The ids it does cite,
|
|
|
|
|
improvise-8haj and improvise-oujb, are the tickets behind two of the rules
|
|
|
|
|
above. They resolve, and the audit checks them like any other.
|
|
|
|
|
|
|
|
|
|
One environment note: in a worktree-isolated agent the shell guard refuses a
|
|
|
|
|
loop that passes a runtime-computed argument to `bd`, so the recipe above
|
|
|
|
@@ -376,9 +395,10 @@ regeneration. Repository policy lives here, outside them:
|
|
|
|
|
- **Work is not done until it is in a pull request and that pull request has
|
|
|
|
|
merged.** A pushed branch is not done, and neither is a green one. In a wave,
|
|
|
|
|
the merge is the orchestrator's, after an adversarial review passes the head
|
|
|
|
|
SHA ("Shipping a wave"). So a wave agent's part ends at an open PR plus its
|
|
|
|
|
hand-back, and the ticket is done, and its bead closed, only when the merge
|
|
|
|
|
lands.
|
|
|
|
|
SHA ("Shipping a wave"). An ADR PR merges only on the user's explicit
|
|
|
|
|
approval as well ("ADR pull requests"). So a wave agent's part ends at an
|
|
|
|
|
open PR plus its hand-back, and the ticket is done, and its bead closed, only
|
|
|
|
|
when the merge lands.
|
|
|
|
|
- **This repository does not opt in to the Beads "team-maintainer" profile.**
|
|
|
|
|
So the pull (`git pull`, or `git pull --rebase` in bd's "full" profile) and
|
|
|
|
|
the bare `git push` that the block lists for that profile are not
|
|
|
|
|
Ed Langley
GitHub