tests/test_repo_hygiene.py and docs/handbook.html: each handbook section records the hash of every README section it reads, and README.md's line cap is 1422 plus one file per raise in tests/readme-cap.d/, so two README pull requests no longer conflict on the footer's one blob or the cap's one line, and a stale page names exactly which sections to re-read (#519)

.github/workflows/tests.yml

@@ -30,8 +30,10 @@ jobs:
       # this suite might grow, even though it no longer matters for
       # `tests/test_repo_hygiene.py::test_the_handbook_follows_the_readmes_
       # outline` itself — #91 moved that check from diffing against a named
-      # commit to hashing the working tree's own README.md, which needs no
-      # history at all and runs the same in a shallow clone.
+      # commit to hashing the working tree's own README.md, and #519 to one
+      # hash per README `## ` section, each recorded by the handbook section
+      # that reads it. Neither needs history, and both run the same in a
+      # shallow clone.
       - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
         with:
           fetch-depth: 0
@@ -152,8 +154,9 @@ jobs:
       # The SAME two commits the ubuntu job pins. Two jobs resolving two
       # versions of the same action is the drift this repository spends a
       # README section on. `fetch-depth: 0` for the reason that job gives —
-      # kept as a generally useful default now that #91 stopped the
-      # handbook's own staleness check from needing history at all.
+      # kept as a generally useful default now that #91 and #519's
+      # per-section hashes stopped the handbook's own staleness check from
+      # needing history at all.
       - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
         with:
           fetch-depth: 0
@@ -224,8 +227,9 @@ jobs:
       # The SAME two commits the other two jobs pin. Three jobs resolving
       # three versions of one action is the drift this repository spends a
       # README section on. `fetch-depth: 0` for the reason the ubuntu job
-      # gives — kept as a generally useful default now that #91 stopped the
-      # handbook's own staleness check from needing history at all.
+      # gives — kept as a generally useful default now that #91 and #519's
+      # per-section hashes stopped the handbook's own staleness check from
+      # needing history at all.
       - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
         with:
           fetch-depth: 0

docs/handbook.html

@@ -468,7 +468,16 @@
   </nav>
 
   <main>
-    <header class="masthead">
+    <header class="masthead" id="masthead">
+
+      <!-- reads README.md § preamble: blob ddadd23a162129f7e64fefce899105661440c05c -->
+
+      <!-- reads README.md § Starting a project in a new organisation: blob 4e4093125221b1ce5d2369613635d189b461d36f -->
+
+      <!-- reads README.md § The three legs: blob 6ebed796b7b135151ff3ca2c5280fb501e001acc -->
+
+      <!-- reads README.md § The double pin, and the lockstep invariant: blob 57fffa08ffad5476f8eae73dd3e8494a02e050c9 -->
+
       <div class="masthead-top">
         <p class="eyebrow"><span class="on">Ratified standard</span> &middot; Apache-2.0</p>
         <h1>openRepoShape</h1>
@@ -548,6 +557,9 @@ <h4>The fastest path &mdash; macOS, Linux, WSL2</h4>
     </header>
 
     <section id="confers">
+
+      <!-- reads README.md § preamble: blob ddadd23a162129f7e64fefce899105661440c05c -->
+
       <div class="card confers">
         <h4>The one thing to read before electing it</h4>
         <p><strong>The shape is elective and confers nothing.</strong> Electing it changes no gate,
@@ -596,6 +608,9 @@ <h4>The one thing to read before electing it</h4>
     </section>
 
     <section id="start">
+
+      <!-- reads README.md § Starting a project in a new organisation: blob 4e4093125221b1ce5d2369613635d189b461d36f -->
+
       <p class="eyebrow">Setup</p>
       <h2>Start here</h2>
       <p>Pick your machine. Each panel says what the machine needs, how the tool offers to supply
@@ -1005,6 +1020,9 @@ <h4>What you have afterwards &mdash; the same on every platform</h4>
     </section>
 
     <section id="partway">
+
+      <!-- reads README.md § Starting a project in a new organisation: blob 4e4093125221b1ce5d2369613635d189b461d36f -->
+
       <p class="eyebrow">Setup</p>
       <h2>If it fails part-way</h2>
       <p>Nothing is created before the typed <code>yes</code>: the preflight, the naming check and
@@ -1037,6 +1055,11 @@ <h2>If it fails part-way</h2>
     </section>
 
     <section id="ci">
+
+      <!-- reads README.md § Starting a project in a new organisation: blob 4e4093125221b1ce5d2369613635d189b461d36f -->
+
+      <!-- reads README.md § The three legs: blob 6ebed796b7b135151ff3ca2c5280fb501e001acc -->
+
       <p class="eyebrow">Setup</p>
       <h2>Reading private legs in CI</h2>
       <p>The <code>validate</code> workflow&rsquo;s default <code>GITHUB_TOKEN</code> cannot clone a
@@ -1090,6 +1113,11 @@ <h2>Reading private legs in CI</h2>
     </section>
 
     <section id="legs">
+
+      <!-- reads README.md § Starting a project in a new organisation: blob 4e4093125221b1ce5d2369613635d189b461d36f -->
+
+      <!-- reads README.md § The three legs: blob 6ebed796b7b135151ff3ca2c5280fb501e001acc -->
+
       <p class="eyebrow">Reference</p>
       <h2>The three legs, and naming</h2>
       <div class="tw">
@@ -1165,6 +1193,9 @@ <h2>The three legs, and naming</h2>
     </section>
 
     <section id="adopt">
+
+      <!-- reads README.md § Adopting an existing repository: blob a768fa1b4fe592c0a9dde7c6abb415e8af37d99c -->
+
       <p class="eyebrow">Reference</p>
       <h2>Adopting an existing repository</h2>
       <p>A repository that already exists is converted <strong>in place</strong>. It KEEPS ITS NAME,
@@ -1212,6 +1243,9 @@ <h2>Adopting an existing repository</h2>
     </section>
 
     <section id="families">
+
+      <!-- reads README.md § Families: a holder for projects that ship separately: blob 89ef0ab5ec8801ab69c7b1fea30a6b2e273f27e2 -->
+
       <p class="eyebrow">Reference</p>
       <h2>Families: a holder for projects that ship separately</h2>
       <p>A <strong>family</strong> is a repository that pins other projects&rsquo; <strong>assembly
@@ -1315,6 +1349,11 @@ <h3>The InkRouter example</h3>
     </section>
 
     <section id="doublepin">
+
+      <!-- reads README.md § Starting a project in a new organisation: blob 4e4093125221b1ce5d2369613635d189b461d36f -->
+
+      <!-- reads README.md § The double pin, and the lockstep invariant: blob 57fffa08ffad5476f8eae73dd3e8494a02e050c9 -->
+
       <p class="eyebrow">Reference</p>
       <h2>The double pin, and the lockstep invariant</h2>
       <p>Each leg is pinned TWICE, in the same commit: by the <strong>gitlink</strong> git records
@@ -1376,6 +1415,9 @@ <h3>Advancing a leg</h3>
     </section>
 
     <section id="copied">
+
+      <!-- reads README.md § Bootstrap is COPIED into the project, not fetched: blob 41f2c88376772ca41ab2fe05668337a4eb2a7bd5 -->
+
       <p class="eyebrow">Reference</p>
       <h2>Bootstrap is COPIED into the project, not fetched</h2>
       <p><code>scripts/bootstrap.py</code>, the validators and <code>AGENTS-shape.md</code> are
@@ -1407,6 +1449,9 @@ <h2>Bootstrap is COPIED into the project, not fetched</h2>
     </section>
 
     <section id="current">
+
+      <!-- reads README.md § Keeping a project's shape current: blob 408c49c1603699fbe7ae74fa16c6330ec7860c10 -->
+
       <p class="eyebrow">Reference</p>
       <h2>Keeping a project&rsquo;s shape current</h2>
       <p>The copies are the trade: a project runs its own gate, which never consults this standard
@@ -1446,8 +1491,10 @@ <h2>Keeping a project&rsquo;s shape current</h2>
         away. Once a human merges a <code>shape/</code> copy and removes it, <code>check</code> calls its row <code>merged-away</code> and <code>apply</code> drops the row.</li>
         <li>A file the standard ADDS later is reported as <code>upstream-added</code> and counts as
         something to do. <code>apply</code> writes NONE of them unless <code>--add &lt;path&gt;</code>
-        names one, per file; <code>--add</code> refuses a path that is already pinned, one the
-        target&rsquo;s lists do not name, and one the root ALREADY has a file at.</li>
+        names one, per file, and names each file it adds in the line-ending block of an adopted
+        root&rsquo;s own <code>.gitattributes</code> when that file carries #471&rsquo;s block;
+        <code>--add</code> refuses a path that is already pinned, one the target&rsquo;s lists do
+        not name, and one the root ALREADY has a file at.</li>
       </ul>
       <p><code>--upstream</code> takes a path to a clone (offline) or an <code>owner/repo</code> it
       bare-clones itself; it defaults to the repository the pin names. <code>make bootstrap</code>
@@ -1460,6 +1507,9 @@ <h2>Keeping a project&rsquo;s shape current</h2>
     </section>
 
     <section id="doctor">
+
+      <!-- reads README.md § Keeping a project's shape current: blob 408c49c1603699fbe7ae74fa16c6330ec7860c10 -->
+
       <p class="eyebrow">Reference</p>
       <h2>Is this repository compliant? <code>openRepoShape --doctor</code></h2>
       <p>Five commands answered that question and the order of them was tribal knowledge.
@@ -1591,6 +1641,11 @@ <h2>Is this repository compliant? <code>openRepoShape --doctor</code></h2>
     </section>
 
     <section id="park">
+
+      <!-- reads README.md § Starting a project in a new organisation: blob 4e4093125221b1ce5d2369613635d189b461d36f -->
+
+      <!-- reads README.md § Carrying in-flight work to another workstation: blob b84512ad39c09085dfe6bf7ea694017f5e28c1dd -->
+
       <p class="eyebrow">Reference</p>
       <h2>Carrying in-flight work to another workstation</h2>
       <p>Two verbs on the assembly root, for the day the machine your half-finished work is on is
@@ -1724,6 +1779,9 @@ <h3>Who implements it, and what the record is</h3>
     </section>
 
     <section id="degrade">
+
+      <!-- reads README.md § The degrade rule: blob e28bf2cdbbee43509e2db13bdd3c2a10ed067276 -->
+
       <p class="eyebrow">Reference</p>
       <h2>The degrade rule</h2>
       <p><code>make bootstrap</code> looks for a wallet review-authority register at
@@ -1738,6 +1796,9 @@ <h2>The degrade rule</h2>
     </section>
 
     <section id="layout">
+
+      <!-- reads README.md § Layout of this repository: blob c8be0af4910debc70cdd1a1f41c6f984caa65794 -->
+
       <p class="eyebrow">Reference</p>
       <h2>Layout of this repository</h2>
       <dl class="files">
@@ -1851,6 +1912,9 @@ <h2>For AI assistants</h2>
     </section>
 
     <footer id="licence">
+
+      <!-- reads README.md § Licence: blob 57e2469bc2ed7fca4cb2543ab2c38e4e061a0e22 -->
+
       <p>Licence <strong>Apache-2.0</strong>. See <code>LICENSE</code> in the repository.</p>
       <p><a href="https://github.com/opensoft/openRepoShape#readme">github.com/opensoft/openRepoShape</a></p>
       <p class="meta">First cut from README.md at c093813 (#71); regenerated at cbca5b4 (#89);
@@ -1886,10 +1950,12 @@ <h2>For AI assistants</h2>
       adoption&rsquo;s <code>--project</code> as the source&rsquo;s own name, added (#499); the
       <code>merged-away</code> verdict, whose row <code>apply</code> drops, added (#502); the
       line-ending block an adoption appends to a root <code>.gitattributes</code> the source keeps,
-      and its verification as the source&rsquo;s bytes plus that block, added (#471) &mdash; a page
-      cannot name the commit that contains it, and the blob below is the fact a test checks.
-      README.md blob f3b378dc5704de79ee63972d0ea0be14dc693209. Every command, flag, exit code
-      and file name on this page is quoted from that README and from AGENTS.md.</p>
+      and its verification as the source&rsquo;s bytes plus that block, added (#471). That list is
+      history, and it ends there.</p>
+      <p class="meta">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 (#519). Every command, flag, exit code and file
+      name on this page is quoted from the README and from AGENTS.md.</p>
     </footer>
   </main>
 </div>

tests/test_agents_md_codes.py

@@ -16,8 +16,8 @@
 
 This is the guard, in both directions, and it is the kind this repository
 already keeps for other copied facts: the Windows two-liner's file names, the
-handbook's README blob, and `docs/cli.md` against `--help`
-(`tests/test_cli_reference.py`).
+handbook's hash of each README section it reads, and `docs/cli.md` against
+`--help` (`tests/test_cli_reference.py`).
 
 WHICH NAMES. Every backticked token in the document whose whole text matches
 `CODE_SHAPE` (`[a-z]+(-[a-z0-9]+)+`), never a pattern read out of a refusal