From d3fec24bc60a9651a836dadf324a40b07b458419 Mon Sep 17 00:00:00 2001 From: Jeff Gonzalez Date: Tue, 8 Sep 2026 10:41:29 -0400 Subject: [PATCH] guarantees: promise visibility about the surface we do not promise MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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/ .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) Claude-Session: https://claude.ai/code/session_018UTxuSizozEA8yDitPuris --- .loom/orientation.md | 6 ++++++ .loom/published/guarantees.md | 21 +++++++++++++++++++++ 2 files changed, 27 insertions(+) diff --git a/.loom/orientation.md b/.loom/orientation.md index 3ee206f..c45b19b 100644 --- a/.loom/orientation.md +++ b/.loom/orientation.md @@ -61,3 +61,9 @@ Three moves, and each has a document that owns the rule: - 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. diff --git a/.loom/published/guarantees.md b/.loom/published/guarantees.md index 432822b..e8c697e 100644 --- a/.loom/published/guarantees.md +++ b/.loom/published/guarantees.md @@ -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/ +.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.*