diff --git a/.opencode/skills/cctest-recipe-upstream/SKILL.md b/.opencode/skills/cctest-recipe-upstream/SKILL.md
index 6d27932..52bac6f 100644
--- a/.opencode/skills/cctest-recipe-upstream/SKILL.md
+++ b/.opencode/skills/cctest-recipe-upstream/SKILL.md
@@ -71,3 +71,13 @@ If the operator's checkout does NOT yet have the mirror remote, emit once before
 In both modes the final output is a set of commands for the operator to run on a machine **with
 push access to `git.coopcloud.tech`** — always print them, even when everything local is
 already prepared.
+
+**History-divegence check before emitting the compare URL.** The autonomic recipe-maintainer
+mirrors' `main` can share only a distant ancestor with upstream `main` (same work re-committed
+with different hashes as the mirror was synced/rebuilt). A 3-dot compare
+`main...<head_ref>` from the raw mirror branch then shows the ENTIRE diverged history, not the
+one upgrade commit. Guard: while preparing, run
+`git merge-base <head_ref> <base_ref>`; if the result is older than a few commits below upstream
+`origin/main`, cherry-pick the upgrade commit(s) onto fresh upstream `origin/main` (branch
+`<head_ref>-rebased`), push THAT to the autonomic mirror, and emit the fetch/push/compare commands
+using the rebased branch instead of the raw one.
diff --git a/scripts/gen-cctest-skills.py b/scripts/gen-cctest-skills.py
index e90c4be..8ea4d21 100644
--- a/scripts/gen-cctest-skills.py
+++ b/scripts/gen-cctest-skills.py
@@ -99,6 +99,16 @@ If the operator's checkout does NOT yet have the mirror remote, emit once before
 In both modes the final output is a set of commands for the operator to run on a machine **with
 push access to `git.coopcloud.tech`** — always print them, even when everything local is
 already prepared.
+
+**History-divegence check before emitting the compare URL.** The autonomic recipe-maintainer
+mirrors' `main` can share only a distant ancestor with upstream `main` (same work re-committed
+with different hashes as the mirror was synced/rebuilt). A 3-dot compare
+`main...<head_ref>` from the raw mirror branch then shows the ENTIRE diverged history, not the
+one upgrade commit. Guard: while preparing, run
+`git merge-base <head_ref> <base_ref>`; if the result is older than a few commits below upstream
+`origin/main`, cherry-pick the upgrade commit(s) onto fresh upstream `origin/main` (branch
+`<head_ref>-rebased`), push THAT to the autonomic mirror, and emit the fetch/push/compare commands
+using the rebased branch instead of the raw one.
 """,
 }