A docs content change between recording an archive lock and publishing it breaks the candidate, and CI cannot see it

[jeremi]

What happened

The v0.24.0 release PR recorded the immutable archive digests for the new
docset in docs/site/src/data/archive-lock.yaml. #799 then merged, changing
docs/site/src/content/** before the candidate was dispatched. The candidate
failed at archive:snapshot --verify-lock, because the built docset no longer
matched the lock.

There is no supported repair once the entry exists:
assertArchiveLockImmutable rejects a change to an existing entry,
addArchiveLockEntry throws already exists, and isLockBackedDocset has no
carve-out for availability: candidate. The release had to revert #799
(d1a6c7b92), publish, and re-land it (#806).

Why CI did not catch it

The docs-archives job runs check:archives, which is the gate that would have
failed. But needs.changes.outputs.docs_archives is computed in
.github/scripts/ci_changes.py from an exact allow-list: ci.yml,
astro.config.mjs, package.json, package-lock.json, a fixed set of
docs/site/scripts/*.mjs, and src/data/{archive-lock,docsets,repo-docs}.yaml.

A pure prose change matches none of them, so the job skips. That is visible on
#806 right now: Immutable docs archives: skipping.

The comment above the filter explains the intent, and the intent is sound for
the steady state: "Publication workflows and this classifier do not alter
archived bytes; their focused tests cover those contracts without replaying
every historical docset."

The gap is a window, not a permanent hole

The assumption behind the filter, that content changes cannot move archived
bytes, holds once a docset is published, because assemble-archives.mjs
restores a published bundle rather than rebuilding it. Note that the pinned
source tag does not provide this: currentSourceGeneratedArtifacts binds
only docs/site/src/content/docs/reference/cli and
docs/site/src/data/generated/cli-reference.json to the tag. Prose is built from
the checked-out tree.

So the assumption is false for exactly one window: between the commit that
records a lock entry and the publication of that docset's bundle. In that
window any docs/site/src/content/** change silently breaks the candidate, and
CI stays green.

Possible fixes

Not proposing a specific one, since this is a design call:

1. Make docs_archives true when docs/site/src/content/** changes and the
   lock contains an entry whose bundle is not yet published. Narrow, but needs
   the classifier to know publication state.
2. Add a cheap standalone check, not the full check:archives replay, that fails
   a PR touching docs/site/src/content/** while an unpublished lock entry
   exists.
3. Leave the classifier alone and encode the ordering rule in
   release/OPERATIONS.md: merge the release PR last, dispatch the candidate
   immediately, and freeze docs/site/src/content/** until the release
   publishes.

Option 3 alone is what the process relies on today, and it is unwritten.

[jeremi]

Two observations from running the gate by hand on both open docs PRs (#806 and #802), which sharpen the scope of this issue.

The allow-list keys on the wrong dimension, not merely on too few paths.
Every entry in the docs_archives set in .github/scripts/ci_changes.py is an
infrastructure path: ci.yml, astro.config.mjs, package.json,
package-lock.json, a fixed set of docs/site/scripts/*.mjs, and
src/data/{archive-lock,docsets,repo-docs}.yaml. Content under
docs/site/src/content/** appears nowhere. But content is exactly what moves
the built docset bytes during the window this issue describes. So a
content-only change can never trigger the archive job by any route, and the
blindness is structural rather than a few missing paths.

Confirmed on the two live PRs, which happen to form a clean A/B.

• docs(evidence): re-land both Evidence source transports #806 is prose-only. CI reports Immutable docs archives: skipping. Run by
  hand: 3 restored, 0 bootstrapped.
• test(docs): check the evidence anchors against source #802 is also substantively prose, but it edits docs/site/package.json to
  register a new npm script. That single unrelated line trips the allow-list,
  so the archive job runs. Run by hand there too: 3 restored, 0 bootstrapped.

#802 got archive coverage by accident of touching a manifest, not because
anything about its content warranted the check. #806 is the honest case.

The comment above the gate states the invariant that fails. It reads:

Rebuild immutable history only when archive inputs or assembly semantics
change. Publication workflows and this classifier do not alter archived
bytes; their focused tests cover those contracts without replaying every
historical docset.

That is true once a bundle is published, and false for the window between
recording a lock entry and publishing the release, which is the whole of this
issue in one line.

Cheapest closing check, if someone picks this up: fail when
docs/site/src/data/archive-lock.yaml names a version with no matching git tag
and the diff touches docs/site/src/content/**. That lives in release tooling
rather than in the docs subtree, so it is a separate owning area from either
open PR.

Credit for the package.json observation goes to the #802 work; recording it
here so it is not lost when that branch merges.