ci(extension): retire the manual-bump guard, true up the docs (step 5)

The guard asked whether a packaged extension file changed without the
version moving. Since step 4 nobody moves the version by hand, so it was
checking a fact that had stopped existing — and it was not merely dead
weight: it would have failed the lane on every real extension change,
demanding a bump that decides nothing. Removed rather than left running
beside the new mechanism (rule 22).

What replaces it is thinner and true. The extension-version lane now
asserts the derivation resolves on this commit, that the derived value is
the plain dotted-numeric shape AMO accepts, and that MAJOR.MINOR agrees
between manifest.json and package.json. MAJOR.MINOR is the one part still
hand-set, and packaging.sh reads it from manifest.json ALONE, so a
divergence ships a version package.json disagrees with. The lane keeps
fetch-depth: 0 — checking that the derivation survives a real checkout is
half its remaining value.

Deliberately not checked there: that the derived value beats what is
already signed. That guard belongs in build.yml, where it compares against
the real ext-* releases. Comparing against origin/main in a lane would be
wrong, because dev legitimately derives a LOWER value whenever main is
ahead on the extension, and a lane that fails for being behind is a lane
people learn to ignore.

packaging.sh is down to two consumers from three. version.spec.js's
"ci.yml derives its pathspec" test would have gone red on that, so it is
rewritten to assert the property rather than the consumer: no workflow
inlines an :(exclude)extension/ literal, across all three. That keeps the
#2397 anti-regression value while surviving consumers coming and going.
A second test pins build.yml to packaging.sh version and fails if it goes
back to grepping the committed value — which is not a style regression but
the #3092 bug itself. build.yml joins extension.yml's trigger paths, since
the suite now asserts against it.

The lockstep test narrows from the whole version string to MAJOR.MINOR.
The committed patch numbers are inert now; asserting on them would fail
for a difference that changes nothing.

Docs. extension/README.md's Release section described extension.yml
signing on main and committing the XPI into frontend/public/ — untrue
since 2026-05-25, and it told the reader to hand-bump both files, which is
now exactly the wrong instruction. Rewritten, with a Versioning section
that says plainly that editing the patch number does nothing and why the
key is commit time rather than a count. ci-requirements.md drops the third
packaging.sh consumer and names every job that needs full history. Root
README no longer claims the extension is signed on main only.

.forgejo/workflows/ci.yml

@@ -2,7 +2,7 @@ name: CI
 
 # CI lanes per FabledRulebook/forgejo.md "CI philosophy":
 #   - lint: ruff only, no dep install — fast-fail for the common lint bounce.
-#   - extension-version: guards the extension publish path (see the job).
+#   - extension-version: the derived version resolves and MAJOR.MINOR agrees.
 #   - backend-lint-and-test: `pytest -m "not integration"`, no service containers.
 #   - frontend-build: vitest unit + vite build.
 #   - integration: pgvector + redis service containers; alembic + `pytest -m integration`.
@@ -42,18 +42,29 @@ jobs:
         # catching syntax errors before the image build.
         run: python -m compileall -q agent/fc_agent
 
-  # Guards the extension publish path, which has no self-correcting behavior.
+  # The extension version is DERIVED, not hand-maintained (milestone 271 step
+  # 4): build.yml computes it from the commit TIME of the newest packaged
+  # extension change and stamps it into manifest.json / package.json at build
+  # time. The guard that used to live here — "packaged files changed but nobody
+  # bumped the version" — was therefore checking a fact that had stopped
+  # existing. Worse than useless: it would have failed this lane on every real
+  # extension change, demanding a bump that decides nothing. Retired 2026-08-27
+  # rather than left running beside the new mechanism (rule 22).
   #
-  # build.yml's sign-extension job keys its AMO-signing cache purely on the
-  # version string in extension/package.json: if an `ext-<version>` Forgejo
-  # release already carries an XPI, signing is SKIPPED and that old signed XPI
-  # is what build-web bakes into `:latest`. Nothing in that path inspects
-  # whether extension/ actually changed — so a forgotten version bump ships a
-  # stale extension on a fully green build, silently. (AMO can't help: it 409s
-  # on re-signing a version, which is exactly why the cache exists.)
+  # Two things are still worth asserting, and this is the only lane that can:
+  # the extension.yml suite runs on node:24-slim, which is exactly why
+  # version.spec.js sticks to packaging.sh's git-free subcommands.
+  #   1. the derivation actually resolves on this commit
+  #   2. MAJOR.MINOR agrees between the two files — the one part still hand-set,
+  #      and packaging.sh reads it from manifest.json ALONE, so a divergence
+  #      ships a version package.json disagrees with
   #
-  # This job makes that case loud, on the dev push, instead of invisible at
-  # merge-to-main. It is pure git + text work — no deps, no services.
+  # Deliberately NOT checked here: that the derived value beats what has already
+  # been signed. That guard belongs in build.yml, where it compares against the
+  # real ext-* releases. Comparing against origin/main here would be wrong —
+  # dev legitimately derives a LOWER value whenever main is ahead on the
+  # extension, and a lane that fails for being behind is a lane people learn to
+  # ignore.
   extension-version:
     runs-on: python-ci
     container:
@@ -61,97 +72,37 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          # Full history: the check diffs against the push's `before` SHA (or
-          # the PR base), which a depth-1 clone wouldn't contain.
+          # The derivation needs real history: a depth-1 clone sees one commit
+          # and produces a wrong, too-low value RATHER THAN FAILING. Checking
+          # that here is half the point of the lane.
           fetch-depth: 0
-      - name: Extension version guard
-        env:
-          BEFORE: ${{ github.event.before }}
-          PR_BASE: ${{ github.event.pull_request.base.sha }}
+      - name: Extension version derives cleanly
         run: |
           set -eu
           # busybox sh on the act_runner — no bashisms (family rule).
-          ver() { grep -E '"version"' "$1" | head -1 | sed -E 's/.*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/'; }
-          PKG=$(ver extension/package.json)
-          MAN=$(ver extension/manifest.json)
-          test -n "$PKG" || { echo "ERROR: no version found in extension/package.json"; exit 1; }
-          test -n "$MAN" || { echo "ERROR: no version found in extension/manifest.json"; exit 1; }
-
-          # (1) Unconditional: the two version strings must agree. `web-ext sign`
-          # reads manifest.json (package.json sits in --ignore-files and isn't
-          # even inside the XPI), so AMO signs MAN and Firefox installs MAN.
-          # build.yml keys its cache, release tag, XPI filename — and therefore
-          # the version /api/extension/manifest reports to the update prompt —
-          # on PKG. Divergence either hard-fails at AMO or ships a mislabelled
-          # XPI whose update prompt lies about what's installed.
+          VERSION=$(sh extension/scripts/packaging.sh version)
+          echo "derived: $VERSION"
+          # The shape AMO accepts, and the shape build.yml will stamp.
+          if ! echo "$VERSION" | grep -qE '^[0-9]+(\.[0-9]+)*$'; then
+            echo "ERROR: derived version '$VERSION' is not plain dotted-numeric."
+            echo "AMO would reject it, and build.yml stamps it verbatim."
+            exit 1
+          fi
+          mm() { grep -E '"version"' "$1" | head -1 | sed -E 's/.*"version"[[:space:]]*:[[:space:]]*"([0-9]+\.[0-9]+).*/\1/'; }
+          MAN=$(mm extension/manifest.json)
+          PKG=$(mm extension/package.json)
+          test -n "$MAN" || { echo "ERROR: no parseable version in extension/manifest.json"; exit 1; }
+          test -n "$PKG" || { echo "ERROR: no parseable version in extension/package.json"; exit 1; }
           if [ "$MAN" != "$PKG" ]; then
-            echo "ERROR: extension version mismatch."
-            echo "  extension/manifest.json = $MAN  <- what AMO signs / Firefox installs"
-            echo "  extension/package.json  = $PKG  <- what CI caches, names, and reports"
-            echo "Set both to the same value."
+            echo "ERROR: MAJOR.MINOR disagrees between the two files."
+            echo "  extension/manifest.json = $MAN  <- packaging.sh reads MAJOR.MINOR from here"
+            echo "  extension/package.json  = $PKG"
+            echo "Only MAJOR.MINOR is hand-set. The patch component is derived from"
+            echo "commit time and overwritten at build time, so the committed patch"
+            echo "numbers are inert — but MAJOR.MINOR still ships. Set both the same."
             exit 1
           fi
-
-          # (2) If the SHIPPED extension changed, the version must have moved.
-          #
-          # Compare against MAIN, not against the previous push. The publish
-          # decision is made at merge-to-main against whatever ext-<version>
-          # already exists, so "differs from main" is the question that matters.
-          # Diffing against the previous dev push instead would demand a fresh
-          # bump on every iteration — push, tweak the extension again, and CI
-          # would insist on a second bump that buys nothing, inflating the
-          # version for no reason. On a main push there is no "main to compare
-          # to" yet, so fall back to that push's own before-SHA.
-          if [ "${GITHUB_REF##*/}" = "main" ]; then
-            BASE="${BEFORE:-}"
-          else
-            BASE=$(git rev-parse --verify -q origin/main 2>/dev/null || git rev-parse --verify -q main 2>/dev/null || echo "")
-            # PR base is the fallback when main isn't in the clone at all.
-            [ -n "$BASE" ] || BASE="${PR_BASE:-}"
-          fi
-          case "$BASE" in
-            ''|0000000000000000000000000000000000000000)
-              echo "No usable base ref (no main in clone / first push) — skipping the bump check."
-              echo "OK: extension version $PKG"
-              exit 0
-              ;;
-          esac
-          if ! git cat-file -e "$BASE^{commit}" 2>/dev/null; then
-            echo "Base commit $BASE not in this clone — skipping the bump check."
-            echo "OK: extension version $PKG"
-            exit 0
-          fi
-          # The exclusion list is NOT written out here — it comes from
-          # extension/scripts/packaging.sh, the one definition of what ships,
-          # shared with web-ext's --ignore-files and the derived-version patch
-          # count. Three hand-kept copies of that fact is how #2397 happened.
-          #
-          # `set -f` is required around the substitution: without it the shell
-          # globs `test/**` against the working tree and silently narrows it.
-          set -f
-          CHANGED=$(git diff --name-only "$BASE" HEAD -- extension/ $(sh extension/scripts/packaging.sh pathspec))
-          set +f
-          if [ -z "$CHANGED" ]; then
-            echo "No packaged extension files changed since $BASE — nothing to guard."
-            echo "OK: extension version $PKG"
-            exit 0
-          fi
-          echo "Packaged extension files changed since $BASE:"
-          echo "$CHANGED" | sed 's/^/  /'
-          PKG_OLD=$(git show "$BASE:extension/package.json" 2>/dev/null | grep -E '"version"' | head -1 | sed -E 's/.*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/')
-          if [ -z "$PKG_OLD" ]; then
-            echo "Could not read the base version — skipping the bump check."
-            echo "OK: extension version $PKG"
-            exit 0
-          fi
-          if [ "$PKG_OLD" = "$PKG" ]; then
-            echo "ERROR: packaged extension files changed but the version is still $PKG."
-            echo "build.yml would find the existing ext-$PKG release, skip AMO signing,"
-            echo "and bake the OLD signed XPI into :latest — a green build shipping stale code."
-            echo "Bump the version in BOTH extension/package.json and extension/manifest.json."
-            exit 1
-          fi
-          echo "OK: extension version $PKG_OLD -> $PKG"
+          echo "OK: MAJOR.MINOR $MAN, derived version $VERSION"
 
   backend-lint-and-test:
     runs-on: python-ci