jeffryandClaude Opus 5
6dcc06ab1c
Both from gap files loom-cli filed as the first real adopter of externals. publication.md: "publishing is not an act you can complete alone" existed only in a sibling document as an aside about a tool. It is a property of the act and now says so, along with the fact that publication has a visibility — which externals' confidentiality rule depends on entirely and this document never mentioned. recording-decisions.md: "never revised" and "must be readable" conflict far enough out. Adopts loom-cli's rule verbatim in substance — drop what the artifact could recover, never drop a decline, a measurement, a belief shown wrong, or a supersession — because compaction is safe in exactly the cases where the entry was redundant and unsafe in exactly the cases the log exists for. Entries 79-81. annotating's gaps are left standing on purpose; it is the most depended-on document and its revision is Jeff's call. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
54 lines
2.3 KiB
Markdown
54 lines
2.3 KiB
Markdown
# 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.**
|
|
|
|
## 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.*
|