From 524a3c3153b95f32b89bb11fb8b1b310c345a852 Mon Sep 17 00:00:00 2001
From: Sam & Claude <hello@clawdie.si>
Date: Thu, 25 Jun 2026 11:29:58 +0200
Subject: [PATCH] =?UTF-8?q?skill(freebsd):=20tighten=20cross-release=20ove?=
 =?UTF-8?q?rride=20=E2=80=94=20one-time,=20IGNORE=5FOSVERSION,=20date=20YY?=
 =?UTF-8?q?YY?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Four corrections from Codex review:

1. One-time caveat: OSVERSION/IGNORE_OSVERSION is for the boundary only.
   Remove it after reboot — persisting would spoof the wrong version on
   the next upgrade and silently pull mismatched packages.

2. IGNORE_OSVERSION=yes as the canonical idiom (does not require knowing
   the exact __FreeBSD_version number).

3. ABI="FreeBSD:15:amd64" marked as redundant (it is already the default
   on 15.x; OSVERSION is the actual lever).

4. Date format: DD.mon.YY → DD.mon.YYYY (matches eu-date-format convention).
   Live BE renamed to 15.1-upgrade-25.jun.2026.
---
 skills/freebsd-os-upgrade/SKILL.md | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/skills/freebsd-os-upgrade/SKILL.md b/skills/freebsd-os-upgrade/SKILL.md
index 763f315..b67a982 100644
--- a/skills/freebsd-os-upgrade/SKILL.md
+++ b/skills/freebsd-os-upgrade/SKILL.md
@@ -77,14 +77,14 @@ pkg update -f && pkg upgrade      # ports packages (separate from base here)
    puts you back exactly where you were.
 
    ```sh
-   bectl create MAJOR.MINOR-upgrade-DD.mon.YY
-   # example:  15.1-upgrade-25.jun.26
+   bectl create MAJOR.MINOR-upgrade-DD.mon.YYYY
+   # example:  15.1-upgrade-25.jun.2026
    bectl list | grep upgrade
    ```
 
-   Name convention: `<target-release>-upgrade-<EU date>` — operator-facing,
-   readable at a glance. pkg does NOT auto-create ZFS boot environments;
-   this must be done manually.
+   Name convention: `<target-release>-upgrade-<EU date (DD.mon.YYYY)>` —
+   operator-facing, readable at a glance. pkg does NOT auto-create ZFS boot
+   environments; this must be done manually.
 
 3. **Upgrade base** (by the method from step 0):
    - **pkgbase**: a pkgbase host already has a `FreeBSD-base` repo — **inspect
@@ -96,11 +96,16 @@ pkg update -f && pkg upgrade      # ports packages (separate from base here)
      `pkg upgrade -n` to confirm 15.1 base packages are actually offered, then
      `pkg upgrade` (base + ports together).
      
-     **Cross-release override:** pkgbase refuses to fetch packages for a
-     newer release while running the old userland. Override with:
-     `env OSVERSION=1501000 ABI="FreeBSD:15:amd64" pkg update -f` then use
-     the same env for `pkg upgrade -n` and the real `pkg upgrade`.
-     (Replace `1501000` with the target release's __FreeBSD_version.)
+     **Cross-release override (one-time, for the boundary only):** pkgbase
+     refuses to fetch packages for a newer release while running the old
+     userland. The standard bypass is `IGNORE_OSVERSION=yes`. Alternatively,
+     spoof the target release with `OSVERSION=<target>` (ABI is already the
+     default and can be omitted):
+     `env IGNORE_OSVERSION=yes pkg update -f` then use the same env for
+     `pkg upgrade -n` and the real `pkg upgrade`.
+     **Remove this override after reboot** — once `freebsd-version` shows the
+     new release, persisting it would spoof the wrong version on the NEXT
+     upgrade and silently pull mismatched packages.
    - **freebsd-update**: `freebsd-update -r <target> upgrade` then
      `freebsd-update install`.
    Either way the new kernel is staged; the system runs the old one until reboot.