Repository navigation
README: five naming families in the Layout block, and the rehearsal flag's Windows spelling (#68) - #70
Merged
Conversation
…lag's Windows spelling (#68) Brett Heap, 2026-09-06: "fix the two readme lines and merge on green too", after a designed reading of the README surfaced both. The Layout block's line for contracts/repository-naming.yaml still said four naming families; the naming section has said five since the FAMILY shape (v0.4, #16). One word. "Rehearse first, creating nothing" documented --local-remote-dir only on openRepoShape and setup.sh, so a Windows reader had no rehearsal. One sentence gives `py setup-project.py Atlas --org <your-org> --local-remote-dir .\rehearsal` and says what it still does over the network: run from a download it self-bootstraps a temporary clone of the standard first (checked in setup-project.py: is_shape_checkout false -> self_bootstrap), from a checkout nothing. The hygiene test that collects every `py <file>` run still holds: all three name setup-project.py. README 967 -> 970; cap moved with the dated rationale. 621 passed, 1 skipped. Lane: xfactory-2 (xFactory-2) Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Contributor
Author
|
@codex review |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
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 3 hours and 40 minutes by commenting @sourcery-ai review. Upgrade to get a review now.
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
Reviewer's GuideThis documentation-only change updates the README to accurately describe five naming families and adds the Windows spelling and behavior of the rehearsal flag for File-Level Changes
Assessment against linked issues
Possibly linked issues
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
There was a problem hiding this comment.
🟡 Changes recommended
The new Windows command is formatted as an inline code span that crosses a newline, which breaks Markdown rendering and undermines the documentation change.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Updates repository documentation to match current naming/layout concepts and to document the Windows spelling of the rehearsal flag, with a corresponding README length-cap adjustment in hygiene tests.
Changes:
- README: fix “four” → “five” naming families in the Layout block.
- README: document Windows usage of
--local-remote-dirviapy setup-project.py .... - Tests: bump the README line-count cap and add dated rationale.
File summaries
| File | Description |
|---|---|
| README.md | Corrects naming-family count and adds Windows rehearsal command documentation. |
| tests/test_repo_hygiene.py | Raises README length cap with rationale tied to the README edits. |
Review details
- Files reviewed: 2/2 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+209
to
+213
| checkout instead and nothing touches the network at all. On Windows the same | ||
| flag goes on the Python entry point — `py setup-project.py Atlas --org | ||
| <your-org> --local-remote-dir .\rehearsal` — which, run from a download, still | ||
| clones the standard into a temporary directory first, and from a checkout | ||
| clones nothing. What it leaves behind is `./Atlas` and three bare repositories |
Contributor
Author
There was a problem hiding this comment.
Taken, in 604bcf2: the command now sits on a line of its own inside one code span. (CommonMark does render a span across a soft line break — line endings become spaces — but a command a reader copies is better whole.) README 970 -> 971, cap moved.
Lane: xfactory-2 (xFactory-2)
Copilot's one finding on PR #70: the inline code span for the Windows rehearsal command broke across a soft line break. CommonMark renders a span across a soft break, but a command a reader copies belongs on one line, so the paragraph is reflowed to put the span on a line of its own. README 970 -> 971; cap moved. Lane: xfactory-2 (xFactory-2) Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
|
There was a problem hiding this comment.
🟡 Changes recommended
The new Windows-focused rehearsal paragraph still references ./Atlas and ./rehearsal, which is inconsistent/confusing for Windows readers and should be made platform-neutral or Windows-appropriate.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
- Files reviewed: 2/2 changed files
- Comments generated: 1
- Review effort level: Lite
| `py setup-project.py Atlas --org <your-org> --local-remote-dir .\rehearsal` — | ||
| which, run from a download, still clones the standard into a temporary | ||
| directory first, and from a checkout clones nothing. What it leaves behind is | ||
| `./Atlas` and three bare repositories in `./rehearsal`, both of which you can |
brettheap
added a commit
that referenced
this pull request
Sep 10, 2026
…he family workstation layout, --family, park/resume and the user commands, the workspace form; a guard that the page follows the README's outline (#89) (#90) * docs/handbook.html: the designed reading of the README at cbca5b4 — the family workstation layout, --family, park/resume and the user commands, the workspace form; a guard that the page follows the README's outline (#89) The page was cut from README.md at `c093813` (#69, PR #71) and #88 fixed one word in it. Everything the README gained in between was missing, so the designed page told a newcomer less than the file it is a reading of. This is the regeneration, at `cbca5b4`, in the page's own design and voice. WHAT THE PAGE GAINED - `#park`, a new section between "Keeping shape current" and "The degrade rule" — the whole of `## Carrying in-flight work to another workstation` (#80): the two root verbs and `ARGS=--dry-run`; `### park <Name>` and `resume <Name>`, from anywhere (#83) with the estate resolution, `--repo`, the fresh-machine `resume --workspace`, and what the two leave behind (including READ THE LINES, not the exit code); `### Who implements it, and what the record is` — the Speckit git extension rather than this repository, the person's record named once in `~/.agents/workspace.yaml`, `<user>-wip` with the home-org default and the opt-in `orgs:` map (#86), nothing under `worktrees/` ever committed, `resume` refusing on divergence, the family holder's dispatch into the WORKING clones, and native Windows parking nothing. One rail entry, `Park and resume`. - `#families` gained two `<h3>`s: "The workstation layout: a plain folder, and two copies of every member" (#79) — the plain `<Family>/`, the holder at `<Family>/<Family>`, `--into` as the PARENT and `--work-dir` as the override, `make siblings`, which copy you work in, and that nothing ever moves a checkout — and "The InkRouter example", whose five `family.py` commands and two trees are the README's current ones (the block it replaced still named `../InkRouter` as the holder). Plus the holder's own `make validate` and its COPY pin. - `#start` gained "Joining a family" (`--family <Family>`, and that standing in the folder needs no flag at all — AGENTS.md) and "What setup.sh actually runs", the seven-command flow including `mkdir -p <into>/<Family>` (#78), with the developer path from a checkout. The install step and the masthead's fastest path now say THREE commands, `unchanged` per file, and what `park` and `resume` are (#83). The rehearsal flag's Windows spelling is the README's own `py setup-project.py … --local-remote-dir .\rehearsal` (#70), replacing an aside that told the reader to go and read `--help`. - `#legs` links `<user>-wip` to where such a repository lives, and gained the paragraph a reader of `openDox` needs: a neutral product may elect the shape and be its own assembly root, `also_matches` recorded rather than thrown away. `#layout` lists `park` and `resume`. `#agents` gained the rule that a refused `park` or `resume` is never worked around with a reset, a stash or a force-push, and that `--workspace` is nobody else's flag to pass. FIDELITY. 39 code blocks on the page: 31 byte-identical to a README block (whole, or a contiguous run of its lines), 0 re-wrapped, 5 quoted from README prose, 2 from README inline code, 1 assembled by the page from three quoted commands (the masthead). Every one of the 13 GitHub anchors resolves to a real README or AGENTS.md heading, all 27 in-page hrefs resolve to an id on the page, and the file still parses with `html.parser` with every tag balanced: one file, inline CSS and one inline script, one Google Fonts link with real fallback stacks, no images and no other network call. THE GUARD. `tests/test_repo_hygiene.py::test_the_handbook_follows_the_readmes_outline` ties the two files together, because nothing did: an explicit `README_HEADING_TO_HANDBOOK_ID` maps every `## ` heading of README.md to the id of the page element that carries it, so a new README section with no entry fails NAMING THE HEADING and a heading deliberately folded into a neighbour is a named decision; `HANDBOOK_SECTION_WITHOUT_A_README_H2` accounts for the four page sections that are not a README `## ` at all, so a page section cannot become unexplained. And the page names the README commit it is a reading of, exactly once, whose README must be byte-identical to the one in the tree — `git diff <sha> -- README.md`, against the working tree, so the page goes stale the moment the README changes rather than one commit later. That last check is skipped, and only that one, when the named commit is not in the clone: a `fetch-depth: 1` CI checkout has one commit and the object is absent there, while the outline checks are tree-only and run everywhere. Evidence: `python3 -m pytest tests/test_repo_hygiene.py -q` 46 passed; `python3 -m pytest tests -q` 889 passed, 1 skipped (`SHAPE_MEDXEHR_CLONE` is unset — pre-existing and unrelated). The five ways the new guard can fail were each exercised in a throwaway clone. Docs and one test only; no README, script, template or workflow change, and both size caps are untouched. Lane: xfactory-2 (xFactory-2) Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * tests.yml: fetch full history so the handbook's staleness check bites in CI (#89) Ruled by Brett Heap on 2026-09-10: *set fetch-depth 0 so the staleness check bites in CI.* `test_the_handbook_follows_the_readmes_outline` compares README.md against the commit `docs/handbook.html` says it is a reading of, which needs that commit's OBJECT present. `actions/checkout`'s default `fetch-depth: 1` fetches one commit, so the object was absent and that one check skipped itself: green in CI, red only on the machine where the page would be regenerated, which is the wrong way round. All three jobs — `tests`, `tests-windows`, `tests-macos`, the only three `actions/checkout` steps in the file — now check out with `fetch-depth: 0`, and each says why in a comment naming the test. The test's BEHAVIOUR is unchanged: the "skipped when the named commit is not in this clone" branch stays, because a `git clone --depth 1` still hits it and a failure about the clone is not a failure about the page. Only its docstring moves, to say that CI is no longer such a clone. Evidence: `python3 -m pytest tests/test_repo_hygiene.py -q` 46 passed (with tests/test_windows_paths.py, 84 passed). The workflow parses under PyYAML and compares equal to HEAD's parse with the three checkout `with:` blocks removed — nothing else in the file moved. No actionlint on this machine; CI's own actionlint step lints `templates/assembly-root/.github/workflows/validate.yml` only, which is untouched. Lane: xfactory-2 (xFactory-2) Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Lane: xfactory-2 (xFactory-2)
Claim: #68 (claim in the issue body)
Closes #68.
What this changes
Two README lines a designed reading of the page surfaced. Brett Heap, 2026-09-06, in session: "fix the two readme lines and merge on green too".
contracts/repository-naming.yamlhad not caught up. One word.--local-remote-dironly onopenRepoShapeandsetup.sh;setup-project.pytakes the same flag (No native Windows path: setup.sh and the openRepoShape command are bash; a Python entry point, Windows CI, and the README path #49's parity, One definition for the two entry points: setup.sh becomes a shim over setup-project.py (follow-up of #49) #50's one definition) but the README never said so, so a Windows reader had no rehearsal. One sentence givespy setup-project.py Atlas --org <your-org> --local-remote-dir .\rehearsaland says, honestly, what it still does over the network: run from a download it self-bootstraps a temporary clone of the standard first; from a checkout, nothing. Checked againstsetup-project.py's self-bootstrap before writing.README hygiene cap moved by the exact lines added, rationale beside it. Nothing else.
Evidence
Linux:
python3 -m pytest tests -q— 621 passed, 1 skipped (main atc093813; the skip is the MedxEHR-backed plan test,SHAPE_MEDXEHR_CLONEunset). README 967 → 970, cap moved with the rationale beside it. macOS and Windows: thetests-macosandtests-windowsjobs on this PR. Docs only; no script changes.Merge word: Brett Heap, 2026-09-06, "fix the two readme lines and merge on green too".
🤖 Generated with Claude Code
Summary by Sourcery
Align the README with the current repository layout and provide complete Windows instructions for rehearsing project setup.
Enhancements:
Documentation:
Tests: