docs(agents): WIP-commit ordering rule + the shared turbo-cache carve-out

[claude]

Fixes#12024
Fixes#12077

Two AGENTS.md doctrine lines, folded into one compression-paid edit because both
land in the same zero-headroom file. One commit per member; each commit is
independently line-neutral, so the ratchet is green at every commit, not just at
the tip.

⛔ Governed surface — draft, human merge

AGENTS.md is a governed surface (Prime Directive #14). This PR stays draft;
it is never flipped ready, never queued, never auto-merged. Landing is the
maintainer's, by hand.

What each member adds

#12024 — the WIP-commit ordering rule, at the head of Build & Test,
immediately under the command block that lists the minutes-long steps:

⛔ Push a WIP commit before every step that takes minutes — a build, a full
test run, a gate sweep, an ablation. Not because you are about to wait: because
you are about to stop being the only copy. The cost rises with how well you are
working — a hard card defers committing because it is not done yet, and the one
killed mid-measurement lost 2,081 lines.

The trigger is the step, not the waiting, exactly as graded. "Commit before
you wait" never fires for an agent that is not waiting — it is working — which is
the population that accumulates the largest uncommitted surface. Placement is
judged on the tree: an agent about to run a minutes-long step is reading that
command block, so the rule sits at the moment of use rather than in a
parallel-agents section (the loss is a restart, which reaches a solo agent too).

#12077 — the build-cache carve-out, beside the stash rule in the
isolation-promise section, after the paragraph enumerating what a worktree does
not isolate:

⛔ Nor the build cache — turbo resolves the repo root through the common
dir, so every worktree replays ONE .turbo/cache. Symptom: a typecheck failing
on a package your diff never touched, unrepaired by a plain rebuild because that
rebuild is a cache HIT — force-rebuild that package. Ablating a build tool is
a sanctioned producer; --force writes the whole closure.

Symptom and remedy are both carried, since the two are otherwise unrecognisable
from the seat that hits them. Ablation is named as a sanctioned producer — the
reverse-verification discipline this repo requires of gate PRs is itself the
producer, not only accidents — and --force is noted as writing the whole
closure, because the prescribed remedy has the wider blast radius.

The payment ledger — every cut, and its surviving home

AGENTS.md was 1158 lines against a ceiling of 1158, headroom ZERO. Every
added line is paid by a same-file deletion. ⛔ No ceiling raise, and no re-wrap:
each cut removes content that survives somewhere named.

cut	lines	surviving home
Documentation Guardrails: the three named-example rows (concepts/, getting-started/, protocol/)	−3	The generic per-tree content/docs/ row directly above them, which covers every tree except references/ and releases/. Its own text called the three "named examples, not the whole set" — that now-dangling sentence goes with them. Zero rules lost: the three rows carried no content the generic row did not.
Skills: the governed-surface paragraph, 4 lines → 2	−2	Prime Directive #14, which carries every clause of it: human-merge only; never merge, queue, arm auto-merge or flip out of draft; the retired per-PR approval check; the report-only post-merge audit. The pointer to #14 is kept.
Prime Directive #11: the stash tail, 3 lines → 2	−1	The Multi-agent stash paragraphs, which carry the hook name, OS_ALLOW_STASH=1 and the collision-free replacements in full — as the cut text itself said ("in Multi-agent discipline below").
Multi-agent section opener, 6 lines → 2	−4	Prime Directive #11, which it restated nearly clause for clause: the same worktree command, the same reset-under-you hazard, the same hook enforcement. What replaces it points at #11 and introduces the carve-outs that follow — the section's own subject.

Total: +10 added, −10 cut, net 0. Ratchet green at 1158/1158.

One cut does double duty. Prime Directive #11 claimed the stash was "the one
thing a worktree does not isolate" — already false against the Multi-agent
section's own "the stash is one CASE" paragraph, and this PR adds a second
counter-example. It now reads "a worktree isolates neither the stash nor the build
cache", which is what #12077 is about: the isolation promise being read wider than
it holds.

#11910 — read first, per the dispatch, and not touched here

#11910 is the open ceiling-family decision and remains open; nothing here depends
on it. Its ruling authorized 961 → 969 for a different card; the ceiling has since
moved to 1158 through later raises. This PR raises nothing — compression paid for
both additions in full, so the escalation clause ("if compression cannot pay, this
converts to a ceiling decision alongside #11910") was not reached.

Verification — union re-run at the final commit 26e7c579

Gate families derived from the actual diff, not recalled:
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (no paths;
the script takes its own change set from the merge base) named 8 families for the
one-path surface AGENTS.md. All were run at the tip commit, plus
check:nul-bytes for the byte discipline. Verdict lines as the gates printed them:

✓ check-skill-line-ratchet: AGENTS.md is 1158 lines (ceiling 1158; headroom 0).
✓ check-skill-line-ratchet: AGENTS.md: widest table row is 1081 bytes (pin 1081; headroom 0).
✓ check-governed-prose: 2 instruction surface(s) name all 5 registered governed
surfaces (docs/adr/** · .claude/** · skills/** · AGENTS.md · CLAUDE.md) and claim no others.
✓ check-skill-id-lint: 22 file(s) clean (pattern /#[0-9]{3,}/g).
✓ check-required-contexts: 6 required context name(s) pinned across 2 workflow(s);
5 instruction surface(s) scanned against 2 retired name(s).
✓ check-agent-test-spelling: 0 violations — 386 file(s) · 4025 bare `--` token(s) …
✓ docs-accuracy-audit scope is in sync with content/docs/: 189 hand-written doc(s).
✓ check-nul-bytes: OK (scanned 6871 text file(s); no raw ASCII control bytes).
check:pm-governed-merges — exit 0.

Exit codes were captured before any pipe (redirect first, then tail), so these
are the gates' own verdicts and not a pipeline's status.

Two notes on what was measured:

• check:required-contexts first returned PREREQUISITE NOT MET (the yaml
  dependency, absent in a fresh worktree). That is not a red gate and is not
  recorded as one — nothing was measured. pnpm install ran, and the line above is
  from the real run afterwards.
• Both new lines are self-contained: no issue-number references in operative text,
  confirmed by the id-lint verdict above, which scans AGENTS.md.

No changeset: the diff is docs-only and publishes nothing, so this PR carries
skip-changeset — the derivation's own changeset section applies only to a card
that is not docs-only.

---

Generated by Claude Code