loom/docs
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

the loom conventions, rendered — and adopted the way the conventions say

Browse Source 
Astro Starlight over .loom/externals/. Every reference page is a copy of a
document published by another loom repository, adopted with loomctl, locked to
the etag it was fetched at. Nothing is written twice.

Two kinds of page. Generated ones are overwritten every build because nobody
typed them. Guides are hand-written, never overwritten, and stamped in
frontmatter with the etags they were written against; when a source moves, the
build renders a banner onto the page asking whether it is still true. It cannot
answer that — only a person can — so it asks where a reader will see it too, and
the site degrades honestly instead of reading as authoritative and being wrong.
npm run ack is the person saying they re-read it.

Declined: having the build stage a polad into the cart. loomctl external check
does that and is right to, but a docs build runs in CI and in worktrees where
there is no cart, and staging a polad is an act of judgment. The build reports;
a person raises.

The guides are worked examples rather than explanations, deliberately. An
explanation is a second saying of a rule owned on the page beside it and goes
stale silently; an example goes stale visibly, because the artifacts in it are
the wrong shape.

Generation is byte-deterministic — locks are walked in path order, no timestamps
— because the diff is most of the value.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
jeffry
2026-09-08 09:51:16 -04:00
co-authored by Claude Opus 5
commit 969524b8ea
37 changed files with 9769 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.loom/README.md
+15
View File
@@ -0,0 +1,15 @@
# `.loom` — loom/docs
**This repository publishes nothing.** *It is a reader.*
**What is here is `externals/`** — a copy of every document the `loom`
organisation publishes, locked to the version it was fetched at. *The site at
[loom.hypertheory-labs.dev](https://loom.hypertheory-labs.dev) is those copies,
rendered, plus four hand-written section fronts.*
**Nothing in `externals/` is edited here.** *A copy that differs from its source
is the only evidence that something moved while nobody was watching, so editing
one destroys the mechanism this repository exists to demonstrate.*
*What we hold about a document goes in a facet beside it — `.usages.md` for what
of ours depends on it, `.gaps.md` for what we expected and did not find.*
.loom/externals/.locks
Vendored
+13
View File
@@ -0,0 +1,13 @@
# loomctl locks — one record per adopted document.
# path<TAB>url<TAB>etag[<TAB>visibility]
# The url is resolved: a short form would follow whatever the default branch
# is at the time you ask. visibility is what the source could be read as when
# it was fetched, because that is checked once and the copy is durable.
git.hypertheory-labs.dev/loom/annotating/annotating.md https://git.hypertheory-labs.dev/loom/annotating/raw/branch/main/.loom/published/annotating.md "9b1f7e6ca92f2339b2d433686c27845362944bdb" public
git.hypertheory-labs.dev/loom/bedrock/loom-directory.md https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/loom-directory.md "ee0f49cb900c0812678061971194325d9cba366a" public
git.hypertheory-labs.dev/loom/bedrock/publication.md https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/publication.md "c0d9231aa8eed3041c60b72da5735585457fbc90" public
git.hypertheory-labs.dev/loom/bedrock/recording-decisions.md https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/recording-decisions.md "d190eeae7929b9a99ecf09211d94e7e5b32635bd" public
git.hypertheory-labs.dev/loom/bedrock/sibling-facets.md https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/sibling-facets.md "a46446a34ccb8bfc533d3cce19f4c88548c4fa04" public
git.hypertheory-labs.dev/loom/bedrock/starting.md https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/starting.md "b9eefba0f4668a496ccfc6a1377277f0721456d2" public
git.hypertheory-labs.dev/loom/cart/cart.md https://git.hypertheory-labs.dev/loom/cart/raw/branch/main/.loom/published/cart.md "15331f1a9cc81bf61a44830cfbb7c274f4c2b119" public
git.hypertheory-labs.dev/loom/externals/externals.md https://git.hypertheory-labs.dev/loom/externals/raw/branch/main/.loom/published/externals.md "a7586eb52caf275d9bcedbbd8042c43e5aaad0b9" public
.loom/externals/git.hypertheory-labs.dev/loom/annotating/annotating.md
Vendored
+158
View File
@@ -0,0 +1,158 @@
# Agreement — annotating
**v0.** Depends on nothing. Everything else depends on this.
**How two parties mark up each other's files without either of them having to
diff anything.** Deliberately minimal — this is the most-depended-on thing
published here, so a revision costs everyone downstream an afternoon.
---
## The protocol
**Whoever wrote a file does not annotate it. Whoever annotates a file does not
edit it.** That is the whole of it, and it exists so that neither party has to
reconcile two versions of the same document.
## Where annotations go
**For any file `plan.md`, annotations go in `plan.notes.md`, beside it.**
The source file is never modified. **A notes file is never annotated** — there is
no `plan.notes.notes.md`.
**A file stays editable until it has annotations.** Until then nobody has
responded and revising it is just continuing to write. **Once notes exist the
source is fixed**, because the quotes in those notes would come loose. **Deleting
the notes releases it.**
## The format
**A heading giving the location and author, a blockquote of the exact source
text, then the comment.**
```markdown
# Annotations for plan.md
## line 13, col 24–48 — jeff
> with a cap of thirty seconds
Where did thirty come from?
## lines 40–47 — jeff
> ## Venue
> This application will be run locally. It will be browser based, but
> …
> to be in the position of rewriting this portion when that happens.
Tauri is the likely landing spot, not Deno.
```
**Rules:**
- **Quote the source markdown, not the rendered text.** The quote is how a reader
finds the span, and **it is the only part that must be exact.**
- **Quote exactly what was annotated.** A phrase selection quotes the phrase; a
block selection quotes the block.
- **Elide long quotes** with `…` on its own line — first line, ellipsis, last
line.
- **Coordinates are optional.** If you can quote accurately but are unsure of
line numbers, write `## — jeff` and leave them off.
- **An entry with no quote at all** is a comment on the whole document. It sorts
first.
Entries appear in document order.
## Asking for a specific kind of answer
**A file may ask for structured responses using heading keywords.** Any heading
level works; the prompt block runs until the next heading of the same or higher
level.
```markdown
## Question: Which storage adapter for v1?
Freeform. Anything the reader wants to say.
## Select: Which of these should land this sprint?
- Block-level anchoring
- Prompt widgets
- Notes file format
## Affirm: Ship behind a flag?
```
`Select` uses the first bulleted list in its block as the options; **any number
may be chosen.** `Affirm` is yes or no. **Only the first word of the heading is
matched, case-insensitively** — whatever follows is free text.
**Answers land in the notes file like everything else, restating the question so
the notes stand alone if the source is discarded:**
```markdown
## Question: Which storage adapter for v1?
**Answer:** File System Access API. No server process this early.
## Select: Which of these should land this sprint?
- [x] Block-level anchoring
- [ ] Prompt widgets
- [x] Notes file format
**Note:** prompt widgets can wait until the format settles.
## Affirm: Ship behind a flag?
**Answer:** No.
```
**Every response type may carry an additional freeform note**, so there is never
a need for an "other" option.
### A rule for whoever writes the prompt
> **Never enumerate an escape hatch.** No *"other"*, no *"it depends"*, no *"leave
> it to the developer."*
**Not because those answers are wrong — because they are always available
anyway**, and enumerating one changes what it costs.
**An escape hatch on the list can be selected and you are done.** Nothing to
write, no reason given, nothing for anyone to see later. **An answer that is
*not* on the list has to be written down**, which means it arrives with a reason
attached.
> **Enumerating "other" converts a recorded deviation into an unrecorded
> compliance.**
**Put only specific, castable options on the list.** If none of them fits, the
person will say so in their own words, and **their own words are the thing you
wanted.**
**A prompt may be skipped on purpose, and that is recorded**, so *considered and
passed* survives as something different from *never got to it*:
```markdown
## Question: Should the shelf survive a restart?
**Skipped.**
```
## What this does not constrain
**Prompts do not limit where else annotations may go.** A file with five prompts
may also carry thirty freeform annotations anywhere in it, and a file with no
prompts is annotated exactly the same way.
**The keyword set is open.** An agreement that uses this one may declare
additional keywords with meaning particular to it. **A reader that does not
recognise a keyword treats the heading as an ordinary annotation** — it must not
drop it.
---
## Roles you must cast
> **Nothing.** This agreement casts all of its own roles. It is the base, and a
> base with local variation in its mechanism would break everything resting on
> it.
**You may still vary it** — in a notes file beside your copy, with a reason, like
anything else. **But understand what it costs:** every agreement you adopt that
depends on this one is now being read through a mechanism the publisher does not
know about.
.loom/externals/git.hypertheory-labs.dev/loom/annotating/annotating.usages.md
Vendored
+12
View File
@@ -0,0 +1,12 @@
# Usages — `annotating`
| what the document says | ours |
|---|---|
| notes freeze the source until they dissolve | `src/content/docs/annotating/index.mdx` |
| dissolving is all-or-nothing | *stated as the move people get wrong* |
**The guide states the annotate-versus-correspond discriminator**, *which is
**not in this document** — it was settled in a cart round and lives in
`cart.gaps.md` in another repository.* **So this page holds a claim its source
does not make**, *and no check will ever catch that.* **It is here because
somebody would otherwise have to rediscover it, which took us a round.**
.loom/externals/git.hypertheory-labs.dev/loom/bedrock/loom-directory.md
Vendored
+22
View File
@@ -0,0 +1,22 @@
# The `.loom` directory
**A repository that uses loom keeps everything in `.loom/` at its root.**
> **Type is determined by location.** *The directory a file is in says what it
> is.* **So frontmatter carries almost nothing, and often nothing at all.**
**A stream is a file. A collection of things with identity is a directory.** *A
log is appended to and no entry is ever addressed; a thing that is referred to
individually gets its own file.*
**Everything not recognised is shown rather than rejected.** *These files are
edited by hand and by agents, constantly, and that is supported. A reader that
fails on an unfamiliar directory is wrong.*
## What is fixed
**Only `.loom/` itself, and that a directory means a kind.** *Which kinds exist
is not fixed here — conventions built on this one declare their own, and a
repository has only the ones it uses.*
**Nothing outside `.loom/` is loom's business.**
.loom/externals/git.hypertheory-labs.dev/loom/bedrock/publication.md
Vendored
+68
View File
@@ -0,0 +1,68 @@
# Publication
**What a repository has handed over for others to depend on lives in
`.loom/published/`.**
> **Publishing is a change of kind, not a change of status.** *An unpublished
> document is an implementation detail you may rename at will. **A published one
> is a contract.***
**So publication is an act somebody performs** — a file moves in — **and the move
is a diff that shows up in review.** *A flag in frontmatter is a line nobody
notices; this is the moment a thing becomes somebody else's problem, and it
should be unmissable.*
**`ls .loom/published/` is *what have we committed to?*** — and it is the question
to ask before changing anything.
## Publishing is not an act you can complete alone
**A file in `.loom/published/` that its intended readers cannot fetch is not
published.** *The move is the act, but the act is not finished until somebody who
is not you can perform the read.*
> **The failure is invisible from the inside.** *Every check available to the
> publisher passes — the file is there, the commit landed, the path is right.*
> **Only a reader can detect it, and a reader who cannot fetch it does not know
> the document exists to ask about.**
*The commonest form is a document that answers "why can you not see this?" and is
published **inside** the thing that cannot be seen.*
**So publication has a visibility, and it is a property of the act rather than of
the file.** *"Others" is not "everyone".* **Naming who the readers are is part of
publishing**, because a repository that depends on this one has to know whether it
is inside that set — *and because a reader who copies a document out inherits the
copy without inheriting the visibility it was published under.*
**The test is a fetch you did not perform.**
## Doing it
1. **Decide it is a contract and not a detail.** *This is the whole decision and
the rest is mechanics.*
2. **Move the file into `.loom/published/`.** *One commit, so the diff carries it.*
3. **Say who the readers are** — *if it is not obvious from where it landed.*
4. **Fetch it.** *From somewhere that is not your machine and not your account.*
5. **Record the decision**, if you keep a log.
**Step 4 is the one that gets skipped and the only one that can fail.** *Steps 1
to 3 are things you do; step 4 is a fact about the world that you find out.*
*Then say what it depends on. A published document that quietly requires a private
one has moved the problem rather than solved it.*
## What is published is a document
**Prose, in whatever form its readers need.** *If a repository organises its
thinking some other way internally, that is its own business:* **a consumer
cannot tell whether it did, and must not need to.**
> **What is not exported is not hidden.** *The rest of the repository is there to
> read. It is simply not what you depend on.*
## There is no directory for what is unpublished
**Everything else is simply elsewhere in the repository.** *Naming the complement
invents a category — and a directory called `internal/` would look like a
security boundary and not be one.*
.loom/externals/git.hypertheory-labs.dev/loom/bedrock/publication.usages.md
Vendored
+11
View File
@@ -0,0 +1,11 @@
# Usages — `publication`
| what the document says | ours |
|---|---|
| the five-step procedure, and that step 4 is the one that fails | `src/content/docs/bedrock/index.mdx` — *the whole second half* |
| publishing is a change of kind, not of status | *why this repository publishes nothing: it only reads* |
**We restate the count — "five steps", "the fourth" — which is the one thing a
guide should not do.** *Kept deliberately, because the ordinal is the point of
the passage.* **If a step is inserted, the guide is wrong and the banner will
fire**, *which is the case this mechanism exists for.*
.loom/externals/git.hypertheory-labs.dev/loom/bedrock/recording-decisions.md
Vendored
+52
View File
@@ -0,0 +1,52 @@
# Recording decisions
**An entry says what was decided, what it is believed to advance, and the belief
that could turn out false.**
> **Only a stated belief can later be shown wrong.** *"To satisfy §4" is a
> citation, not a reason — it points at a label.* **A constraint whose reason
> cannot be found gets re-litigated as a defect by whoever inherits it.**
**Appended, newest last, never revised.** *A later entry supersedes an earlier
one by saying so.* **A revised record cannot show that anybody changed their
mind, which is most of what a reader wants from it.**
**No status, no assignee, nothing to process.** *The moment an entry can be "not
yet applied", somebody must track which ones are — and the record becomes a work
tracker, which is how a thing that outlives its authors turns into a queue nobody
reads.*
## Declines belong here too
**What you considered and did not do, with the reason you did not.**
*Almost nobody writes these, and three weeks later somebody proposes the thing
you already rejected — because the rejection lived somewhere that did not
survive.*
## Compaction, and the entries it may never touch
**"Never revised" and "somebody must be able to read it" both hold, and far
enough out they conflict** — *a log nobody can get through has stopped being a
record.*
**Compaction is allowed. Dropping an entry is not the same as revising one**, and
the uncompacted log is in git history, which is where a reader who needs it goes.
> **An entry may be dropped when a competent reader could recover it by reading
> the artifact.**
>
> **An entry may never be dropped when it records a decline, a measurement, a
> belief that was shown wrong, or one entry superseding another.**
*Which means **compaction is safe in exactly the cases where the entry was
redundant with the artifact, and unsafe in exactly the cases the log exists
for.*** **The four protected kinds are the ones with no other home:** *the code
shows what was built and can never show what was refused, what was measured, what
turned out false, or that somebody changed their mind.*
**A compaction is itself a decision, and gets an entry.**
## Where it lives
`.loom/event-log.md`. **A stream, so a file.**
.loom/externals/git.hypertheory-labs.dev/loom/bedrock/sibling-facets.md
Vendored
+28
View File
@@ -0,0 +1,28 @@
# Sibling facets
**For any file `x.md`, other things said about it live beside it as
`x.<facet>.md`.**
> **A facet is owned by whoever wrote the facet, never by whoever wrote `x.md`.**
**That is the whole of it.** *It exists so that two parties can both write about
one document without either of them reconciling two versions of it.*
## What a convention using this must decide
**Three things, and it must say all three or its adopters will not know they had
a choice.**
- **What the facet is called.** *`notes`, `usages`, `gaps` — the name is the
contract; a reader recognises the pair on sight.*
- **What fixes `x.md` while the facet exists.** *Something must, or the facet
comes loose from what it is about.*
- **How the pair is released.** *There must be an answer. **A convention that
does not say leaves its adopters stuck**, and they will not notice, because a
question nobody asks looks like a question already answered.*
## Why the facet is never owned by the source's author
**Because the source may not be theirs to change.** *An adopted document belongs
to whoever published it; a facet beside it is the only place a reader has to put
what they think.*
.loom/externals/git.hypertheory-labs.dev/loom/bedrock/starting.md
Vendored
+75
View File
@@ -0,0 +1,75 @@
# Starting one of these in a repository
**Make a `.loom/` directory. Everything else follows from two questions.**
---
## What can a reader not already know?
**That is what you publish**, in `.loom/published/`, as ordinary documents.
**Not what your service does** — its code says that. **Not how Kubernetes or
Kafka or React work** — that is somebody else's documentation, and a copy of it
here goes stale silently while reading as though it were true.
> **Write the delta.** *"The default ingress class publishes to the internet, so
> omitting it is how you leak something."* **Nobody could have guessed that, and
> nothing else here will tell them.**
**A good page ends with how to check it is still true**, and a date. *Nothing
serves the truth about a running system, so the only mechanism is somebody
looking.*
## What do you need that nothing provides?
**That is a gap**, in `.loom/gaps/`.
**The test: could you say whose job it is?** *If yes, it is a claim against them
and belongs with them. If no, it is a gap.*
**Record what you are doing instead** — *"we are using Docker Hub for now."*
**Forgetting it was provisional is the disease; the provisional answer is fine.**
---
## Then, only if you have something to say
**`.loom/externals/`** — a copy of somebody's document you depend on, with what
you use and what you expected and did not find, beside it. See
[externals](https://git.hypertheory-labs.dev/loom/externals).
**`.loom/venues/`** — choices you made about something with no document to hang
them on. *Kafka, React, HTTP.*
**`.loom/event-log.md`** — decisions, if you are keeping them here.
> **A file that carries no delta should not exist.** *If you do exactly what
> somebody else's document says, write nothing — recording the adoption is
> ceremony.*
## Write a `.loom/README.md`
**Say what is in `published/` and why somebody would want it.** *Link the
documents. One line for the curious about what `.loom` is.*
**Nobody should need to understand any of this to use it** — *they are documents
in a folder, and a reader who ignores the vocabulary entirely should still get
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.* **It describes what a home cluster
offers to somebody deciding whether to put something on it**, and a reader who
has never heard of any of this still gets what they came for.
**It was private, and being unable to link to it is what made the split obvious.**
*The operational tree is a version inventory and a target list; the pages telling
somebody what to decide are neither.* **So the manifests moved to a private
sibling and the documents stayed** — *and the documents got better for being
written to a stranger, which was not the reason for doing 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.
.loom/externals/git.hypertheory-labs.dev/loom/cart/cart.md
Vendored
+335
View File
@@ -0,0 +1,335 @@
# Agreement — the cart
**v2.** Depends on `annotating/v0`.
**How two parties work out what something means before one of them changes it.**
---
## Why
An AI has no good way to say *"I need to know more from you before I do this, and
I suspect you don't know either, and I don't want to make you look stupid."*
Neither do most people — **they assume the lightbulb will arrive once enough
content has been offloaded on them.**
**The cart gives that sentence somewhere to go where it does not read as an
obstruction.**
### Say what you will do if nobody answers
**Every open item states its own fallback.** *"If unanswered I will store an
opaque string and not link it."*
**This is what stops the cart from stalling.** Without it an unanswered question
is an unresolved obligation and work stops; with it, **silence is a usable
reply** and the round can close with items still open in a way both parties
understand.
> **Silence means proceed. It never means dropped.**
*A fallback that quietly becomes the decision is worth knowing about later, so it
is worth being able to find them.*
## The cart is the round, not the folder
**A cart is one bounded exchange.** It starts, it runs, it **converts**, and then
it is gone. The directory is only where a cart happens.
**What ends a cart is size, not time.**
> **A cart converts when it exceeds what two people can hold at once.**
*A whiteboard's virtue is that it is bounded and erasable: when it fills, you have
to decide what matters. Cover the walls and you have removed the only thing it
was doing for you.*
**A cart that cannot convert and a commit that cannot be reviewed are the same
failure.** The sphere got bigger than a head.
## Two files. Only ever two.
**One daily per presence.** One for the owner of the code. One for **everyone
else**, collapsed into a single voice.
**A presence is not a person.** Three people on the outside speak as one, or they
do not speak — and **they do their disagreeing somewhere else first, in their own
cart, where they are the two parties.** Carts nest by party-pair, not by topic.
**There is never a third file.** `jill-daily.md`, `bill-daily.md`,
`im-the-ceo.md` is a chat log; a chat log has no bound; **something with no bound
never converts.**
**The test, when someone wants a third:** *what happens to this file when the
person changes?* **If it transfers, it was a stake. If it dies, it was a person.**
*If someone with authority wants in: have them write it as a venue constraint for
the org instead. **An authority claim entering as a venue fact carries a reason
and can be shown wrong. Entering as a voice in a cart, it cannot.***
## Only dailies get annotated
**Anything else you put in someone's cart is a specimen.**
> **Specimen** — evidence. *Look at this; it may bear on your decision.* It
> belongs to the repository the cart lives in, **and they may throw it away
> without asking you.** Default: discard.
> **Polad** — a candidate artifact, shaped exactly like what it would become,
> staged so you can see whether it fits. Default: apply or discard.
**Promotion is explicit.** A specimen cannot drift into a kept file — **if you
want to keep it, it must be re-shaped as a polad and placed deliberately.**
*Otherwise `docs/` fills with things nobody threw away.*
**A specimen cannot travel between carts.** If it still matters in the next one,
**it is reintroduced, with a fresh reason** — *"this is still here because of line
1,237."* Anything that travels silently accrues standing nobody re-affirmed.
**So responding to a specimen means restating it in your own daily, in your own
words.** That costs precision and buys something better:
> **Pinning a defect in place lets you be exact without having understood.
> Restating surfaces the misunderstanding that pinning hides.**
## Converting destroys, so extract first
**The cart is not committed. So conversion does not archive it — it deletes it.**
*Every earlier version of this agreement was wrong about that by accident: a
committed cart left its dailies in history, and "gone" was only ever true of the
tree.*
> **At conversion the cart is the only copy of everything in it.** *The dailies,
> the annotations, the answers to every prompt, and the write-ahead log.*
**So before converting, extract:**
- **every answer to a `Question`, `Select` or `Affirm`** — *an answer lands in a
notes file, a notes file dies at dissolve, and an untracked cart has no history
to fall back on.* **A prompt answered and not extracted was never answered.**
- **every write-ahead entry that survived** — *promote or discard, and both are
acts.*
- **every fallback that quietly became the decision** — *say so in the entry, in
those words.*
**Staging as you go turns conversion into a move rather than a rewrite.** *Keep
the write-ahead log current during the round and there is nothing to reconstruct
at the end, which is when you have least appetite for it.*
*Two rules in this agreement now both push toward loss — **act as if the shelf is
discarded daily**, and **the cart is not committed.** They are both right and
together they mean **nothing in a cart is safe by default.***
## Conversion emits two things
**The artifact** — the code, the decision, the change — **and the declines.**
> **A decline is what you considered and did not do, with the reason you did
> not.**
**Almost nobody writes these.** Three weeks later someone proposes the thing you
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 — **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:**
```
{wherever you put carts}/
├── current/
│ ├── name one meaningless word
│ ├── {x}-daily.md
│ └── {y}-daily.md
└── shelf/ remnants of the last round, if any
```
**The directory names are fixed on purpose.** A cart directory you can name
becomes `PROJ-1234` within a month, and then the cart *is* a ticket — with a
status, an assignee, and a backlog behind it. **The name goes in a file, where
nothing navigates by it.**
**Three states, visible in a listing:** no `current/` → no cart. `current/` alone
→ open, last round fully resolved. **`current/` and `shelf/` → carry-forward
pending.**
### Converting: whose act it is, and who decides when
**The cart lives in someone's repository, and it is theirs to reshape and theirs
to convert.** This is not a permission question.
**But converting ends a round the other presence may be standing in**, so:
> **Do not convert while someone is mid-thought. Ask whether they are ready. If
> you convert alone anyway, say so** — and expect them to reintroduce whatever
> they were in the middle of.
*The harm is smaller than it sounds: **the shelf catches what did not resolve**,
so nothing is destroyed. What is taken is the round, and a round is recoverable
by reintroduction with a reason.*
**If a tool offers a convert action, its confirmation should restate this and
nothing more.** A dialog that invents an obligation creates **shadow policy** —
something everyone obeys, nobody agreed to, and which cannot be found or argued
with.
### Deciding *when* belongs to a presence that can feel the bound
**The size trigger assumes someone notices a cart getting full. Not every
presence has that instrument.**
An AI in a cart **will not feel it filling and will keep going until told to
stop** — not from carelessness; there is nothing there to feel it with. **Asking
would produce an answer, and the answer would be fabricated.**
> **When one party cannot feel a cost, the decision belongs to the party who
> can.** Sensor placement, not authority.
*The same reason an agent commits and does not push: the consequences of a push
land on people it cannot experience. **Say who owns the conversion call, in your
notes file, before you need it.***
**If neither presence can feel it** — two agents in a cart with no human — **size
is not an available trigger** and you need a different one. We do not have a good
answer for that case.
### A third trigger, from use
**A cart may want to convert when the ground shifts under it**, at any size —
*not* a change of subject, but a change of the coordinate system: the protocol
itself changed, or a venue moved, and the round you are in was framed by
something that no longer holds.
*Reported by the first adopter, from a cart that was small and still wanted to
end. It may be its own trigger or too rare to be worth naming.*
### The shelf
**One live cart. Ever.** *"Let's switch to another cart"* is how nothing ever
converts.
**The shelf holds what did not resolve when the last cart converted**, and
carrying something forward means **re-authoring it**, not moving it.
> **Act as if the shelf is discarded at least once a day.**
**Nothing enforces that, and it is still the useful rule**, because it sorts
without enforcing: **if you would mind losing it overnight, it was never shelf
material.** It is a polad to apply, an entry to log, or a decline to record.
**Which is why no polad ever goes in the shelf.** A polad has exactly two exits —
**applied or discarded** — and forcing that at conversion is the point, because
conversion is when you know most about it.
**If you find mid-round that you are in the wrong cart**, move it out of here
entirely — **not to the shelf**, which is a carry-forward slot with nothing to
carry into. Anything from it that still matters is **reintroduced later with a
fresh reason.** *And it owes one sentence: what the conversation turned out to
be. Not a justification — the name of the round you were actually in.*
## The cart's name
**Give the cart a meaningless name.** A uuid, or `watermelon`. **Meaningless on
purpose**, so it cannot accrue a category.
**Tag durable entries with it.** The tag says exactly one thing:
> **Everything tagged with this name was considered in a single sphere of
> understanding.**
**The cart is gone by then.** You keep the boundary without keeping the container
— so you can later ask *what else was in the room when we decided this*, which is
the question someone who was not there actually asks.
---
## Roles you must cast
**An agreement adopted with these uncast has not been adopted. It has been
filed.**
## Select: Where does a cart live?
- `.loom/cart/`
- somewhere else under `.loom/`
- outside `.loom/` entirely
- there is no directory; carts happen somewhere that is not the repository
## Select: What is the durable record that declines go into?
- an event log file in the repository
- ADRs
- commit trailers
- an issue tracker
- nothing yet — declines are written and lost, knowingly
## Select: What isolates work in progress while a cart is open?
- a local branch
- a worktree
- a separate clone
- nothing; work happens in place
## Question: Who are the two presences, and what happens to each file if that person leaves?
*Name them. If either answer is "the file dies," you have a person and not a
stake, and the cart will grow a third file within a month.*
---
## What we know is unsettled
**Whether size is the only conversion trigger.** Size is what has been observed —
a cart might also want to convert on a **change of subject** at small size, and
there is no example either way.
**Whether `specimen` and `polad` stay two roles.** They are two here because
promotion is a deliberate act. If specimens routinely turn out to persist without
anyone promoting them, that is one role with a discovered property, and this is
wrong.
.loom/externals/git.hypertheory-labs.dev/loom/cart/cart.usages.md
Vendored
+12
View File
@@ -0,0 +1,12 @@
# Usages — `cart`
| what the document says | ours |
|---|---|
| a round is two presences, two files, and a name in a file | `src/content/docs/cart/index.mdx` — *the worked example is a real round* |
| the cart is not committed; converting destroys | *the example says so, and it is the part most likely to go stale* |
| durable entries are tagged with the round name | *the example ends on a tagged entry* |
**The guide quotes a `Select` verbatim from a real cart.** *If the shape of an
open item changes — the fallback line especially — the quote is wrong and the
banner will not say so*, **because the banner fires on the whole document
moving, not on the sentence we depended on.**
.loom/externals/git.hypertheory-labs.dev/loom/externals/externals.md
Vendored
+148
View File
@@ -0,0 +1,148 @@
# Externals
**How a repository records what it depends on, and finds out when it changes.**
## Pull what you use
**You fetch a copy of somebody's document and keep it** at
`.loom/externals/<host>/<path>.md`.
> ~~*The path says where it came from, so nothing has to record an origin.*~~
> **This was false and it was load-bearing.** *A stored path is short enough to
> read and therefore too short to resolve: it drops the host's routing, the
> branch, and — worst — the `published/` segment, **which is the whole contract.***
**The path is for a person. The origin is recorded in the lock**, resolved: host,
route, branch, and full path.
*Record the **resolved** URL and not the short form. A host may redirect a short
form to whatever the default branch is **at the time you ask** — so a lock holding
one is locked to a moving target, and a rename of the branch reports as a change
in the document.*
**Pull what you need to understand, not everything it depends on.** *A document
you fetch may refer to others; follow one when you hit something you do not know.
**Pre-resolving that is how you get a `node_modules`.***
### Confidentiality does not travel with the copy
**Adopting is copying.** *So a document from a repository somebody may not read
ends up in a repository they may* — **and the publisher loses control of it at the
moment of adoption**, because the copy's visibility is governed by your repository
and not by theirs.
> **Do not adopt from a source less readable than the repository you are adopting
> into.** *If you may read it and your readers may not, copying it publishes it.*
**Two ways out, and the second is better when it is available.**
**Reference-only** — *record the lock and fetch on demand, keep no copy.* **You
give up reading it offline**, which is most of what a copy is for, *and you keep
the dependency recorded and checkable.*
**Ask them to publish** — *the thing you needed was almost certainly not the
confidential part.* **A repository that must stay private can still have a public
sibling that publishes**, and the split is usually along a line that already
exists: **the operational tree is what is sensitive; the pages telling somebody
what to decide are not.**
## Two facets beside it
- **`.usages.md`** — *what we use, and **which of our artifacts depend on it***
- **`.gaps.md`** — *what we expected here and did not find*
> **A usage that does not name what it justifies is half a usage.** *"We use the
> tailnet approach" is weak. **"We use the tailnet approach — see
> `manifests/ingress.yaml`" is the whole value**, because it answers the only
> question reconciliation asks.*
## What a lock holds
**One record per adopted document, in `.loom/externals/.locks`:**
- **where it was fetched from** — *resolved, as above*
- **the publisher's `ETag`** — *verbatim*
**It is committed**, because the thing it locks is committed, and *a lock that
travels separately from what it locks is the drift this is meant to prevent.*
> **A document with no lock is not broken; it is unlocked.** *Report it and fetch
> again.* **Do not adopt whatever the remote currently serves as the lock** — that
> asserts your copy is the one being served, which is the thing you were going to
> check.
## Freshness is a conditional request
**Locked on the publisher's `ETag`, verbatim — never a hash you compute.** *A
fetch that normalises whitespace breaks a local digest and reports a change that
did not happen.*
| | |
|---|---|
| **`304`** | nothing changed |
| **`200`** | changed — the new copy is a candidate, not a replacement |
| **`410`** | gone — follow whatever the response points at |
| **`404`** | **unresolved.** *Report both readings; do not pick one* |
**`404` is two different answers wearing one status.** *The document was
withdrawn, or you no longer have access — **and over HTTP they are
indistinguishable**, because a host that distinguished them would leak the
existence of things you may not see.*
> **Say both. Do not guess.** *They want different actions — re-pull elsewhere,
> versus ask somebody for access — and a tool that picks one will be wrong half
> the time silently.*
*Over ssh they **are** distinguishable — permission denied against repository not
found — so a client that has both transports should say which it used.*
## Reconciliation runs the other way
**You cannot fold your facets back into their document.** *So the question is
not what do we rewrite here:*
> **Given what changed in theirs, what do we change in ours?**
**The facets usually survive unchanged.** *What moves is the manifests, the
config, the code that a usage named — which is why a usage names them.*
**And gaps reconcile too**, which is the half nobody builds for: *a new version
may have filled one, and nothing will tell you.*
> **A facet describes the local pair.** *A gap is true of **the copy you hold**,
> not of the document upstream — so a publisher fixing their end does not close
> it.* **It closes when you fetch the new copy and replace the pair**, and until
> then it is still true of what is in your tree.
**What survives a closed gap is not the gap. It is what the gap justified.** *If
you recorded a local workaround, ask whether it is retired or merely no longer
provisional* — **the second is the common case and it is invisible in the code**,
which is why it is an entry in your own log. *Somebody inheriting your workaround
will go looking for the gap that justified it, and find nothing.*
*A closed gap is **not** a decline. A decline is what you considered and did not
do; a closed gap is what you needed and got.*
**The new copy replaces the old pair wholesale.** *There is no merging a document
you do not own.*
## Venues, for things you cannot fetch
**`.loom/venues/<name>.md`** — *Kafka, React, HTTP.* **Choices we made about
something with no document to hang them on.**
*If there is a document, hang it there instead: **put a choice where
reconciliation will look for it.***
## Gaps that belong to nobody
**`.loom/gaps/`** — *a need with no owner.* **The test: could you say whose job
this is?** *If yes, it is a claim against them and belongs in their `.gaps.md`.*
> **Moving a file from `gaps/` into an external's `.gaps.md` is how a gap gets
> homed.** *The position is the claim.*
**A gap records the local workaround beside the need.** *"We are using Docker Hub
for now."* **Forgetting it was provisional is the disease; the provisional answer
is fine** — and when the gap is finally homed, every workaround that should be
retired is findable.
.loom/externals/git.hypertheory-labs.dev/loom/externals/externals.usages.md
Vendored
+11
View File
@@ -0,0 +1,11 @@
# Usages — `externals`
| what the document says | ours |
|---|---|
| a copy, a lock, and facets beside it | **the entire repository** — every reference page is an adopted copy |
| the lock is the publisher's etag, verbatim | `scripts/generate.mjs` reads it and never computes one |
| do not adopt from a source less readable than yours | *why this site can hold only public documents* — `README.md` |
| the lock's fourth column is visibility | `src/content/docs/externals/index.mdx` — *quotes `public` / `not-public`* |
**The guide reproduces the lock's column order.** *If a fifth column is added,
the code tolerates it and the guide is wrong.*
.loom/orientation.md
+62
View File
@@ -0,0 +1,62 @@
<!-- Generated by `loomctl orient`. Safe to overwrite; nobody typed it.
Regenerate after adopting a document or reconciling a change. -->
# What this repository depends on
Copies of other people's documents are kept under `.loom/externals/`, at a path
that says where each came from. **They are copies: do not edit them.** Anything
you want to say about one goes in a file *beside* it, never into it.
Three moves, and each has a document that owns the rule:
- **A copy is wrong, or you needed something it does not say** — write it in
`<name>.gaps.md` beside the copy.
- **What of ours depends on a copy** — write it in `<name>.usages.md` beside it.
- **A source changed** — `loomctl external check` says so and stages the new copy;
`loomctl external apply` takes it. Neither edits anything on its own.
## `git.hypertheory-labs.dev/loom/annotating/annotating.md`
- source: https://git.hypertheory-labs.dev/loom/annotating/raw/branch/main/.loom/published/annotating.md
- what of ours depends on it: `.loom/externals/git.hypertheory-labs.dev/loom/annotating/annotating.usages.md`
## `git.hypertheory-labs.dev/loom/bedrock/loom-directory.md`
- source: https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/loom-directory.md
- what of ours depends on it: **nothing recorded** — no `.usages.md`
## `git.hypertheory-labs.dev/loom/bedrock/publication.md`
- source: https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/publication.md
- what of ours depends on it: `.loom/externals/git.hypertheory-labs.dev/loom/bedrock/publication.usages.md`
## `git.hypertheory-labs.dev/loom/bedrock/recording-decisions.md`
- source: https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/recording-decisions.md
- what of ours depends on it: **nothing recorded** — no `.usages.md`
## `git.hypertheory-labs.dev/loom/bedrock/sibling-facets.md`
- source: https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/sibling-facets.md
- what of ours depends on it: **nothing recorded** — no `.usages.md`
## `git.hypertheory-labs.dev/loom/bedrock/starting.md`
- source: https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/starting.md
- what of ours depends on it: **nothing recorded** — no `.usages.md`
## `git.hypertheory-labs.dev/loom/cart/cart.md`
- source: https://git.hypertheory-labs.dev/loom/cart/raw/branch/main/.loom/published/cart.md
- what of ours depends on it: `.loom/externals/git.hypertheory-labs.dev/loom/cart/cart.usages.md`
## `git.hypertheory-labs.dev/loom/externals/externals.md`
- source: https://git.hypertheory-labs.dev/loom/externals/raw/branch/main/.loom/published/externals.md
- what of ours depends on it: `.loom/externals/git.hypertheory-labs.dev/loom/externals/externals.usages.md`
## This repository publishes
See `.loom/published/`. What is handed over for others to depend on is
there; the rest of the repository is not hidden, it is simply not what
anybody depends on.