docs(cache): write down the producer half of the leftover naming contract

daniel/gitdan's host-level arbiter (scripts/ci-cache-reclaim.sh) reclaims the
dot-prefixed trees this repo's scripts strand inside the cache volumes it
scans, and reads this repo's reader markers to decide whether one is still
live. That arrangement was documented only on the consuming side: a
contributor here could add or rename a dot-prefixed shape with no local signal
that anything outside the repo depended on the spelling, and the arbiter
enumerates by explicit prefix — deliberately, so it never sees a .reading-*
marker as a candidate — which makes an unannounced shape invisible to it
rather than conservatively handled.

Adds the producing side's half at the sites someone changing a name will
actually be looking at, pointing at gitdan's LEFTOVER NAMING CONTRACT block as
canonical rather than restating it:

- cache-lib.sh gains a header block naming every shape this repo creates under
  a cache root, its producing function, and how each strands; plus the rule
  that adding a shape obliges the same matching prefix over there as renaming
  one does.
- Site notes at .stage-'s and .reading-'s producing lines, and at
  .evicting-'s in prune-cache.sh.
- publish-snapshot.sh's .publish-old- / .publish-new- pair is documented as
  the shapes that are NOT in the arbiter's list today, with .publish-new-
  called out as the one that strands exactly as .stage- does and that neither
  side reclaims.
- The staleness direction: CACHE_READ_STALE_SECONDS and STALE_LOCK_SECONDS are
  mirrored there and the mirrors must be >= ours, because raising ours alone
  makes the arbiter delete a tree under an in-flight clone (its minimum-age
  guard does not back-stop that case). Lowering ours is safe in any order.
- README gains a short section a newcomer meets before adding a scratch
  directory under a cache root, cross-linked from the cache-layout block.

Comments and docs only; no behaviour change.

Closes #7

scripts/prune-cache.sh

@@ -85,6 +85,10 @@ ROOT="${1:?usage: prune-cache.sh <cache-root> <own-target-dir> <protected-branch
 OWN_DIR="${2:?}"
 PROTECTED_REFS="${3:-}"
 MIN_FREE_PCT="${4:-10}"
+# Mirrored by daniel/gitdan's ci-cache-reclaim.sh, whose copy must be >= this
+# one — raising this without raising theirs first lets that script treat a lock
+# this side still honours as abandoned. Same direction and same reasoning as
+# CACHE_READ_STALE_SECONDS; the argument is written out in cache-lib.sh.
 STALE_LOCK_SECONDS="${STALE_LOCK_SECONDS:-7200}"
 # An aside directory is in flight for one rename plus one marker glob —
 # milliseconds. Anything older belongs to a pass that died between the two, so
@@ -174,6 +178,12 @@ is_locked() {
 # leaves the source inode unchanged, which is precisely why the publish side
 # can rotate a snapshot out from under a live reader. A declined eviction
 # therefore costs a deferred eviction and nothing else.
+#
+# `.evicting-<name>-<pid>` is a contract name shared with daniel/gitdan's
+# host-level arbiter (see the cross-repo contract at the top of cache-lib.sh).
+# The sweep at the top of this script reclaims these on every pass, so the only
+# one that reaches the arbiter belongs to a repo whose workflow has stopped
+# running — which is exactly the case no in-workflow pass can reach.
 evict_dir() {
   local dir="$1" name aside
   name=$(basename "$dir")