[brettheap]

Lane: openreposhape-3 (openRepoShape-3)
Claim: #519 (comment)

What

• README.md is cut into segments. The preamble (everything before the first ## ), then one segment per ## heading, up to the next one. A ## line inside a code fence is not a heading, as _readme_h2s always read it; _readme_h2s now takes its headings from the same segmenter, so the outline the tables check and the segments the markers name come from one reading. Every byte is in exactly one segment.

• A segment's fingerprint is the git blob sha1 of its text with CRLF read as LF, computed in Python (sha1(b"blob <len>\0" + data)). It never runs git hash-object: the path form applies .gitattributes, --stdin does not, and the two disagree on CRLF. A carriage return anywhere in README.md is refused anyway (README is LF-only by .gitattributes), so the fold cannot hide a lone-CR change.

• Each part of docs/handbook.html records what it reads. It carries one comment per README segment it reads, <!-- reads README.md § <heading or preamble>: blob <40 hex> -->. Every marker sits at the top of its section, with nothing but blank lines and other markers between it and the opening tag, alone on its line with a blank line above and below. The masthead gains id="masthead" so a failure can name it.

• HANDBOOK_READS is the mapping, one row per part of the page, and the markers must match their row exactly. I worked it out by reading both documents:

  README segment	read by
  preamble	masthead, confers
  Starting a project in a new organisation	masthead, start, partway, ci, legs, doublepin, park
  The three legs	masthead, ci, legs
  Adopting an existing repository	adopt
  Families: a holder for projects that ship separately	families
  The double pin, and the lockstep invariant	masthead, doublepin
  Bootstrap is COPIED into the project, not fetched	copied
  Keeping a project's shape current	current, doctor
  Carrying in-flight work to another workstation	park
  The degrade rule	degrade
  Layout of this repository	layout
  Licence	licence (the footer)

  agents reads AGENTS.md and has an empty row. The cross-reads of § Starting are each for text the README says only there:

  • ci renders the worked example's paragraph on private legs;
  • legs quotes the validate-repository-naming.py --explain Atlas Atlas-spec Atlas-code line from "What setup.sh does";
  • doublepin repeats "editing the pin by hand ... is what it exists to refuse" from Daily work;
  • park carries openRepoTools' install line from "Install the command".

  The masthead reads four segments: its lede is the preamble, its fastest path the Quick start, its diagram the legs table, and its caption the double pin's first sentence. The table changes only when the page's structure changes. A README edit that only moves text moves marker hashes, never the table.

• test_the_handbook_follows_the_readmes_outline's check (4) is replaced by:

  • (a) every marker names a segment that exists; a renamed heading fails naming the marker and the headings there are;
  • (b) every segment is read by a page section, i.e. some row of HANDBOOK_READS lists it;
  • (c) every marker's blob is its segment's fingerprint now; a stale one fails naming the segment, every page section that reads it and the new value, with Regenerate docs/handbook.html: the sections the README gained since #71 (family workstation layout, --family, park/resume, the user commands, the workspace form) and a guard that the page follows the README's outline #89's re-read wording;
  • (d) each part's markers are exactly its row, with none missing and none extra. Every part has a row, every row names a real part and real segments, and README_HEADING_TO_HANDBOOK_ID agrees with the table.

  The test also refuses:

  • a marker that is mistyped, outside every page part, repeated in one section, not alone between blank lines, or not at the top of its section;
  • two headings with one name, where (c) then offers no hash for that name;
  • a carriage return in README.md;
  • a ## heading GitHub renders that the cut would miss: indented one to three spaces, ## followed by a tab or by nothing, or a setext - underline under top-level paragraph text. A rule under a list item's or a block quote's paragraph, or under an indented line, is not one; the setext refusal adds "or, if you meant a horizontal rule, put a blank line above it";
  • in the footer, a whole-README hash in any spelling, or any "added (#N)" clause but HANDBOOK_HISTORY_CLAUSES, the frozen history in order, before the closing sentence or after it.

  Every check reports in one run. HANDBOOK_README_BLOB is gone.

• The footer. The single README.md blob fact is removed. The "added (#N)" prose is kept as history, ending with tests.yml and adopt-project.py: the Windows job installs git-filter-repo 2.47.0, so the adoption test files that skip without it run there, and a source that keeps its own root .gitattributes gets one marked block of /<copy> text eol=lf lines appended to it in the split, so a Windows clone writes the pinned copies at the root with the bytes the pin records; the verification counts that file as the source's bytes followed by exactly that block, and update-shape.py apply --add extends it (#471) #511's "added (tests-windows never executes an adoption: git-filter-repo is not installed there, so the eight adopt suites skip and v1.0.0's "adopt works on Windows" is unverified #471)", and closed by one sentence, "That list is history, and it ends there.". Its clause numbers are frozen in HANDBOOK_HISTORY_CLAUSES, so a new clause is refused before the sentence or after it. Then: "Each section that reads the README records every README section it reads, with the hash of each as it read it, in comments at the top of the section, and a test checks those records against the README (docs/handbook.html: stop every README PR rewriting the handbook's README blob and line cap, so open README PRs stop conflicting with each other #519)."

• The line cap is README_CAP_BASE (1422) plus the raises in tests/readme-cap.d/*.txt. Each file is named for the issue or PR that grows the README (519.txt). Line 1 is +N, line 2 an ISO date, then one or more lines of reason.

  • Files are read as UTF-8, with a byte-order mark allowed. UTF-16 is refused with "save it as UTF-8 (PowerShell: Set-Content -Encoding utf8)". Dotfiles and editor backups are ignored; any other name that is not <n>.txt is refused with its path.
  • Every file is validated, and both failure messages carry the format, so the directory has no README and does not exist until the first raise. The test prints the cap it computed.
  • The docstring history and dated comments stay, with a note that raises from 2026-10-14 on go in the ledger.

• README.md does not change in this PR. I checked first: git hash-object README.md, git rev-parse HEAD:README.md and the Python sha1 all gave ae817c5fdb324ff60440b959a15f3ad3b2a18b43, the footer's value at the time. The README changes main brought in with tests.yml and adopt-project.py: the Windows job installs git-filter-repo 2.47.0, so the adoption test files that skip without it run there, and a source that keeps its own root .gitattributes gets one marked block of /<copy> text eol=lf lines appended to it in the split, so a Windows clone writes the pinned copies at the root with the bytes the pin records; the verification counts that file as the source's bytes followed by exactly that block, and update-shape.py apply --add extends it (#471) #511 are re-read below.

• Other references.

  • tests/test_agents_md_codes.py's docstring now names the per-section hashes, not "the handbook's README blob".
  • .github/workflows/tests.yml's three comments on park with no estate around you parks every estate (reverses ruling 3 of #82 for the no-estate case); resume unchanged #91's single README hash now name docs/handbook.html: stop every README PR rewriting the handbook's README blob and line cap, so open README PRs stop conflicting with each other #519's per-section hashes. actionlint exits 0, and the push that carried it was accepted.
  • Nothing in AGENTS.md, README.md or docs/cli.md told an author to edit the footer blob or the cap, and there is no CONTRIBUTING file.

Why

Brett Heap's ruling 29 on #519, 2026-10-14T15:18:19Z, "Hash per section (Recommended)": "Each handbook section records the hash of the README section it covers; a failing test names exactly which handbook sections to re-read. The single README hash and the per-PR "added (#N)" notes in the footer retire. Each line-cap raise becomes its own small file with its reason."

Every README pull request had to rewrite the same two places: the footer's README.md blob line, with its "added (#N)" clause, and the cap's assert line, with its dated comment. Any two open at once conflicted pairwise, and one red check named the whole page to re-read when one section had moved.

Now a README change moves only the markers of the segments it touches, and a cap raise is a new file. Every marker is alone between blank lines because git conflicts on edits to adjacent lines. I checked that with git merge-file: two adjacent changed lines conflict, and one unchanged line between them merges cleanly.

Known limit. § Starting is about a third of the README (lines 83-545) and is read by seven page sections. Two PRs that both touch it conflict on those seven marker lines. That is by design under ruling 29: both changed the same section, and each has to re-read the page sections that read it.

Fix round (2f26ce3), from the independent review of 0f808df

• SF1. Four § Starting markers sat inline beside page text quoted from another README section (ci, legs, doublepin, park). Every marker now sits at the top of its section, alone between blank lines, and the test enforces it. That rule replaces the adjacent-marker rule.
  • Reproduced in a scratch --shared clone, two branches off each head: A rewords README 606 (--repo, not --org) and ci's page line, then moves the three § The three legs markers; B edits README 87 and a line of start, then moves the seven § Starting markers. A merges B.
  • On 0f808df: CONFLICT (content): Merge conflict in docs/handbook.html at 1066-1072, where ci's § Starting marker meets the reworded ci line, as the review found.
  • On 2f26ce3: MERGE: clean, and tests/test_repo_hygiene.py tests/test_readme_sections.py on the merge gave 121 passed.
• SF2. Two markers on one line passed the adjacency check. The alone-on-its-line rule refuses them, with a fixture case.
• SF3. A secondary marker could be deleted silently. HANDBOOK_READS now holds the markers to their rows exactly, and its messages say the table changes only with the page's structure, and that a section added is a row added.
• N1-N8 as listed under What: the retired-hash pattern in any spelling, and the closed footer history (N1); README LF-only (N2); the ledger's BOM, UTF-16 and ignored names (N3); no hash offered for a doubled heading (N4); headings the cut would miss (N5); the footer wording (N6); the workflow comments (N7); read_bytes().decode("utf-8") in the cap test (N8).

Final round: nits (3c93888) and the merge of main (1839889)

From the re-review of 2f26ce3 (READY WITH NITS):

• A. "At the top of its section" is enforced. A marker has nothing but blank lines and other markers between it and its part's opening tag. A fixture moves a marker below a paragraph, blank lines and all, and is refused.
• B. A new "added (#N)" clause before the closing sentence passed. The footer's clause numbers are now the frozen tuple HANDBOOK_HISTORY_CLAUSES, in order. A new clause anywhere in the footer is refused, and so is a reordering. The fixture that let a merged-in clause through is replaced by one refusing added (#600) before the sentence, plus one for order.
• C. The setext check refused valid horizontal rules. A line indented by a tab or four spaces is no paragraph text. The scan tracks whether the paragraph above sits in a list item or a block quote (a lazy line, or one indented under an open list), and a rule under such a paragraph passes. The review's three cases are fixtures that pass, and a paragraph after a closed list still fails.

The merge. Main is 5ed3e5d. #511 landed with README and handbook edits made under the old footer rule, and conflicted here in the footer only.

• Footer. tests.yml and adopt-project.py: the Windows job installs git-filter-repo 2.47.0, so the adoption test files that skip without it run there, and a source that keeps its own root .gitattributes gets one marked block of /<copy> text eol=lf lines appended to it in the split, so a Windows clone writes the pinned copies at the root with the bytes the pin records; the verification counts that file as the source's bytes followed by exactly that block, and update-shape.py apply --add extends it (#471) #511's "added (tests-windows never executes an adoption: git-filter-repo is not installed there, so the eight adopt suites skip and v1.0.0's "adopt works on Windows" is unverified #471)" clause is kept as the last clause of the frozen history, before "That list is history, and it ends there.". Its README.md blob f3b378d… sentence is dropped. HANDBOOK_HISTORY_CLAUSES gains 471 in the merge commit, the one test change the merge makes.
• .github/workflows/tests.yml merged cleanly. tests.yml and adopt-project.py: the Windows job installs git-filter-repo 2.47.0, so the adoption test files that skip without it run there, and a source that keeps its own root .gitattributes gets one marked block of /<copy> text eol=lf lines appended to it in the split, so a Windows clone writes the pinned copies at the root with the bytes the pin records; the verification counts that file as the source's bytes followed by exactly that block, and update-shape.py apply --add extends it (#471) #511's install git-filter-repo step is byte for byte main's, and actionlint exits 0.
• Markers moved after a re-read (git diff 31219459 5ed3e5de -- README.md). Only three README sections moved:
  • § Adopting an existing repository (adopt). The ### heading's new wording, the block appended to a kept root .gitattributes, and its verification as the source's bytes plus the block are all in tests.yml and adopt-project.py: the Windows job installs git-filter-repo 2.47.0, so the adoption test files that skip without it run there, and a source that keeps its own root .gitattributes gets one marked block of /<copy> text eol=lf lines appended to it in the split, so a Windows clone writes the pinned copies at the root with the bytes the pin records; the verification counts that file as the source's bytes followed by exactly that block, and update-shape.py apply --add extends it (#471) #511's own page edit. The rest is compression to keep the README's line count: .gitignore left out of an example list (the README still names it as a collision in § Keeping), "root tree" for "root tree after the split", "as drop". The page's longer wording stays true. Covered.
  • § Bootstrap is COPIED (copied). The appended block as the other answer is in tests.yml and adopt-project.py: the Windows job installs git-filter-repo 2.47.0, so the adoption test files that skip without it run there, and a source that keeps its own root .gitattributes gets one marked block of /<copy> text eol=lf lines appended to it in the split, so a Windows clone writes the pinned copies at the root with the bytes the pin records; the verification counts that file as the source's bytes followed by exactly that block, and update-shape.py apply --add extends it (#471) #511's page edit; "who just clones" is compression. Covered.
  • § Keeping a project's shape current (current, doctor). apply --add now names each file it adds in an adopted root's own .gitattributes block. tests.yml and adopt-project.py: the Windows job installs git-filter-repo 2.47.0, so the adoption test files that skip without it run there, and a source that keeps its own root .gitattributes gets one marked block of /<copy> text eol=lf lines appended to it in the split, so a Windows clone writes the pinned copies at the root with the bytes the pin records; the verification counts that file as the source's bytes followed by exactly that block, and update-shape.py apply --add extends it (#471) #511's page edits did not cover this, so I amended current's upstream-added item, in the page's voice. The doctor subsection is untouched by tests.yml and adopt-project.py: the Windows job installs git-filter-repo 2.47.0, so the adoption test files that skip without it run there, and a source that keeps its own root .gitattributes gets one marked block of /<copy> text eol=lf lines appended to it in the split, so a Windows clone writes the pinned copies at the root with the bytes the pin records; the verification counts that file as the source's bytes followed by exactly that block, and update-shape.py apply --add extends it (#471) #511. Both markers moved.
• No anchor moved. No link pointed at the renamed ### heading.
• Wording (8237225). In current's upstream-added item, apply --add now names an added file in an adopted root's own .gitattributes "when that file carries tests-windows never executes an adoption: git-filter-repo is not installed there, so the eight adopt suites skip and v1.0.0's "adopt works on Windows" is unverified #471's block", replacing "when the root carries one": a root adopted before tests-windows never executes an adoption: git-filter-repo is not installed there, so the eight adopt suites skip and v1.0.0's "adopt works on Windows" is unverified #471 has the file and no block, and nothing is written there. The README is untouched, so no marker moved.

This head is a new H0 for ruling 27: a hand-resolved docs conflict plus test changes. It needs all three OSes green.

Tests

tests/test_readme_sections.py is new, with 76 tests on fixture text only (no real files, no git, explicit line endings). It covers:

• the segmenter: fences, ###, the empty preamble, CRLF, a lone CR;
• the fingerprint, against git's own blob hashes;
• the headings the cut would miss, and the lines that are not headings: ##Name, an --- after a blank line, a table delimiter, --- after a list item or an ATX heading, a fenced line, indented code;
• each message from (a) to (d), and the table rules: a dropped marker, an extra one, a part with no row, a row with no part, an unknown segment;
• the five layout failures (shares its line, two markers on one line, no blank above, no blank below, not at the top of its section);
• the footer: closed history, a new clause before the close, a reordered history, three retired spellings, a late clause, the closing sentence missing;
• the ledger: BOM, ignored names, thirteen malformed shapes each named by path, a directory, the over-cap message.

Each rule bites. I switched off one rule at a time in a scratch copy, then restored the file and checked its sha256. Each switch failed at least one test:

• layout: 4 failed;
• missing marker: 1;
• extra marker: 1;
• heading map: 1;
• CR: 2;
• uncut headings: 6;
• late clause: 1;
• N4 skip: 1;
• BOM: 1;
• ignored names: 1;
• UTF-16: 2;
• short retired hash: 2;
• top of section: 1;
• frozen clause tuple: 2;
• container tracking: 3;
• the tab rule: 1.

On head 1839889, run from the worktree with /usr/bin/python3 -m pytest tests/test_repo_hygiene.py tests/test_readme_sections.py tests/test_agents_md_codes.py tests/test_adopt_attributes_eol_block.py -q --basetemp=<scratch> -o tmp_path_retention_policy=failed -p no:cacheprovider: 213 passed (53 + 76 + 47 + 37). tests/test_adopt_attributes_eol_block.py is #511's new file. It reads no repository document, but it ran on the merge anyway, with no skips. No test #511 added or changed reads README.md or docs/handbook.html. The full suite is left to CI on three OSes.

Composes with

#511 landed and is merged in (above). I checked the open PR list again on this head: no other open PR touches README.md, docs/handbook.html, .github/workflows/tests.yml or the test files this PR changes.

Left out

• A README inside tests/readme-cap.d/: both failure messages carry the format.
• AGENTS.md's own line cap, which works the same old way. docs/handbook.html: stop every README PR rewriting the handbook's README blob and line cap, so open README PRs stop conflicting with each other #519 is about the README.

Lands after the v1.0.0 tag (v1.1.0).

Closes #519.

🤖 Generated with Claude Code

Summary by Sourcery

Replace the handbook’s single README hash and shared line-cap edit point with per-section fingerprints and file-based cap raises to reduce README pull-request conflicts and provide targeted staleness guidance.

New Features:

• Record a git blob fingerprint for every README segment consumed by each handbook section and validate those records against the current README.
• Replace the single README line-cap assertion with a 1422-line base plus independently tracked, reasoned raises in tests/readme-cap.d/.

Bug Fixes:

• Make handbook staleness failures identify the changed README segment and every handbook section that must be re-read.
• Reject malformed or ambiguous README headings, misplaced or mistyped handbook markers, stale footer history, invalid cap-ledger entries, and unsupported line endings.

Enhancements:

• Segment README.md consistently for outline checks and per-section fingerprints, while enforcing complete handbook read mappings and marker layout.
• Retire the whole-README footer hash and freeze the historical added-issue clauses with an explicit closing sentence.
• Update hygiene documentation and CI comments to describe per-section README hashes.

Documentation:

• Update the handbook footer to document per-section README hashes and remove the retired whole-README hash.

Tests:

• Add comprehensive fixture-based coverage for README segmentation, fingerprints, handbook marker mappings and layout, footer history, and cap-ledger validation.
• Expand repository hygiene checks to aggregate and report all handbook, README, footer, and line-cap violations in one run.

[sourcery-ai]

Sorry @brettheap, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 2 days and 7 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Reviewer's Guide

The PR removes the shared handbook footer hash and README cap assertion as conflict hotspots, replacing them with fence-aware per-section README fingerprints and markers, targeted aggregated validation, a per-raise cap ledger, and extensive fixture-based tests.

Sequence diagram for detecting a stale handbook section

sequenceDiagram
    participant Author
    participant README as README.md
    participant Test as Repository hygiene test
    participant Handbook as docs/handbook.html

    Author->>README: Edit one README section
    Author->>Test: Run tests
    Test->>README: Segment text and compute blob fingerprint
    Test->>Handbook: Read marker for the segment
    Test-->>Author: Report changed segment and handbook sections to re-read

Loading

Flow diagram for per-section README fingerprint validation

flowchart LR
    README[README.md] --> Segmenter[Fence-aware section segmenter]
    Segmenter --> Fingerprint[Python Git blob SHA-1 per segment]
    Fingerprint --> Markers[Handbook section markers]
    Markers --> Checks[Aggregated hygiene checks]
    Checks -->|stale or missing| Report[Name segment and handbook sections to re-read]

Loading

File-Level Changes

Change	Details	Files
Replace the handbook’s single whole-README hash with per-segment read markers and comprehensive consistency validation.	Segment README.md into the preamble and fence-aware ## sections, with CRLF-normalized Git blob fingerprints computed in Python. Annotate each handbook part with the README segments it reads and add the masthead identifier needed for validation. Validate marker existence, ownership, uniqueness, spacing, segment coverage, current hashes, heading-to-section mappings, and no-README exceptions in one aggregated check. Provide targeted stale-content diagnostics identifying affected handbook sections, marker locations, new hashes, and re-read guidance; assert the retired footer hash is absent.	docs/handbook.html tests/test_repo_hygiene.py
Move README line-cap increases from a shared assertion and comment into an extensible per-raise ledger.	Define a fixed base cap of 1422 and sum validated tests/readme-cap.d/*.txt raises. Validate filenames, positive +N amounts, ISO dates, UTF-8 content, reasons, and non-file entries with path-specific diagnostics. Include the computed cap and ledger format in both normal output and over-cap or malformed-ledger failures.	tests/test_repo_hygiene.py
Add fixture-driven regression coverage for README segmentation, fingerprints, handbook markers, diagnostics, and cap-ledger parsing.	Cover fenced headings, subsections, empty preambles, byte preservation, CRLF behavior, and Git-compatible blob hashes. Exercise all handbook validation failure classes, including stale and partially updated markers, renamed or duplicate segments, malformed or misplaced markers, spacing conflicts, and mapping errors. Test absent, valid, CRLF, malformed, directory, and over-cap ledger cases without using repository files or Git.	tests/test_readme_sections.py
Update documentation of repository hygiene guards to describe per-section handbook hashes.	Replace the test docstring’s whole-README blob reference with the per-section hash model.	tests/test_agents_md_codes.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#519	Replace the handbook’s single whole-README blob hash with checks that record and validate the README sections each handbook part reads, so README edits no longer require rewriting one shared footer hash.	✅
#519	Replace the shared README line-cap assertion with a fixed base cap plus per-change ledger files, so each cap increase does not edit the same test line as other README PRs.	✅

Possibly linked issues

• docs/handbook.html: stop every README PR rewriting the handbook's README blob and line cap, so open README PRs stop conflicting with each other #519: The PR removes the shared footer hash, records hashes per handbook section, and makes each line-cap increase a separate file, directly addressing the issue.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sonarqubecloud]

Quality Gate passed

Issues
6 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud