diff --git a/docs/initiatives/canary-rollout-adr.md b/docs/initiatives/canary-rollout-adr.md index d9d73a40e..f20e1e77b 100644 --- a/docs/initiatives/canary-rollout-adr.md +++ b/docs/initiatives/canary-rollout-adr.md @@ -19,7 +19,8 @@ The machine-readable ring map is `standards/canary-rings.json`; the gate logic i The release-strategy initiative ([#495](https://github.com/petry-projects/.github-private/issues/495)) replaced a floating-`@main` deploy — where a merge was instantly live across the agents' own self-review duty *and* every consumer repo, with no canary and no rollback — with a **versioned-release model**: immutable `/vX.Y.Z` releases plus **moving channel tags** (`/next`, `/ring0`, `/ring1`, `/stable`) that callers pin to. -See [`agentic-release-strategy.md`](./agentic-release-strategy.md) for the full analysis and [`docs/release/versioning.md`](../release/versioning.md) for the tag mechanics. +See [`agentic-release-strategy.md`](./agentic-release-strategy.md) for the full analysis and +[`docs/release/versioning.md`](https://github.com/petry-projects/.github-private/blob/main/docs/release/versioning.md) for the tag mechanics. Once #499–#502 and #868 landed, the concentric rings, the soak gate, and the promotion/rollback workflow were **built and machine-backed** — no longer aspirational. This ADR records the decisions those artifacts encode so the public-repo standard can be promoted to match (and link here) instead of carrying a "not yet built" note. @@ -126,7 +127,8 @@ matching the ring map in [`standards/canary-rings.json`](../../standards/canary- - Initiative [#495](https://github.com/petry-projects/.github-private/issues/495) — safe release strategy for agentic workflows. - [`docs/initiatives/agentic-release-strategy.md`](./agentic-release-strategy.md) — the initiative analysis (rings, channels, health-gated promotion); §5.1 mutable-ref exception. - [`docs/initiatives/agentic-release-strategy-orchestration.md`](./agentic-release-strategy-orchestration.md) — how the child issues (#496–#503) were delivered; the dependency DAG. -- [`docs/release/versioning.md`](../release/versioning.md) — immutable-release vs. moving-channel-tag mechanics; cross-repo reusables. +- [`docs/release/versioning.md`](https://github.com/petry-projects/.github-private/blob/main/docs/release/versioning.md) — + immutable-release vs. moving-channel-tag mechanics; cross-repo reusables (canonical copy in `.github-private`). - [`standards/canary-rings.json`](../../standards/canary-rings.json) — machine-readable ring map (source of truth). - [`scripts/lib/canary-rollout.sh`](../../scripts/lib/canary-rollout.sh) / [`scripts/canary-rollout.sh`](../../scripts/canary-rollout.sh) / [`.github/workflows/canary-rollout.yml`](../../.github/workflows/canary-rollout.yml) — gate core, orchestrator, and scheduler. diff --git a/docs/release/versioning.md b/docs/release/versioning.md deleted file mode 100644 index da7906e02..000000000 --- a/docs/release/versioning.md +++ /dev/null @@ -1,196 +0,0 @@ -# Agent versioning & release channels - -Status: **active** (Phase 1 of the [Safe Release Strategy](../initiatives/agentic-release-strategy.md) -initiative, epic #495). Implements issue #496. - -This defines how the **dev-lead** and **pr-review** agents are versioned and how callers select a -version. It is the foundation the rest of the initiative (rings, promotion, rollback) builds on. - -## What is versioned - -A "release" of an agent is the reusable workflow **plus the scripts it executes** — they move -together, so a version is a single repo commit that contains a known-good combination: - -| Agent | Reusable workflow | Key scripts (non-exhaustive) | -|---|---|---| -| `pr-review` | `.github/workflows/pr-review.yml` | `scripts/review-one-pr.sh`, `scripts/review-batch.sh`, `scripts/post-pr-review.sh`, `scripts/engine.sh`, `scripts/lib/*` | -| `dev-lead` | `.github/workflows/dev-lead-reusable.yml` | `scripts/dev-lead-*.sh`, `scripts/engine.sh`, `scripts/lib/*` | -| `feature-ideation` | `petry-projects/.github` → `.github/workflows/feature-ideation-reusable.yml` (**cross-repo**) | reusable-owned (lives in the public repo; this repo holds only the thin caller `.github/workflows/feature-ideation.yml`) | -| `agent-shield`, `auto-rebase`, `dependency-audit`, `dependabot-automerge`, `dependabot-rebase`, `pr-review-mention` (the six #482 reusables) | `petry-projects/.github` → `.github/workflows/-reusable.yml` (**cross-repo**) | reusable-owned (live in the public repo; this repo holds only the thin caller stubs) | - -`pr-review` and `dev-lead` both live in this repo, so a release tag points at a whole-repo commit; the -tag *name* scopes it to one agent so the two can be released and promoted independently. - -The rest are the exception: their reusables live in **`petry-projects/.github`** (this repo holds only -the thin caller stubs), so a "release" is a commit on that public repo, and their release/channel tags -must be cut **against `petry-projects/.github`, not this repo's `origin`**. This is `feature-ideation` -plus the six reusables #482 migrated to channel tags — see [Cross-repo reusables](#cross-repo-reusables) -below. - -## Tag scheme - -Two kinds of tag, per agent: - -| Kind | Format | Mutable? | Purpose | -|---|---|---|---| -| **Immutable release** | `/vMAJOR.MINOR.PATCH` | No (annotated, never moved) | Audit trail + rollback target | -| **Channel** | `/` | Yes (moved on promotion) | What callers pin to | - -Channels (Phase 1 defines `stable`; Phase 2 adds `next` and per-ring channels): - -- `/stable` — the production channel (blue). Callers in production pin here. -- `/next` — the candidate channel (green). **Live for `dev-lead`** (#499). -- `/ring0`, `/ring1`, … — per-ring channels for staged promotion. **Live for `dev-lead`** (#499/#500). - -Examples: `pr-review/v1.0.0`, `pr-review/stable`, `dev-lead/v1.0.0`, `dev-lead/stable`, -`dev-lead/next`, `dev-lead/ring0`, `dev-lead/ring1`. - -### Ring channels (live for `dev-lead`) - -The candidate (`next`) and ring channels are real moving tags, created alongside `stable`. A caller -pins **once** to its ring channel and is never edited again; a release flows outward ring-by-ring as -each ring's tag is advanced. - -Ring membership (canonical model — see [#500](https://github.com/petry-projects/.github-private/issues/500)). -`next` is **host-relative**: it always resolves to the repo that *hosts* the reusable, and `ring0` -covers the other org-infra repo, so `next` + `ring0` always span `.github` + `.github-private`, -partitioned by which one is the host: - -| Ring | Channel | Members (general) | Role | -|---|---|---|---| -| **next** | `/next` | the repo that **hosts** the reusable | canary / dogfood at the source | -| **ring0** | `/ring0` | `.github` **and** `.github-private` (host already in `next`) | org-infra self-host | -| **ring1** | `/ring1` | `TalkTerm`, `bmad-bgreat-suite` | named low-traffic consumers | -| **stable** | `/stable` | everything else | full-fleet production | - -Concretely for **`dev-lead`** (hosted in `.github-private`): `next` = `.github-private`, -`ring0` = `.github`, `ring1` = `{TalkTerm, bmad-bgreat-suite}`, `stable` = the rest. -**Production self-review/dev duty stays pinned to `stable` even within ring 0** — the agent validating -fixes is never the unvalidated candidate (the circular-dependency fix #500 targets). The intended -machine-readable source of truth is `standards/canary-rings.json`, consumed by the promotion -automation (#501). - -A staged rollout advances the channels in order — `next` → `ring0` → `ring1` → `stable` — validating -at each step (see [`runbook.md` §2c](./runbook.md#2c-staged-canary--ring-rollout)). All four channels -may sit at the same commit between releases; they diverge while a candidate is being staged. The -`check_dev_lead_stub` compliance audit accepts any `dev-lead/{stable,next,ring}` channel pin (it -rejects `@main` and frozen `@vX.Y.Z`/`@` — callers must pin a *moving* channel). pr-review still -uses `stable` only; its ring channels are pending under #499. - -`feature-ideation` uses the full per-ring channel set — `{next, ring0, ring1, stable}` — so it can be -promoted through the same canary → ring → stable model. Its tags follow the identical name scheme -(`feature-ideation/vX.Y.Z`, `feature-ideation/next`, `feature-ideation/ring0`, -`feature-ideation/ring1`, `feature-ideation/stable`) but are cut against `petry-projects/.github` -(see [Cross-repo reusables](#cross-repo-reusables)). - -The six **#482 reusables** — `agent-shield`, `auto-rebase`, `dependency-audit`, `dependabot-automerge`, -`dependabot-rebase`, `pr-review-mention` — use the same `{next, ring0, ring1, stable}` set (#870), -replacing the single-hop `/stable`-only migration #482 cut by hand. They are `.github`-hosted, so -like `feature-ideation` their tags are cut against `petry-projects/.github`. Their ring membership is an -**explicit org-owner assignment** (#870, matching #866), and it does **not** follow the host-relative -`$host`/`$org_infra` default above — `next` is `.github-private` (the dogfood lab) even though the -reusables are hosted in `.github`, which sits in `ring0`: - -| Channel | Member repo(s) | -|---|---| -| `next` | `.github-private` | -| `ring0` | `.github` (the host) | -| `ring1` | `TalkTerm`, `bmad-bgreat-suite` | -| `stable` | `markets`, `broodly`, `ContentTwin`, `google-app-scripts` (full-fleet production) | - -### Semantic versioning - -- **MAJOR** — breaking change to the caller contract (workflow inputs/secrets, required permissions, - the merge-gate behavior a consumer relies on). -- **MINOR** — backward-compatible capability (new safety check, new optional input). -- **PATCH** — backward-compatible fix (bug fix, prompt tweak, resilience hardening). - -## How callers select a version (no per-caller churn) - -GitHub does **not** allow an expression in a `uses:` ref, so version selection is **a moving channel -tag**, not a variable. Each caller pins **once** to a channel and is never edited again; promotion is a -central move of the channel tag (see the initiative doc §5.1): - -```yaml -# A consumer / self-host caller pins once to the per-agent channel: -uses: petry-projects/.github-private/.github/workflows/pr-review.yml@pr-review/stable -uses: petry-projects/.github-private/.github/workflows/dev-lead-reusable.yml@dev-lead/stable -``` - -> Shorthand: the initiative doc writes `@stable`; the concrete tag is the **per-agent** channel -> (`pr-review/stable`, `dev-lead/stable`) so the agents promote independently. - -## The v1.0.0 baseline - -The first release was cut from the production `main` at the time of issue #496: - -- `pr-review/v1.0.0`, `dev-lead/v1.0.0` — immutable baselines. -- `pr-review/stable`, `dev-lead/stable` — channels pointing at v1.0.0. - -`v1.0.0` is **"what is in production today,"** the current rollback floor — *not* a certified-perfect -version. The health-gated promotion added in Phase 2 (#501) is what makes *future* promotions to -`stable` genuinely validated before they become production. - -## Cross-repo reusables - -Everything above assumes the agent's reusable workflow lives **in this repo**, so a release tag is a -whole-repo commit here and tags are cut against this repo's `origin`. That holds for `pr-review` and -`dev-lead`. It does **not** hold for the cross-repo reusables — `feature-ideation` and the six #482 -reusables (`agent-shield`, `auto-rebase`, `dependency-audit`, `dependabot-automerge`, -`dependabot-rebase`, `pr-review-mention`): - -- Their reusables live in **`petry-projects/.github`** (`.github/workflows/-reusable.yml`); this - repo carries only the thin caller stubs `.github/workflows/.yml`. -- Therefore a release is a commit on **`petry-projects/.github`**, and the `/vX.Y.Z` immutable + - `/` tags must be cut **against that repo**, not this repo's `origin`. -- `scripts/cut-release.sh` recognizes each of these agents (`valid_agent`) and, for a cross-repo agent, - **resolves the ref and creates/moves the tags against `petry-projects/.github` via `gh api`** (#872, - wired). `--dry-run` previews the immutable + channel tag names; a live `--push` creates the annotated - `/vX.Y.Z` release object and force-moves the `/` tag on `.github`, and needs - `GH_TOKEN` with `contents:write` on that repo. (`origin/main` in `--ref` means `.github`'s `main` — the - `origin/` prefix is stripped for the cross-repo API lookup.) -- Because these channel tags live on `petry-projects/.github`, the protective ruleset that bounds them - (the mutable-ref exception) is created **there**, not on this repo — see - [`AGENTS.md`](../../AGENTS.md) "Release channel tags & the mutable-ref exception". - -> **Now registered in `standards/canary-rings.json`.** The promotion automation -> (`scripts/canary-rollout.sh`, #501) now moves channel tags **cross-repo** via `gh api` ref updates on -> each agent's host repo (#1054), so the six reusables above are registered under the full -> `{next, ring0, ring1, stable}` model (#870) — the earlier "automation can't move cross-repo tags" -> gap is closed. `feature-ideation` remains **absent** for now: its host + ring assignment aren't settled, -> and registering an agent before then would advertise a promotion the registry can't yet describe. - -### The six #482 reusables (ring assignment) - -PR #482 migrated these six to moving channel tags **single-hop** — it cut only `/stable` (+ a manual -off-convention `/v2.0.0`) and put all consumers on `stable`, with no `next`/`ring*`. #870 brings -them under the full `{next, ring0, ring1, stable}` model with the explicit, org-owner ring assignment in -[Ring channels](#ring-channels-live-for-dev-lead) above. Note this assignment is **explicit, not -host-relative**: `next` is `.github-private` even though the reusables are hosted in `.github` (which -sits in `ring0`). Re-cutting their releases on a sane incremental-semver basis (reconciling the manual -`/v2.0.0` tags) and cutting the `next`/`ring0`/`ring1` channels is an operational step done via -`cut-release.sh`, whose cross-repo publish path is now wired (#872). - -## Cutting / moving tags - -Use `scripts/cut-release.sh` (tested in `tests/test_cut_release.bats`) rather than ad-hoc `git tag`: - -```bash -# Cut an immutable release for an agent at a ref (default ref: origin/main): -scripts/cut-release.sh pr-review 1.1.0 --push - -# Cut a release AND advance that agent's stable channel to it (a promotion): -scripts/cut-release.sh pr-review 1.1.0 --channel stable --push - -# Preview without touching anything: -scripts/cut-release.sh pr-review 1.1.0 --channel stable --dry-run - -# Cross-repo agent (reusable in petry-projects/.github): cut against that repo via -# gh api (#872). --dry-run previews; --push publishes (needs contents:write on .github): -scripts/cut-release.sh feature-ideation 1.4.0 --channel ring0 --dry-run -scripts/cut-release.sh feature-ideation 1.4.0 --channel ring0 --push -``` - -The promote/rollback **runbook** (when to move `stable`, how to roll back, verify, gotchas) lives in -[`runbook.md`](./runbook.md). The automated, health-gated promotion workflow is issue #501; tag-protection -so only the promotion workflow may move a channel tag is issue #505.