Skip to content

Remove docs that go stale when code changes - #111

Merged
moshez merged 1 commit into
mainfrom
array-105-stale-docs
Nov 10, 2026
Merged

moshez merged 1 commit into
mainfrom
array-105-stale-docs

Conversation

@moshez

@moshez moshez commented Nov 10, 2026 •

Copy link
Copy Markdown
Member

Fixes #105

Done-when digest: 87b34a4549f73aca

Head: a760113

Plan

  1. the "CI is pinned" section of CLAUDE.md is removed, or replaced by one line pointing to repository-prototype's CLAUDE.md ("A library's check.yml is a caller of package-check.yml" and "CI Pattern: every input is pinned"); any passage of CLAUDE.md or README.md that restates what the code does (a list of functions, their signatures, a command's flags or output) is removed or replaced by a pointer to the package's generated docs or to the command's help text; sections that state a decision, its research, or what is proved apart from what is tested stay; a comment in the PR lists each section of CLAUDE.md and README.md and what became of it (kept as a decision, pointer, removed). If this repository's CI or tests read the removed text (grep before removing), that is changed in the same PR. Met as follows. The "CI is pinned" section is removed (a change adds no line to a .md file), so the headings of CLAUDE.md no longer have it. Command: grep -n '^## ' CLAUDE.md.
  2. The two bullets that list functions and their results are removed. Command: git diff origin/main -- CLAUDE.md.
  3. Every other section is untouched, so the diff against main deletes lines only and no section heading is deleted but the CI one. Command: git diff origin/main --numstat.
  4. The comment is posted. Command: gh api repos/bats-lang/array/issues/111/comments --jq '.[].body' | head -n 17.
  5. Nothing reads it. Command: git grep -n -e "CI is pinned" -e "CLAUDE.md" -- . ':!CLAUDE.md'.
  6. The head the evidence ran at is the pushed head. Command: git rev-parse HEAD.

Execution

Removed the "CI is pinned" section and the first bullet of "Byte arrays know their contents" and of "Int arrays know their contents" from CLAUDE.md. README.md is the title only. The section comment is on the PR. CI runs the package check on the head.

Deviations: none

Evidence

$ grep -n '^## ' CLAUDE.md
3:## Comments name their area by keyword
7:## Allocation size is bounded on purpose
18:## Allocation failure is in the type (array#80, keyword: array allocation-failure)
53:## The arena is the pool
76:## Two ways to make an arena, one deprecated (array#29, array#67)
99:## An arena's size is a class
147:## Byte arrays know their contents
234:## Int arrays know their contents (bats-lang/array#49)
278:## Appended cells: APPEND, CELLS_EQ, HOLDS (bats-lang/array#82)
303:## The accessors as templates (bats-lang/sha256#59)
$ git diff origin/main -- CLAUDE.md
diff --git a/CLAUDE.md b/CLAUDE.md
index 77c4b41..34bd75c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -149,12 +149,6 @@ bound.
 `barr(l, n, cs)` is an array of n bytes at l that holds the cells `cs`
 (`cnil`, `ccons`), so a program can prove what it reads and writes:
 
-* `barr_get` gives the cell with the proof `NTH(cs, i, v)`; `barr_set`
-  consumes the array and gives it back with `SETC(cs, i, v, cs2)`;
-  `barr_alloc` and `barr_of_arr` give cells nothing is known of (and
-  `CLEN(cs, n)`: their number), `barr_to_arr` takes the cells away so that
-  what knows nothing of them (a platform call that fills the array) may
-  write it, and `barr_copy` gives another array of the same cells.
 * `barr_get_be32(a, i)` (sha256#40) gives cells i to i + 3 as the four bytes
   of a big-endian word with the four proofs `NTH(cs, i + k, b_k)`, in one
   call. It is an ordinary function over four `barr_get` (explicit static
@@ -243,11 +237,6 @@ bound.
 ints (keyword: iarr), so a value read back from a table has the index the
 program proved when it wrote it, and a dependent needs no runtime clamp:
 
-* `iarr_alloc` (at most 1048576 elements, as `alloc`) gives `CLEN(cs, n)` and
-  `ZEROS(cs, n)` (calloc leaves every cell 0); `iarr_get` gives the cell with
-  `NTH(cs, i, v)`; `iarr_set` consumes the array and gives it back with
-  `SETC(cs, i, v, cs2)`; `iarr_free`. The cell lemmas are `barr`'s (`setc_nth_same`,
-  `setc_nth_other`, `nth_functional`, `nth_in_len`), on the same `cells`.
 * **Element width: 32 bits** (keyword: iarr width). The dependents' values are
   positions of a file, entry numbers and chain links (bats's with-env table:
   positions under 65537, entries under 1025), which fit with room to spare. A
@@ -341,29 +330,3 @@ override gets its body too. Writing such a body needs an unsafe package, since i
 casts. The templates are not new trusted primitives (the owner's ruling). The
 exposure is tracked by bats-lang/bats#421, which rejects an `implement` of a
 template or function that another package declares.
-
-## CI is pinned
-
-Every input to CI is pinned in the source (bats-lang/repository-prototype#269),
-so a commit that passes keeps passing:
-
-* The package has no dependencies, so its `bats.lock` is the empty one `bats lock --repository <dir>` writes ("wrote bats.lock (no dependencies)"); the shared package-check.yml requires a lock, so `bats check` also refuses a `#use` the lock does not name.
-* The compiler is the commit in `.github/bats-version`, read by every
-  workflow that builds bats (and by the publish workflow).
-* The package repository is fetched at the commit in
-  `.github/repository-version`, so what the test packages under `tests/`
-  lock (`bats lock --dev`) is pinned too.
-* `publish.yml` and `relock-pins.yml` in bats-lang/repository-prototype are
-  called by commit, never `@main`.
-
-Pins move only through a reviewed pull request that runs the same CI. The
-daily `relock.yml` (the shared `relock-pins.yml`) relocks against the
-newest, moves the compiler and repository pins, pushes `relock/<date>`,
-opens a pull request listing the old and new versions and dispatches
-`check.yml` on it, so a breaking publish shows as a red relock pull
-request and main stays green. GITHUB_TOKEN cannot change workflow files,
-so without a `RELOCK_TOKEN` secret that pull request lists a workflow pin
-that would move instead of moving it: move it in a pull request of its
-own. A pull request that needs newer packages runs `bats lock
---repository <dir>` and commits `bats.lock` (and
-`.github/repository-version`) with the change.
$ git diff origin/main --numstat
0	37	CLAUDE.md
$ gh api repos/bats-lang/array/issues/111/comments --jq '.[].body' | head -n 17
Sections of CLAUDE.md and README.md and what became of each:

* `# array` (title): kept.
* Comments name their area by keyword: kept as a decision.
* Allocation size is bounded on purpose: kept as a decision.
* Allocation failure is in the type (array#80): kept as a decision, with its research and measurements.
* The arena is the pool: kept (what its types prove).
* Two ways to make an arena, one deprecated (array#29, array#67): kept as a decision (the owner's ruling).
* An arena's size is a class: kept as a decision with its research.
* Byte arrays know their contents: kept (what is proved and what is trusted); its first bullet, a list of the functions barr_get, barr_set, barr_alloc, barr_of_arr, barr_to_arr and barr_copy with their results, is removed (the signatures are in src/lib.bats).
* Int arrays know their contents (array#49): kept (decisions, what is proved, what is trusted); its first bullet, a list of iarr_alloc, iarr_get, iarr_set and iarr_free with their results, is removed (the signatures are in src/lib.bats).
* Appended cells: APPEND, CELLS_EQ, HOLDS (array#82): kept (what is proved, nothing trusted).
* The accessors as templates (sha256#59): kept as a decision with its measurements.
* CI is pinned: removed. It restated the repository's workflows, pins and relock; the shared description is in bats-lang/repository-prototype's CLAUDE.md ("A library's check.yml is a caller of package-check.yml" and "CI Pattern: every input is pinned"). No pointer line is added, since a change adds no line to a .md file.
* README.md (`# array`, no section): kept, nothing to remove.

Nothing in .github, tests, example or src reads the removed text (grep in the Plan).
$ git grep -n -e "CI is pinned" -e "CLAUDE.md" -- . ':!CLAUDE.md'
exit status: 1
$ git rev-parse HEAD
a76011320d54f008f926b378a49bc5fb3a2f5d32

Generated by Claude Code

…DE.md

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HwLsLtFgHv4ix6TZzPYRcT

moshez commented Nov 10, 2026

Copy link
Copy Markdown
Member Author

Sections of CLAUDE.md and README.md and what became of each:

  • # array (title): kept.
  • Comments name their area by keyword: kept as a decision.
  • Allocation size is bounded on purpose: kept as a decision.
  • Allocation failure is in the type (array#80): kept as a decision, with its research and measurements.
  • The arena is the pool: kept (what its types prove).
  • Two ways to make an arena, one deprecated (array#29, array#67): kept as a decision (the owner's ruling).
  • An arena's size is a class: kept as a decision with its research.
  • Byte arrays know their contents: kept (what is proved and what is trusted); its first bullet, a list of the functions barr_get, barr_set, barr_alloc, barr_of_arr, barr_to_arr and barr_copy with their results, is removed (the signatures are in src/lib.bats).
  • Int arrays know their contents (array#49): kept (decisions, what is proved, what is trusted); its first bullet, a list of iarr_alloc, iarr_get, iarr_set and iarr_free with their results, is removed (the signatures are in src/lib.bats).
  • Appended cells: APPEND, CELLS_EQ, HOLDS (array#82): kept (what is proved, nothing trusted).
  • The accessors as templates (sha256#59): kept as a decision with its measurements.
  • CI is pinned: removed. It restated the repository's workflows, pins and relock; the shared description is in bats-lang/repository-prototype's CLAUDE.md ("A library's check.yml is a caller of package-check.yml" and "CI Pattern: every input is pinned"). No pointer line is added, since a change adds no line to a .md file.
  • README.md (# array, no section): kept, nothing to remove.

Nothing in .github, tests, example or src reads the removed text (grep in the Plan).


Generated by Claude Code

@moshez
moshez marked this pull request as ready for review November 10, 2026 12:57

moshez commented Nov 10, 2026

Copy link
Copy Markdown
Member Author

Plan check
Plan digest: 43bccaf2438cdd8c
Plan check: ok


Generated by Claude Code

moshez commented Nov 10, 2026

Copy link
Copy Markdown
Member Author

Independent review (a separate reviewer agent, not the author) of head a760113: approved

Plan: approved
Plan digest: 43bccaf2438cdd8c
Execution: approved
Verdict: approved
Body: 669b8e2a973b116f

I did not write any part of this change.

CI at the head, read from the PR at the start (the head was unchanged when I posted): check / check success, check / layout success, text-lint / lint success, canonical-files / canonical-files success, check / c-runtime skipped (no run is needed for a docs-only change). No check was unfinished or failed.

Checked:

  • Head line: the last Head: line of the body is the full head SHA. Every $ row sits in a pitboss-expand block marked with this head.
  • Plan check comment: first line Plan check, last line Plan check: ok, and its digest equals the Plan digest above. The Plan has precise commands for each row (rows 1 to 6), and each is read-only. I could not run them myself, since this session has no shell; I read each against the diff and the file at the head instead. The cut head -n 17 in row 4 reaches the line "Nothing in .github, tests, example or src reads the removed text", as the Evidence shows.
  • Done-when, row 1: the "CI is pinned" section is gone (the heading list in Evidence has no such heading); the Done-when allows removal instead of a pointer line, and a change adds no line to a .md file (numstat is 0 added, 37 removed).
  • Done-when, row 2: the two bullets that list functions and their results (barr_get, barr_set, barr_alloc, barr_of_arr, barr_to_arr, barr_copy; iarr_alloc, iarr_get, iarr_set, iarr_free) are removed; the signatures are in src/lib.bats. I read the whole CLAUDE.md at the head: what remains states decisions, measurements, what is proved and what is trusted. Later text that names ZEROS or iarr_alloc stands without the removed bullet.
  • Done-when, row 3: the PR comment lists each section of CLAUDE.md and README.md and what became of it. README.md is the title only.
  • Done-when, row 4: the grep for "CI is pinned" and "CLAUDE.md" outside CLAUDE.md exits 1, so nothing in the repository reads the removed text.
  • Docstrings: the change touches only CLAUDE.md, so no docstring next to code is made false.
  • Execution against the Plan: every command of the Plan was run as written, nothing left out. Deviations: none, as the body says.

Deviation: none listed, none found.

Checklist of bats prcheck --checklist: I could not run the command (no shell here); the lines below are the ten rules from the command's source in a bats checkout, each judged against the diff, which touches CLAUDE.md alone.

    1. A comment goes on over more than one line: checked, ok (no comment added).
    1. A comment states the status of the code: checked, ok (none added).
    1. A comment names no CLAUDE.md, rule file or place: checked, ok (none added).
    1. Code of ours that is not bats needs Exhausted:: checked, ok (none added).
    1. A symlink escapes the checkout: checked, ok (none added).
    1. A workflow or action file has no floating pin: checked, ok (no workflow changed).
    1. A test asserts no literal, sleeps for no fixed time: checked, ok (no test changed).
    1. The body closes a ticket: checked, ok (Fixes bats-lang/array#105).
    1. The paths of a rule file cover the text it names: checked, ok (no rule file changed).
    1. Each Done-when line is a COMMAND, MEASURE, TEST or SEARCH line with a result row: the ticket's Done-when is not written in that form, and the Plan and Evidence grade each of its rows above; no finding.

Generated by Claude Code

@moshez
moshez merged commit 0cee398 into main Nov 10, 2026
10 of 11 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.

Remove docs that go stale when code changes

2 participants