Docs: SPEC §9 + §13 — note appctl prod upgrade tooling

§9 gains a Shipped entry for the new prod-upgrade subcommand
(f87660e), covering VER resolution (default `latest`, virtual
`test`), the dirty-tree prompt, the unknown-ref bail-before-stop
behaviour, completion changes, and the fact that the `latest`
tag is local-only at v0.26.0 (bcdc63a) until pushed.

§13 picks up the two prior commits (f87660e, 86baa95) on top of
the existing list. Note §13 still lags the 10 commits between
14b1cfd and f87660e (v0.26.0 release era + R02-N03 fix + dev/prod
compose split + /check skill + Makefile→appctl + HTTP_PORT) —
those should be backfilled in a follow-up.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

SPEC.md

@@ -1657,6 +1657,22 @@ OIDC kill-switch (`OIDC_ENABLED=false`):
       `CapacityCalculator.php` and its tests are untouched. First fix
       from `doc/REVIEW_02.md`.
 
+- [x] **`appctl prod upgrade` — pinned redeploy by release tag**
+      (`f87660e`). New subcommand on the `bin/appctl` wrapper that
+      stops the prod stack, fetches, checks out a target ref, rebuilds
+      images, and starts the stack again. The target defaults to the
+      `latest` lightweight git tag (manually pointed at the current
+      release; bump with `git tag -f latest vX.Y.Z`). The keyword
+      `test` is virtual and resolves to `origin/main` HEAD after
+      fetch, so bleeding-edge redeploys don't need a real branch tag.
+      Dirty working trees print the diff and prompt before any
+      destructive step; an unknown ref errors out *before* the stack
+      is stopped. Bash completion offers `latest`, `test`, and every
+      `v*` tag from `git tag` at the third word. `latest` is local-
+      only on the repo where this was introduced (`bcdc63a` =
+      `v0.26.0`) — it is not pushed to `origin` and won't appear in
+      fresh clones until someone runs `git push origin latest`.
+
 ### Upcoming
 
 Nothing scheduled.
@@ -1848,6 +1864,8 @@ before acting — nothing here is load-bearing once it grows stale.
 ## 13. Git history (as of this writing)
 
 ```
+86baa95 Docs: SPEC §11 — add `appctl prod upgrade` row to the command table
+f87660e Tooling: appctl prod upgrade — pin a prod box to a release tag
 14b1cfd Fix R02-N01: drop JS-side capacity arithmetic, server is authoritative
 ef9b9b8 Fix R01-N16, doc R01-N17: composer-audit helper + admin-manual cadence note
 a0b717e Fix R01-N18: trust OIDC email only when issuer hasn't marked it unverified