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

* docs(agents): require a WIP commit before every minutes-long step

Make the commit-ordering rule trigger on the STEP, not on waiting: push a
WIP commit before a build, a full test run, a gate sweep or an ablation,
because that is the moment the worktree stops being the only copy. The
"commit before you wait" framing never fires for an agent that is not
waiting — it is working — which is precisely the population that
accumulates the largest uncommitted surface.

Placed at the head of Build & Test, immediately under the command block
that lists the minutes-long steps themselves, so the rule is read at the
moment of use.

Paid for in place against a zero-headroom ceiling (1158/1158), no raise:
  - Documentation Guardrails: the three named-example rows (concepts/,
    getting-started/, protocol/) deleted (-3). Surviving home: the
    generic `content/docs/<tree>/` row directly above them, which covers
    every tree except references/ and releases/ and whose own text called
    them "named examples, not the whole set" (that dangling sentence is
    dropped with them).
  - Skills: the governed-surface paragraph compressed 4 lines -> 2 (-2).
    Surviving home: Prime Directive #14, which carries every clause —
    human-merge only, never merge/queue/arm/flip-draft, the retired
    per-PR approval check, and the post-merge audit.

Net 0 lines; check-skill-line-ratchet green at 1158/1158, widest table
row unchanged at 1081 bytes (pin 1081).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JANH3y7qe3MD8aLaLXci8N

* docs(agents): carve the shared turbo cache out of the isolation promise

The worktree rules promise isolation, and agents read that promise as
covering the build cache. It does not: turbo resolves the repo root
through the git COMMON directory, so every linked worktree replays one
`.turbo/cache` in the primary checkout — the same class of shared state
as the stash stack already documented beside it.

Carries the symptom and the remedy, because the two are otherwise
unrecognisable: a typecheck failing on a package the diff never touched,
which a plain rebuild does not repair because that rebuild is a cache
HIT. The remedy is a forced rebuild of that package. Ablating a build
tool is named as a sanctioned producer of poisoned entries — the
discipline this repo requires of gate PRs is itself the producer — and
`--force` is noted as writing the whole dependency closure, since the
remedy has the wider blast radius.

Paid for in place against a zero-headroom ceiling (1158/1158), no raise:
  - Prime Directive #11's stash tail compressed 3 lines -> 2 (-1), and
    its claim that the stash is "the one thing a worktree does not
    isolate" corrected — that sentence was already false against the
    Multi-agent section's own "the stash is one CASE" paragraph, and
    this change adds a second counter-example. Surviving home: the same
    Multi-agent paragraphs, which carry the hook name, OS_ALLOW_STASH=1
    and the collision-free replacements in full.
  - The Multi-agent section opener compressed 6 lines -> 2 (-4). It
    restated Prime Directive #11 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, which is the section's own subject.

Net 0 lines; check-skill-line-ratchet green at 1158/1158, widest table
row unchanged at 1081 bytes (pin 1081).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JANH3y7qe3MD8aLaLXci8N

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

AGENTS.md

@@ -48,6 +48,11 @@ pnpm typecheck        # turbo typecheck — per-package `tsc --noEmit`; tsup/vit
 pnpm docs:dev         # docs site
 ```
 
+**⛔ 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.
+
 Type-check coverage and its debt counts are ratcheted in CI
 (`pnpm check:type-check-coverage`, `pnpm check:type-check-debt`; the script headers are
 the authority on detail): every package declares a `typecheck` script or carries a
@@ -235,9 +240,8 @@ localStorage / auth gotchas.
     repo**, so sibling repos (`objectui`/`cloud`) you touch are covered too (deliberate non-task override:
     `OS_ALLOW_MAIN_EDITS=1`, one switch for both). The Bash guard is precision-first: it never blocks reads, and any
     shape it cannot resolve with confidence (`bash -c …`, `xargs`, `node -e`, a `$VAR`/glob target) is allowed through
-    — the rule still outranks the hook. **The one thing a worktree does *not* isolate is the stash** — `refs/stash`
-    lives in the **common** `.git`, shared by every worktree; a third hook (`guard-shared-stash.sh`, `OS_ALLOW_STASH=1`)
-    blocks the mutating forms, and the collision-free replacements are in Multi-agent discipline below.
+    — the rule still outranks the hook. **A worktree isolates neither the stash nor the build cache** — the
+    third hook (`guard-shared-stash.sh`, `OS_ALLOW_STASH=1`) and the replacements live in Multi-agent discipline below.
 12. **Contract-first — fix the metadata, not the runtime.** This is a metadata-driven framework: `packages/spec` is
     the one contract between metadata *producers* and the runtime/renderers that *consume* it. When a piece of metadata
     "doesn't work," ask **first**: *is it spec-compliant? is this the long-term-correct direction?* If the metadata is
@@ -362,12 +366,8 @@ localStorage / auth gotchas.
 
 ## Multi-agent working discipline
 
-This repo is worked on by **multiple agents in parallel**. **Use one git worktree per
-agent/task** (`git fetch origin main && git worktree add ../objectstack-<task> -b <branch>
-origin/main`; run `pnpm install` in the new tree) so file systems are physically isolated —
-mandatory, not a preference (Prime Directive #11), and hook-enforced. Working in the shared `main` checkout is *not* a
-supported fallback: branches get switched and shared files — including ones you just wrote
-— get reset *under you* mid-task (full sessions were silently reverted before enforcement).
+This repo is worked on by **multiple agents in parallel**, one worktree per task —
+mandatory, hook-enforced, and specified in **Prime Directive #11**. What it does not cover:
 
 **⛔ `git stash` is the sharpest thing the worktree does NOT isolate — never run a bare
 `git stash push`/`pop`.** `refs/stash` lives in the **common** `.git` directory, so every
@@ -409,6 +409,11 @@ ref's content by occurrence counts on disk; fetch into a ref you own (`git fetch
 staging. ⛔ **No hook backs this one** — safe and unsafe spellings are both ordinary
 `git checkout` / `git fetch`, so a mechanical block would fire on correct usage.
 
+**⛔ 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.
+
 **Doing reverse verification ("revert the fix, watch the diagnostics")? Commit the fix
 FIRST.** Committed, restoring is `git checkout <your-branch> -- <path>`, out of a commit
 that really exists. Against an **uncommitted** edit there is no restore point at all: the
@@ -709,10 +714,7 @@ Root also exports: `defineStack`, `composeStacks`, `defineView`, `defineApp`, `d
 | `content/docs/references/` | **AUTO-GEN** | ❌ Never hand-edit. Regenerated by `packages/spec/scripts/build-docs.ts`. |
 | `content/docs/releases/` | **RELEASE-OWNED** | ❌ Never edit in a code PR. Release notes are written **centrally at release time**, compiled from changesets + the ADR-0087 registries — not accreted a row per PR. Per-PR appends made `releases/v<major>.mdx` the repo's hottest conflict magnet (three PRs raced the same table inside one afternoon), and every manual resolution risks dropping someone else's row. Your PR's input is its **changeset**; for spec removals also the D2/D3 registry entries. Factual error on a releases page → dedicated docs-only PR or an issue, never a rider on code changes. |
 | `**/translations/*.generated.ts` (nine packages — `platform-objects`, five plugins, three services) | **AUTO-GEN** | ❌ Never hand-edit the file *structure*. Run `node scripts/check-i18n-bundles.mjs --write` to regenerate all nine (merge mode preserves every existing **translated-locale** value; the default locale `en` is rewritten from the source on every run — it is a copy of the source, not a translation: when the extractor merged `en` too, a stale bundle entry always beat an edited source string, so the served text drifted from the source silently under a green gate. Hand-edits to `en.*.generated.ts` therefore do not survive and belong in the source metadata instead); `pnpm i18n:extract` still covers `platform-objects` alone. Translated-locale *values* (`zh-CN` / `ja-JP` / `es-ES`) are hand-written and expected to be: the gate compares against a merge-mode extract, so editing one of those strings is fine, while adding or dropping keys is drift. `pnpm check:i18n` gates all nine in CI, and `pnpm check:i18n-coverage` ratchets untranslated declared labels. |
-| `content/docs/<tree>/` — every tree except `references/` and `releases/` above | hand-written | ✅ Update that tree's own `meta.json` when adding a page: each is an explicit ordered `pages` array with no rest-spread, so a page you add but never list is absent from the nav. The rows below are named examples, not the whole set. |
-| `content/docs/concepts/` | hand-written | ✅ |
-| `content/docs/getting-started/` | hand-written | ✅ |
-| `content/docs/protocol/` | hand-written | ✅ |
+| `content/docs/<tree>/` — every tree except `references/` and `releases/` above | hand-written | ✅ Update that tree's own `meta.json` when adding a page: each is an explicit ordered `pages` array with no rest-spread, so a page you add but never list is absent from the nav. |
 
 ### Touched `packages/spec`? Regenerate its artifacts BEFORE pushing
 
@@ -830,10 +832,8 @@ such lists drifted stale as skills landed):
 - `.claude/skills/` — repo-internal agent playbooks; every entry must carry
   `metadata.internal: true`.
 
-⛔ **Both roots are governed surfaces**: a PR touching either is human-merge only and may
-never be queued, armed or flipped out of draft — **Prime Directive #14**. No per-PR check
-holds this any more; the discipline is the whole barrier, and a post-merge audit lists
-what landed.
+⛔ **Both roots are governed surfaces** — human-merge only, never queued, armed or flipped
+out of draft, and no per-PR check holds it: **Prime Directive #14** is the whole barrier.
 
 ---