Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 5 additions & 6 deletions .claude/agents/portfolio-surveyor.md
Original file line number Diff line number Diff line change
Expand Up @@ -739,16 +739,15 @@ public and private — no per-repo loop needed to enumerate):
This includes drafts and promoted PRs from humans and actionable trusted bots — EXCEPT trusted
**programmed bot PRs**: the shared agent-skills updater's exact generated path in `platform` and
`ksail` (maintainer
direction 2026-07-23), Homebrew-tap cask PRs (GoReleaser's for `ksail`/`ksail-desktop` and
World at Ruin's CD-generated ones on `goreleaser/world-at-ruin`, maintainer direction
2026-07-18). Apply this
direction 2026-07-23), and the tap's own Cask bump PRs (`chore(cask): update <cask> to
v<version>` on `bump-<cask>-<version>`, homebrew-tap#2568). Apply this
exemption **only** when the checked-in exact classifier exits 0. It is a declared classifier,
so run it as this forge-first pipeline, the only shape the guard admits (monorepo#3123):
`gh api --paginate --slurp repos/devantler-tech/<repo>/pulls/<n>/commits | jq -c '{repo:"<repo>",author:"<author>",head_ref:"<headRefName>",title:"<title>",head_oid:"<headRefOid>",files:<files_json>,skill_owners:<skill_owners_json-or-null>,commits:(add | map({sha, author_login:(.author.login // ""), author_name:.commit.author.name, author_email:.commit.author.email, author_date:.commit.author.date, committer_login:(.committer.login // ""), committer_name:.commit.committer.name, committer_email:.commit.committer.email, committer_date:.commit.committer.date, message:.commit.message, verified:(.commit.verification.verified == true), parents:[.parents[].sha]}))}' | <repo-root>/.claude/scripts/programmed-bot-review-exemption.sh --input -`.
Substitute each `<…>` as a JSON literal; a value containing `'` cannot be quoted, so
report that PR `QUERY-UNKNOWN` rather than improvise. Pass the repository basename (`ksail`, not `devantler-tech/ksail`) and the author exactly as
that repo's arm compares it: `app/<slug>` for App-authored arms (`app/ksail-bot`), plain
`devantler` for the homebrew-tap cask arms. Never the REST `<slug>[bot]` the deepening
that repo's arm compares it: `app/<slug>` (`app/ksail-bot`, and `app/botantler-1`
for the platform and agent-plugins updaters and the tap's Cask bump PRs). Never the REST `<slug>[bot]` the deepening
query returns: well-formed, matches no arm, exits 1, spends a metered lane (monorepo#2991).
For an installed-skill updater PR (any changed path under `.agents/skills/`), `skill_owners_json`
is **required**: a compact JSON object mapping each changed skill root (`.agents/skills/<name>`)
Expand All @@ -759,7 +758,7 @@ public and private — no per-repo loop needed to enumerate):
tripwire the caller may skip never fires. Every other arm ignores it (pass `null`).
`files_json` is every path from the deepening query as one JSON string array. The pipeline
builds the commit list itself, from the REST commits endpoint with both raw dates verbatim —
the classifier compares them to tell a fresh release commit from a rewritten one. Do not
the classifier's schema requires them, and a payload without them exits 2. Do not
substitute `gh pr view --json commits`: it omits raw committer provenance and both dates.
The list's last SHA must equal `headRefOid`; an agent/maintainer adaptation commit therefore
revokes the exemption even when the branch, title, and files still look generated. Exit 1 means
Expand Down
91 changes: 25 additions & 66 deletions .claude/guides/merge-policy.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,9 +43,9 @@ Conventional-Commit title, then **merge with the command that matches the author
author-scoped list, which is what made the unsafe arming look prescribed.
For an unconditional author, use
`gh pr merge <n> --repo devantler-tech/<repo> --auto --squash --match-head-commit <sha>`; for **trusted programmed bot PRs** (exit-0 agent-skills updater PRs,
and tap cask PRs — the carve-out below) the review parts are intentionally absent and
and the tap's Cask bump PRs — the carve-out below) the review parts are intentionally absent and
are NOT required — their required checks, zero threads, and no-conflict state alone gate the merge,
which for the exit-0 updater is the head-pinned **direct** merge above, never `--auto`;
which for the exit-0 updater and a Cask bump PR is the head-pinned **direct** merge above, never `--auto`;
- a **human-trusted author** (`devantler`, i.e. **every machine-local agent-own PR**) **cannot use `--auto`**
(auto-merge is bot-only) and merges **directly** with
`gh pr merge <n> --repo devantler-tech/<repo> --squash --match-head-commit <sha>` once
Expand Down Expand Up @@ -882,9 +882,12 @@ gated by required CI and auto-merge rather than an AI review:
`chore(deps): update agent skills` title in `platform` and `ksail`, authored by
those repositories' exact updater App and changing only their generated installed-skill roots —
**and only where every changed skill is owned by the reviewed suite upstream** (see below).
- **Programmed release PRs** (maintainer direction 2026-07-13, ksail#6095; widened 2026-07-18):
every product's Homebrew-tap cask PR, including World at Ruin's CD-generated
`chore(cask): update world-at-ruin to vX.Y.Z` PRs on `goreleaser/world-at-ruin`.
- **Programmed Cask bump PRs** (homebrew-tap#2568, which replaced the product cask PRs of maintainer
directions 2026-07-13 and 2026-07-18): the tap's own hourly `bump-casks` workflow opens one PR per
outdated Cask, authored by `app/botantler-1` on `bump-<cask>-<version>` with the title
`chore(cask): update <cask> to v<version>`, changing only `Casks/<cask>.rb` in one GitHub-signed
commit whose message is the title. KSail's GoReleaser cask pipeline (ksail#8394) and World at
Ruin's CD cask job (world-at-ruin#1713) are gone, so no `goreleaser/*` cask PR opens any more.

**`agent-plugins` updater PRs require semantic review.** Bundled skills are executable agent
instructions sourced from several upstreams, so path and commit provenance prove who produced an
Expand Down Expand Up @@ -940,64 +943,20 @@ Never infer it from the title alone. Qualifying PRs run through required CI and
request CodeRabbit, Codex, Cursor Bugbot, or a local review, chase ancillary reviewer output, or count
a missing review as a hygiene gap. Their checks, threads, and conflict state still gate auto-merge.
Any adaptation commit or out-of-bound file revokes the exemption and restores the normal review gate.
A cask PR's `brew style --fix` autocorrect commits are **not** adaptations: the tap's
`generator-bot` commit and KSail's own release-pipeline tidy-up are part of the programmed shape, and
the classifier recognises each only by its exact author and committer identity and message, inside
the same cask-file boundary. The tap bot's commit carries no resolvable GitHub login, so its login is
passed as an empty string (the commit query in the classifier's usage header coalesces it); every
other extra commit still sends the PR to review.

🔴 **The exemption proves provenance, never ripeness: a cask PR's DRAFT state is the CD's release
fence, and only the release clears it** (monorepo#2992). A product's CD opens its Homebrew-tap cask PR
as a draft so the tap cannot merge it while the GitHub release is still a draft, and leaves it a draft
when its own hand-off fails. Exit 0 plus a clear pentad cannot see either state, so "draft + exempt +
CLEAN" is **not** "promote me": an agent promoted and merged `homebrew-tap#1496` over exactly that
fence. Before promoting a draft cask PR, judge its release at the PR head:

```sh
cask=$(gh api "repos/devantler-tech/homebrew-tap/contents/Casks/<name>.rb?ref=<headRefOid>" \
-H "Accept: application/vnd.github.raw") || { echo "cask read FAILED — UNKNOWN" >&2; exit 2; }
if release=$(gh api repos/devantler-tech/<repo>/releases/tags/v<version> 2>release.err); then :
elif grep -q '(HTTP 404)' release.err; then release=null # absent, or still a draft
else echo "release read FAILED — UNKNOWN" >&2; exit 2; fi
jq -n --arg cask "$cask" --argjson release "$release" '{cask:$cask, release:$release}' |
.claude/scripts/release-cask-ripeness.sh --input -
```

`release` is `null` only when that read returned **404**: a draft release is not readable by tag, so a
draft and an absent release both arrive as `null`. On a 404, `gh api` still prints the error body on
stdout, so never pass its output through unchecked; any other failed read is UNKNOWN. Promote only
on exit **0** (`RIPE`): the release is published, carries every asset the cask installs, and each
pinned `sha256` equals the digest GitHub records for that asset. On exit **1** keep the draft and park
the PR on the release; on exit **2** keep the draft and report it UNKNOWN. The CD run's conclusion is
not the test: a published release can sit behind a CD run reported `cancelled`.

🔴 **`RIPE` is necessary, not sufficient: the product's CD hands off its own cask PR, so never promote
one while a run of that product's CD workflow is queued or in progress** (monorepo#4980). The CD
promotes its cask PR itself minutes after the release publishes, and it adds the labels its hand-off
checks only while it promotes a draft. On 2026-11-12 an agent promoted `homebrew-tap#2528` 28 seconds
before KSail's CD reached that step, the CD refused the already-ready PR, and the run went red. So an
agent's promotion is the fallback for a cask PR the CD left a draft after its run ended. Before
promoting, read the product's CD runs (`cd.yaml` for KSail and World at Ruin):

```sh
for state in requested waiting pending queued in_progress; do
n=$(gh api "repos/devantler-tech/<repo>/actions/workflows/cd.yaml/runs?status=$state&per_page=1" \
--jq .total_count) || { echo "CD run read FAILED — UNKNOWN" >&2; exit 2; }
[ "$n" = 0 ] || { echo "CD run $state — leave the draft to the CD" >&2; exit 1; }
done
```

Promote only when every read succeeds and counts zero. Otherwise keep the draft: the running CD
hands it off, or its next run re-drafts it at a newer release.

**Ripeness belongs to a head, not to the PR.** The CD reuses one `goreleaser/<name>` branch, so the
next release force-pushes a newer, possibly still-draft version into a cask PR that is already
promoted. On 2026-10-01 this happened twice: `homebrew-tap#1767` was promoted RIPE at v7.198.8 and
again at v7.198.9, and each time it moved to an unpublished version before it merged. So a cask PR
is the exception to "qualifying PRs run through auto-merge" above: **never arm `--auto` on it**,
because the head pin then guards only the arming and a later force-push would merge a head nobody
judged. Merge in the same sitting as the promotion: wait for the required checks to settle, then
merge directly, pinned to the exact head you judged RIPE (`--match-head-commit <sha>`). If the head
moved first, the earlier verdict no longer applies: judge the new head again, and if it is not RIPE,
convert the PR back to a draft and say which release it is waiting on.
A Cask bump PR has no autocorrect commit, because `brew bump-cask-pr` runs `brew style --fix` before
the workflow commits. Its one commit, plus a trailing base-refresh merge GitHub writes when that same
App's token asks to update the branch, is the whole programmed shape; any other commit, including a
second one from the workflow, sends the PR to review.

**A Cask bump PR's release is published by construction.** `brew livecheck` reads the release GitHub
lists as latest, which is not a draft or a prerelease, so the workflow moves a Cask only to a
published release, and `brew bump-cask-pr` takes every `sha256` from that release's assets
(homebrew-tap#2568). The draft fence, the release-ripeness check and the product CD hand-off
(monorepo#2992, monorepo#4980) guarded the product pipelines' cask PRs and are retired with them.
The workflow arms the PR's auto-merge itself, so a qualifying bump PR merges once the tap's required
checks pass, with no agent action. 🔴 **Never arm or re-arm that auto-merge yourself:
`app/botantler-1` is not `--auto`-eligible** (above). A bump PR that stalls, with a failed check or
an auto-merge that does not fire, is rung-one work: an adaptation commit restores the review gate as
above, and otherwise re-run the classifier at the current head and merge directly, pinned with
`--match-head-commit` to the head it judged. Closing a bump PR is not neutral: the workflow skips a
version whose branch already has a closed PR, so that Cask then waits for the next release.
5 changes: 1 addition & 4 deletions .claude/guides/merge-policy.sensors.tsv
Original file line number Diff line number Diff line change
Expand Up @@ -92,10 +92,6 @@ MP-093 dependency-automation-and-programmed-bot-prs Supplying it can only withdr
MP-094 dependency-automation-and-programmed-bot-prs It is **required on this arm** and omitting it returns computational .claude/scripts/programmed-bot-review-exemption.sh matches_suite_owned_skills && updater_verdict 0
MP-095 dependency-automation-and-programmed-bot-prs The other arms take seven arguments and never consult narrative - -
MP-096 dependency-automation-and-programmed-bot-prs Never infer it from the title alone. none - -
MP-097 dependency-automation-and-programmed-bot-prs 🔴 **The exemption proves provenance, never ripeness: computational .claude/scripts/release-cask-ripeness.sh NOT-RIPE release
MP-098 dependency-automation-and-programmed-bot-prs On a 404, `gh api` still prints the error body on none - -
MP-099 dependency-automation-and-programmed-bot-prs So a cask PR is the exception to "qualifying PRs none - -
MP-100 dependency-automation-and-programmed-bot-prs `RIPE` is necessary, not sufficient none - -
MP-101 you-own-every-pull-request-in-the-portfolio--whoever-authored-it A park is that state only while `blocked-check.sh` reports the PR computational .claude/scripts/blocked-check.sh PARKED
MP-102 you-own-every-pull-request-in-the-portfolio--whoever-authored-it Its blocker is still owned work (*A park is never a resting place* below). none - -
MP-104 you-own-every-pull-request-in-the-portfolio--whoever-authored-it **A park is never a resting place** (agent-plugins#699 computational .claude/scripts/blocked-check.sh no current route
Expand All @@ -111,3 +107,4 @@ MP-113 you-own-every-pull-request-in-the-portfolio--whoever-authored-it Closing
MP-114 you-own-every-pull-request-in-the-portfolio--whoever-authored-it The PR itself, its review, CI or evaluation is never its blocker none - -
MP-115 you-own-every-pull-request-in-the-portfolio--whoever-authored-it Edit it in place on every later run, never post a second computational .claude/scripts/blocked-check.sh DUPLICATE
MP-116 you-own-every-pull-request-in-the-portfolio--whoever-authored-it **An upstream blocker is re-checked against live releases on its Wait for issue** computational .claude/scripts/blocked-check.sh STALE
MP-117 dependency-automation-and-programmed-bot-prs Never arm or re-arm that auto-merge yourself none - -
8 changes: 5 additions & 3 deletions .claude/guides/trust-and-input.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,16 +60,18 @@ and an actionable maintainer comment on a PR you did not create stays a named bl
satisfied or withdrawn. The plugin reads an absent or unrecognised value as `hands-off`, so deleting
this line silently stops the engineer from driving the maintainer's interactive PRs; changing it is the
maintainer's call. The root `AGENTS.md` *Trust gate* carries the declaration the plugin reads.
**`app/botantler-1` is narrowly trusted only for programmed agent-skills updater PRs.** The App is
**`app/botantler-1` is narrowly trusted only for programmed agent-skills updater PRs and the tap's own Cask bump PRs.** The App is
not added to the general trusted-author set. Its PR may be built when the exact programmed-bot
classifier named in the merge-policy guide exits 0 or 3: exit 0 is the **no-review** path — which is a **direct,
head-pinned merge, NEVER `--auto`** (see *Merge policy*: this App's permission comes from a classifier
result about one specific commit, and `--auto` cannot carry a condition) — while exit 3 is the
normal semantic-review path for a genuine updater PR — an `agent-plugins` marketplace update, or a
`platform`/`ksail` installed-skill update touching a skill this suite does not own. Any other
`platform`/`ksail` installed-skill update touching a skill this suite does not own. A
`homebrew-tap` `bump-<cask>-<version>` PR qualifies only on exit 0; its own workflow arms its
auto-merge, which an agent never arms or re-arms. Any other
`app/botantler-1` PR is external for **execution** purposes — reviewed statically and never run
locally — while remaining drivable and mergeable like any other PR. This path-specific grant covers
the updater without extending build/run trust to every PR the App could author.
the updater and the Cask bump without extending build/run trust to every PR the App could author.
**GitHub Copilot — two roles, treated differently:** the
Copilot **coding agent** (`Copilot`, `copilot-swe-agent[bot]`) is **NOT** trusted — treat its PRs as
external, meaning **never run its branch code**; they are reviewed statically, then driven and merged
Expand Down
2 changes: 0 additions & 2 deletions .claude/scripts/foreground-poll-guard.test.sh
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,6 @@
# test-inputs: .claude/scripts/pr-ownership-disclosure.test.sh
# test-inputs: .claude/scripts/pr-worktree-holder.sh .claude/scripts/pr-worktree-holder.test.sh
# test-inputs: .claude/scripts/programmed-bot-review-exemption.sh
# test-inputs: .claude/scripts/release-cask-ripeness.sh
# test-inputs: .claude/scripts/release-cask-ripeness.test.sh
# test-inputs: .claude/scripts/surveyor-hook-dispatch.sh
# test-inputs: .claude/scripts/surveyor-hook-dispatch.test.sh .claude/settings.json
# test-inputs: .claude/skill-ownership-allowlist.tsv .claude/skills/portfolio-maintenance/SKILL.md
Expand Down
2 changes: 0 additions & 2 deletions .claude/scripts/kata-measure-date.test.sh
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,6 @@
# test-inputs: .claude/scripts/pr-ownership-disclosure.test.sh
# test-inputs: .claude/scripts/pr-worktree-holder.sh .claude/scripts/pr-worktree-holder.test.sh
# test-inputs: .claude/scripts/programmed-bot-review-exemption.sh
# test-inputs: .claude/scripts/release-cask-ripeness.sh
# test-inputs: .claude/scripts/release-cask-ripeness.test.sh
# test-inputs: .claude/scripts/surveyor-hook-dispatch.sh
# test-inputs: .claude/scripts/surveyor-hook-dispatch.test.sh .claude/settings.json
# test-inputs: .claude/skill-ownership-allowlist.tsv .claude/skills/portfolio-maintenance/SKILL.md
Expand Down
Loading
Loading