amadan
AGENTS.md: take a worktree, and cut it from a fresh main
Several sessions share this machine and some share a checkout, and a checkout has one HEAD, one index and one working tree between all of them. A branch switch under somebody else's uncommitted work destroys it with nothing on screen to say so. A branch cut from a stale main is a conflict scheduled for later; one cut from another task's branch carries that task's commits into yours. Written against 2026-09-17 in meet, where the shared checkout sat on one task's branch while holding a different task's feature uncommitted on disk, and the same feature ended up existing twice, once on each side of a rename, because two sessions branched from different starting points.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1 file changed,
+38
−0
AGENTS.md+38 −0
CI failed — run details
CI log
=== test === swift test Building for debugging... [0/13] Write sources [2/13] Write swift-version--28C01585A1F674EC.txt [4/15] Emitting module RastrilloNative [5/15] Compiling RastrilloNative CoalescedRunner.swift [6/16] Wrapping AST for RastrilloNative for debugging [8/18] Emitting module RastrilloNativeTests [9/18] Compiling RastrilloNativeTests CoalescedRunnerTests.swift [10/19] /home/paulca/.local/state/amadan/runner/repos/rastrillo__native/wt/main/.build/x86_64-unknown-linux-gnu/debug/RastrilloNativePackageDiscoveredTests.derived/all-discovered-tests.swift [11/19] Write sources [12/19] Wrapping AST for RastrilloNativeTests for debugging [14/22] Compiling RastrilloNativePackageDiscoveredTests all-discovered-tests.swift [15/22] Emitting module RastrilloNativePackageDiscoveredTests [16/22] Compiling RastrilloNativePackageDiscoveredTests RastrilloNativeTests.swift [17/23] /home/paulca/.local/state/amadan/runner/repos/rastrillo__native/wt/main/.build/x86_64-unknown-linux-gnu/debug/RastrilloNativePackageTests.derived/runner.swift [18/23] Write sources [19/23] Wrapping AST for RastrilloNativePackageDiscoveredTests for debugging [21/25] Emitting module RastrilloNativePackageTests [22/25] Compiling RastrilloNativePackageTests runner.swift [23/26] Wrapping AST for RastrilloNativePackageTests for debugging [24/26] Write Objects.LinkFileList [25/26] Linking RastrilloNativePackageTests.xctest Build complete! (6.70s) Test Suite 'All tests' started at 2026-09-19 18:18:14.593 Test Suite 'debug.xctest' started at 2026-09-19 18:18:14.600 Test Suite 'CoalescedRunnerTests' started at 2026-09-19 18:18:14.600 Test Case 'CoalescedRunnerTests.testBurstWaitsForTrailingPassAndReusesOriginalOperation' started at 2026-09-19 18:18:14.600 Test Case 'CoalescedRunnerTests.testBurstWaitsForTrailingPassAndReusesOriginalOperation' passed (0.001 seconds) Test Case 'CoalescedRunnerTests.testCancelledWaiterDoesNotCancelSharedRefresh' started at 2026-09-19 18:18:14.601 Test Case 'CoalescedRunnerTests.testCancelledWaiterDoesNotCancelSharedRefresh' passed (0.0 seconds) Test Case 'CoalescedRunnerTests.testSequentialCallsEachRefresh' started at 2026-09-19 18:18:14.601 Test Case 'CoalescedRunnerTests.testSequentialCallsEachRefresh' passed (0.0 seconds) Test Suite 'CoalescedRunnerTests' passed at 2026-09-19 18:18:14.601 Executed 3 tests, with 0 failures (0 unexpected) in 0.002 (0.002) seconds Test Suite 'debug.xctest' passed at 2026-09-19 18:18:14.602 Executed 3 tests, with 0 failures (0 unexpected) in 0.002 (0.002) seconds Test Suite 'All tests' passed at 2026-09-19 18:18:14.602 Executed 3 tests, with 0 failures (0 unexpected) in 0.002 (0.002) seconds ◇ Test run started. ↳ Testing Library Version: 6.2 (3fdabe5392108d8) ↳ Target Platform: x86_64-unknown-linux-gnu ✔ Test run with 0 tests in 0 suites passed after 0.001 seconds. === companion === cd examples/companion && xcodegen generate /bin/sh: 1: xcodegen: not found make: *** [Makefile:6: companion] Error 127 amadan: step companion failed: exit status 2 amadan: job failed at step companion — its output is above, not at the tail of this log
diff --git a/AGENTS.md b/AGENTS.md| index 1d54a5d..57ac771 100644 |
| --- a/AGENTS.md |
| +++ b/AGENTS.md |
| @@ -8,3 +8,41 @@ Run `make ci` before pushing. `.amadan/ci.d` calls the same Make targets. |
| Keep platform-specific dependencies out of the shared Swift target. Add a |
| component only after proving adoption in existing applications. Comments |
| explain the failure prevented; review user-facing English before translating. |
| + |
| +## Work in a worktree, and catch main up first |
| + |
| +Take a worktree for the work. Do not work in the shared checkout. |
| + |
| + git -C <repo> fetch origin |
| + git -C <repo> worktree add ../<repo>-<task> -b <branch> origin/main |
| + |
| +Both halves matter, for different reasons. |
| + |
| +**The worktree**, because several sessions share this machine and some |
| +share this repository, and a checkout has one HEAD, one index and one |
| +working tree between all of them. A branch switch under somebody else's |
| +uncommitted work destroys it with nothing on screen to say so, and two |
| +sessions editing the same paths disagree quietly instead of conflicting |
| +loudly. A worktree gives the work its own HEAD and its own files, and |
| +costs a directory. |
| + |
| +**From `origin/main`, after a fetch** — not from whatever the checkout |
| +happens to be sitting on. A branch cut from a stale main is a merge |
| +conflict scheduled for later, against files somebody else has renamed in |
| +the meantime. A branch cut from another task's branch is worse: it |
| +carries that task's commits into yours, where they are reviewed as |
| +though you wrote them, and the two can only be separated by hand. |
| + |
| +Remove it when the work has landed — `git worktree remove` — so that |
| +`git worktree list` keeps saying something true. |
| + |
| +Written down because of 2026-09-17, in `meet`. The shared checkout was |
| +sitting on one task's branch while holding a *different* task's feature |
| +uncommitted on disk — some four hundred lines, a new migration among |
| +them — put there by a session nobody else knew was working in that tree. |
| +Two other sessions were meanwhile coordinating over the same checkout by |
| +asking each other not to touch it, which is the arrangement a worktree |
| +makes unnecessary. Nothing was lost. Nothing about the arrangement would |
| +have said so if it had been, and by then the same feature existed twice, |
| +once on each side of a rename, because the two sessions had branched |
| +from different starting points. |