docs(readme): close four seams, 5446 → 5232 words - #21
Merged
Merged
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
factory has no tree on hausfold.co, so
README.mdis the operator manual andits 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.
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.batshas a case per gate, no agent pane has to survive the night## Overnight on a closed lidmachine-sleptand thepass-retryrule were already in The runner. Its one unique fact, the lid leversudo pmset -a disablesleep 1on power, moved up beside them## What it deliberately does not doNO_COLOR,CLICOLOR_FORCE=1,TERM=dumband a pipe keep their names; the sentence links snug for what they doPlus 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.denyfloor table,requireGreen's two-sidedalwayscaveat, the four unknown lines, the fixer gate table and the leasesemantics 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:
fixer, whosecap(2) is also absent fromthe example and present on
config print— a claim the cut itself createdretry fires on unknown kinds, so "a pass full of unknowns" and the
pass-retryname are back~100 PRsfigure had no home anywhere, and numbers are a keep;restored
merge-failedseam was only half closed, and is now a pointerThe identifier diff loses exactly one span: the bare
dumbfrom "anddumbbeats even that", which survives as
TERM=dumbin the same sentence.Verification
bats test/241 ok,shellcheck -xclean. The one failure — the watchdog'sempty-pidfile case, which turns on
ulimit -f 0— fails identically on apristine
origin/mainon this Mac and is green onubuntu-latest. Unrelatedto this change, which is README only.
🤖 Generated with Claude Code