From bf5a3c26d89ecdd7b2b15211bfb0706a48ff9e7f Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 30 Jul 2026 12:40:08 +0000 Subject: [PATCH] docs(agents): the two multi-agent failure modes that cost this branch the most rounds MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both written from one branch's lifetime, so every row is something actually hit rather than something that might happen. #9 — refresh a long-lived worktree's build state after merging main. Four stale artefacts each fail AS IF your change broke something, naming other people's exports, other packages' files, or config you never touched: packages/spec/dist check:api-surface reports OTHER people's exports as "N breaking"; check:i18n-coverage rejects an example config for a value the spec allows node_modules a package cannot resolve a dependency it declares runtime/.objectstack/ fixture rows accumulating across runs .cache/objectui-* dozens of lint errors in files never opened None is CI-visible — CI checks out fresh and installs clean — so the whole cost lands on whoever is debugging, which is exactly why it is worth recognising in one step instead of re-diagnosing per gate. Also records that OS_SKIP_DTS=1 leaves no .d.ts, so gen:api-surface cannot run under it at all. #10 — a clean merge is not a working merge. Git conflicts on overlapping lines and says nothing when two changes are individually fine and jointly wrong. Both examples are recent: a test pinning a response body's exact shape landed while that shape was being changed elsewhere (merged clean, failed CI), and a domain file was deleted while another agent's guard still declared it (caught only because the guard existed). Hence pull main and re-run before opening a PR, and again before merging. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01CYbS3kS8xzsHNXFTzp4e2z --- .changeset/agents-md-worktree-staleness.md | 28 +++++++++++++++++++ AGENTS.md | 31 ++++++++++++++++++++++ 2 files changed, 59 insertions(+) create mode 100644 .changeset/agents-md-worktree-staleness.md diff --git a/.changeset/agents-md-worktree-staleness.md b/.changeset/agents-md-worktree-staleness.md new file mode 100644 index 0000000000..71854dc019 --- /dev/null +++ b/.changeset/agents-md-worktree-staleness.md @@ -0,0 +1,28 @@ +--- +--- + +Two additions to AGENTS.md's multi-agent discipline. Deliberately empty +frontmatter: documentation, this releases nothing. + +**#9 — refresh a long-lived worktree's build state after merging `main`.** Four +distinct stale artefacts each fail *as if your change broke something*, naming +other people's exports, other packages' files, or config you never touched: +`packages/spec/dist` (makes `check:api-surface` report someone else's exports as +breaking, and `check:i18n-coverage` reject a valid example config), `node_modules` +(a package cannot resolve a dependency it plainly declares), `packages/runtime/ +.objectstack/` (fixture rows accumulating across runs), and `.cache/objectui-*` +(dozens of lint errors in files you have never opened). None is CI-visible — CI +checks out fresh — so the cost lands entirely on whoever is debugging. Also notes +that `OS_SKIP_DTS=1` leaves no `.d.ts`, which makes `gen:api-surface` impossible +rather than merely slow. + +**#10 — a clean merge is not a working merge.** Git conflicts on overlapping +lines; nothing warns when two changes are individually fine and jointly wrong. +Both examples are real and recent: a test pinning a response body's exact shape +landed while that shape was being changed elsewhere, and a domain file was deleted +while another agent's guard still declared it. The first merged clean and failed +CI; the second was caught only because the guard existed. Hence: pull `main` and +re-run before opening a PR, and again before merging. + +Written from one branch's lifetime — every row is a failure that cost a debugging +round, so the list is what was actually hit rather than what might happen. diff --git a/AGENTS.md b/AGENTS.md index 30bec24afa..ce5686a7bd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -117,6 +117,37 @@ own worktree, operate defensively: up your own instance on a random high port (`pnpm dev -- --fresh -p `) and **shut it down yourself when the task is done** (`kill $(lsof -ti tcp:)`). Don't leave orphan servers behind. +9. **After pulling `main` into a long-lived worktree, refresh its build state + before you trust a single test or gate.** A worktree that has been open across + several merges accumulates artefacts that are stale relative to the source, and + every one of them fails **as if your change broke something** — naming other + people's exports, other packages' files, or config you never touched: + + | stale artefact | how it presents | why it lies | + |---|---|---| + | `packages/spec/dist` | `check:api-surface` reports *other people's* exports as "N breaking (removed/narrowed)"; `check:i18n-coverage` rejects an example config for a value the spec allows | both read the built `.d.ts`, not `src/` | + | `node_modules` | a package fails to resolve a dependency it plainly declares (`Cannot find package 'hono'`) | the merge moved `pnpm-lock.yaml` | + | `packages/runtime/.objectstack/` | `datasource-autoconnect` sees each row 6× | gitignored fixture state accumulating across runs | + | `.cache/objectui-*` | `pnpm lint` reports dozens of errors in files you have never opened | a full objectui checkout left by `build-console.sh`, linted as if it were ours | + + So after any `git merge origin/main`: + `pnpm install --frozen-lockfile && pnpm build && rm -rf packages/runtime/.objectstack` + (add `rm -rf .cache` if you have run the console build). Note `OS_SKIP_DTS=1` + keeps a build fast but leaves no `.d.ts`, so `gen:api-surface` cannot run at + all under it — that one needs a real build. + + None of this is CI-visible: CI checks out fresh and installs clean. It costs + only *your* time, which is exactly why it is worth recognising in one step + rather than re-diagnosing per gate. +10. **A clean merge is not a working merge.** Git conflicts on overlapping lines; + nothing warns you when two changes are individually fine and jointly wrong. + Real examples from one branch's lifetime: a test asserting a response body's + exact shape landed while that shape was being changed elsewhere (merged clean, + failed CI); a domain file was deleted while another agent's guard still + declared it. **Before opening a PR, and again before merging, pull `main` and + re-run the suite** — the second CI round is where these surface, and the guards + in `scripts/check-*.mjs` exist largely because this class of breakage is + invisible to `git merge`. ---