[brettheap]

Lane: openreposhape-5 (openRepoShape-5)
Claim: #341 (comment)

From anywhere but a checkout of the standard (a downloaded setup.sh, curl … | bash -s -- --help, a git archive extraction), setup.sh --help went down section 0 like any other run. It cloned the public upstream before printing a word, died with git's exit 128 offline, and otherwise printed the CLONE's setup-project.py usage. scripts/render-cli-reference.py inherited all of it in such a tree: every rendering, --check included, reached GitHub and then documented upstream's flags under that tree's setup.sh heading. The clone attempts were reproduced on 87d2eb7, offline (GIT_ALLOW_PROTOCOL=file); what the generator renders when that clone succeeds is read from the code, not reproduced:

	base 87d2eb7	this branch
lone setup.sh, bash setup.sh --help	(0) self-bootstrap, git clone --quiet --depth 1 -- https://github.com/opensoft/openRepoShape.git <tmp>, fatal: transport … not allowed, exit 128	the shim's own text, exit 0, no clone (GIT_TRACE), no temporary directory
same, OPENREPOSHAPE_REPO=<checkout>	a local clone, then the clone's usage: setup-project.py …	the shim's own text, no clone
bash -s -- -h < setup.sh	the clone, exit 128	the shim's own text, exit 0
render-cli-reference.py --check in a copy with no .git	tried the clone (stopped only by GIT_ALLOW_PROTOCOL, surfacing as setup.sh --help exited 128)	refuses, naming the tree, exit 2, no clone

What changed

setup.sh

• Section 0's one scan of the command line now also notes -h and --help before the first --.
• The shim answers them first: before the $OPENREPOSHAPE_REPO guard, before mktemp, before git clone. That is where setup-project.py answers them: before it looks at anything.
• The text says:
  • this is the bash front door to setup-project.py;
  • any other run from here first clones the standard into a temporary directory, from $OPENREPOSHAPE_REPO or, when that is unset or empty, https://github.com/opensoft/openRepoShape.git;
  • the one flag list is python3 setup-project.py --help, which answers with no network from a checkout or from that one file downloaded on its own, and docs/cli.md in the repository.
• It lists no flag, so One definition for the two entry points: setup.sh becomes a shim over setup-project.py (follow-up of #49) #50's one --help still holds.
• The default is now one constant, DEFAULT_SHAPE_REPO (the name setup-project.py gives it), read by both the clone and the help. The help never prints the variable's value.
• Inside a checkout nothing changes: the shim still execs setup-project.py before section 0 reads a word.
• The header comment no longer says the shim "parses nothing". It now says the shim parses nothing of the RUN, and names the three things section 0 reads. The comment above the scan no longer says the scan never decides what the run does: the first two reads only decide whether a temporary directory is removed and whether a ref is checked out, and the third decides whether there is a run at all.

scripts/render-cli-reference.py

• require_a_checkout() asks setup.sh's own is_shape_checkout question: git -C <tree> rev-parse --show-toplevel, and scaffold-project.py plus contracts/repository-naming.yaml at that top level.
• It also asks that the top level IS the tree (os.path.samefile). A copy nested inside another checkout passes the shim's probe, and its setup.sh --help would print that checkout's usage.
• It is called in main(), before the no-bash logic, and at the top of render(), which tests/test_cli_reference.py calls directly. The refusal names the tree and says to run it in a git clone, exit 2.
• It reads git's answer the way the shim's $(...) does: os.fsdecode(...).rstrip("\r\n"), so a checkout whose path ends in a space, or is not UTF-8, is a checkout here too.
• Every child now runs under GIT_ALLOW_PROTOCOL=file, so a regression fails closed.
• Inside a checkout neither measure changes a byte of a rendered help block. --check was [ok] before, and [ok] after regenerating.

Docs

• README.md: "python3 setup-project.py --help and, from a checkout, setup.sh --help list every flag, this one included. From a download, setup.sh --help clones nothing and lists none: it names setup-project.py --help … and docs/cli.md". That is +3 lines against main; the README cap in tests/test_repo_hygiene.py goes 1419 -> 1422, with its dated paragraph. openRepoShape --help is not the subject any more, because it names eight of setup-project.py's fourteen flags besides --help. § What setup.sh does no longer gives the shim a line count ("about seventy lines of code"; it was 93 before this change and is 122 now), here, in the handbook and in setup-project.py's docstring.
• docs/handbook.html: the page's copy of that sentence and of the shim's description, the footer's history clause, and the new README blob (5465d135…).
• openRepoShape --help: its one sentence "./setup.sh --help prints setup-project.py's usage, which lists them all" was false from a download. It now names python3 setup-project.py --help, and ./setup.sh --help "in a checkout of this standard".
• docs/cli.md is regenerated: a note under setup.sh saying what --help does outside a checkout, and that openRepoShape sentence.
• tests/test_setup_sh.py: test_no_test_here_depends_on_gh_being_authenticated's docstring is made true.

Decisions (the coordinator's; Brett may reverse)

1. The shim's answer outside a checkout is option (a), with no flag list. It is a short text of its own, exit 0, with no clone, no network and no temporary directory. Inside a checkout --help is still setup-project.py's.
   • -h is treated like --help, because setup-project.py reads both.
   • Only arguments before -- count. setup.sh <Project> -- --help is still a run, whose scaffold is asked for ITS help.
   • Known false positives (written into the shim's comment): runs setup-project.py would refuse anyway, such as --org --help or --wat --help, get the text and exit 0 instead of exit 2. Nothing is created either way.
   • One known false negative: --visibility -- --help, where -- is a value, still clones as before. Fixing it would need the value-flag table in bash, which is the second parser One definition for the two entry points: setup.sh becomes a shim over setup-project.py (follow-up of #49) #50 removed.
2. Whose help. The shim's text is its own, so it names no clone URL or ref. No path that prints a usage is left unattributed. setup.sh <P> -- --help prints the clone's scaffold usage under the (0) self-bootstrap clone line and checkout: <tmp>, which already say whose it is.
3. The generator gets both measures: the checkout refusal and GIT_ALLOW_PROTOCOL=file.
4. Docs: README, the handbook's reading of it, the shim's header, the test docstring and openRepoShape --help's sentence, with docs/cli.md regenerated.
5. The One definition for the two entry points: setup.sh becomes a shim over setup-project.py (follow-up of #49) #50 guard is changed on purpose. tests/test_setup_project_py.py::test_setup_sh_parses_no_flags_of_its_own refused any --help in the shim's code. It now excuses the spelling in exactly two places: the lines of shim_help(), each of which must be one say "..." with no $(, ${ or backtick in it, and section 0's one -h|--help) label. Outside those two, neither --help nor a bare -h may occur in the code. It still refuses -y), -h), --yes) and a second --help) label, and since fix round 1 it also refuses a quoted "--help"), a [[ $1 == --help ]] reader anywhere else (the developer path, the scan), and a reader hidden in a say line.

Evidence

• Targeted runs on the PR head e2df9a8 (d15a888, the fix round, merged with origin/main 53bee5b; the branch's first commit 968db85 is the writer's 16d1639 re-authored with the same tree 0d3243f8), with a stub gh first on PATH, GH_TOKEN bogus, an empty GH_CONFIG_DIR, GIT_ALLOW_PROTOCOL=file and a blanked git identity:
  • tests/test_setup_sh.py and tests/test_setup_project_py.py: 132 passed, 0 skipped;
  • tests/test_cli_reference.py, tests/test_repo_hygiene.py, tests/test_agents_md_codes.py and tests/test_openreposhape_command.py: 164 passed, 0 skipped;
  • all six files together: 296 passed, 0 skipped, 0 failed. Before the merge, on a throwaway merge of d15a888 and main 5678f68, the same six files gave 296 passed as well. review341 ran them on 968db85 merged with main 3ef059c: 132 + 162 passed.
• The new tests against base 87d2eb7's code: 15 failed. These are every new behaviour test (the shim's help ×4 spellings, its text, no echo, bash -s), the five generator refusal tests, GIT_ALLOW_PROTOCOL and the shim-probe tie. The 9 that pass are the "unchanged" guards (-h/--help inside a checkout, -- --help passthrough ×2) and pre-existing tests.
• Mutation proof: 18 single-hunk mutations in a throwaway worktree, each caught by a named test. They cover:
  • the help exit;
  • -h;
  • the -- stop;
  • help after the env guard;
  • the default not named;
  • a flag line added;
  • the default not shared;
  • a second --help) label;
  • main's guard, render's guard, and both;
  • the top-level-is-the-tree check;
  • the files check;
  • GIT_ALLOW_PROTOCOL;
  • the files drifting from the shim;
  • the Tool note;
  • the openRepoShape sentence;
  • the README sentence.
• The new tests:
  • tests/test_setup_sh.py (WINDOWS_SKIP with the rest of the file):
    • --help, -h, after a run's arguments, and beside --keep-shape-checkout --shape-ref: exit 0, the shim's text, no (0) self-bootstrap, no usage, no git clone in GIT_TRACE, nothing in TMPDIR;
    • the text names the variable, its default, setup-project.py --help and docs/cli.md, and no flag but --help;
    • a forged $OPENREPOSHAPE_REPO is never echoed;
    • bash -s -- --help;
    • <Project> -- --help and -- -h still clone (locally) and reach the scaffold's usage. This is also the positive control that the trace sees a clone;
    • inside a checkout, -h and --help are setup-project.py --help byte for byte, on stdout and on stderr (stderr was not compared before the fix round; by probe it was already identical).
  • tests/test_cli_reference.py:
    • a git ls-files copy with no .git, one inside an unrelated work tree, and one inside a work tree that looks like a checkout of the standard: --check and a plain write both exit 2, naming the tree, with nothing written and no clone;
    • render() itself refuses;
    • the checkout refusal comes before the no-bash one;
    • child_env() pins GIT_ALLOW_PROTOCOL=file;
    • the generator's files are the ones the shim's probe reads;
    • (fix round 1) --check in a real git init copy whose path ends in a space, and in one whose path is not UTF-8, exits 0 with [ok]; each is skipped where the file system cannot hold the name (both on Windows; the second wherever creating the directory fails, which is expected on macOS, where no runner was available here).

Merge-tree (re-run after merging origin/main 53bee5b into the branch)

• origin/main is an ancestor of the head: the branch carries a merge commit, e2df9a8, so it is mergeable with main by construction. render-cli-reference.py --check is [ok] on it.
• bump-leg.py: a workflow file or a leg pin that is not UTF-8 is refused by name before anything moves, so a Latin-1 comment no longer ends the run in a UnicodeDecodeError traceback (#289) #352 landed as 53bee5b (bump-leg.py: a committed workflow file under .github/workflows/ or a contracts/<role>-pin.yaml that is not UTF-8 ends in a UnicodeDecodeError traceback, exit 1, with no refusal naming the file, so the operator reads Python's decode error and --dry-run dies the same way #289) and conflicted in docs/handbook.html's footer, as predicted. The merge keeps both "added (#n)" clauses in landing order after "(AGENTS.md, README and scaffold-project.py --help say nothing of the scaffold's two path-collision refusals (scaffold-leg-path-collides, scaffold-pin-collides) or that spec, code and shape cannot be pinned, so a human or agent can learn of them only by hitting them #288)": (bump-leg.py: a committed workflow file under .github/workflows/ or a contracts/<role>-pin.yaml that is not UTF-8 ends in a UnicodeDecodeError traceback, exit 1, with no refusal naming the file, so the operator reads Python's decode error and --dry-run dies the same way #289), then (setup.sh: the shim self-bootstraps before it hands over and its pre-scan never looks for --help, so setup.sh --help run from anything but a checkout of the standard (a downloaded copy, curl … | bash -s -- --help, a git archive extraction) clones github.com/opensoft/openRepoShape before printing a word, prints the clone's usage rather than its own, dies with git's exit 128 offline, and makes scripts/render-cli-reference.py in such a tree reach GitHub, though setup-project.py --help answers offline from the same place #341), and keeps this branch's README.md blob 5465d135ca7263010ee354424041f90c4553d2e7, which is git hash-object README.md again: main does not touch README.md and its own blob is e8da9381….
• scaffold-project.py and adopt-project.py ask the project's YAML reader and validate-manifest.py about the manifest's values before anything exists, so --id null, --tracking-branch true and a blank --elected-by are refused (#258, #261) #314 has landed (3ef059c). The other open PRs that share a file with this branch, re-checked against d15a888 before the merge (heads fetched at that time) and bump-leg.py: a workflow file, the workflows directory or the leg's pin that this user cannot open is refused by name with a remedy, so the run ends in exit 2 and not a PermissionError traceback (#383) #403 again against e2df9a8:
  • clean against this branch: adopt-project.py: execute records in project.yaml which leg the plan gave each submodule a leg keeps, and shape-doctor.py holds the submodule to that row, so one in the other leg is MISPLACED and a real adoption's placement reads ok (#189) #394 (tests/test_repo_hygiene.py, not the README cap; it conflicts with main alone in tests/test_manifest_validator.py, a file this branch does not touch), templates: project.yaml, the leg pins and family.yaml quote their text placeholders, so --id 007, --tracking-branch 2026, --spec-path true or --org null read back as typed, and family.py add quotes a member id alike (#259) #395 (one-line visibility assertion edits in tests/test_setup_sh.py and tests/test_setup_project_py.py, independent of this branch; its hunks in docs/cli.md are at :246-279), family.py: init asks the holder's reader and validate-family.py about family.yaml before creating anything, --dry-run too, so --id null, --tracking-branch true, a blank --created-by and --created-on 20261011 are refused (#307) #397, family.py: add --dry-run makes every refusal add makes before it mounts, reads the member from throwaway clones outside the holder for the row's id and digest, and prints the row, gitlink, .gitmodules section and trailers without mounting, writing or committing anything, and add takes --trailer as bump does, so every subcommand has the dry run the module's EXIT CODES line promises (#326) #400 and adopt-project.py: plan --help says what --spec-path and --code-path are, the default and key each records, and the two refusals plan makes on them, so docs/cli.md no longer lists the two flags that choose where a leg is mounted as bare lines (#340) #401 (each regenerates other sections of docs/cli.md);
  • bump-leg.py: a workflow file, the workflows directory or the leg's pin that this user cannot open is refused by name with a remedy, so the run ends in exit 2 and not a PermissionError traceback (#383) #403 (head 5b1da66) still conflicts in the same footer hunk: it merges clean with main alone and conflicts with this branch. Whoever lands second keeps every clause in landing order after "(bump-leg.py: a committed workflow file under .github/workflows/ or a contracts/<role>-pin.yaml that is not UTF-8 ends in a UnicodeDecodeError traceback, exit 1, with no refusal naming the file, so the operator reads Python's decode error and --dry-run dies the same way #289)" — (bump-leg.py: a workflow file, a .github/workflows/ directory or a leg pin that this user cannot open ends the run in a PermissionError traceback, exit 1, under --dry-run as well, because cmd_bump and plan_workflows read them with no handler and main() catches Refusal and CommandFailed only, so no refusal names the file or says to make it readable #383) and (setup.sh: the shim self-bootstraps before it hands over and its pre-scan never looks for --help, so setup.sh --help run from anything but a checkout of the standard (a downloaded copy, curl … | bash -s -- --help, a git archive extraction) clones github.com/opensoft/openRepoShape before printing a word, prints the clone's usage rather than its own, dies with git's exit 128 offline, and makes scripts/render-cli-reference.py in such a tree reach GitHub, though setup-project.py --help answers offline from the same place #341) — and the blob of the README that lands. If bump-leg.py: a workflow file, the workflows directory or the leg's pin that this user cannot open is refused by name with a remedy, so the run ends in exit 2 and not a PermissionError traceback (#383) #403 lands first, this branch merges main again and takes its clause; if this branch lands first, bump-leg.py: a workflow file, the workflows directory or the leg's pin that this user cannot open is refused by name with a remedy, so the run ends in exit 2 and not a PermissionError traceback (#383) #403 must take the (setup.sh: the shim self-bootstraps before it hands over and its pre-scan never looks for --help, so setup.sh --help run from anything but a checkout of the standard (a downloaded copy, curl … | bash -s -- --help, a git archive extraction) clones github.com/opensoft/openRepoShape before printing a word, prints the clone's usage rather than its own, dies with git's exit 128 offline, and makes scripts/render-cli-reference.py in such a tree reach GitHub, though setup-project.py --help answers offline from the same place #341) clause and the blob 5465d135…, not e8da9381….
• docs/cli.md: templates: project.yaml, the leg pins and family.yaml quote their text placeholders, so --id 007, --tracking-branch 2026, --spec-path true or --org null read back as typed, and family.py add quotes a member id alike (#259) #395, family.py: init asks the holder's reader and validate-family.py about family.yaml before creating anything, --dry-run too, so --id null, --tracking-branch true, a blank --created-by and --created-on 20261011 are refused (#307) #397, family.py: add --dry-run makes every refusal add makes before it mounts, reads the member from throwaway clones outside the holder for the row's id and digest, and prints the row, gitlink, .gitmodules section and trailers without mounting, writing or committing anything, and add takes --trailer as bump does, so every subcommand has the dry run the module's EXIT CODES line promises (#326) #400 and adopt-project.py: plan --help says what --spec-path and --code-path are, the default and key each records, and the two refusals plan makes on them, so docs/cli.md no longer lists the two flags that choose where a leg is mounted as bare lines (#340) #401 all merged clean with d15a888 plus main 5678f68, and the generator's --check was [ok] on each merged tree (templates: project.yaml, the leg pins and family.yaml quote their text placeholders, so --id 007, --tracking-branch 2026, --spec-path true or --org null read back as typed, and family.py add quotes a member id alike (#259) #395's head 1ef3310, family.py: init asks the holder's reader and validate-family.py about family.yaml before creating anything, --dry-run too, so --id null, --tracking-branch true, a blank --created-by and --created-on 20261011 are refused (#307) #397's abb27e6, family.py: add --dry-run makes every refusal add makes before it mounts, reads the member from throwaway clones outside the holder for the row's id and digest, and prints the row, gitlink, .gitmodules section and trailers without mounting, writing or committing anything, and add takes --trailer as bump does, so every subcommand has the dry run the module's EXIT CODES line promises (#326) #400's 7062a47, adopt-project.py: plan --help says what --spec-path and --code-path are, the default and key each records, and the two refusals plan makes on them, so docs/cli.md no longer lists the two flags that choose where a leg is mounted as bare lines (#340) #401's 409f10b). Should one ever conflict, regenerating resolves it.

Left out (candidate follow-ups, not filed here)

• setup.sh --preflight from a download still clones before checking the machine, though setup-project.py answers --preflight before its own self-bootstrap. The preflight is Python, so the shim cannot answer it itself; it needs its own decision.
• From a download, setup.sh --help still needs Python 3.9 and git first: the interpreter and git checks run before the checkout probe, as they always did.
• Windows does not run the shim. The generator refusal tests do run there: they reach the refusal before any bash. The tests-windows job is their first run on that platform.

Fix round 1 (review341's CHANGES NEEDED 0/1/5)

One commit (d15a888) on top of 968db85, then a merge of origin/main 53bee5b (e2df9a8), no force:

• S1 (should). The One definition for the two entry points: setup.sh becomes a shim over setup-project.py (follow-up of #49) #50 guard excused the spelling --help everywhere in the shim, so a second reader in any form but an unquoted label passed it. It now excuses the spelling in shim_help()'s say "..." lines and the one -h|--help) label, and nowhere else (decision 5). Mutation proof in a throwaway worktree: the guard passes on the unmutated shim and fails on each of review341's three variants (a quoted "--help") label, a [[ "${1:-}" == --help ]] reader in the developer path, a [[ "$arg" == --help ]] reader inside the scan) and on four more (a reader as its own line in shim_help(), one chained after a say, one substituted into a say, a bare -h reader). The first four and the bare -h reader fail only the guard, and the help tests around it stay green; the chained and substituted say variants also break the help's own output.
• N1. The inside-a-checkout test compares stderr as well as stdout. With the developer-path reader above, it now fails and test_help_exits_zero still passes.
• N2. The generator reads git's top level with os.fsdecode(...).rstrip("\r\n"), so a checkout at a path ending in a space, or not UTF-8, is accepted again, as the shim accepts it. A test for each; on 968db85's generator both fail with exit 2 "not a checkout".
• N3. README and the handbook name python3 setup-project.py --help as the command that lists every flag; openRepoShape --help names eight of fourteen. The handbook's copy, its footer clause and its README blob follow. README stays 1422 lines, so its cap does not move.
• N4. "About seventy lines of code" is dropped from README, the handbook and setup-project.py's docstring: the shim is 122 lines of code, 93 before this change, and a count in prose goes stale again.
• N5. The comment above section 0's scan says the third read decides whether there is a run at all.
• docs/cli.md is unchanged: no --help text moved, and --check is [ok].

Closes #341

🤖 Generated with Claude Code

Summary by Sourcery

Make downloaded setup.sh help offline and self-contained, and restrict CLI reference generation to the checkout whose tools it documents.

New Features:

• Make setup.sh -h and setup.sh --help from downloads, piped input, and other non-checkout contexts return the shim’s own offline guidance without cloning or creating temporary files.

Bug Fixes:

• Prevent the CLI reference generator from cloning upstream or documenting the wrong help output when run outside the standard repository checkout.
• Preserve the existing checkout behavior where setup.sh delegates help to setup-project.py, while keeping arguments after -- directed to the scaffold.

Enhancements:

• Require CLI reference rendering to run from the top level of a valid standard checkout and fail clearly otherwise.
• Make generator child processes fail closed against network-based Git operations.
• Centralize the default repository value used by the shim’s clone behavior and help text.

Documentation:

• Update the README, handbook, and generated CLI reference to describe download versus checkout help behavior and the authoritative flag-list commands.

Tests:

• Add coverage for shim help behavior, passthrough semantics, no-clone guarantees, repository-value handling, and checkout preservation.
• Add generator tests for invalid, nested, unusual-path, and valid checkout layouts, including network isolation and refusal ordering.
• Strengthen hygiene checks to constrain the shim’s help parsing and documentation size.

[brettheap]

(lane openRepoShape-5, 2026-10-12T18:57Z) @codex review

[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 by commenting @sourcery-ai review. Upgrade to get a review now.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[sourcery-ai]

Reviewer's Guide

The PR makes setup.sh --help safe and useful outside a checkout without cloning, while retaining normal checkout and passthrough semantics; it also makes the CLI-reference generator refuse non-checkout trees, fail closed against network cloning, and updates tests and documentation accordingly.

Sequence diagram for safe setup.sh help outside a checkout

sequenceDiagram
    participant User
    participant SetupSh as setup.sh
    participant Help as shim_help
    participant Git
    participant Python as setup-project.py

    User->>SetupSh: --help or -h
    SetupSh->>SetupSh: scan arguments before --
    alt help requested outside a checkout
        SetupSh->>Help: shim_help()
        Help-->>User: short shim text, no flag list
        SetupSh-->>User: exit 0
    else normal run outside a checkout
        SetupSh->>Git: git clone --quiet --depth 1 -- SHAPE_REPO
        Git-->>SetupSh: temporary checkout
        SetupSh->>Python: exec setup-project.py
    else help inside a checkout
        SetupSh->>Python: exec setup-project.py --help
        Python-->>User: complete usage
    end

Loading

Flow diagram for setup.sh argument handling and passthrough

flowchart TD
    A[setup.sh receives arguments] --> B{Scan before --}
    B -->|find -h or --help| C{Outside a checkout?}
    C -->|yes| D[shim_help; exit 0]
    C -->|no| E[exec setup-project.py help]
    B -->|no help before --| F{Checkout available?}
    F -->|yes| G[exec setup-project.py with unchanged arguments]
    F -->|no| H[clone standard to temporary directory]
    H --> I[exec setup-project.py]
    B -->|-- encountered| J[pass remaining arguments to scaffold-project.py]

Loading

File-Level Changes

Change	Details	Files
Make downloaded or piped setup.sh --help self-contained and network-free while preserving checkout and passthrough behavior.	Scan only pre--- arguments for -h/--help. Answer with fixed shim-owned guidance before repository validation, temporary-directory creation, or cloning. Centralize the clone default in DEFAULT_SHAPE_REPO and keep the shim’s help free of a flag list. Retain setup-project.py help byte-for-byte inside a checkout and preserve -- passthrough to scaffold help.	setup.sh tests/test_setup_sh.py tests/test_setup_project_py.py
Prevent CLI-reference generation from documenting the wrong checkout and make regressions fail closed offline.	Require the target tree to be the top level of a git checkout containing the same marker files used by the shim. Invoke the checkout guard from both main() and direct render() calls, before bash checks. Preserve git path bytes using os.fsdecode(...).rstrip("\r\n") and reject nested or non-checkout trees with exit 2. Force child processes to use GIT_ALLOW_PROTOCOL=file.	scripts/render-cli-reference.py tests/test_cli_reference.py
Align user-facing documentation and generated CLI reference with the new help ownership and checkout requirements.	Explain that downloaded setup.sh --help clones nothing and points to python3 setup-project.py --help and docs/cli.md. Update the handbook, command help text, generated CLI reference, and history/blob metadata. Remove stale shim line-count claims and update repository hygiene limits.	README.md docs/handbook.html openRepoShape docs/cli.md setup-project.py tests/test_repo_hygiene.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#341	Make setup.sh -h and setup.sh --help from outside a checkout answer without cloning or creating a temporary checkout, while preserving the existing in-checkout help and -- passthrough behavior.	✅
#341	Prevent scripts/render-cli-reference.py from rendering or checking a tree that is not the top level of a standard checkout, and ensure its child processes cannot reach network Git transports.	✅
#341	Update user-facing documentation and relevant test descriptions to explain what setup.sh --help does outside a checkout and where to find the complete flag list.	✅

Possibly linked issues

• setup.sh: the shim self-bootstraps before it hands over and its pre-scan never looks for --help, so setup.sh --help run from anything but a checkout of the standard (a downloaded copy, curl … | bash -s -- --help, a git archive extraction) clones github.com/opensoft/openRepoShape before printing a word, prints the clone's usage rather than its own, dies with git's exit 128 offline, and makes scripts/render-cli-reference.py in such a tree reach GitHub, though setup-project.py --help answers offline from the same place #341: The PR fixes the issue by handling -h/--help before self-bootstrap and refusing non-checkout trees in the generator.

---

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.

[brettheap]

(lane openRepoShape-3, 2026-10-12T19:56:44Z) A v1.0.0 scope notice. Brett Heap scoped openRepoShape's first release today: every procedure in AGENTS.md works end to end for ordinary repositories on Linux, macOS and Windows. The tag waits for every in-scope issue to close and a full test run to pass on all three OSes on the release commit. This PR closes #341 (P2, parent #459): in scope, in the v1.0.0 milestone. Nothing changes in how it lands. Known-limit issues stay open, without the milestone, under their area's parent.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
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