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

guarantees: promise visibility about the surface we do not promise

Browse Source 
loom's .usages.md for this page found the hole. The docs site depends on the
command surface — its README and publish script tell a person to type loomctl
external add loom/<repo> <doc>.md — and this page explicitly does not promise it.
Nothing parses the command, which is exactly why no check would catch a rename:
the thing that moved is not a document anybody adopted.

The answer is not to promise the surface, which would freeze the CLI. It is to
promise that a change to it lands on this page — which consumers already lock — so
a rename reports 200 the day it happens. The exclusion goes from "you are on your
own" to "you will be told", and it costs one append-only section.

Same shape as a supersession in the event log: the record is not that the thing
never changes, it is that the change is findable by whoever depended on it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018UTxuSizozEA8yDitPuris
This commit is contained in:
jeffry
2026-09-08 10:41:29 -04:00
co-authored by Claude Opus 5
parent 4e7aa1ff1f
commit d3fec24bc6
2 changed files with 27 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.loom/published/guarantees.md
+21
View File
@@ -88,6 +88,27 @@ has not earned.**
**That anything is checked when you are not looking.** *Nothing here runs on a
schedule, and a document nobody checks is a document nobody is checking.*
## What is promised about the things that are not promised
**The command surface may change. This page will say when it does.**
*A consumer whose README tells a person to type `loomctl external add loom/<repo>
<doc>.md` depends on that command by name — **not by parsing it, which is why no
check would ever catch a rename**. The thing that moved would not be a document
they adopted.*
> **So the exclusion is narrower than "you are on your own".** *We do not promise
> the surface holds; **we promise that a change to it lands here**, on a page you
> can lock* — **and a lock on this page reports `200` the day a command is
> renamed.**
**That is the whole mechanism, and it costs one section:**
### Surface changes
*Append-only, newest last. Nothing yet — the commands have not been renamed since
this page existed.*
---
*Verified fetchable by somebody who is not us on 2026-09-08.*