cart/.loom/published/cart.md

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.