Skip to content

docs(readme): close four seams, 5446 → 5232 words - #21

Merged
JulienMartel merged 1 commit into
mainfrom
worktree-slim-factory-readme
Sep 11, 2026
Merged

JulienMartel merged 1 commit into
mainfrom
worktree-slim-factory-readme

Conversation

@JulienMartel

Copy link
Copy Markdown
Contributor

factory has no tree on hausfold.co, so README.md is the operator manual and
its floor is higher than a doc page's. It was already dense — 21.0 words per
code span against the 20.4 the haus docs pass landed on — so trimming sentences
would have cost facts. This cuts duplication instead, under hausfold.co's
AGENTS.md "Cutting a page": the keep rules beat any word count, and a fact is
moved, never evicted.

5446 → 5232 words (−214, 3.9%). Density 21.0 → 20.1 w/span, at the floor.

The four seams

Each is a fact another document already carries in full.

removed who owns it
the foreman history — the fixer gates were once a skill an agent re-read each wakeup haus's docs/night-shift-internals.md, in full. History is on the evict list, so no link is owed. The live claims stay: the gates are code, test/factory-watchdog.bats has a case per gate, no agent pane has to survive the night
## Overnight on a closed lid the README itself, two sections up: machine-slept and the pass-retry rule were already in The runner. Its one unique fact, the lid lever sudo pmset -a disablesleep 1 on power, moved up beside them
## What it deliberately does not do the lede (nothing phones anywhere), the tier 1 opener (no model decides), the runner (90 minutes, then revoke). The one claim with no other home — factory opens no PRs — moved into the tier 1 section
the colour env rules snug's README, which carries all four semantics. NO_COLOR, CLICOLOR_FORCE=1, TERM=dumb and a pipe keep their names; the sentence links snug for what they do

Plus two smaller ones: three back-references to the starter config collapsed
into one statement where the JSON example is introduced, and the card section's
second account of merge-failed's two causes reduced to a pointer at the first.

What was deliberately not touched

The tier 1 filter, the tier1.deny floor table, requireGreen's two-sided
always caveat, the four unknown lines, the fixer gate table and the lease
semantics are byte-identical. A half-stated safety rule is worse than a long
one.

Assurance

A fresh reviewer diffed the claims rather than the identifiers and found four
real problems, all fixed before this PR:

  • the new key-set sentence omitted fixer, whose cap (2) is also absent from
    the example and present on config print — a claim the cut itself created
  • "which is the retry above" had dropped the term that makes it resolve; the
    retry fires on unknown kinds, so "a pass full of unknowns" and the
    pass-retry name are back
  • the lede's ~100 PRs figure had no home anywhere, and numbers are a keep;
    restored
  • the merge-failed seam was only half closed, and is now a pointer

The identifier diff loses exactly one span: the bare dumb from "and dumb
beats even that", which survives as TERM=dumb in the same sentence.

Verification

bats test/ 241 ok, shellcheck -x clean. The one failure — the watchdog's
empty-pidfile case, which turns on ulimit -f 0 — fails identically on a
pristine origin/main on this Mac and is green on ubuntu-latest. Unrelated
to this change, which is README only.

🤖 Generated with Claude Code

The README is factory's only manual, so its floor is high and it was already
dense: 21.0 words per code span against the 20.4 the haus docs pass landed on.
Trimming sentences would have cost facts, so this cuts duplication instead.

Four seams, each a fact another document already carries in full:

- The foreman history (the fixer gates were once a skill an agent re-read) is
  haus's `docs/night-shift-internals.md` in full, and history is on the evict
  list. The live claims stay: the gates are code, `test/factory-watchdog.bats`
  has a case per gate, no agent pane has to survive the night.
- "Overnight on a closed lid" restated the runner's own `machine-slept` and
  `pass-retry` rules from two sections above. Its one unique fact, the lid
  lever `sudo pmset -a disablesleep 1`, moves up beside them.
- "What it deliberately does not do" restated the lede (no telemetry), the
  tier 1 opener (no model decides) and the runner (90 minutes, then revoke).
  The one claim with no other home, that factory opens no PRs, moves into the
  tier 1 section.
- The colour env rules are snug's. `NO_COLOR`, `CLICOLOR_FORCE=1`, `TERM=dumb`
  and a pipe keep their names and the sentence links snug's README for what
  they do, which carries all four semantics.

Plus three back-references to the starter config collapsed into one statement
where the example is introduced, and the card's second account of
`merge-failed`'s two causes reduced to a pointer at the first.

No fact is evicted. The identifier diff loses only the bare `dumb` from "and
`dumb` beats even that", which survives as `TERM=dumb` in the same sentence.
Density lands at 20.1 w/span, at the floor, which is where a cutting pass
stops.

`bats test/` 241 ok, shellcheck clean. The one failure, the watchdog's
empty-pidfile case, fails identically on a pristine `origin/main` here and is
green in CI: it turns on `ulimit -f 0`, which this Darwin shell takes
differently from ubuntu-latest. Unrelated to this change, which is README
only.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQGpxDDCoyZFjLemzAFZsZ
@JulienMartel
JulienMartel merged commit 8c3d3f8 into main Sep 11, 2026
2 checks passed
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