loom-cli/.loom/event-log.md

# Event log

**Appended, newest last, never revised.** *A later entry supersedes an earlier one
by saying so.*

*Entries tagged `osprey` were all considered in a single sphere of understanding.*

---

## 2026-09-07 — what this tool is `osprey`

**Decided:** *`loom-cli` is a fetcher and a comparator.* **It fetches a document
you depend on and tells you whether the publisher's copy has moved.** *It reports
and never repairs.*

**Believed to advance:** *every act in the loom model is a file in somebody's
repository — publishing is writing one, adopting is fetching a URL, homing a gap
is an `mv`.* **Almost nothing needs a program**, so the program should be the
part that cannot be done by hand: an HTTP request, repeated.

**Belief that could be shown wrong:** *that reporting is enough.* **If every
report is followed by the same manual act, we have moved the work rather than
removed it**, and the missing command will be obvious.

## 2026-09-07 — the design lives here and not in a spec `osprey`

**Decided:** *this log is the artifact of `osprey`.* **No specification document
is written, and the specimen that opened the round is discarded.**

**Believed to advance:** *every entry here carries a belief that could be shown
wrong, so a reader can see which parts are load-bearing and which were guesses.*
**A spec flattens all of it to equal confidence** — *which is how the specimen
managed to be wrong, with a straight face, within a day of being written.*

**Belief that could be shown wrong:** *that a reader can build from a log.* **It
is ordered by time and not by topic**, so somebody arriving reads chronologically
and holds the corrections in their head. *Fine at fifteen entries and not at
eighty. When a newcomer cannot build from it without a guide, the guide is the
next thing to write — and not before.*

## 2026-09-07 — freshness is a conditional request `osprey`

**Decided:** *the tool records the publisher's `ETag`, verbatim and opaque, and
sends it back as `If-None-Match`.* **It never computes a hash of anything.**

**Believed to advance:** *`externals` requires it, and we now have the empirical
reason as well as the stated one.* **On gitea a raw file's `ETag` is its git blob
hash; on GitHub it is not.** *A design that compares a local hash to a remote
`ETag` works on exactly one host by coincidence.*

**Belief that could be shown wrong:** *that `ETag` is stable enough to lock on.*
**A proxy, a CDN, or a host that regenerates the header per request would produce
a change report where nothing changed.** *Untested against anything but gitea and
GitHub.*

## 2026-09-07 — supersedes nothing: the path is for a person `osprey`

**Decided:** *the origin URL is recorded in the lock, not derived from the stored
path.*

**Believed to advance:** *the path `\.loom/externals/<host>/<path>.md` does not
round-trip.* **Measured:** *the document we hold as
`git.hypertheory-labs.dev/loom/externals/externals.md` is served from
`/loom/externals/raw/branch/main/.loom/published/externals.md`* — **the stored
path has dropped the route, the branch, and `.loom/published/`.**

*The third is not routing.* **`publication.md` makes `.loom/published/` the whole
contract**, and a tree that erases it cannot say whether a copy came from
somebody's published surface or from a file they may rename at will.

**Belief that could be shown wrong:** *that people will still read the path as a
location.* **If anybody writes code that parses it back into a URL, the path
should stop looking like one.**

## 2026-09-07 — the lock, and what it holds `osprey`

**Decided:** *one record per adopted document in `.loom/externals/.locks`: the
**resolved** origin URL, and the `ETag` it came with.*

**Believed to advance:** *the specimen said there would be no lock file, on the
strength of the `ETag`-as-blob-hash claim.* **That claim failed twice**, so the
file exists and is named for what it is. *It was briefly called `.etags`, from
when we believed there would be one field.*

**Resolved, and not the short form.** *Measured: gitea `303`s
`/loom/externals/raw/externals.md` to `/raw/branch/main/…`* — **so a lock holding a
short URL is locked to whatever the default branch is at the time you ask**, and a
branch rename reports as a change in the document.

**Belief that could be shown wrong:** *that one file is cheap.* **Two fetches in
one round conflict inside it, and the conflict is in a file no human can resolve
by reading.** *If that bites, it becomes one record per document and the tree is
mirrored twice.*

## 2026-09-07 — unlocked is a state `osprey`

**Decided:** *a document with no lock is reported as unlocked.* **`check` never
adopts whatever the remote is currently serving as the lock.**

**Believed to advance:** *adopting it would assert the local copy is the one being
served, which is the thing you were about to check.* **It is the hash assumption
in a different coat, and it fails silently in the one case that matters — a copy
somebody edited.**

**Belief that could be shown wrong:** *that anybody will run `pull` again to fix
it.* **If unlocked documents simply accumulate, the report is noise and something
has to lock them.**

## 2026-09-07 — `404` is unresolved, and that is no longer provisional `osprey`

**Decided:** *`check` reports a `404` as unresolvable — the document was withdrawn
or we have lost access — and names both readings without picking one.*

**Believed to advance:** *over HTTP they are the same response, because a host
that distinguished them would leak the existence of things you may not see.*

**This entry exists because the status of the behaviour changed and the code did
not.** *It began as a local workaround recorded in a `.gaps.md` against
`externals`, which listed `410` and not `404`.* **`externals` has since added the
`404` row, so the gap is closed and the facet is deleted at this reconciliation.**

> **The workaround is not retired. It is now the specified behaviour.** *Unchanged
> in the code and entirely changed in status — and this log is the only place that
> says so.* **Somebody inheriting this will find the behaviour and go looking for
> the gap that justified it, and find nothing.**

**Belief that could be shown wrong:** *that reporting both readings is useful.*
**If in practice it is always one of them, the report is a ritual** — *and that is
worth knowing.*

## 2026-09-07 — declined: `check` does not resolve the `404` over ssh `osprey`

**Considered:** *the two readings **are** distinguishable over ssh — permission
denied against repository not found — and `externals` now says so.* **Demonstrated
here by accident:** *`loom/settled` returned `404` over HTTP while an ssh clone of
it succeeded.*

**Not done, because:** *it needs a key, a non-default port, and a second
transport* — **and it would be fixing rather than reporting**, which is the rule
this design held all round.

**Belief that could be shown wrong:** *that a person will do it.* **The ssh
disambiguation is one command and it is in the document; if nobody ever runs it,
the ambiguity was never actionable and reporting it was theatre.**

## 2026-09-07 — declined: `init` `osprey`

**Considered and rejected**, not deferred.

**Because:** *its temptation is to scaffold, and four empty directories assert four
things nobody has decided.* **A file that carries no delta should not exist.**

**Belief that could be shown wrong:** *that starting is easy without it.* **If
people repeatedly fail to start**, *the useful version creates one file and asks
one question* — **and creating the tree is still not the feature.**

## 2026-09-07 — declined: worktree, clone; and where a round lives `osprey`

**Decided:** *the cart lives on the default branch; the work is isolated on a
branch named for the cart.*

**Believed to advance:** *a cart is a venue and the work is an artifact.* **`cart`
says three states are visible in a listing, and a branch makes all three
invisible** — *a venue only visible if you know which branch to check out is not a
venue.* **Both dailies land on the default branch, one commit per exchange.**

**Declined: a worktree, and a separate clone.** *Both isolate concurrent working
directories, and `cart` says there is one live cart, ever.* **They solve a problem
the agreement says cannot exist.**

**Belief that could be shown wrong:** *that the dailies and the work have
different audiences.* **If a daily needs to quote a file that only exists on the
branch, the split makes the daily unreadable from where it lives**, and the answer
collapses to one branch for both.

## 2026-09-07 — `publish` is renamed `reachable`, and it earned its place `osprey`

**Decided:** *the command is `loom reachable <path>` — one anonymous request
against a document in `.loom/published/`.*

**Believed to advance:** *the old name said the tool performs publication, which
is the one thing the model says it never does.* **It performs a fetch with a
different subject**, which keeps it inside a fetcher and a comparator.

**It was nearly cut for being a third kind of thing. Then it was validated three
times in one afternoon**, against loom's own repositories:

```
loom/settled              404 anon   the page written to fix "settled is private"
jeffry/homelab-cluster    404 anon   and bedrock's public starting page named it
                                     as the better answer
loom/.loom                200 anon   fetchable — but not where a reader lands
```

**All three are now fixed.** *The third was not a `reachable` failure and is
recorded as the tool's boundary:* **`reachable` answers *can anybody fetch this*
and does not answer *will anybody find it*.** *The second is not testable by a
fetcher and a comparator, and trying is the first step in the tool becoming
something else.*

**Belief that could be shown wrong:** *that publication failures are common enough
to need a command.* **Three for three is a small sample from one publisher in one
week.**

## 2026-09-07 — the `ETag`/blob coincidence is a migration aid `osprey`

**Recorded so it is not rediscovered as a good idea.**

*With eight adopted documents and no locks, `check` was run by hand by hashing the
local copies and comparing to remote `ETag`s* — **the exact thing the convention
forbids** — **and it worked**, because on gitea the two coincide. *It found
exactly one drifted document, correctly.*

**It is worth doing once, on gitea, to lock what was fetched by hand before the
tool existed. It is not a mechanism.**

> **The coincidence has now been found twice and rejected twice.** *The next person
> to notice it will think they have found the good idea again.*

## 2026-09-07 — annotate to ask; write in your own file to assert `osprey`

**Decided:** *responses between two presences are correspondence — each writes in
their own file — and annotation is reserved for asking or challenging.*

**Believed to advance:** *the freeze is not "you cannot edit", it is "you cannot
edit without resolving what was said".* **An annotation creates an obligation**,
which makes it the blocking form and correspondence the non-blocking one.

*And the cost is practical: **dissolving a multi-pass file is expensive**, so the
cost of annotating rises with the length of the thing annotated.* **Annotate
early, or accept the cost when the question is worth blocking on.**

**Belief that could be shown wrong:** *this rule is in neither `cart` nor
`annotating`.* **It is our reading of their text, and `cart` is loom's** — *they
may say we have it wrong.*

## 2026-09-07 — why this tool exists, in one story `osprey`

**Gitea's ssh is on port `2222`.** *I did not know that. I tried to clone, got
`Permission denied (publickey)`, and spent three tool calls and a guess chasing it
as an authentication problem before finding the port.*

**The fact was published.** *`jeffry/homelab-cluster`, in `.loom/published/gitea.md`,
says:*

> **A clone URL without the port will not work**, and the failure looks like an
> authentication problem rather than a wrong port.

**It named my failure before I had it, and I could not read it** — *the repository
was not fetchable by anybody who is not its owner.*

**This happened inside the round that was designing the fix**, *and it failed for
the reason that round had just spent two passes identifying.* **A document that is
correct, published, and unreachable is worth exactly as much as one that was never
written.**

**Believed to advance:** *nothing in this log is a stronger reason for the tool to
exist.* **`reachable` is why the document can be fetched. `pull` and `check` are
why it is still true when you read it.**

**Belief that could be shown wrong:** *that the tool would have helped.* **I would
have had to already depend on that document to have pulled it** — *and the thing I
needed was the one I did not know I was missing.* **A fetcher does not solve
discovery, and this story is partly a discovery problem wearing a freshness
problem's clothes.**

## 2026-09-07 — supersedes the `reachable` entry: publication is not publicness `marmalade`

**The entry above records three publication failures found by `reachable` and says
all three are fixed. One of them was not a failure.**

**`jeffry/homelab-cluster` is private on purpose** — *it describes a running
cluster, and its owner does not want outsiders reading what is on it.* **It
publishes six documents to an audience that is not the public**, *which
`publication.md` permits in the word we misread:*

> **What a repository has handed over for **others** to depend on.**

***Others*, not *everyone*.**

**So the tool as logged would have reported a correct repository as broken.** *An
anonymous fetch returning `404` is the intended outcome there*, **and a check that
treats anonymous reachability as success produces a false positive on every
deliberately-private publisher.**

**What survives:** *the defect that round found in `bedrock/starting.md` was real,
and it was never about `homelab-cluster`.* **A public document promised that a
private repository was the better answer**, *and the promise was the defect.*
**The link was removed; naming it as private, the way `.loom` names `settled`,
would also have answered it and would have kept the better document findable.**
*That call is loom's and it is already made.*

**Believed to advance:** *a check that cannot fail teaches nothing, and one that
fails on correct repositories is worse* — **it trains people to ignore it.**

**Belief that could be shown wrong:** *that anonymous is still the right default.*
**If most publication here is to private audiences, the default is wrong** and the
command should refuse to run without being told who to ask as.

## 2026-09-07 — measured: a read token, and what a host will tell you `marmalade`

**A gitea read token was issued for one session and destroyed after.** *Recorded
because these are facts about the host that nothing else here writes down.*

**A read token authenticates raw HTTP on a private repository.** *`404`
anonymously, `200` with `Authorization: token` or `Bearer`, and `If-None-Match`
returns `304` authenticated.* **So `add` and `check` work against private
repositories** — *the assumption the specimen made and nobody had run.*

**`/api/v1/repos/{o}/{r}` reports `admin, push, pull: true` for a token that
cannot write.** *Those are the account's rights.*

**But a refused write names the token's scopes in the error body.** *So:*

> **A token cannot be asked what it may do. It can only be told, by being
> refused.**

*Supersedes the specimen's "the name is the only record", which was too strong.*
**For this tool the rule is unchanged and the reason is different:** *`loomctl`
never writes, so it never provokes the only response that would tell it anything.*

**Belief that could be shown wrong:** *that gitea keeps doing this.* **The scope
list in an error body is not a documented interface** — *it is a message, and
messages change.*

## 2026-09-07 — the CLI has nouns, and one of them is not built `marmalade`

**Decided:** *`loomctl`, with subcommands.* **`loomctl external …` now; `loomctl
beads …` when it exists.**

**Believed to advance:** *`external` is what somebody else published that we depend
on.* **The verb `check` means the same thing wherever it appears — ask somebody
else whether what we believe is still true.**

**Declined: a plugin boundary.** *`kubectl` and `gh` grew plugins after somebody
outside wanted in.* **The seam gets built when it is a reported gap, not a designed
one** — *which is how loom says that arrives, with a name attached and a workaround
recorded beside it.*

**Declined: a field where a repository declares who it published for.** *It would
let a tool compare intent to result, and it asserts a category nobody decided.*
**The better version needs no declaration: derive it from the other side, by
reading everybody's `externals/` to see who actually depends on you.** *That is
`registry`'s shape.*

**Belief that could be shown wrong:** *that one noun justifies the structure.*
**Until `beads` exists, `loomctl external` is a subcommand with nothing to be
distinguished from.**

## 2026-09-07 — declined: `published check` `marmalade`

**Considered and rejected.** *The command that would ask whether somebody who is
not you can fetch what you published.*

**Because it simulates a consumer, and `registry` will have real ones.** *An
observed fetch beats a synthetic probe — the probe says a stranger **could** have
fetched it; a registry says somebody **did**.* **Building the probe first builds a
worse version of the thing that is coming.**

**And it removes the only thing complicating the credential story:** *`--as
<context>` existed almost entirely to serve this command.*

**Belief that could be shown wrong, two ways:**

- **`registry` never materialises**, *and nothing ever asks the question.*
- **`registry` records *declared* consumers rather than *observed* fetches.** *"Who
  says they depend on us" is not "who can actually read us"* — **then this comes
  back.**

*Cost of deciding: the command found three real problems in one afternoon, one of
which was a false positive it would have produced forever.* **The workaround is one
`curl`, and a real need with a cheap workaround is a gap rather than a missing
feature.**

## 2026-09-07 — kept, though nothing implements it `marmalade`

> **A check performed with your own credential proves nothing.** *It helps you
> complete alone an act that, by definition, you cannot* — **and then tells you it
> was fine.**

**Believed to advance:** *whoever builds `registry`'s consumer view needs this
before they design it*, **because the tempting implementation is for the publisher
to verify their own publication** — *the same mistake with a database behind it.*

**And it is cheap to detect:** *`/api/v1/user` gives the acting login, the
repository gives its owner.* **One request**, *and nobody thinks to make it.*

## 2026-09-07 — `external list` talks to git, measured `marmalade`

**Decided:** *`list` enumerates a publisher's `.loom/published/` by shelling out to
`git`* — **`clone --filter=blob:none --depth=1 --no-checkout`, then `ls-tree`.**

**Believed to advance, and measured across three hosts:**

```
git archive --remote   gitea ok · github 422 · gitlab 404
partial clone          gitea ok · github ok · gitlab ok      124–144KB
REST                   /api/v1/repos/{o}/{r}/contents/{p}
                       /repos/{o}/{r}/contents/{p}           (api.github.com)
                       /api/v4/projects/{url-encoded}/repository/tree
```

**The argument is consistency, not thrift.** *One mechanism against three hosts
instead of three adapters* — **and REST `404`s on a private repository, which is
the case that matters.**

**The failure mode to build for:** *`--filter` is a server capability and git's
fallback is **silent***, warning `filtering not recognized by server` and
downloading everything. **`--depth=1` bounds it. Detect the warning and say so.**

**Belief that could be shown wrong:** *that shelling out stays simple.* **The first
time we need output `git` does not print stably, the library trade looks
different.**

## 2026-09-07 — nothing needs ssh, and nothing needs write access `marmalade`

**Decided:** *every transport is HTTPS on 443, and no token this tool is given
should carry `write:repository`.*

**Measured:** *partial clone with the blob filter works over gitea's **smart
HTTP***, so `list` never needed ssh — *it was built that way out of habit.*

**The tool writes only to the working tree** — *a fetched document, a lock, a
facet* — **and never commits or pushes.** *Committing and pushing are the person's,
under their own credentials.*

> *Same reason `cart` gives for an agent committing and not pushing:* **the
> consequences of a push land on people it cannot experience.** *A tool that can
> push is a tool that can publish, and publishing is an act somebody performs.*

**Implementation:** *never build `https://<token>@host/…`* — **git writes it into
`.git/config` and it surfaces in `git remote -v` and logs.** *Pass
`-c http.extraHeader="Authorization: token …"` per invocation instead.*

**Belief that could be shown wrong:** *that every host we meet allows token auth
over git-HTTPS.* **A host that does not would need ssh for `list` and nothing
else.**

## 2026-09-07 — untested, and load-bearing `marmalade`

**Nobody has confirmed that a gitea PAT scoped `read:repository` authenticates
*git over HTTPS*, not only the API and raw files.** *Those are different paths in
gitea; the token we had was measured only against the second.*

**Measured:** *an unauthenticated HTTPS clone of a private repository returns
`Failed to authenticate user`* — **so something is required, and which something is
unknown.**

**Recorded rather than assumed** *because it is the first thing to run against the
next token*, **and because if a read scope is not enough, that is the only argument
for keeping ssh.**

## 2026-09-07 — `--help` is the documentation surface `marmalade`

**Decided:** *`--help` is what a person or an agent actually runs when handed an
unfamiliar CLI, so it is the surface that has to be good* — **say what a command
does and what it will not do.**

**A `.loom/published/` for `loomctl` is deferred, not declined.** *The distinction
matters because `init` was declined.* **It earns publication when somebody depends
on this tool's behaviour rather than reading its help.**

## 2026-09-07 — decided by fallback: where the credential lives `marmalade`

**Nobody chose this; the fallback became the decision and that is recorded so it
can be found.**

**One file in `~`, kubeconfig-shaped, holding hosts and credentials together.**
*Never in a repository, and nothing that reads from a repository.*

**Believed to advance:** *the config is no longer only a secret* — **it is how you
talk to a host at all**, *API shape, ssh port if it ever matters, which transport a
command uses.* **Some of that is not secret and several people would want the same
values.**

> **The split is expected and was not done:** *a host list that can be committed,
> and a credential file that cannot.* **It was named rather than decided.**

**Belief that could be shown wrong:** *that one file is fine until somebody
shares.* **The first time two people want the same host list, the file has to
split**, *and doing it later means moving a file people have already written by
hand.*

## 2026-09-07 — Go, and `git` on `PATH` `marmalade`

**Decided:** *`loomctl` is written in Go.*

**Believed to advance:** *it gets installed on other people's machines — a laptop,
a cluster node, a CI runner* — **and a single static binary is the difference
between "download it" and "first install a runtime."** *The work is precise HTTP
header control, shelling out to `git`, and reading files; the standard library does
the first and third with no dependencies.*

**Considered: TypeScript on npm.** *A real distribution channel and the familiar
one.* **Not chosen because it puts a runtime in front of a tool meant to be run
casually and often** — *including by agents in loops that pay start-up cost every
time.*

**Consequence: `git` must be on `PATH`.** *`list` shells out rather than using a
library, because the behaviour measured across three hosts **is** git's behaviour —
filter support, the silent fallback, the user's existing credential helpers.*
**`list` is the only command that needs it, which makes `list` the seam if this
ever bites.**

**Belief that could be shown wrong:** *that distribution is the deciding
constraint.* **If `loomctl` only ever runs in one or two places, the binary
advantage is worth little and the choice was made on a cost nobody pays.**

## 2026-09-07 — a wrinkle in the isolation role `marmalade`

**`osprey` cast the isolation role as: the cart on the default branch, the work on
a branch named for the cart.** *It assumed the work happens **during** the round.*

**Both rounds so far have been design rounds that decide work happening
**after**.** *So the branch is named for the round that authorised it, and outlives
the cart that named it.*

**Recorded rather than fixed.** *The role still works; its justification was
written for a case that has not yet occurred.* **If a round ever does produce code
while it is open, nothing here changes.**

## 2026-09-07 — `loomctl external` exists, and its first run reconciled two documents `marmalade`

**Built: `list`, `add`, `check`.** *Go, no dependencies outside the standard
library, `git` shelled out for `list` only.*

**The first real run did the thing the tool is for.** *Eight documents were
adopted by hand before it existed; `check` reported all eight `unlocked`, and
`add` locked them* — **and two came back changed**, `bedrock/starting.md` *and*
`cart/cart.md`. **Neither change would have been noticed by anybody.**

**Believed to advance:** *the lock is what makes `check` possible at all.* **With
no lock there is nothing to compare and the only honest report is `unlocked`** —
*and the tool refuses to invent one by adopting whatever the remote currently
serves.*

**Belief that could be shown wrong:** *that a per-person path derived from the URL
is good enough.* **`<host>/<owner>/<repo>/<name>.md` guesses that the first two
path segments name an owner and a repository**, *which is true of gitea, GitHub and
GitLab and is not a rule.* **`--path` exists for when it is wrong.**

## 2026-09-07 — supersedes the isolation role: a cart is not committed `marmalade`

**`cart` is now `v1` and it changed the thing we cast a role on.**

> **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 two-file rule defends against somebody asking for one; version control does
not require anybody to ask** — *anyone who can clone can add a third, and the
agreement's test is never invoked because nobody had the conversation.*

**And it is what makes a round end.** *Committed, a cart is gone from the tree and
permanent in history* — **so "gone" means "no longer live" and the negotiation
stays quotable forever.** *Ignored, gone means gone.*

**So `.loom/cart/` is now in `.gitignore`.** *The isolation role entry above
assumed the cart lived on the default branch; **the cart lives on no branch.***
*What survives of that entry is the other half: work is isolated on a branch named
for the round that authorised it.*

**Not undone: `osprey` and `marmalade` are already in this repository's history.**
*Rewriting history to honour a rule adopted afterwards would cost more than it
buys*, **and the two rounds are quotable forever, which is exactly what `v1` says
not to want.** *Recorded rather than repaired.*

**Belief that could be shown wrong, and it is a real conflict:** *the annotation
protocol this repository works under says **commit before dissolving, git is the
only archive of the conversation.*** **An ignored cart has no archive**, so
dissolving a notes file destroys the annotations outright. *One of the two is
wrong and it is not ours to settle.*