check-doc-drift: check 9 — what the next build bakes differently must be named in the CHANGELOG

The two most recent Unreleased entries (pi-extensions 25c1265: task tool +
fork-gate; mempalace-toolkit 817b3a8: the mine deadline that never reached
the transport) reached this image through floating *_REF=main ARGs. Neither
produced a diff here, so nothing asked for a CHANGELOG line, and neither had
one until a reader asked. Same class as check 8 — a claim with no in-repo
anchor rots — and the hand practice that covered it (the per-release
"Dependency audit" table, Baked-in vs Upstream-now) is a someone-remembers
mechanism that had lapsed.

Method, no docker/crane/token: last published vX.Y.Z from Hub's tag list
(one request, now shared with check 8); its amd64 config blob via the
anonymous registry API carries one se.jordbo.pi-devbox.<name>-ref label per
component with the SHA the build-args baked. "Would bake" is resolved the way
resolve-versions does it: 40-hex ARG is itself, branch/tag via git ls-remote
with the peeled ^{} form preferred, pi-studio = highest semver tag (label on
<tag>-studio), PI_VERSION as a literal against the pi-version label. Nine
components, ~7.5 s. Unchanged: OK. Moved: the new value's 7-char prefix (tag
for studio, version for pi) must appear above the last published version's
"## " heading — Unreleased plus any not-yet-published section, which is what
the release commit turns Unreleased into, so the tag build passes on the same
text. A published tag with no heading is a failure, not a skip.

First run found a move nobody had recorded: pi-observational-memory 7b397f4
-> cba0334 (6 commits, 3.1.1 -> 3.1.3; memory workers now routed by the
model's exact provider instead of the first registered provider with a
matching api — upstream #70). Named in the CHANGELOG with the honest scope:
no expected effect on the shipped bedrock-only configuration, unmeasured.

Sabotage-tested, expectation written before each run:
  obsmem SHA removed from CHANGELOG ............ rc=1  DRIFT
  Unreleased renamed to "## v1.9.3 — …" ........ rc=0  (release-commit shape)
  "## v1.9.2" heading mangled to v1.9.2-typo .... rc=1  — this one FAILED first:
      \b accepted "v1.9.2-typo" as v1.9.2's heading; now (\s|$)
  bare "## v1.9.2" (no date) ................... rc=0
  ARG PI_OBSMEM_REPO renamed ................... rc=2  (blind gate must not pass;
      read_arg calls are bare top-level assignments on purpose — nested in a
      heredoc's $(...) the exit 2 is swallowed by cat)
  offline (proxy to a closed port) ............. rc=0, 2 SKIPs counted
  SKIP_REF_CHECK=1 ............................. rc=0, 1 SKIP counted
  restored ..................................... rc=0, files byte-identical
GIT_TERMINAL_PROMPT=0 on ls-remote: a repo flipped private fails in 0.3 s as
a SKIP instead of waiting for a username until the job times out.

Header, lint.yml job comment and AGENTS.md all still said this gate "needs
no network" — false since check 8 (2026-09-14). Now: two classes, hermetic
1-7 and published-state 8-9 that SKIP loudly and counted when offline.
Considered and not added: compose <-> .env.example variable cross-check (the
four mismatches are commented-out lines, the mempalace-server compose file's
own variables, and entrypoint-consumed ones — it would fire on nothing
wrong); "documented tag exists on Hub" (check 8 already SKIPs by name; a
hard fail would misreport the tag-to-publish window).

CHANGELOG.md

@@ -13,6 +13,70 @@ Pre-v1.0.0 tags followed the pi npm version (`v{pi_version}[letter]`).
 
 ## Unreleased
 
+**New check 9 in `scripts/check-doc-drift.sh`: anything the next build would bake
+differently from the last *published* release must be named in the CHANGELOG text
+above that release's heading.** The two entries below this one are why. The
+`task` tool and `fork-gate` (pi-extensions `25c1265`) and the mine-deadline fix
+(mempalace-toolkit `817b3a8`) both reach this image through floating
+`*_REF=main` ARGs, so neither produced a diff in this repo, nothing here asked
+for a CHANGELOG line, and neither had one until a reader asked. Same shape as
+check 8: a claim with no in-repo anchor rots. The hand practice that existed for
+it — the "Dependency audit" table in each release's notes, *Baked in vN* against
+*Upstream now* — is a "someone remembers" mechanism, and it had lapsed.
+
+How it measures, with no `docker`, `crane` or token: the last published
+`vX.Y.Z` is the highest such tag in Hub's list (one request, shared with
+check 8); that tag's amd64 config blob is read through the anonymous registry
+API (token → index → per-arch manifest → config) and carries one
+`se.jordbo.pi-devbox.<name>-ref` label per component holding the SHA the
+build-args actually baked. "What the next build would bake" is resolved the way
+`resolve-versions` does it — a 40-hex ARG is itself, a branch or tag is
+`git ls-remote`d with the peeled `^{}` form preferred (the un-dereferenced SHA of
+an annotated tag is the tag object; this repo has raised that false alarm once
+already), pi-studio is the highest semver tag read from `<tag>-studio`'s labels,
+and `PI_VERSION` is compared as a literal against the `pi-version` label. Nine
+components, 7.5 s.
+
+The rule: unchanged needs no mention. Moved requires the new value's 7-char SHA
+prefix (tag name for pi-studio, version string for pi) somewhere above the last
+published version's `## ` heading — `## Unreleased` plus any not-yet-published
+`## vX.Y.Z`, which is what the release commit turns Unreleased into, so the tag
+build passes on the same text — sabotage-tested: renaming `## Unreleased` to
+`## v1.9.3 — …` stays green; mangling the published `## v1.9.2` heading goes
+red, and that test caught a `\b` that would have accepted `v1.9.2-typo` as the
+heading (now `(\s|$)`). Naming the SHA rather than the repo is
+deliberate: it is what the audit table always recorded, and it makes the failure
+message's compare URL one click from knowing what moved. Every upstream commit
+re-reds the gate until the CHANGELOG names the new head; that is the intended
+cost — **the thing that gets baked is the thing that gets named.** A published
+tag with no CHANGELOG heading is a failure, not a skip.
+
+**First run found a move nobody had recorded.** `pi-observational-memory`
+`7b397f4 → cba0334` (6 upstream commits, 2026-09-14..16, 3.1.1 → 3.1.3): the
+memory workers' `streamSimple` lookup used to iterate every extension-registered
+provider and take the first whose `api` matched the model's, so two providers
+sharing an API type could route the observer to the wrong one (upstream #70);
+it now asks for the model's exact provider and keeps the `api` match as a
+consistency check. Reaches this image on the next variant build via
+`PI_OBSMEM_REF=master`. No behaviour change expected on the shipped
+configuration — every profile here uses the built-in `amazon-bedrock` provider
+and no extension registers one — but that is an expectation, not a
+measurement; the code path only differs when an extension has called
+`registerProvider`.
+
+Header and `lint.yml` comment corrected alongside: both still said this gate
+"needs no network", which check 8 made false on 2026-09-14. There are now two
+classes — hermetic checks 1–7, and published-state checks 8–9 that SKIP loudly
+and counted when offline. Considered and not added, with reasons in the script:
+a `docker-compose.yml` ↔ `.env.example` variable cross-check (the four
+mismatches are commented-out lines, the mempalace-server compose file's own
+documented variables, and two entrypoint-consumed variables — a gate there
+would fire on nothing wrong), and a "documented tag exists on Hub" check
+(check 8 already SKIPs a missing tag by name, and a hard fail would
+misreport the window between tagging and publish).
+
+---
+
 **The rule "use `pi-task`, not `fork`, for a brief that carries a prohibition" was
 written in the global `AGENTS.md` and in the pi-extensions skill, and it lost to
 the `fork` tool's own description anyway.** Measured on tor-ms22, 2026-09-17: five