Skip to content

Remove docs that go stale when code changes - #96

Merged
moshez merged 1 commit into
mainfrom
css-81
Nov 12, 2026
Merged

moshez merged 1 commit into
mainfrom
css-81

Conversation

@moshez

@moshez moshez commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

Fixes #81

Done-when digest: 87b34a4549f73aca

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. Read: git diff --stat origin/main...HEAD shows only the two removals (CLAUDE.md and README.md, no added line); rows 2 to 5 show each part.
  2. The CLAUDE.md section is gone: cat CLAUDE.md shows only the title.
  3. The Features list of README.md is gone and its API pointer to docs/lib.md stays, with Usage, Proven colours and Safety: cat README.md shows them.
  4. The comment lists each section and what became of it: gh api repos/bats-lang/css/issues/96/comments --jq '.[].body | split("\n---")[0]' shows it.
  5. Nothing in CI or tests reads the removed text: grep -rn "CI is pinned" .github tests scripts src bats.toml finds nothing.
  6. The head: git rev-parse HEAD.

Execution

Removed the CLAUDE.md section and the README Features list, grepped first for readers of the text (none), posted the section comment.

Deviations: none

Evidence

Head: 9c2e38c

$ git diff --stat origin/main...HEAD
 CLAUDE.md | 29 -----------------------------
 README.md |  8 --------
 2 files changed, 37 deletions(-)
$ cat CLAUDE.md
# css
$ cat README.md
# css

CSS value types and rendering for the [Bats](https://github.com/bats-lang) programming language.

## Usage

There is no GC: colors, values, selectors, declarations and rules are
linear. The emitters borrow them; free each with its `*_free`.

```bats
#use array as A
#use builder as B
#use css as C

val r = $C.Rule($C.Class($A.text_lit("card"), 4),
  $C.Decl($A.text_lit("color"), 5, $C.Color($C.RGB(255, 0, 0))))
val b = $B.create()
val () = $C.emit_rule(b, r)
val () = $C.css_rule_free(r)
```

## Proven colours

A theme's colours can be proven at compile time; a colour is a static
`int` 0xRRGGBB.

- `src/contrast.bats`: WCAG 2 relative luminance (`LUM`) and contrast
  (`CONTRAST(a, b, k)`: at least k/10:1), so text that is hard to read
  does not type-check.
- `src/harmony.bats`: rules for a harmonious theme, over the channels
  (`RGB`): hue arcs (`HUE`), chroma, HSV saturation (`CALM`,
  `SATNEAR`), the brightest channel (`PEAK`) and relative lightness
  (`LIGHTER`); hue families (`FAMILIES`, `IN3`: at most three arcs, each
  at most 30 degrees wide), neutrals (`NEUTRAL`), and text/ground pairs
  that do not vibrate (`NOVIB`). The module's header gives the source of
  each rule.

`tests/static` holds a theme that is accepted and one rejected fixture
per rule.

## API

See [docs/lib.md](docs/lib.md) for the full API reference.

## Safety

Safe library — `unsafe = false`.
$ gh api repos/bats-lang/css/issues/96/comments --jq '.[].body | split("\n---")[0]'
Sections of CLAUDE.md and README.md and what became of each:

- CLAUDE.md, "CI is pinned": removed (restated the workflows, pins and relock behavior that repository-prototype's CLAUDE.md describes; nothing reads it).
- README.md, title and one-line description: kept (high level).
- README.md, "Features": removed (a list of the units, colors, selectors and class_text, which the code and docs/lib.md state).
- README.md, "Usage": kept as a decision (linear values, the emitters borrow, each is freed with its *_free) with its example.
- README.md, "Proven colours": kept (states what is proved and which fixtures test it).
- README.md, "API": kept as a pointer (to docs/lib.md, the generated API reference).
- README.md, "Safety": kept as a decision (unsafe = false).


$ grep -rn "CI is pinned" .github tests scripts src bats.toml
exit status: 1
$ git rev-parse HEAD
9c2e38c02b02d07548fc42cd5f4cff3450394be6

Generated by Claude Code

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

moshez commented Nov 12, 2026

Copy link
Copy Markdown
Member Author

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

  • CLAUDE.md, "CI is pinned": removed (restated the workflows, pins and relock behavior that repository-prototype's CLAUDE.md describes; nothing reads it).
  • README.md, title and one-line description: kept (high level).
  • README.md, "Features": removed (a list of the units, colors, selectors and class_text, which the code and docs/lib.md state).
  • README.md, "Usage": kept as a decision (linear values, the emitters borrow, each is freed with its *_free) with its example.
  • README.md, "Proven colours": kept (states what is proved and which fixtures test it).
  • README.md, "API": kept as a pointer (to docs/lib.md, the generated API reference).
  • README.md, "Safety": kept as a decision (unsafe = false).

Generated by Claude Code

moshez commented Nov 12, 2026

Copy link
Copy Markdown
Member Author

Plan check
Plan digest: 09287a9f95b79a2c
Plan check: ok


Generated by Claude Code

moshez commented Nov 12, 2026

Copy link
Copy Markdown
Member Author

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

Plan: ok. Every Done-when row of ticket css#81 has a row in the Plan, and each row that names evidence gives the exact command: git diff --stat origin/main...HEAD, cat CLAUDE.md, cat README.md, the gh api repos/bats-lang/css/issues/96/comments --jq ... call, grep -rn "CI is pinned" .github tests scripts src bats.toml and git rev-parse HEAD. All are read-only and can run as written. No row asks for a nox run, a repeated run or a CI result. The PR has a Plan check comment ending in Plan check: ok, with digest 09287a9f95b79a2c.
Plan digest: 09287a9f95b79a2c
Body: 7cc5a7b14ad7a491
Verdict: Plan approved

Findings: none.

  • Done-when part 1 (the "CI is pinned" section removed): the diff removes it, leaving only the title in CLAUDE.md.
  • Done-when part 2 (a passage that restates the code is removed or replaced by a pointer): the diff removes the README "Features" list, which listed units, colours and selectors. The "API" pointer to docs/lib.md stays. docs/ is generated and not committed, so the pointer is to the generated reference.
  • Done-when part 3 (decisions and proof statements stay): "Usage", "Proven colours" and "Safety" are kept.
  • Done-when part 4 (a comment listing each section and what became of it): the comment is on the PR and covers every section of both files.
  • Done-when part 5 (CI and tests that read the removed text): the Plan greps for it before removal and again afterwards.
  • Docstrings: the diff touches only CLAUDE.md and README.md, so no docstring next to code is made false.

Generated by Claude Code

moshez commented Nov 12, 2026

Copy link
Copy Markdown
Member Author

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

Plan: approved. Every Done-when row of ticket css#81 has a row in the Plan, and each row that names evidence gives the exact command: git diff --stat origin/main...HEAD, cat CLAUDE.md, cat README.md, the gh api repos/bats-lang/css/issues/96/comments --jq ... call, grep -rn "CI is pinned" .github tests scripts src bats.toml and git rev-parse HEAD. All are read-only and can run as written. No row asks for a nox run, a repeated run or a CI result. The PR has a Plan check comment ending in Plan check: ok, with digest 09287a9f95b79a2c.
Plan digest: 09287a9f95b79a2c
Body: 7cc5a7b14ad7a491
Verdict: approved

Findings: none.

  • Done-when part 1 (the "CI is pinned" section removed): the diff removes it, leaving only the title in CLAUDE.md.
  • Done-when part 2 (a passage that restates the code is removed or replaced by a pointer): the diff removes the README "Features" list, which listed units, colours and selectors. The "API" pointer to docs/lib.md stays. docs/ is generated and not committed, so the pointer is to the generated reference.
  • Done-when part 3 (decisions and proof statements stay): "Usage", "Proven colours" and "Safety" are kept.
  • Done-when part 4 (a comment listing each section and what became of it): the comment is on the PR and covers every section of both files.
  • Done-when part 5 (CI and tests that read the removed text): the Plan greps for it before removal and again afterwards.
  • Docstrings: the diff touches only CLAUDE.md and README.md, so no docstring next to code is made false.

Generated by Claude Code

@moshez
moshez marked this pull request as ready for review November 12, 2026 00:51

moshez commented Nov 12, 2026

Copy link
Copy Markdown
Member Author

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

Plan: approved (fixed)
Execution: approved
Verdict: approved
Body: 7cc5a7b14ad7a491

Findings: none. I did not write any part of the change.

  • Head: the PR head is 9c2e38c and the last Head: line of the body names it in full.
  • Checks at the head (run 43130388502): check / check success, check / layout success, check / c-runtime skipped. text-lint / lint and canonical-files are success.
  • Evidence: the six blocks are each pitboss-expand blocks marked with the head, and each is the Plan's command as written (git diff --stat origin/main...HEAD, cat CLAUDE.md, cat README.md, the gh api .../issues/96/comments --jq call, the grep -rn "CI is pinned" ... call, git rev-parse HEAD). The diff matches: 37 deletions in CLAUDE.md and README.md, no added line.
  • Done-when: the "CI is pinned" section is removed and CLAUDE.md keeps its title. The README "Features" list is removed, and "Usage", "Proven colours", "API" (pointer to docs/lib.md) and "Safety" stay. The section comment lists every section of both files with what became of it. The grep for the removed text in .github tests scripts src bats.toml finds nothing.
  • Docstrings: the diff touches only CLAUDE.md and README.md, so no docstring or comment next to code is made false.
  • Doc lines: the diff adds no line to a .md file.
  • Lint tests, failures, order tables: no lint, check or order is changed.
  • Checklist: I run nothing, so bats prcheck --checklist was not run by me; for the ledger, each of its lines is unchecked by this review.
    Deviation: none listed in the PR body, and the diff shows no stray file or mode change.

Generated by Claude Code

@moshez
moshez merged commit 8cecd8e into main Nov 12, 2026
9 of 12 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