diff --git a/docs/migration.md b/docs/migration.md index 947531a..fe2b2fc 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -5,8 +5,12 @@ This mechanism was renamed **agent-ops → Olympus** This page answers one question: **if your repo already uses the mechanism, what breaks — and what do you change?** -Short answer: **a wrapper pinned to a pre-rename tag keeps working unchanged.** -You only do the edits below when you *re-pin* to an Olympus-named release. +Short answer: **GitHub Actions does not follow repo renames for `uses:`, so +every consumer must change the `uses:` owner to `Netis/olympus`** — even one +pinned to a pre-rename tag. For a pinned-tag consumer that owner edit is the +*only* change needed (the tag travelled with the repo; keep `.agent-ops.json` +and `agent_ops_ref`). The rest of the migration below applies only when you +*re-pin* to an Olympus-named release. ## Impact by how you pinned @@ -16,22 +20,27 @@ Netis/agent-ops/.github/workflows/.yml@` in their wrapper workflows | You pinned to… | What happens after the rename | What to do | |---|---|---| -| **A pre-rename tag** (`@v0.2.0`) — the documented, recommended way | **Nothing breaks.** That tag's content is frozen at the old (agent-ops-named) code, and GitHub permanently redirects the old `Netis/agent-ops` `uses:` path to `Netis/olympus`. The old code reads your old `.agent-ops.json` — fully self-consistent. | Nothing now. Migrate only when you choose to upgrade to an Olympus-named tag. | -| **A moving ref** (`@main`, a branch) — an anti-pattern the README warns against | **Drifts on the next run.** You'll pull post-rename HEAD, whose loader looks for `.olympus.json`; your file is still `.agent-ops.json`, so config silently falls back to built-in defaults (label names, gate thresholds, bot login, build command all revert) → wrong behavior, not a clean error. | Migrate now (below), or pin to a tag. | -| **Upgrading to an Olympus tag** (`@v0.3.0`+) | The new code expects the new names. | Do the full migration below before bumping. | +| **A pre-rename tag** (`@v0.2.0`) — the documented, recommended way | **The `uses:` reference breaks.** GitHub Actions does **not** follow repository renames when resolving `uses:` — the run fails with `repository not found`. (git/web/API *do* redirect, which is why the reusable workflow's own inner `actions/checkout` of `Netis/agent-ops` still clones — but the outer `uses:` is resolved first, and that resolution is not redirected.) | **Change the `uses:` owner** to `Netis/olympus`, keeping the same `@tag`. The tag travelled with the repo, so `Netis/olympus@v0.2.0` is the same frozen code; keep your `.agent-ops.json` and the `agent_ops_ref` input exactly as they are. | +| **A moving ref** (`@main`, a branch) — an anti-pattern the README warns against | The `uses:` reference breaks the same way (no rename redirect), **and** once you fix the owner you'll pull post-rename HEAD, whose loader looks for `.olympus.json`; your file is still `.agent-ops.json`, so config silently falls back to built-in defaults (label names, gate thresholds, bot login, build command all revert) → wrong behavior, not a clean error. | Repoint the owner **and** do the full migration below (or pin to a tag). | +| **Upgrading to a post-rename Olympus tag** (a tag cut after the rebrand, once one exists) | The new code expects the new names. | Repoint the owner **and** do the full migration below before bumping. | -The redirect is a courtesy, not a contract: it lapses the moment anyone creates -a new repo at the old `Netis/agent-ops` path. Treat it as a grace period, not a -permanent alias. +Be precise about *which* redirect: GitHub redirects **git, web, and API** access +from the old `Netis/agent-ops` path — that (and only that) is what keeps the +inner `actions/checkout` working. It is a courtesy, not a contract: it lapses +the moment anyone creates a new repo at the old path, so **never recreate +`Netis/agent-ops`.** The Actions `uses:` resolver is **not** redirected at all, +which is why the owner edit above is mandatory rather than optional. ## heron specifically -heron is **not a consumer yet** — it still runs its own in-tree -`scripts/agent-bot/*` + `.github/workflows/*` (the roadmap's standing dogfood -target is to *replace* those with pinned Olympus wrappers). So the rename's -impact on heron today is **zero**. When heron onboards as consumer #1, it -onboards straight to the Olympus names — no migration debt. This is the whole -point of doing the rename now, at zero live consumers. +heron **is** consumer #1: its `.github/workflows/` wrappers delegate to the +mechanism via pinned tags — `guard`/`implement`/`triage`/`revise` at `@v0.2.0` +and `review` at `@v0.3.1` — plus a `.agent-ops.json` policy file. Every one of +those tags predates the rebrand, so the rename hits heron exactly as the +pre-rename-tag row above describes: the five `uses: Netis/agent-ops/...@tag` +lines fail to resolve until their owner segment becomes `Netis/olympus` (same +tags; `.agent-ops.json` and `agent_ops_ref` stay). Tracked in +[Netis/heron#164](https://github.com/Netis/heron/issues/164). ## The mapping (when you do migrate) diff --git a/docs/pantheon.md b/docs/pantheon.md index 9c52f48..735c960 100644 --- a/docs/pantheon.md +++ b/docs/pantheon.md @@ -51,8 +51,8 @@ operate the loop. - Consumer wrapper references: `uses: Netis/agent-ops/.github/workflows/...` → `Netis/olympus/...` and the `agent_ops_ref` input → `olympus_ref`. - (GitHub redirects renamed-repo `uses:` paths, but examples and docs must - not rely on redirects.) + (GitHub Actions does **not** redirect renamed-repo `uses:` paths — a pinned + consumer must change the owner segment by hand; see [migration.md](migration.md).) - Config file `.agent-ops.json` → `.olympus.json`; schema `schema/agent-ops.schema.json` → `schema/olympus.schema.json`. - Env prefixes: `AGENT_OPS_*` → `OLYMPUS_*`; `MARA_*` → `ARGUS_*`. @@ -83,5 +83,5 @@ self-contained PR plus one repo-settings change. evals checks). - `examples/consumer/` wrappers reference `Netis/olympus@` and `.olympus.json`, and a doctor run against the example passes. -- The old repo URL redirects (GitHub-side) — verified once after the - settings change. +- The old repo URL redirects (GitHub-side, for git/web/API — **not** Actions + `uses:`) — verified once after the settings change. diff --git a/scripts/lint/check-legacy-naming.sh b/scripts/lint/check-legacy-naming.sh index 3b825bc..88c216d 100755 --- a/scripts/lint/check-legacy-naming.sh +++ b/scripts/lint/check-legacy-naming.sh @@ -12,10 +12,11 @@ # 2. THIS repo's own CI — a regression guard so the rename never silently # leaks back in (the new label/bot/config/env names stay the only ones). # -# IMPORTANT for consumers: a wrapper pinned to a PRE-rename tag (e.g. @v0.2.0) -# keeps working *unchanged*. That tag's content is frozen and GitHub redirects -# the old `uses:` path. You only need these edits when you re-pin to an -# Olympus-named tag — this is an upgrade pre-flight, not a "you're broken" alarm. +# IMPORTANT for consumers: GitHub Actions does NOT redirect `uses:` on a repo +# rename, so a wrapper pinned to a PRE-rename tag (e.g. @v0.2.0) must still +# change its `uses:` owner to Netis/olympus (same @tag — the tag travelled with +# the repo). Keep `.agent-ops.json` + `agent_ops_ref` until you re-pin to an +# Olympus-named tag, when the rest of these edits apply. # # scripts/lint/check-legacy-naming.sh [DIR] # default: current repo # @@ -57,7 +58,7 @@ echo "olympus migration check — scanning for legacy agent-ops naming" # --- MUST fix before re-pinning to an Olympus-named tag -------------------- scan MUST "Mechanism repo reference (uses:)" \ 'Netis/agent-ops' \ - 'Netis/agent-ops → Netis/olympus (GitHub redirects for now; update + re-pin to an Olympus tag)' + 'Netis/agent-ops → Netis/olympus (Actions does NOT redirect uses: on rename — change the owner; the same @tag still works)' scan MUST "Version-pin workflow input" \ 'agent_ops_ref' \ 'agent_ops_ref: → olympus_ref:'