README.md and the handbook: the sentences #566, #572 and #573 leave false or incomplete (an ambiguous record that arrives answered, the spec mount's CONTRACTS_DIR, a second setup run refused at the plan)

One README and handbook pull request, with the wording those PRs' bodies hold.

From the checklist triage of 2026-10-15; Brett Heap approved its recommendations at 2026-10-15T16:49:38Z. One pull request covers the lines below.

Lands after: #566, #572 and #573.

Decision applied: the triage's D7: one README and handbook PR after #566, #572 and #573 land, instead of a README edit in each.

Lines

L2-50: README "Ambiguous is an answer" says every ambiguous entry gets leg: null and blocks execute; contracts/path-classification.yaml: a source's own single-repository.yaml is asked drop or root, drop by default, under its own rule, so adopt-project.py plan no longer asks a record no leg reads the spec, code or root question (#528) #566 adds default: drop. Where: README.md:777-779; docs/handbook.html (§ adopt, marker :1198). Effort S; all. On main 26c1600: On contracts/path-classification.yaml: a source's own single-repository.yaml is asked drop or root, drop by default, under its own rule, so adopt-project.py plan no longer asks a record no leg reads the spec, code or root question (#528) #566's head 19ffe4a, rule ambiguous-single-repository-record is leg: ambiguous with default: drop, and plan writes leg: drop, which execute takes; README.md:777-779 on main still says "Those entries get leg: null … execute refuses while any remain", and contracts/path-classification.yaml: a source's own single-repository.yaml is asked drop or root, drop by default, under its own rule, so adopt-project.py plan no longer asks a record no leg reads the spec, code or root question (#528) #566 changes only AGENTS.md. (source)

Rides along (backlog; tick it here if the same change covers it)

L2-41: README's "If it fails part-way" box gives no word that the plan refuses a second run first. Where: README.md:457-458; docs/handbook.html:1040. Effort S; all. On main 26c1600: The sentence "A second run is refused while they exist" is unchanged at README.md:457-458 and stays true after family.py and scaffold-project.py: --dry-run asks the real run's own question about existing remotes, so family-remote-exists and scaffold-remote-exists come at the plan, and a missing gh is gh-not-found, not a traceback (#537) #573 (whose head c6b32d7 does not touch README), so this is a precision gap; it rides with the README cluster (ct461x459-D1). (source)
L2-51: README says the adopted Makefile exports $(CURDIR)/spec/contracts, true of the default mount only after adopt-project.py: the Makefile block execute appends and the cross-leg follow-up name each leg where the plan mounts it, so --spec-path legs/spec exports a CONTRACTS_DIR that exists and a nested --code-path gets the right ../ path (#522) #572. Where: README.md:766-767. Effort S; all. On main 26c1600: Main still hardcodes CONTRACTS_DIR ?= $(CURDIR)/spec/contracts (scripts/shape_materialize.py:988), so README matches main today; adopt-project.py: the Makefile block execute appends and the cross-leg follow-up name each leg where the plan mounts it, so --spec-path legs/spec exports a CONTRACTS_DIR that exists and a nested --code-path gets the right ../ path (#522) #572 (head 22ce69b) does not touch README, and the line sits under "### The worked example: MedxEHR" (README.md:752), which used the default mount, so it is a precision gap like v1.1.0's Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459.c6147965882.2. (source)

Each line above is marked → this issue on its tracking issue. Tick it there too when this closes.

The lines as written on the tracking issues

L2-50 (nit, docs; README.md, #566 re-verify): README's "Ambiguous is an answer" paragraph has an exception it does not state: a source's own single-repository.yaml record now arrives as leg: drop.

README.md:776-779 at 19ffe4a says entries the policy cannot call "get leg: null, review_required: true and the QUESTION; execute refuses while any remain, because an unanswered question is never an implicit root". After contracts/path-classification.yaml: a source's own single-repository.yaml is asked drop or root, drop by default, under its own rule, so adopt-project.py plan no longer asks a record no leg reads the spec, code or root question (#528) #566 the record gets leg: drop, its rule's default, with review_required: true and its question, and execute takes it as written.

contracts/path-classification.yaml: a source's own single-repository.yaml is asked drop or root, drop by default, under its own rule, so adopt-project.py plan no longer asks a record no leg reads the spec, code or root question (#528) #566's PR body holds the words (impl528-adopt-single-repo/pr-body.md, "README follow-up"): "One question comes answered: a source's own single-repository.yaml record is written leg: drop, its rule's default, still review_required: true with its question beside it, and execute drops it unless a person writes root." The paragraph stays true without them but is incomplete. The hold on 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 over: 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) #551 landed it (2026-10-14T23:19:25Z).

README is at its cap (1427 lines on main 2e6c6fa, which is 1422 plus 5 from tests/readme-cap.d/550.txt), so the sentence needs its own tests/readme-cap.d/528.txt, and the handbook section that mirrors this README section needs its mirror sentence and its marker moved. The sentence is true only once contracts/path-classification.yaml: a source's own single-repository.yaml is asked drop or root, drop by default, under its own rule, so adopt-project.py plan no longer asks a record no leg reads the spec, code or root question (#528) #566 lands, so make the change with or after it.

— #461, comment

L2-41 (nit, docs; README.md, #573 review): README's "If it fails part-way" box still says "A second run is refused while they exist", with no word that the plan refuses it first once #573 lands.

README.md:448-460 at 0c81423 (the sentence is at :457-458). family.py and scaffold-project.py: --dry-run asks the real run's own question about existing remotes, so family-remote-exists and scaffold-remote-exists come at the plan, and a missing gh is gh-not-found, not a traceback (#537) #573's PR body holds suggested wording, held until 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 landed: "A second run is refused while they exist, at the plan in step (5), before the yes: the plan is the scaffold's --dry-run, which asks whether each of the three already exists (family.py init --dry-run and scaffold-project.py --dry-run exit 0 without asking whether the remotes already exist #537)."

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) #551 (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 on main, so the hold is over. The sentence is true only after family.py and scaffold-project.py: --dry-run asks the real run's own question about existing remotes, so family-remote-exists and scaffold-remote-exists come at the plan, and a missing gh is gh-not-found, not a traceback (#537) #573 lands, so a README change belongs with or after family.py and scaffold-project.py: --dry-run asks the real run's own question about existing remotes, so family-remote-exists and scaffold-remote-exists come at the plan, and a missing gh is gh-not-found, not a traceback (#537) #573. A README change also has to follow 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) #551's rule for the handbook's recorded hash.

Direction: make the README change after family.py and scaffold-project.py: --dry-run asks the real run's own question about existing remotes, so family-remote-exists and scaffold-remote-exists come at the plan, and a missing gh is gh-not-found, not a traceback (#537) #573 lands, with the wording above.

— #461, comment

L2-51 (nit, docs; README.md, #572 re-verify): README says the root Makefile exports CONTRACTS_DIR ?= $(CURDIR)/spec/contracts, which is true of the default mount only.

README.md:765-766 at 22ce69b (:766-767 on main 2e6c6fa). After adopt-project.py: the Makefile block execute appends and the cross-leg follow-up name each leg where the plan mounts it, so --spec-path legs/spec exports a CONTRACTS_DIR that exists and a nested --code-path gets the right ../ path (#522) #572 the adopted Makefile exports the path where the plan mounts the spec leg, for example $(CURDIR)/legs/spec/contracts for --spec-path legs/spec.

adopt-project.py: the Makefile block execute appends and the cross-leg follow-up name each leg where the plan mounts it, so --spec-path legs/spec exports a CONTRACTS_DIR that exists and a nested --code-path gets the right ../ path (#522) #572's PR body suggests (impl522-adopt-leg-paths/pr-body.md, "README follow-up"): "the root Makefile it materializes exports CONTRACTS_DIR, pointing at the contracts/ of the spec leg where the plan mounts it ($(CURDIR)/spec/contracts by default)". 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) #551 (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) has landed, so the hold is over. Make the change with or after adopt-project.py: the Makefile block execute appends and the cross-leg follow-up name each leg where the plan mounts it, so --spec-path legs/spec exports a CONTRACTS_DIR that exists and a nested --code-path gets the right ../ path (#522) #572, and give it its own tests/readme-cap.d/ file if the line count grows.

The pinned AGENTS-shape.md says the same thing (L2-33 on Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459, whose "after bootstrap.py: a leg detached off the pin is left where it is and said, so a commit made there is no longer stranded when its branch is already at the pin, the not moving an existing branch line names where the checkout is, and bump-leg.py and AGENTS-shape.md say "or says why not" (#533) #556" is moot: bootstrap.py: a leg detached off the pin is left where it is and said, so a commit made there is no longer stranded when its branch is already at the pin, the not moving an existing branch line names where the checkout is, and bump-leg.py and AGENTS-shape.md say "or says why not" (#533) #556 landed as 64fc9a8). docs/release-notes/v1.0.0.md:374 lists the old behaviour as a known limit and stays as written.

— #461, comment

CLAIMED — lane openRepoShape-2, session 81650e29-c906-4fe8-96c9-55580bfe0c44@Eagle, 2026-10-15T18:23:36Z, for #606

Logged in lanes/log/openRepoShape-2.md at 3b628e99c2d6dcd8dfb26e9cc09339c89abe9c5b.

The three reads (lane-collision-protocol Rule 1):

1. existing `CLAIMED —` comments on opensoft/openRepoShape#606:
   none
2. `gh pr list --repo opensoft/openRepoShape --state all --search "#606"`, kept where the row or its body names `#606`:
   none
3. `git ls-remote --heads git@github.com:opensoft/openRepoShape` branches naming `606` as a whole token:
   none

Merge origin/main 396c0ff into fix/606-readme-followups: #598's insta…

tests: a tests-git-bash job runs the launcher's and install.sh's suit…

Merge origin/main bf7b19b into fix/606-readme-followups: #596's Git B…

README.md and the handbook: a Free-plan project keeps its CI secrets …

README.md and the handbook: a public root takes organisation secrets …

README.md and the handbook: a public root's org secrets are registere…

(lane openRepoShape-2, 2026-10-16T12:35:40Z)

One more rider for this issue: L2-66 from #461 (DB6). From the checklist triage of 2026-10-15, batch 3; Brett Heap approved its recommendations at 2026-10-16T12:14:51Z. Its DB6 adds this line to this issue's "Rides along".

Rides along (backlog; tick it here if the same change covers it)

L2-66: README's "If the legs are private" paragraph ties the advice to set REPOSITORY secrets to private legs, but what decides it is whether the assembly root is private or internal. (source)

It closes with #627. #627's round of 2026-10-16 (333095c, in head 83ca2db) rewrites that sentence by the root's visibility: it now reads "as REPOSITORY secrets on the assembly root when it is private or internal and the organisation is on the GitHub Free plan". The line is marked → #606 on #461. Tick it there too when this closes.

The line as written on #461

L2-66 (nit, docs; README.md, #602 review): README's "If the legs are private" paragraph ties the advice to set REPOSITORY secrets to private legs, but what decides it is whether the assembly root is private or internal.

README.md:510-514 at 55faad2: "If the legs are private, CI needs a credential to fetch them: a GitHub App ... as REPOSITORY secrets on the GitHub Free plan, where organisation secrets do not reach private repositories". The validate workflow runs in the root, and on the Free plan an organisation secret reaches a public repository only. So private legs under a public root can take the credential as an organisation secret, and a private root needs repository secrets. The assembly root's own README says it by repository (templates/assembly-root/README.md:79-83), and so does README.md:628-631.

adopt-project.py and scaffold-project.py: the Free-plan secrets hint goes by the assembly root's own visibility on GitHub and names the root as its reason, so a public source adopted with private legs is no longer told its organisation secrets resolve to EMPTY (#602) #621's body holds suggested words (impl602-free-plan-hint-root/pr-body.md, "README follow-up"): "as REPOSITORY secrets on the assembly root when it is private or internal and the organisation is on the GitHub Free plan, where organisation secrets reach only public repositories". README.md and the handbook: the sentences #566, #572 and #573 leave false or incomplete (an ambiguous record that arrives answered, the spec mount's CONTRACTS_DIR, a second setup run refused at the plan) #606 (README and handbook) does not list this line, and adopt-project.py and scaffold-project.py: the Free-plan secrets hint goes by the assembly root's own visibility on GitHub and names the root as its reason, so a public source adopted with private legs is no longer told its organisation secrets resolve to EMPTY (#602) #621 names README.md and the handbook: the sentences #566, #572 and #573 leave false or incomplete (an ambiguous record that arrives answered, the spec mount's CONTRACTS_DIR, a second setup run refused at the plan) #606 as its home, so README.md and the handbook: the sentences #566, #572 and #573 leave false or incomplete (an ambiguous record that arrives answered, the spec mount's CONTRACTS_DIR, a second setup run refused at the plan) #606 needs to take it or it stays here.

The paragraph is in README's ## Starting a project in a new organisation section, so the change follows 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) #551's hash step for that section's seven handbook markers (for example docs/handbook.html:475). README is at its line cap, so the edit has to keep the line count or take its own tests/readme-cap.d/ file. The handbook has no twin of this sentence.

— #461, comment

Merge origin/main (de92614) into l3-563-docs

README.md, the handbook and the v1.1.0 notes: the adopted repository …

Navigation Menu

Repository navigation

README.md and the handbook: the sentences #566, #572 and #573 leave false or incomplete (an ambiguous record that arrives answered, the spec mount's `CONTRACTS_DIR`, a second setup run refused at the plan) #606

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

README.md and the handbook: the sentences #566, #572 and #573 leave false or incomplete (an ambiguous record that arrives answered, the spec mount's CONTRACTS_DIR, a second setup run refused at the plan) #606

Description

Activity

brettheap commented on Oct 15, 2026

brettheap commented on Oct 16, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

README.md and the handbook: the sentences #566, #572 and #573 leave false or incomplete (an ambiguous record that arrives answered, the spec mount's `CONTRACTS_DIR`, a second setup run refused at the plan) #606