From 7a72f4d9f2b325d4f922de373fa7f3d22c0b5cab Mon Sep 17 00:00:00 2001 From: REPPL <77722411+REPPL@users.noreply.github.com> Date: Wed, 30 Sep 2026 17:50:11 +0100 Subject: [PATCH] docs(brief): the surfaces register matches v0.12.0's commands The independent docs review at 4b9b29c85 held the cut on five sentences in 04-surfaces/README.md that describe an earlier command tree: - the drain row and the bare-invocation sentence said bare `drain` refuses to start because the run is not built; drain.go runs one move of the run per invocation (runDrain -> loop.Drain) without --dry-run; - the people/release row omitted `reflect` (helpgroups.go files it under release); - the agents-block row omitted `intent consistency ingest`, `intent prepass` and `lab` (helpgroups.go; commands/lab.md declares block: agents); - the person-verb cap read fourteen; consolidate_test.go holds fifteen. The bare-render exception reason for drain in barerender.go carried the same stale claim; it now says what the bare verb does. The reason text is read only by the bare-render test, so no behaviour changes. Assisted-by: Claude:claude-opus-5-5 --- .abcd/development/brief/04-surfaces/README.md | 12 ++++++------ internal/surface/cli/barerender.go | 6 +++--- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/.abcd/development/brief/04-surfaces/README.md b/.abcd/development/brief/04-surfaces/README.md index e034f396c..2f943d8bd 100644 --- a/.abcd/development/brief/04-surfaces/README.md +++ b/.abcd/development/brief/04-surfaces/README.md @@ -47,7 +47,7 @@ are wiring rather than user-facing surface are listed separately under | 32 | `/abcd:scribe` | shipped | Build the ledger scribe's context from the ledger alone, and ingest what it transcribed without letting it author anything | [`32-scribe.md`](32-scribe.md) | | 33 | `/abcd:source` | shipped | Keep the documents you consult in a local corpus, record what each one changed, and ban the confidential ones' names at commit time | [`33-source.md`](33-source.md) | | 34 | `/abcd:build` | shipped | Start the loop that takes one READY intent to delivered, refusing while a question is open or a peer holds it | [`34-build.md`](34-build.md) | -| 35 | `/abcd:drain` | shipped | Preview with `--dry-run` which open issues a machine may fix alone, in what order, and what happens to the rest; the shipped surface is that preview, and bare `drain`, the run itself, refuses to start | [`35-drain.md`](35-drain.md) | +| 35 | `/abcd:drain` | shipped | Work the open ledger unattended: preview with `--dry-run` which open issues a machine may fix alone and in what order, then run it one lane at a time, routing every hand-back by its kind | [`35-drain.md`](35-drain.md) | ## How much of this table a machine keeps honest @@ -140,14 +140,14 @@ the command's sentence (the section below). | people | records | `build`, `capture`, `decide`, `intent`, `memory`, `source`, `spec` | | people | checks | `lint` | | people | portability | `disembark`, `embark` | -| people | release | `launch` | -| agents and hosts | — | `banlist`, `changelog`, `docs`, `drain`, `guard`, `guard hook`, `history`, `ideate`, `ideate record`, `identity`, `implement`, `inbox`, `intent audit ingest`, `mode`, `peers`, `reading`, `report`, `scribe`, `site`, `statusline` | +| people | release | `launch`, `reflect` | +| agents and hosts | — | `banlist`, `changelog`, `docs`, `drain`, `guard`, `guard hook`, `history`, `ideate`, `ideate record`, `identity`, `implement`, `inbox`, `intent audit ingest`, `intent consistency ingest`, `intent prepass`, `lab`, `mode`, `peers`, `reading`, `report`, `scribe`, `site`, `statusline` | The placement is presentation. No verb is hidden, renamed, moved or nested by it, every verb runs the same whichever block lists it, and the group titles carry no adr-40 bucket meaning. `version` is the root's `--version` flag (itd-2609212130136102), not a verb, so it is in neither block, and the person's -count is held by a test at fourteen verbs at most. The +count is held by a test at fifteen verbs at most. The product thinker placed the people's verbs and nine of the agent entries; the rest are the technical ruling of 2026-09-25 in [`DECISIONS.md`](../../../work/DECISIONS.md), which gives each its reason. @@ -201,8 +201,8 @@ because its one operand is the quoted title it mints a record from, and bare starts a run for; the run's state renders through `abcd implement status`. Bare `abcd reflect` prints its usage, because its one operand is the cut release whose retrospective seed it renders. Bare -`abcd drain` refuses to start, because bare is the run itself and the run is not -built; what a drain would do renders through its dry run. Bare +`abcd drain` is the run itself, one move per invocation, so it is not a render; +what a drain would do renders through its dry run. Bare `abcd source` renders the corpus under the user-level home rather than anything in the repository, so where there is no corpus it refuses naming `abcd source init`. Bare `abcd identity` and bare `abcd ahoy remote` list their sub-verbs, diff --git a/internal/surface/cli/barerender.go b/internal/surface/cli/barerender.go index e5ce2d2cd..dc03eb4c3 100644 --- a/internal/surface/cli/barerender.go +++ b/internal/surface/cli/barerender.go @@ -19,9 +19,9 @@ var bareRenderExceptions = map[string]string{ "refuses (exit 2) naming the form, and writes nothing", "disembark": "a parent of stage sub-verbs that each act on a named repository or " + "lifeboat; with no operand there is no state to render, so bare prints its sub-verbs", - "drain": "bare is the run itself, which is not built, so bare refuses to start " + - "(exit 2) naming the missing lane, or the repository's missing eligibility record, " + - "and writes nothing; what a drain would do renders with --dry-run", + "drain": "bare is the run itself, one move per invocation, so it is not a render; " + + "without the repository's eligibility record it refuses (exit 2) naming how to " + + "add it, and writes nothing; what a drain would do renders with --dry-run", "docs": "a parent holding the citation-baseline writer alone; the documentation's " + "state is `abcd lint docs`, so bare prints its sub-verb", "embark": "a parent whose sub-verbs act on a named lifeboat; with no operand there " +