From d3ed51f7171767fef0a0e8e1e7457a5bba9de255 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 26 Aug 2026 02:07:28 +0000 Subject: [PATCH 1/2] docs(agents): require a WIP commit before every minutes-long step MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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//` 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 Claude-Session: https://claude.ai/code/session_01JANH3y7qe3MD8aLaLXci8N --- AGENTS.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 57bb733aa9..f99201a73d 100644 --- a/AGENTS.md +++ b/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 @@ -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.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//` — 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//` — 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. --- From 26e7c579996a838229f0dc273d918518819ef830 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 26 Aug 2026 02:09:57 +0000 Subject: [PATCH 2/2] docs(agents): carve the shared turbo cache out of the isolation promise MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_01JANH3y7qe3MD8aLaLXci8N --- AGENTS.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f99201a73d..77193ad844 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -240,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 @@ -367,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- -b -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 @@ -414,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 -- `, out of a commit that really exists. Against an **uncommitted** edit there is no restore point at all: the