jeffryandClaude Opus 5
969524b8ea
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>
5.2 KiB
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.
# 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
## — jeffand 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.
## 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:
## 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:
## 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.