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
88 changes: 74 additions & 14 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,20 +22,28 @@ re-deriving them by hitting the same walls. Every one cost real time or a strand
qa-lead epic (#1643, 2026-09-13 → 2026-09-21). They complement — and cross-link, rather than
duplicate — the deeper standards in the sections below and in `docs/`.

### Merging to `main` does not activate agent code — say whether a channel cut is required
### Merging to `main` does not activate agent code — say when it will reach each channel

**This is the single most expensive omission on this list — do not skip it.** Agents run their
scripts from a **channel tag**, not from `main`. `pr-review-trigger.yml` pins
`@pr-review/v1-next`; `persona-mention.yml` pins `@persona-mention/v1-next`; each caller stub pins
its reusable at a moving channel tag, never at `main`. A fix merged to `main` is **inert** until
`scripts/cut-release.sh <agent> <ver> --channel <tier> --push` moves that channel tag onto the
commit. This bit twice in one week: #1795's CI-gate fix (merged, yet still deadlocking every PR
until `pr-review/v1.10.0` was cut) and #1875's approval read-back (merged, yet still announcing
phantom approvals until the channel caught up to the new commit). **Rule: after merging any change
under `scripts/` or a `*-reusable.yml`, state whether a channel cut is required** — see
its reusable at a moving channel tag, never at `main`. A fix merged to `main` is **inert** until a
channel tag moves onto the commit. This bit twice in one week: #1795's CI-gate fix (merged, yet
still deadlocking every PR until `pr-review/v1.10.0` was cut) and #1875's approval read-back
(merged, yet still announcing phantom approvals until the channel caught up to the new commit).

**You normally do not cut that release yourself.** The Release Manager automation (see
["Release automation — who cuts and moves tags"](#release-automation--who-cuts-and-moves-tags))
**auto-cuts** a new `<agent>/vX.Y.Z` and moves `<agent>/v<MAJOR>-next` on its next 4-hourly sweep
once the change is on `main`. **Every ring beyond `next` moves only by gated promotion.** So the
lag is real but bounded: usually a few hours to reach `next`, and longer to reach `stable`.

**Rule: after merging any change under `scripts/`, `prompts/`, `personas/` or a `*-reusable.yml`,
state which channel(s) must carry it and when.** The normal answer is "rides the next autocut to
`<agent>/v<M>-next`; reaches `stable` via ring promotion". Hand-run `scripts/cut-release.sh` only
for the exceptions listed in that section. See
["Release channel tags & the mutable-ref exception"](#release-channel-tags--the-mutable-ref-exception)
for the tag model, `docs/release/versioning.md` for the scheme, and `scripts/cut-release.sh` for the
promotion command.
for the tag model and `docs/release/versioning.md` for the scheme.

### Verify by execution, never by run status or diff

Expand Down Expand Up @@ -661,8 +669,54 @@ intentionally **mutable** and are an accepted, documented exception because they
first-party channel tag regardless of whether its namespace has been added to the ruleset yet.
- Immutable `vX.Y.Z` tags are the real rollback targets; `scripts/cut-release.sh` refuses to overwrite
an existing release tag.
- Channel-tag moves happen only via the (forthcoming) health-gated promotion workflow (#501); the
ruleset bypass will be tightened to that workflow's identity when it lands.
- Routine channel-tag moves are made by the health-gated Release Manager automation (#501/#993,
below), which is a ruleset bypass actor through the `petry-projects-release-manager` GitHub App.
The only other sanctioned path is a maintainer running `cut-release.sh` as an org admin or with
that App's token.

#### Release automation — who cuts and moves tags

Release tags on this repo's agents (`pr-review`, `dev-lead`, `ci-failure-analyst`) and on the
`petry-projects/.github`-hosted reusables are cut and moved by the **Release Manager**. That is the
`Canary Rollout` workflow in **`petry-projects/.github`**
Comment thread
codeant-ai[bot] marked this conversation as resolved.
Resolved
(`.github/workflows/canary-rollout.yml` + `scripts/canary-rollout.sh`, relocated there from this
repo under #613), acting as the **`petry-projects-release-manager[bot]`** GitHub App. Its registry
(each agent's host, reusable path, rings and gate knobs) is **`standards/canary-rings.json` in
`petry-projects/.github`**, not in this repo. Each sweep (cron `33 */4 * * *`, every 4 hours;
GitHub may delay scheduled runs) runs `autocut` → `promote-all` → `sync-issues`:

| Step | What it does | Armed by | Human control |
|---|---|---|---|
| **autocut** (#1069, #1019) | Cuts the immutable `<agent>/vX.Y.Z` at host `main` HEAD and moves `<agent>/v<MAJOR>-next` onto it. It fires when the reusable file **or** a watched path (`scripts/`, `prompts/`, `personas/` by default; overridable per agent via `agent_ref_paths`) differs from the current `next` candidate. The bump is detected from the change: breaking (`!`, `BREAKING CHANGE`, or a `workflow_call` interface break) → major, which seeds a new `v<M+1>-next`; `feat` → minor; anything else → patch. | org variable `CANARY_AUTO_CUT` | `autocut.bump` in `canary-rings.json` forces a level. Clearing the variable stops all auto-cuts. |
| **promote-all** (#1045; gate: `.github#548`) | Advances each agent **one ring per sweep** (`next` → `ring0` → `ring1` → `stable`) when its graduated gate returns PROMOTE (per-transition dwell and sample floors, e.g. 4h / 8h / 12h). BLOCKED or REGRESSION agents are left in place. | org variable `CANARY_AUTO_PROMOTE` (unset = read-only `evaluate-all`) | `require_confirmation: true` on a transition holds it in AWAITING_CONFIRMATION until someone dispatches `promote <agent> --confirm`. **Today only `dev-lead`'s `ring1 → stable` sets it**; every other agent reaches `stable` with no human step once armed. |
| **sync-issues** | Opens or updates one issue per blocked agent (`needs-human` on REGRESSION, `canary-confirm:<agent>` when awaiting confirmation) and auto-closes it once cleared. | runs every sweep | Read the issue; act with a dispatch. |

**What this means when you work here:**

- **Do not hand-cut after a routine merge.** Autocut will do it. A manual
`cut-release.sh <agent> <ver> --channel next --push` that races the sweep fails with
Comment thread
don-petry marked this conversation as resolved.
Resolved
`release tag '<agent>/vX.Y.Z' already exists`. That is harmless, but a release tag existing does
**not** prove `next` moved, because autocut creates the release first and moves the channel
second. Check that `<agent>/v<M>-next` resolves to the release's commit:
`git ls-remote --tags origin '<agent>/v<M>-next' '<agent>/vX.Y.Z^{}'`. If it doesn't, move it
with `cut-release.sh <agent> <X.Y.Z> --promote --channel next --push` rather than cutting a
new version. Always check the current tags before cutting by hand.
- **Hand-run `cut-release.sh` (as an org admin or with the release-manager App token) only when:** the fix cannot wait
for the next sweep; the change sits outside autocut's watched paths; autocut is disarmed; or you
are promoting or rolling back deliberately. Use `--promote --channel <tier>` to move a channel to
an **existing** release, and never cut a new version just to move a channel.
- **Rollback** is a channel move back to an earlier immutable tag. Either dispatch the `Canary
Rollout` workflow in `petry-projects/.github` with `command=rollback agent=<agent> ring=<tier> to=vX.Y.Z`, or run
`cut-release.sh <agent> <X.Y.Z> --promote --channel <tier> --push`.
Comment thread
don-petry marked this conversation as resolved.
Resolved
- **A release that needs a human go/no-go must be configured *before* its candidate reaches the
ring.** Examples are a model swap such as epic #1895 / #1899, or a behaviour change that needs
canary metrics. Add `require_confirmation: true` to that agent's transition in
`petry-projects/.github` `standards/canary-rings.json`, or disarm `CANARY_AUTO_PROMOTE`, which is
fleet-wide. An issue label such as `dev-lead:hands-off` stops dev-lead from acting on the issue,
but **it does not stop the promotion gate**.
- **Who did what:** releases tagged by `petry-projects-release-manager[bot]` came from the
automation, and releases tagged by a person were cut by hand. The `Canary Rollout` run's job
summary and the promotion Deployments record the gate evidence for every move.

Compliance audits must therefore **not** flag any first-party reusable channel tag (e.g.
`@pr-review/v1-stable`, `@dev-lead/v1-stable`, `@ci-failure-analyst/v0-stable`, or other `<name>/v<M>-<tier>`
Expand Down Expand Up @@ -693,9 +747,15 @@ even though every ref looks valid, because the stub is ahead of the channel it p
what the channel currently resolves to, not against what `main` will eventually ship.
- **Sequencing for a new `workflow_call` input (in order):**
1. **Land it in the reusable** — add the input to `workflow_call.inputs` on `main` and merge.
2. **Promote the pinned channel** to a commit that declares it via
`cut-release.sh <agent> <version> --channel <name>` (cuts the immutable `vX.Y.Z` and moves the
`<name>` channel tag to it).
2. **Promote the pinned channel** to a commit that declares it. For `next` this happens on the
next autocut sweep; later rings follow by gated promotion. Wait until
`git ls-remote --tags origin '<agent>/v<M>-<name>'` resolves to a commit that declares the
input. To force it as an org admin or with the release-manager App token, run
`cut-release.sh <agent> <X.Y.Z> --promote --channel <name> --push` to move the channel to an
**existing** release that declares the input. Only when no such release exists yet, run
`cut-release.sh <agent> <new-version> --channel <name> --push`; without `--promote` it
always cuts a new tag and fails if that version exists (see
["Release automation — who cuts and moves tags"](#release-automation--who-cuts-and-moves-tags)).
3. **Only then teach the stub to forward it** — add the `with:` line to the caller stub, now that the
pinned channel resolves to a commit that declares the input.

Expand Down
59 changes: 37 additions & 22 deletions docs/release/runbook.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,15 +28,31 @@ The goal: cut, promote, and **roll back in < 5 minutes with no per-caller edits
and no manual file surgery** — every rollout/rollback is a single central tag
move.

> **Current state — most of this is automated.** Routine releases no longer need
> the manual steps below. The Release Manager (the `Canary Rollout` workflow in
> `petry-projects/.github`, acting as the `petry-projects-release-manager[bot]`
> App) auto-cuts `<agent>/vX.Y.Z` and moves `<agent>/v<MAJOR>-next` every 4-hour
> sweep, and promotes through the rings by its health gate when armed. See
> [`AGENTS.md` "Release automation — who cuts and moves tags"](../../AGENTS.md#release-automation--who-cuts-and-moves-tags).
> The procedures here are the **manual and override path**, for urgent cuts,
> deliberate promotions and rollbacks. Two differences from the older text
> below: channels are major-scoped `<agent>/v<MAJOR>-<tier>` (#1184), so a bare
> `<agent>/stable` in an example is the legacy form; and channel moves must go
> through `cut-release.sh`, because a local `git push --force` of a protected
> channel tag is rejected (GH013).

---

## Roles & gating

- **Cutting an immutable `vX.Y.Z` tag** is harmless (it rolls out nothing until
`stable` moves) and may be done as part of normal release prep.
- **Promotion (moving `<agent>/stable`)** is a production rollout to every
caller. It is **Phase-1 human-driven**: it requires explicit human
authorization each time. Do not move a channel tag autonomously.
- **Promotion (moving a ring channel, ultimately `<agent>/v<MAJOR>-stable`)** is
a production rollout to every caller in that ring. The Release Manager's gated
`promote-all` does it when `CANARY_AUTO_PROMOTE` is armed. It moves one ring per
sweep, and a `require_confirmation` transition waits for a human `--confirm`
dispatch. A maintainer can also do it by hand as an override. The agents
themselves (dev-lead, pr-review, …) must never move a channel tag.
- **Who *can* move a channel tag:** the `release-channel-tags` ruleset (targets
tags `pr-review/**`, `dev-lead/**`) restricts `update`/`deletion` with bypass
limited to **OrganizationAdmin** and the automation **Integration** app. The
Expand Down Expand Up @@ -90,30 +106,28 @@ scripts/cut-release.sh dev-lead 1.2.0 --ref origin/main --channel stable --push
### 2b. Already-cut release — move the channel only

`cut-release.sh --channel` creates the immutable tag first, so it **errors if
`vX.Y.Z` already exists** (`immutable tags are never overwritten`). To promote an
already-cut release, move the channel tag directly:
`vX.Y.Z` already exists** (`immutable tags are never overwritten`). This is also
what you see if autocut already cut that version. To move a channel to an
already-cut release, use `--promote` (#992), which moves the channel through the
API path without cutting anything:

```bash
# Advance pr-review/stable to the already-cut pr-review/v1.5.3:
git fetch origin --tags
TARGET=$(git rev-parse 'pr-review/v1.5.3^{commit}')
git tag -f pr-review/stable "$TARGET"
git push origin pr-review/stable --force
# Advance pr-review/v1-stable to the already-cut pr-review/v1.5.3:
scripts/cut-release.sh pr-review 1.5.3 --promote --channel stable --push
```

> **Known gap:** `cut-release.sh` has no channel-only-move mode. Until a
> `--channel-only` flag exists (follow-up), use the direct `git tag -f` above.
> Channel tags are lightweight (point straight at the commit); the immutable
> `vX.Y.Z` tags are annotated.
> Channel tags are lightweight (they point straight at the commit); the immutable
> `vX.Y.Z` tags are annotated. Do not `git tag -f` + `git push --force` a channel:
> the `release-channel-tags` ruleset rejects that update (GH013).
>
> **Cross-repo agents.** `feature-ideation` and the six #482 reusables
> (`agent-shield`, `auto-rebase`, `dependency-audit`, `dependabot-automerge`,
> `dependabot-rebase`, `pr-review-mention`) have `<agent>/<channel>` tags that live
> on `petry-projects/.github`, so a promotion is a tag move on **that** repo
> (`git push <petry-projects/.github remote> <agent>/<channel> --force`), not this
> repo's `origin`. The exact remote/target for the automated path is an open
> question — `cut-release.sh` refuses a live cut for any cross-repo agent until it
> is resolved; preview with `--dry-run`.
> repo's `origin`. `cut-release.sh` resolves and moves them against
> `petry-projects/.github` via `gh api` (#872); a live `--push` needs `GH_TOKEN` with
> `contents:write` there.

Then **verify** (§4).

Expand Down Expand Up @@ -157,17 +171,18 @@ git push --force origin dev-lead/stable
# → verify (§4) + soak on 'stable'
```

- **Promotion is gated at every ring** — advancing each channel (including `next`)
is a channel-tag move, so it is human-authorized (Roles & gating). Don't script
the whole loop unattended; advance a ring only after the previous ring is healthy.
- **Promotion is gated at every ring.** The Release Manager's health gate decides
when each channel advances (Roles & gating). Advance a ring by hand only as a
deliberate override, and only after the previous ring is healthy.
- **Validate the candidate, don't trust it.** Treat a ring's failures as the
release until proven otherwise — classify them (regression vs. pre-existing
class) before advancing. A clean canary across rings is the gate for `stable`.
- **Rollback at any stage** is the same single move in reverse against the prior
immutable `vX.Y.Z` (§3) — for that ring's channel, or for `stable` if already
promoted.
- The fully automated, health-gated version of this loop is issue #501; today it
is a human-driven sequence of the moves above. A required input to that gate is
- The fully automated, health-gated version of this loop (#501/#993) is live in
`petry-projects/.github` (relocated under #613); the moves above are the manual
override path. A required input to that gate is
the **shadow-mode dual-run** signal (#605) — run the `next` candidate silently
alongside `stable` on a PR and compare, blocking promotion on a regression. See
[`shadow-mode.md`](./shadow-mode.md).
Expand Down
Loading