diff --git a/cc-ci-plan/plan-phase-canon-canonical-sweep.md b/cc-ci-plan/plan-phase-canon-canonical-sweep.md index befae06..509f6af 100644 --- a/cc-ci-plan/plan-phase-canon-canonical-sweep.md +++ b/cc-ci-plan/plan-phase-canon-canonical-sweep.md @@ -5,11 +5,16 @@ actually doing anything** — confirmed live: `nightly-sweep.timer` is deployed (`nightly_sweep.py`, last run 2026-06-17 03:09 UTC exit 0), but **only `custom-html` is `WARM_CANONICAL` -enrolled and ZERO `canonical.json` records exist** — i.e. the machinery has **never actually promoted a canonical end-to-end**. This phase makes it **real and proven**, as the **substitute for** that hollow -nightly sweep, with two additions the operator wants: +nightly sweep, with the operator's refinements (2026-06-17): 1. **Sync each recipe mirror's `main`** on `git.autonomic.zone/recipe-maintainers/` to its - **upstream** (`git.coopcloud.tech/coop-cloud/`) first, so the sweep tests true upstream latest. -2. **Skip a recipe whose `main` is unchanged** vs its current canonical (no rerun needed). + **upstream** (`git.coopcloud.tech/coop-cloud/`) first, so the sweep sees true upstream + tags/latest. +2. **Trigger on a new RELEASED VERSION, not a new commit.** Test a recipe only when its latest **release + tag** on the synced `main` is **newer** than its current canonical version — **skip when there is no + new version**, even if `main` has new *untagged* commits. The sweep tests releases, not arbitrary commits. +3. **Promote the canonical only to a TAGGED release.** A canonical advances only to a version that has a + real release tag (a published release) — never to an arbitrary untagged commit. …then **run CI cold-on-`main` for each recipe and actually promote the canonical for any that pass** — and **prove the whole thing works**. **The deliverable is correctness, verified end-to-end** — and the @@ -38,6 +43,11 @@ cold-on-latest run **actually write `canonical.json`** (recipe/version/commit/st subsequent `--quick` warm-reattach uses it (`deploy_canonical` reattaches the retained volume). If it doesn't happen today, find and fix why (this is the real defect behind the hollow sweep). A canonical must demonstrably exist and be reusable before anything else is meaningful. + - **Promote-gate addition (operator 2026-06-17): only promote to a TAGGED release.** Extend + `should_promote_canonical` so a promote ALSO requires the tested version to correspond to a published + **release tag** (`warm_reconcile.recipe_tags`): green + cold + latest + enrolled **+ tagged**. The + canonical must always be a real release — never an arbitrary untagged `main` commit. An untagged state + must never be written as a canonical. **B. Enroll ALL recipes (operator decision 2026-06-17).** Set `WARM_CANONICAL = True` for **every** recipe cc-ci tracks (the `used-recipes.md` set) — the sweep promotes a canonical for each that passes, not just @@ -55,9 +65,15 @@ to coopcloud upstream — reuse `recipe-upgrade`'s `open-recipe-pr.sh - go-git private-mirror auth, fetches coopcloud via an `upstream` remote, closes already-merged-upstream PRs, leaves unrelated PRs). This is a **faithful mirror sync, not a push of our own changes.** -**D. Add skip-when-unchanged.** After sync, if the recipe's `main` commit == its canonical record's commit -(no change since the last promotion) → **skip** (log `SKIP unchanged`). This is the operator's efficiency -ask and is also the determinism property (see M2 run-twice proof). +**D. Trigger on a new RELEASED VERSION (skip when no new version).** After sync, compute the recipe's +latest **release tag** version reachable on `main` and compare it to the canonical record's version: + - latest release tag **== canonical version** → **skip** (`SKIP no-new-version`) — *even if `main` has + new untagged commits*. The sweep tests releases, not arbitrary commits. + - latest release tag **newer than** canonical → run CI **cold on that tagged version** → promote on green + (tagged, per §2.A). + - no release tag at all (recipe never released) → skip with a recorded reason. + This is the operator's trigger refinement (version/tag-keyed, **not** commit-keyed) and the determinism + property (M2 run-twice → everything skips). **E. Keep it deterministic + AI-free at runtime** (it already is — a script + timer). The additions must stay pure code: no AI calls during the run. AI (the loops) only authors + verifies. @@ -66,46 +82,46 @@ stay pure code: no AI calls during the run. AI (the loops) only authors + verifi exact day/time is not critical — pick a low-traffic slot; it's a one-line tune. `Persistent = true` to catch up a missed run. This is the only schedule work; do not over-invest in it. -**Plays-nice-with-`samever` (operator wants this CONFIRMED, not assumed).** In the sweep, two distinct -guards keep the upgrade tier from a vacuous same-version run — and they use **deliberately different -keys**, so verify them together: - - **skip-when-unchanged uses COMMIT equality** (`main` commit == canonical commit) → if literally - nothing changed, the recipe is skipped *before* the upgrade tier runs. This is the primary - same-version avoider in the sweep. - - **`samever` uses VERSION equality** → for the case where `main` *changed* (new commit) but the version - LABEL still equals the canonical's version (a non-version-bump recipe change), the upgrade tier's base - would equal the head version, and `samever` steps back to the previous published version so a real - delta is still tested. - These are complementary: commit-equality (skip) is the coarse filter; version-equality (`samever`) is - the backstop for "changed commit, same version label." Together the sweep must **never** run a vacuous - `vX → vX` upgrade **and never** wrongly skip a real change. M2 must prove all three sweep paths - explicitly (see Gates). +**Plays-nice-with-`samever` (operator wants this CONFIRMED).** The release-tag trigger (D) makes the +sweep and `samever` **orthogonal** — confirm they don't interfere: + - In the **sweep**, a recipe runs **only when a new release tag exists**, so the version under test is + always *newer* than the canonical → the upgrade tier's base (previous canonical/released version) is + strictly older → **`samever`'s same-version step-back never fires in the sweep** (the tag trigger + already prevents a `vX→vX` run; no-new-version recipes are skipped outright). + - `samever` remains the guard for the **PR path** (`!testme`), where a PR can carry the same version + label as the canonical without cutting a release — that's where the step-back matters, and it's + owned/proven by the `samever` phase, not here. + So in the sweep, verify only: (a) no new release tag → recipe SKIPPED (no upgrade-tier run, no promote); + (b) new release tag → `canonical(older) → new tagged version`, a real delta, promote (tagged). The sweep + must never promote an untagged version and never run a same-version upgrade. ## 3. Gates **M1 — machinery works locally, each piece proven.** (A) a real `canonical.json` is produced by a green -cold run on ≥1 recipe and reused by a warm reattach — **demonstrated, not assumed**. (C) mirror-sync and -(D) skip-when-unchanged implemented, reusing the existing reconcile + sweep code, with unit tests -(skip = commit-equality; sync invoked per recipe; promote still gated on green+cold+latest+enrolled). -(B) enrollment scope decided + recorded (≥several recipes enrolled, or the decouple decision). Adversary -cold-verifies: a canonical actually exists + reattaches; skip-logic correct; sync is faithful-mirror-only; -a RED recipe does NOT promote (prior known-good intact); no AI at runtime. +cold run on ≥1 recipe and reused by a warm reattach — **demonstrated, not assumed** — and the promote gate +now also requires a **release tag** (untagged → no promote). (C) mirror-sync and (D) the **new-release-tag +trigger** implemented, reusing the existing reconcile + sweep code, with unit tests (trigger = latest +release tag vs canonical version, NOT commit; sync invoked per recipe; promote gated on +green+cold+latest+enrolled+**tagged**). (B) all recipes enrolled. Adversary cold-verifies: a canonical +actually exists + reattaches; an **untagged** state never promotes; the trigger skips no-new-tag recipes +and runs new-tag ones; sync is faithful-mirror-only; a RED recipe does NOT promote; no AI at runtime. **M2 — proven end-to-end in real CI (the heart of this phase).** A full sweep run across the enrolled set on cc-ci: mirrors synced to upstream, **canonicals actually promoted for the green recipes** (records exist with correct version+commit), red recipes left intact, unchanged recipes skipped — with a per-recipe results log. **Determinism proof: run the sweep a SECOND time immediately → it SKIPS every -recipe** (all `main` == the canonicals just promoted) = a clean no-op, no CI rerun. Confirm the **deployed -timer fires the real (non-hollow) job** — after a fire, canonicals have advanced (evidence), not exit-0 -on an empty set. +recipe** (latest release tag == canonical version for all → skip all) = a clean no-op, no CI rerun. +Confirm the **deployed timer fires the real (non-hollow) job** — after a fire, canonicals have advanced +(evidence), not exit-0 on an empty set. **Tagged-promote proven:** show a green run on an untagged state +does NOT promote, and a green run on a tagged release DOES. -**`samever` interaction proven (operator-required).** Demonstrate, with evidence, all three sweep paths: -(1) `main` commit == canonical commit → recipe SKIPPED (no upgrade tier run); (2) `main` changed + -version bumped → upgrade tier runs `canonical(older) → head(new)`, a real delta; (3) `main` changed but -version label == canonical version → `samever` steps back to the previous published version (base version -< head version), NOT a vacuous `vX→vX` and NOT skipped. Confirm the boundary explicitly: a -same-version-label-but-different-commit recipe is **not** skipped (commits differ) and **does** hit the -`samever` step-back. Construct the scenarios if the natural recipe set doesn't cover all three. +**`samever` orthogonality proven (operator-required).** Demonstrate, with evidence, the two sweep paths: +(1) **no new release tag** (latest tag == canonical version, even with new untagged commits on `main`) → +recipe SKIPPED — no upgrade-tier run, no promote; (2) **new release tag** → cold-test the new tagged +version, upgrade `canonical(older) → new`, a real delta, promote (because tagged). Confirm `samever`'s +step-back **never fires inside the sweep** (the tag trigger prevents same-version runs) — its same-version +behavior is owned/proven by the `samever` phase on the PR path. Construct scenarios if the live recipe set +doesn't cover both. No AI in the loop. Fresh Adversary PASS on both milestones → `## DONE`. @@ -127,10 +143,12 @@ No AI in the loop. Fresh Adversary PASS on both milestones → `## DONE`. ## 5. Definition of Done -The canonical sweep **actually works and is proven**: a green cold-on-latest run produces a real, -reusable `canonical.json`; the sweep reconciles each recipe mirror's `main` to upstream, skips recipes -whose `main` is unchanged vs canonical, runs CI on the rest, and promotes the canonical for any that pass -— across a real multi-recipe set, demonstrated end-to-end in CI, including the run-twice no-op determinism -proof and a real (non-hollow) timer fire. Enrollment scope + the warm-volume budget decided/recorded; the -runtime job is AI-free; it is the substitute for the hollow nightly sweep (not a parallel job). M1 + M2 -fresh Adversary PASSes in REVIEW-canon.md. +The canonical sweep **actually works and is proven**: a green cold run on a **tagged release** produces a +real, reusable `canonical.json` (an untagged state never promotes); the sweep reconciles each recipe +mirror's `main` to upstream, **skips recipes with no new release tag** (even if `main` has new untagged +commits), runs CI cold on the new tagged version for the rest, and promotes the canonical only to that +tagged release — across all enrolled recipes, demonstrated end-to-end in CI, including the run-twice no-op +determinism proof, the tagged-promote proof, and a real (non-hollow) timer fire. `samever` confirmed +orthogonal (never fires in the sweep). All recipes enrolled + warm-volume budget recorded; the runtime job +is AI-free; it is the substitute for the hollow nightly sweep (not a parallel job). M1 + M2 fresh Adversary +PASSes in REVIEW-canon.md.