Skip to content

docs: the presentation standard states what is true, not what was planned - #493

Merged
JulienMartel merged 1 commit into
mainfrom
worktree-bench-holt-haus-2
Aug 29, 2026
Merged

docs: the presentation standard states what is true, not what was planned#493
JulienMartel merged 1 commit into
mainfrom
worktree-bench-holt-haus-2

Conversation

@JulienMartel

Copy link
Copy Markdown
Contributor

What

docs/cli-presentation.md's Order of work table and the run of "What N
shipped" sections behind it are gone. Every row was done once hausfold/haus#568
landed the last three painters, and this repo's own rules say a finished plan
stops being a doc and that a doc states what is true now, not how it got that
way.

The same content returns in the present tense, minus the history and the PR
numbers, as three sections:

  • Who draws through it — the caller inventory (scruff imports the package;
    bench, haus.sh/haus-show.sh drive the coprocess; the statusline and
    image preview take roles only; lane-open.sh injects HAUS_UI_SH into the
    snippet another shell runs), the two escape bans of different strengths, the
    one exception named inside the stricter one, and the three role collisions.
  • Rules a caller has to meet — the record protocol, one coprocess per
    command opened lazily and staying dead once dead, the descriptor a background
    painter must duplicate, the sudo repaint rule, which-stream-is-a-property-of-
    the-command, one colour precedence, forcing the tty gate where colour is right
    without one, the UI_SH sentinel collision, bash 4+, the width probe that can
    kill its caller, and where the signal policy lives.
  • Why the fallback lives in snug — generated from one list, shipped beside
    the binary, reachable by a haus user with no workshop checkout.

Where the standard stops is untouched — decisions, not a backlog.

bench (two comments), test/bench.bats (one) and AGENTS.md's routing row cited
the table by step number; they now cite the section that holds the fact. The
routing row drops its "one row is still open (10)" warning.

Why

The table was the durable record of what was left. There is nothing left, so it
was a record of history in a file whose whole job is to be the current contract —
and four files cited it by a number that was about to stop resolving.

Verify

bats test/bench.bats — 186/186 (comment-only changes to bench; the suite is
run because it greps the script's own text in places).

Sweep confirming the claim: across the family, the only shell files still
holding an SGR escape are bootstrap.sh, haus-activate.sh,
build-golden-vm.sh, trill/scripts/dev-install.sh and this repo's
script/issue-labels.sh + script/probes/*.sh — every one of them named in
Where the standard stops — plus snug/share/ui.sh, which is the painter,
and the statusline's TINT_FABLE, which the doc names.

Watch out

  • A clean-context assurance pass caught three wrong claims in the first cut, all
    fixed before this PR: the two bans are not one ban (the painters' bans SGR
    colour only, which is why image-preview.sh may ship a DECTCEM cursor
    escape), the statusline has three collisions not two (ADD/PR_OPENok
    and DEL/PR_CLOSEDerr is the third), and "no hardcoded index survives"
    holds for user-driven surfaces only.
  • test(phase-painter): cite the standard's sections, not its step numbers haus#569 does the same de-citation in test/phase-painter.bats.
    Independent — neither PR depends on the other's order.
  • bench overlap: clean against every lane and origin/main; one lane is
    elsewhere in bench and test/bench.bats, no shared region.

…nned

Every row of the order-of-work table is done — the last three haus painters
landed in hausfold/haus#568 — so the table and the run of "What N shipped"
narrative behind it are a finished plan, which this repo's own rules say stops
being a doc. What replaces them is the same content in the present tense, minus
the history:

- **Who draws through it** — the caller inventory, how each reaches the runtime,
  the two escape bans of different strengths and the one exception named in the
  stricter one, and the three collisions eleven statusline slots make against
  nine roles.
- **Rules a caller has to meet** — the record protocol, the one-coprocess-per-
  command economy, the descriptor a background painter must duplicate, the sudo
  repaint rule, stream-is-a-property-of-the-command, one colour precedence,
  forcing the tty gate where colour is correct without one, the `UI_SH` sentinel
  collision, bash 4+, the width probe that can kill its caller, and where the
  signal policy lives.
- **Why the fallback lives in snug** — generated from one list, shipped beside
  the binary, reachable by a haus user with no workshop checkout.

**Where the standard stops** is untouched: it is a set of decisions, not a
backlog, and the four surfaces outside the standard are still outside it.

The three files that cited the table by step number — `bench` twice,
`test/bench.bats` once — now cite the section that holds the fact. AGENTS.md's
routing row drops the open-row warning and states both bans instead of the one.

An assurance pass on the diff caught three claims the first cut got wrong and
they are fixed here: the two bans are not one ban (the painters' is SGR-colour
only, which is why `image-preview.sh` may ship a DECTCEM cursor escape), the
statusline has three collisions and not two, and "no hardcoded index survives"
is true of user-driven surfaces only — the installers and maintenance scripts
still hold theirs on purpose.

Verify: `bats test/bench.bats` — 186/186.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_016bn18dzSqSTSpVWQVaLLRJ
@JulienMartel
JulienMartel merged commit 3e49c7a into main Aug 29, 2026
2 checks passed
@JulienMartel
JulienMartel deleted the worktree-bench-holt-haus-2 branch August 29, 2026 13:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant