loomctl external: list, add, check — and its first run found two changed documents

Go, standard library only, with git shelled out for list alone. list enumerates a publisher's .loom/published by partial clone and ls-tree; add fetches one document, writes it under .loom/externals and records the resolved origin and the publisher's ETag in .loom/externals/.locks; check asks conditionally and reports. The first real run did what the tool exists for. All eight documents adopted by hand before it existed reported unlocked — the tool refuses to invent a lock by adopting whatever the remote currently serves, since that would assert the local copy is the one being served, which is the thing it was about to check. Locking them fetched two that had moved: bedrock/starting.md, which now says the worked example is private and will not link to something you cannot fetch, and cart.md, which went to v1. cart v1 changes a role we cast: a cart is not committed, because a committed cart grows a third file by itself — version control does not require anybody to ask, so the two-file rule is never invoked — and because ignored, gone means gone. Adds .loom/cart/ to .gitignore and supersedes the isolation entry rather than editing it. osprey and marmalade are already in history and are left there: rewriting to honour a rule adopted afterwards costs more than it buys. Records the conflict this creates rather than settling it: the annotation protocol here says commit before dissolving because git is the only archive, and an ignored cart has no archive, so dissolving would destroy the annotations outright. Credentials are read-only, per host, and passed to git through the environment rather than argv, because argv is visible to every process on the machine. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018UTxuSizozEA8yDitPuris
2026-09-07 14:48:29 -04:00
parent f0b3269610
commit 1543df0a0c
12 changed files with 897 additions and 7 deletions
@@ -60,9 +60,13 @@ what they came for.*

 ## Look at one instead of reading this

-**[`jeffry/homelab-cluster`](https://git.hypertheory-labs.dev/jeffry/homelab-cluster)**
-— *six documents, one gap, no decomposition, and a `README` that says what the
-root documents are for and what these are for.*
+**There is a worked example — six documents, one gap, no decomposition — and it
+is private.**

-**It is a better answer than this page**, and if the two ever disagree, it is
-right.
+*It describes a cluster in enough detail to be a target list, so it is not
+published, and **this page will not link you to something you cannot fetch.***
+**If you have access, ask for it by name; if you do not, the two questions at the
+top are the whole of it.**
+
+> **A public page naming a private thing as its canonical answer is worse than no
+> example**, and this page did exactly that until somebody measured it.
@@ -1,6 +1,6 @@
 # Agreement — the cart

-**v0.** Depends on `annotating/v0`.
+**v1.** Depends on `annotating/v0`.

 **How two parties work out what something means before one of them changes it.**

@@ -104,9 +104,54 @@ already rejected, and the rejection is gone because it lived in an annotation
 that died with the round.

 **A decline needs no file of its own.** It is an entry in whatever durable record
-you keep, and **it should say what you believed, not just what you chose** — only
+you keep — **which must outlive the cart**, *and therefore cannot be inside it* — and **it should say what you believed, not just what you chose** — only
 a belief can later be shown wrong.

+## The cart is local, and that is what keeps it to two files
+
+**A cart is two developers working side by side.** *Everything else — the wider
+team, the people who need to know, the thing that has to be tracked — is issues,
+chat, whatever you already have.* **This is not that channel and it does not scale
+into one.**
+
+> **So the cart is not committed.** *It lives in the working tree of the machine
+> the two presences share, and `.loom/cart/` is ignored by version control.*
+
+**The reason is not tidiness. A committed cart grows a third file by itself.**
+*The rule above defends against somebody asking for one; **version control does
+not require anybody to ask.*** *Anyone who can clone can add `joe-rose.md`, and
+then `sue-rose.md`, and the agreement's defence — **what happens to this file when
+the person changes?** — is never invoked, because nobody ever had the
+conversation.*
+
+**This is also what makes a round actually end.** *Committed, a cart is gone from
+the tree and permanent in history — **so "gone" means "no longer live" and
+negotiation stays quotable forever.*** **Ignored, gone means gone**, which is what
+the round dying was for.
+
+*The cost, stated: **two presences who do not share a filesystem cannot use a
+cart.*** *That is a real limit and it is the right one — if you need a medium
+between machines, you need the other channel, and reaching for a cart there is
+how it becomes a chat log.*
+
+## What is not yet a decision goes in the write-ahead log
+
+**A round produces things that are neither questions nor decisions:** *something
+observed, something that may turn out to be noise, something you would kick
+yourself for losing and cannot yet justify writing down.*
+
+**`event-log.wal.md`, in the cart.** *Findings, not decisions.* **Nothing in it is
+durable and nothing in it has been decided.**
+
+**At conversion, each entry either becomes an entry in the durable record or is
+discarded.** *Same two exits as a polad, and for the same reason: **conversion is
+when you know most about it.***
+
+> **Write the reason it is not yet an entry.** *An observation you cannot justify
+> promoting is worth keeping; **one you have not said why you are hesitant about
+> will be promoted by whoever finds it, on the strength of it having been written
+> down.***
+
 ## Where a cart lives, and the shelf

 **A fixed path, and at most two things in it:**