feat(site): the llms mirrors are gated, and a tag cannot carry stale ones

Task 15's monorepo half. The site half is committed in the site repo and
deliberately held — see the plan.

The mirrors state the shipping versions in prose and the site will copy them
from the release tag, so a mirror that lags makes the published site lag,
silently: the copy succeeds and stale numbers look exactly like fresh ones.
finish-release.mjs now refuses to tag a tree whose mirrors do not name the
release. v0.24.5 would have failed that gate, which is why the site half is
held rather than pushed.

The test's first draft forbade any 0.x/7.x string other than the current one
and failed on "were retired in 0.24.0" — a correct historical sentence. A doc
is free to discuss an older release; it is not free to omit the current one,
and a lagging mirror omits it because the old number sits where the new one
goes. So the assertion is positive, the one-line summary is pinned separately
because "mentions 0.24.5" and "says we ship 0.24.5" are different claims, and
the remaining bound is stated in the test rather than hidden.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NynrRND6ZUwGvq3ZUTCfxG

Author: dmealing

docs/superpowers/plans/2026-08-29-website-self-updating-codegen.md

@@ -2102,7 +2102,7 @@ git commit -m "feat(site): per-registry version payload (never one version strin
 - Modify (site repo): `.github/workflows/deploy.yml`
 - Test: `scripts/site/llms.test.ts`
 
-- [ ] **Step 1: Write the failing test**
+- [x] **Step 1: Write the failing test**
 
 ```ts
 import { describe, test, expect } from "bun:test";
@@ -2128,7 +2128,7 @@ describe("llms mirrors", () => {
 });
 ```
 
-- [ ] **Step 2: Add the deploy copy step**
+- [x] **Step 2: Add the deploy copy step**
 
 In the same clone the Task 13 step already made — do not clone twice:
 
@@ -2137,26 +2137,58 @@ In the same clone the Task 13 step already made — do not clone twice:
         cp /tmp/mo/docs/llms/llms-full.txt "$GITHUB_WORKSPACE/www/llms-full.txt"
 ```
 
-- [ ] **Step 3: Stop tracking the mirrors in the site repo**
+- [x] **Step 3: Stop tracking the mirrors in the site repo**
 
 `git rm --cached www/llms.txt www/llms-full.txt` and gitignore them. A file that is both committed and overwritten at deploy invites someone to edit the copy that loses.
 
-- [ ] **Step 4: Verify live**
+- [~] **Step 4: Verify live**
 
 After the deploy, `curl -s https://metaobjects.dev/llms.txt | head -20` must match `docs/llms/llms.txt`.
 
 **State the claim honestly.** An earlier draft said this "removes 20 of the original 31 hand-edited version references." It does not. `docs/llms/llms.txt` contains literal `0.24.4` (3×), `7.24.4` (6×) and `0.24.0`; `llms-full.txt` has 10 more. Copying them de-duplicates the edit — those refs stop being maintained in TWO repos and stay maintained in ONE — but nothing here generates them from `SitePayload.registries`.
 
 Generating them is a real follow-on (template + the `registries` block), deliberately not folded in: `docs/llms/*` is also consumed directly by agents from this repo, so templating it is a change to an adopter-facing artifact and deserves its own decision.
 
-- [ ] **Step 5: Commit**
+- [x] **Step 5: Commit**
 
 ```bash
 git add scripts/site/llms.test.ts && git commit -m "feat(site): llms mirrors generated at deploy"
 ```
 
 ---
 
+> **DONE 2026-08-30 except step 4, which waits on the next release — and the reason is a
+> defect this task found in the tag, not in the copy.**
+>
+> Monorepo: `scripts/site/llms.test.ts`, plus a new gate in `scripts/finish-release.mjs`.
+> Site repo: `deploy.yml` + `.gitignore`, **committed at `ef743d7` and deliberately NOT
+> pushed.**
+>
+> **Why it is held.** `v0.24.5`'s `docs/llms/` still reads `0.24.4`: the docs refresh has
+> always been a post-tag commit, and the tag was cut mid-release. Deploying the copy step
+> against that tag would REGRESS the live mirrors by a release — worse than the drift this
+> task removes. `finish-release.mjs` now refuses to tag a tree whose mirrors do not name the
+> release, so the next tag is fresh by construction and the site half can be pushed
+> immediately after it.
+>
+> **One structural change the plan did not call for.** The plan put the `cp` beside the
+> injection, inside the guard that skips when the tag predates the injector. But step 3
+> UNTRACKS the mirrors, so a skipped copy no longer leaves a stale file — it leaves **no
+> file**, and `/llms.txt` 404s on a documented URL. The copy therefore runs BEFORE that
+> guard, it has its own presence check, and a missing source warns rather than failing, on
+> the same reasoning as the injector guard: one absent text file must not take down the
+> site.
+>
+> **The test's first draft was wrong in a way worth keeping.** It forbade any `0.x`/`7.x`
+> string other than the current one, and failed on *"`@verifiedBy` … were retired in
+> `0.24.0`"* — a correct historical sentence. Rewritten to assert POSITIVELY that each
+> mirror names the current npm and Maven versions, which is what a lagging mirror stops
+> doing, and to pin the one-line summary separately: "the file mentions 0.24.5 somewhere"
+> and "the summary says we ship 0.24.5" are different claims and only the second is acted
+> on. Bound stated in the test: it passes if a mirror names the current version and leaves
+> an old shipping claim beside it. Proven by staling `docs/llms/llms.txt` — both assertions
+> red, green on restore.
+
 ### Task 16: `--metamodel --site` stops lying
 
 A flag the CLI accepts and silently ignores. This ships to adopters and is worth fixing on its own, independent of the website.

scripts/finish-release.mjs

@@ -132,7 +132,25 @@ for (const rel of ["scripts/site-inject-ci.mjs", "examples/showcase/site-payload
 }
 ok("the deploy's injector and payload are both in the tagged tree");
 
-// ── 5. the tag the DEPLOY will resolve is the one being cut ──────────────────
+// ── 5. the llms mirrors state this release ───────────────────────────────────
+// The site COPIES docs/llms/* from this tag (Task 15), so a mirror that lags makes the
+// published site lag — silently, because the copy succeeds and stale numbers look like
+// fresh ones. `v0.24.5` carries mirrors reading `0.24.4`, because the docs refresh has
+// always been a post-tag commit; with the tag moving to the end, it no longer has to be.
+for (const rel of ["docs/llms/llms.txt", "docs/llms/llms-full.txt"]) {
+  const text = out(`git show HEAD:${rel}`);
+  const missing = [
+    ...(text.includes(VERSION) ? [] : [`npm ${VERSION}`]),
+    ...(text.includes(MAVEN_VERSION) ? [] : [`Maven ${MAVEN_VERSION}`]),
+  ];
+  if (missing.length > 0) {
+    die(`${rel} does not name ${missing.join(" or ")} — refresh the mirrors before tagging, ` +
+        `or the site publishes the previous release's versions (RELEASING-docs-checklist).`);
+  }
+}
+ok("the llms mirrors state this release");
+
+// ── 6. the tag the DEPLOY will resolve is the one being cut ──────────────────
 // The repo carries two tag lines and `sort -V` over a bare `v*` returns v7.20.12, which
 // has no examples/showcase at all. This mirrors deploy.yml's own filter, so a change to
 // either is caught here rather than on a deploy nobody is watching.
@@ -146,7 +164,7 @@ ok(`the site deploy will resolve ${tag}`);
 
 if (CHECK_ONLY) { ok("--check: gates passed; no tag cut"); process.exit(0); }
 
-// ── 6. cut it ────────────────────────────────────────────────────────────────
+// ── 7. cut it ────────────────────────────────────────────────────────────────
 execSync(`git tag -a ${tag} -m "metaobjects ${VERSION} / ${MAVEN_VERSION}"`, { cwd: REPO, stdio: "inherit" });
 execSync(`git push origin ${tag}`, { cwd: REPO, stdio: "inherit" });
 ok(`cut and pushed ${tag}`);

scripts/site/llms.test.ts

@@ -0,0 +1,66 @@
+// The agent-facing mirrors the site serves at metaobjects.dev/llms.txt.
+//
+// These files are consumed two ways — read directly out of this repo by an agent, and
+// served by the website — so they are the one artifact where "correct in the repo" and
+// "correct on the site" have historically been different facts. Task 15 makes the site
+// copy from here at deploy so there is one maintained copy; these pin the properties that
+// copy assumes.
+import { describe, expect, test } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { buildPayload } from "./payload.js";
+
+const REPO = resolve(import.meta.dirname, "../..");
+const MIRRORS = ["llms.txt", "llms-full.txt"] as const;
+const read = (f: string) => readFileSync(resolve(REPO, "docs/llms", f), "utf8");
+
+describe("llms mirrors", () => {
+  for (const f of MIRRORS) {
+    test(`docs/llms/${f} exists and is non-trivial`, () => {
+      expect(existsSync(resolve(REPO, "docs/llms", f))).toBe(true);
+      expect(read(f).length).toBeGreaterThan(1000);
+    });
+  }
+
+  test("neither mirror contains an absolute home path", () => {
+    // The site publishes these verbatim. A leaked home path is the public-repo hygiene
+    // rule failing in the one file that is served to the open internet by design.
+    for (const f of MIRRORS) expect(read(f)).not.toMatch(/\/(home|Users)\//);
+  });
+
+  test("each mirror STATES the shipping versions, so a lagging copy fails", () => {
+    // The failure mode this exists for: a release bumps the versions, the mirrors are not
+    // refreshed, the site copies them at deploy, and the site lags a release — silently,
+    // because the copy succeeds and stale numbers look exactly like fresh ones.
+    //
+    // Asserted POSITIVELY, and the first draft of this test got it wrong in a way worth
+    // recording: it forbade every 0.x/7.x string other than the current one, and failed on
+    // `"...were retired in 0.24.0"` — a correct historical sentence. A doc is free to talk
+    // about an older release. It is not free to omit the current one, and a mirror that
+    // lagged would omit it, because the old number would be sitting where the new one goes.
+    //
+    // The bound, stated rather than hidden: this passes if a mirror names the current
+    // version AND leaves an old shipping claim beside it. Catching that needs a rule for
+    // which sentences are claims, which is what produced the false failure above.
+    const { npm, maven } = buildPayload(REPO).registries;
+    for (const f of MIRRORS) {
+      const text = read(f);
+      expect({ file: f, npm: text.includes(npm), maven: text.includes(maven) })
+        .toEqual({ file: f, npm: true, maven: true });
+    }
+  });
+
+  test("the one-line summary names both current coordinates", () => {
+    // The structural touch-point RELEASING-docs-checklist calls out first, and the line an
+    // agent reads before anything else. Pinned separately from the containment check above
+    // because "the file mentions 0.24.5 somewhere" and "the summary says we ship 0.24.5"
+    // are different claims, and only the second is what a reader acts on.
+    const { npm, maven } = buildPayload(REPO).registries;
+    for (const f of MIRRORS) {
+      const summary = read(f).split("\n").find((l) => l.startsWith("> A cross-language"));
+      expect(summary).toBeDefined();
+      expect(summary).toContain(npm);
+      expect(summary).toContain(maven);
+    }
+  });
+});