[brettheap]

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

What

• repo_shape.Refusal assumes no remedy. A refusal built without one prints its REFUSED line alone; str() adds the trailer only when there is one. repo_shape is shared by every tool and both kinds of root, and cannot know whose remedy is right, so its default was one tool's remedy printed under all of them.
• REMEDIATION keeps its name and its bytes. It is the assembly root's lockstep remedy, and validate-pins.py is the one place it is right: the validator prints it under each refusal it makes that names no remedy of its own. That covers its own refusals and those load_yaml, git_out and find_repo_root raise for it, so its output is byte for byte what it was. It imports only REMEDIATION, on a line of its own; every repo_shape.py a root was ever given defines that name. Beside a repo_shape.py that still defaults to it, the validator prints it once.
• family.py add and add --dry-run name an unreadable .gitmodules as the holder's gate does. The code is now gitmodules-unreadable, with the words and remedy the holder's validate-family.py uses for the same file (family.py: add never reads .gitmodules, so a section under ANOTHER name whose path is already members/<P> (a "ghost" section) does not stop it: it exits 0 and commits two sections for one path, validate-family.py says family ok, and a recursive clone takes the LATER section, so with the ghost second it dies fetching the ghost's URL #300), where add said git-failed. With no .gitmodules in the working tree, git reads the index's copy or HEAD's; the remedy then says which one and how to put it back (git checkout [HEAD] -- .gitmodules).
• shape-doctor.py. refusal_line quotes a refusal that has no remedy whole. A row ended by a refusal with no remedy has no NEXT; on main its NEXT was the lockstep sentence.
• adopt-project.py. Its report of a failure once a leg repository exists (adopt-project.py: every failure once a leg repository exists flushes stdout, then prints REFUSED <step>., what failed and one notice of what the run left, so a failed git filter-repo no longer exits 2 with an empty stderr (#171, #188, #177) #445) left the lockstep remedy off by comparing against it. It now leaves an absent remedy off too, so no empty line follows its REFUSED <step>. line.

On the issue's three decisions: (1) the remedy now comes from the caller, and repo_shape gives none by default. (2) add uses gitmodules-unreadable and the gate's remedy. (3) validate-family.py is NOT changed: its refusals lose the wrong trailer through the holder's repo_shape.py.

Why

The issue reproduces on current main (ec4a7a0). I measured it on three projects scaffolded into local bare remotes and a family holder made with family.py init and add. Everything ran offline, with a gh stub that exits 97, GH_TOKEN=bogus, an empty GH_CONFIG_DIR, an empty global git config and GIT_ALLOW_PROTOCOL=file. There were 36 runs, main ec4a7a0 against head 9d313e7. $R is the scratch root; shas are masked for the comparison.

The issue's three rows. Main:

REFUSED git-failed: `git config -z --file .gitmodules --list` in $R/h/Fam exited 128: fatal: bad config line 4 in file .gitmodules
Remediation: run `git submodule update --init --recursive`, then `python3 scripts/validate-pins.py`. If the PIN itself is stale, advance the gitlink, `contracts/<leg>-pin.yaml` and every workflow `@<sha>` that names the leg in ONE commit (see README, 'The lockstep invariant').
add: exit 2
REFUSED member-pin-commit: Nova: pin.commit is '<12 hex>', which is not 40 hex. An abbreviated oid, a branch or a tag is a moving reference.
Remediation: run `git submodule update --init --recursive`, then `python3 scripts/validate-pins.py`. If the PIN itself is stale, ...
validate-family.py: exit 2
REFUSED family-wrong-kind: $R/h/Fam/family.yaml: kind is 'project-manifest', expected 'family-manifest'
Remediation: run `git submodule update --init --recursive`, then `python3 scripts/validate-pins.py`. If the PIN itself is stale, ...
bump: exit 2

Head:

REFUSED gitmodules-unreadable: .gitmodules could not be read as git reads it: `git config -z --file .gitmodules --list` in $R/h/Fam exited 128: fatal: bad config line 4 in file .gitmodules
Remediation: git cannot read it either, so none of this holder's submodules can be cloned from it as it stands. Mend the file by hand (`git config -f .gitmodules --list` says where it breaks), then run this again.
add: exit 2
REFUSED member-pin-commit: Nova: pin.commit is '<12 hex>', which is not 40 hex. An abbreviated oid, a branch or a tag is a moving reference.
validate-family.py: exit 2
REFUSED family-wrong-kind: $R/h/Fam/family.yaml: kind is 'project-manifest', expected 'family-manifest'
bump: exit 2

All 36 runs follow. "lockstep" is the Remediation: run \git submodule update ...trailer. On all 22 rows markedlockstep → none`, the head output is main's with that one line removed, checked by script. Every exit code is unchanged.

#	case	exit main → head	code main → head	remedy main → head	head bytes == main
F1	family.py add over an unparsable .gitmodules	2 → 2	git-failed → gitmodules-unreadable	lockstep → own: git cannot read it either, so none of this holde…	no
F1d	family.py add --dry-run over an unparsable .gitmodules	2 → 2	git-failed → gitmodules-unreadable	lockstep → own: git cannot read it either, so none of this holde…	no
F1v	holder validate-family.py over the same .gitmodules	2 → 2	gitmodules-unreadable	own: git cannot read it either, so none of this holde…	yes
F2	holder validate-family.py, a short member pin.commit	2 → 2	member-pin-commit	lockstep → none	no
F3	family.py bump, family.yaml of the wrong kind	2 → 2	family-wrong-kind	lockstep → none	no
F4	family.py bump, family.yaml not a mapping	2 → 2	family-unreadable	lockstep → none	no
F5	holder validate-family.py, family.yaml not a mapping	2 → 2	family-manifest-unreadable	lockstep → none	no
F6	holder bootstrap.py, family.yaml not a mapping	2 → 2	family-manifest-unreadable	lockstep → none	no
F7	holder validate-family.py, family.yaml unparsable	2 → 2	yaml-unparsable	lockstep → none	no
F8	family.py siblings, family.yaml unparsable	2 → 2	yaml-unparsable	lockstep → none	no
F9	holder validate-family.py, no contracts/shape-pin.yaml	2 → 2	shape-pin-missing	lockstep → none	no
F10	update-shape.py check on the holder, shape pin with files: []	2 → 2	update-pin-no-files	lockstep → none	no
F11	family.py init, the holder's local remote exists and is not a git repository	2 → 2	remote-unreadable	lockstep → none	no
F12	shape-doctor on the holder (sanity, nothing broken)	0 → 0	—	none	yes
F13	family.py add, the member's project.yaml id is not an id	2 → 2	member-bad-id	lockstep → none	no
F14	family.py add, the member's project.yaml is not a mapping	2 → 2	member-manifest-unreadable	lockstep → none	no
F15	family.py add, the member's project.yaml is unparsable	2 → 2	yaml-unparsable	lockstep → none	no
F16	git status of the holder after the refused adds	0 → 0	—	none	yes
A0	validate-pins.py, nothing broken	0 → 0	—	none	yes
A1	validate-pins.py, a short spec-pin commit (pin-tag-only)	2 → 2	pin-tag-only	lockstep	yes
A2	validate-pins.py, spec-pin unparsable (load_yaml in repo_shape)	2 → 2	yaml-unparsable	lockstep	yes
A3	validate-pins.py, no contracts/shape-pin.yaml	2 → 2	shape-pin-missing	lockstep	yes
A4	validate-pins.py, spec leg not initialized	2 → 2	pin-submodule-uninitialized	lockstep	yes
A5	validate-pins.py --root outside any git repository	2 → 2	not-a-git-repo	lockstep	yes
A6	validate-pins.py, project.yaml not a mapping	2 → 2	manifest-unreadable	lockstep	yes
A7	validate-manifest.py, project.yaml not a mapping	2 → 2	manifest-unreadable	lockstep → none	no
A9	assembly bootstrap.py, project.yaml unparsable	2 → 2	yaml-unparsable	lockstep → none	no
A10	bump-leg.py, project.yaml unparsable	2 → 2	yaml-unparsable	lockstep → none	no
A11	bump-leg.py, project.yaml not a mapping	2 → 2	bump-leg-manifest-unreadable	lockstep → none	no
A12	validate-repository-naming.py --project, not a mapping	2 → 2	manifest-unreadable	lockstep → none	no
A13	update-shape.py check, shape pin with files: {} (the issue comment)	2 → 2	update-pin-no-files	lockstep → none	no
A14	adopt-project.py check, plan of the wrong kind	2 → 2	plan-wrong-kind	own: this is a PLACEMENT plan, written by `shape-doct…	yes
A14b	adopt-project.py check, plan of another wrong kind	2 → 2	plan-wrong-kind	lockstep → none	no
A14c	adopt-project.py check, plan not a mapping	2 → 2	plan-unreadable	lockstep → none	no
A15	adopt-project.py check, plan unparsable	2 → 2	yaml-unparsable	lockstep → none	no
A16	shape-doctor.py, project.yaml unparsable: the manifest row quotes REFUSED yaml-unparsable: … through refusal_line	1 → 1	yaml-unparsable (quoted)	not quoted	yes

The doctor's catch-all row, measured in process on a scaffolded root with one check that runs a failing git rev-parse through repo_shape.git_out: on main "next" is the lockstep sentence; on head it is null.

family.py bump and remove now put the holder back when they fail after writing (#416), and a refusal raised then ends with the sentence saying what was put back. Injecting a git-failed refusal with no remedy at the commit step, in process, on main and head:

main: REFUSED git-failed: injected before the commit. Nothing was bumped: the bump has been undone — the gitlink at members/IRRS put back in the index as it was, family.yaml restored byte for byte, members/IRRS back on main at <12 hex> — and the holder is exactly as it was before this command.
      Remediation: run `git submodule update --init --recursive`, then `python3 scripts/validate-pins.py`. If the PIN itself is stale, ...
head: REFUSED git-failed: injected before the commit. Nothing was bumped: the bump has been undone — the gitlink at members/IRRS put back in the index as it was, family.yaml restored byte for byte, members/IRRS back on main at <12 hex> — and the holder is exactly as it was before this command.

remove, and both verbs after the commit has landed, read the same: main adds the lockstep line, and head ends at the sentence. Exit 2 in all eight runs.

What the issue said that no longer holds on current main: it was drafted at c7c02fa, where the holder's validator said family ok over an unparsable .gitmodules. Since #317 that validator refuses gitmodules-unreadable (row F1v). After #267, update-shape.py's pin refusals sit in check_pin rather than read_pin, with the same codes. The sites the issue lists are all still there. An AST scan finds 67 repo_shape Refusal(...) built without a remediation, in 14 files. Eleven of them are in repo_shape.py's own helpers, which every tool reaches. validate-pins.py's 17 keep the lockstep remedy wherever that validator prints them, and the other 50 now carry none. Two of the 50 are #416's member-store-gone, which only its rollback sentence reads, through the refusal's detail, so their remedy was never printed.

Scope. scripts/repo_shape.py and templates/assembly-root/scripts/validate-pins.py are pinned copies; repo_shape.py is copied out of scripts/, not templates/. update-shape.py check will therefore report upstream-changed for both in every assembly root, and for repo_shape.py in every family holder. This lands a digest-moving change before the v1.0.0 tag, as ruled. validate-family.py, family.py's other remedies and every refusal code AGENTS.md names are unchanged; tests/test_agents_md_codes.py passes.

Tests

tests/test_refusal_default_remediation.py, new, 20 tests:

• 14 fail on main ec4a7a0 and pass on head. They cover the Refusal default and __str__, git_out/load_yaml refusals, add/add --dry-run against the holder gate's lines, the index and HEAD copies, the issue's short member pin and wrong-kind bump, update-shape.py check on files: 0/false/~/{}/[], and the doctor row's NEXT.
• 6 pass on main as well, because they guard what must not change: REMEDIATION's words, validate-pins.py's two lines on pin-tag-only and yaml-unparsable, its single trailer beside an old-default repo_shape.py, refusal_line, and adopt-project.py's late-failure line with no empty remedy line under it. I checked that each one bites by breaking the fix in a scratch copy:
  • without the validator's handler, 2 fail;
  • with the handler made unconditional, the old-default test fails;
  • without refusal_line's guard, 1 fails;
  • with REMEDIATION's words changed, 1 fails;
  • with the blob-case remedy dropped, 2 fail;
  • with adopt-project.py comparing only against REMEDIATION again, 1 fails.

The new file skips nothing on any OS. The family runs are offline with the offline fixture's gh shim, which add --local-remote-dir never calls. The skips below are existing tests' own (git-filter-repo absent, symlinks, file names a platform refuses).

Targeted runs on head 9d313e7, with git-filter-repo 2.47.0 first on PATH:

• A, 51 files: the new file; the repo_shape readers and YAML tests; the validators and the naming policy; every test_family*.py, including family.py: bump and remove put the holder back when a hook, a lock or git refuses them after they write, and say what they put back or what is left with the commands that put it back; they ask first what their dry runs ask first; and remove refuses a held index.lock before it unmounts and a .gitmodules that gives the member's path to two submodules, of which git rm took out one (#365, #360) #416's test_family_bump_remove_rollback.py, and scaffold-project.py and family.py: --tracking-branch is asked of git check-ref-format --branch before anything exists, so ~, a..b, x.lock and a/ are refused under --dry-run and no longer die at the first git init -b after gh repo create has made the repositories (#283) #355's test_tracking_branch_ref.py; bump-leg.py; update-shape.py, including update-shape.py: apply --add refuses a path under a file the root keeps as update-add-not-a-directory before it writes anything, and a write that fails after the copies is update-write-failed, rolled back, so neither leaves a rewritten copy and an unmoved pin behind a traceback (#285) #346's test_update_shape_add_not_a_directory.py; the doctor's, including test_shape_doctor.py and test_shape_advisory.py; the scaffold pin tests and test_scaffold_leg_path_collisions.py; Both roots' scripts/bootstrap.py: main escapes what stdout cannot encode and spells each value it prints, so name: "a\ud83db" or 日本 under PYTHONIOENCODING=ascii no longer ends make bootstrap in a traceback (#391) #456's test_bootstrap_spelling.py; the guards test_repo_hygiene.py, test_cli_reference.py, test_agents_md_codes.py, test_git_output_decoding.py and test_stdout_encoding.py. Result: 2685 passed, 8 skipped in 1257.13s (0:20:57), exit 0.
• B, 9 adopt-project.py files, among them test_adopt_late_failure.py, test_adopt_filter_repo_failure.py 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's test_adopt_plan_leg_path_help.py: 448 passed, 1 skipped in 161.97s (0:02:41), exit 0.

Composes with

Trial merges (git merge-tree --write-tree --name-only <branch> HEAD) on 9d313e7, against every open branch that touches a file this PR touches:

branch	PR	result
fix/pin-files-not-a-list	#343	CLEAN
fix/update-shape-pinned-copy-symlink	#347	CLEAN
fix/adopt-check-hand-edited-plan	#356	CLEAN
fix/doctor-manifest-kinds-unreadable-pin	#358	CLEAN
fix/ruleset-hint-tracking-branch	#373	CLEAN
fix/trailer-non-ascii-old-git	#376	CLEAN
fix/adopt-refuse-existing-split-branch	#382	CLEAN
fix/adopt-spell-question-and-submodule	#384	CLEAN
fix/adopt-check-link-and-manifest	#387	CLEAN
fix/adopt-record-submodule-placement	#394	CLEAN
fix/template-quoted-placeholders	#395	CLEAN
fix/family-init-values	#397	CLEAN
fix/doctor-next-is-only-a-command	#402	CLEAN
fix/pin-source-env-collisions	#409	CLEAN
fix/validate-pins-workflow-not-utf8	#419	CLEAN
fix/adopt-plan-field-types	#435	CONFLICT adopt-project.py
fix/link-source-values	#453	CLEAN
fix/family-bump-peels-annotated-tag	#466	CLEAN
fix/doctor-mid-merge-not-compliant	#468	CONFLICT docs/handbook.html
fix/adopt-pin-writes-pin-file	no PR	CONFLICT adopt-project.py docs/cli.md

• Both roots' scripts/bootstrap.py: main escapes what stdout cannot encode and spells each value it prints, so name: "a\ud83db" or 日本 under PYTHONIOENCODING=ascii no longer ends make bootstrap in a traceback (#391) #456 landed while this was tested and conflicted in scripts/repo_shape.py's module docstring only: this PR rewords the Refusal bullet in the list of what the module carries, and Both roots' scripts/bootstrap.py: main escapes what stdout cannot encode and spells each value it prints, so name: "a\ud83db" or 日本 under PYTHONIOENCODING=ascii no longer ends make bootstrap in a traceback (#391) #456 added a spelled bullet right after it. The rebase onto ec4a7a0 keeps both bullets.
• adopt-project.py: check names, and execute refuses before the work directory is made, a plan whose source: or legs: is not a mapping or whose allow_empty_legs: or paths: is not a list of what plan writes, and asks the same first of a pins: that is not a list, so a number or a boolean in any of the four no longer ends both in a traceback and allow_empty_legs: code is no longer read as four legs (#386) #435 and fix/adopt-pin-writes-pin-file conflict in adopt-project.py (the second in docs/cli.md too), in exactly the hunks each already conflicts in against main ec4a7a0. None of them is at _failed_loudly, so this PR adds no conflict to them.
• shape-doctor.py: a root whose index holds an unmerged path gets a merge FINDING naming the paths, with git -C <root> status as its NEXT, and the verdict INVALID (merge), exit 1, on a rung above every other but CANNOT ANSWER, so a merge git commit refuses no longer reads COMPLIANT, exit 0, once checkout --ours takes the markers out, or DRIFTED about a leg that never moved (#424) #468 conflicts in docs/handbook.html, which this PR does not touch; it conflicts there against main too.
• No open branch relies on the old default: none of their diffs names repo_shape.REMEDIATION or the lockstep trailer's words, or compares a refusal's remedy against it. update-shape.py read_pin refuses update-pin-row, and the pinned validate-pins.py and validate-family.py report shape-pin-row, when a shape pin's files: is not a list, so files: 5, true or 1.5 no longer ends check, apply, shape-doctor.py and the project's own validator in TypeError: ... is not iterable (#290) #343 gives update-pin-row its own remedy and leaves update-pin-no-files without one, which with this PR prints its line alone (rows F10 and A13).

Left out

• Per-site remedies for the refusals that now print their line alone, such as member-pin-commit (family.py bump) and shape-pin-missing (restore from history).
• Narrowing validate-pins.py's lockstep remedy on its refusals that are not about a leg (shape-pin-missing, manifest-missing, neutral-pin-*), kept byte-identical here on purpose.
• tests/test_shape_doctor.py::test_the_quoted_refusal_line_is_the_refusals_own_less_its_remediation still says "the loader's default remedy" in its docstring; it passes because it passes REMEDIATION explicitly.

Closes #370

🤖 Generated with Claude Code

Summary by Sourcery

Make refusal remediation caller-owned so each tool reports only guidance appropriate to its repository root.

Bug Fixes:

• Ensure refusals without a caller-provided remedy print only their refusal line instead of an unrelated lockstep instruction.
• Report unreadable .gitmodules files from family.py add using the holder validator's error code and actionable remedy.
• Prevent adoption failure reports and shape-doctor output from emitting stale or empty remediation lines.

Enhancements:

• Keep the assembly root lockstep remediation in validate-pins.py, preserving its existing output while making remediation ownership explicit.

Tests:

• Add coverage for remedy ownership, holder .gitmodules handling, validator compatibility, shape-doctor output, update-shape refusals, and adoption failures.

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

[sourcery-ai]

Reviewer's Guide

This PR removes the incorrect global lockstep remediation from shared Refusal construction, makes callers explicitly supply remedies, preserves validate-pins.py's historical assembly-root output, and gives family add a matching holder-specific .gitmodules diagnostic with comprehensive regression coverage.

Sequence diagram for caller-specific refusal remediation

sequenceDiagram
    participant Tool
    participant RepoShape as repo_shape
    participant Validator as validate-pins.py
    participant Output

    Tool->>RepoShape: Refusal(code, detail)
    RepoShape-->>Tool: refusal with no remediation
    Tool->>Output: print refusal line only

    Validator->>RepoShape: Refusal(code, detail)
    RepoShape-->>Validator: refusal with no remediation
    Validator->>Output: print refusal plus REMEDIATION

Loading

Sequence diagram for unreadable .gitmodules handling in family add

sequenceDiagram
    participant Add as family.py add
    participant Git
    participant Holder

    Add->>Git: git config -z --file .gitmodules --list
    alt .gitmodules is readable
        Git-->>Add: submodule configuration
    else .gitmodules is unreadable
        Git-->>Add: refusal with git error
        Add->>Holder: construct gitmodules-unreadable refusal
        Holder-->>Add: holder-specific remediation
        Add-->>Add: print refusal and remediation
    end

Loading

Flow diagram for refusal rendering without a default remedy

flowchart TD
    A[Refusal created] --> B{remediation supplied?}
    B -->|yes| C[Render REFUSED line and remediation]
    B -->|no| D[Render REFUSED line alone]
    C --> E[Caller prints result]
    D --> E
    F[shape-doctor refusal_line] --> G{remediation supplied?}
    G -->|yes| H[Remove remediation trailer]
    G -->|no| I[Keep complete refusal line]

Loading

File-Level Changes

Change	Details	Files
Make refusal remediation caller-owned instead of applying a shared default.	Change Refusal's default remediation to empty and omit the trailer when absent. Keep the assembly lockstep remedy exported under REMEDIATION for callers that explicitly need it. Update shared-reader and downstream reporting behavior so refusals without remedies remain single-line and doctor NEXT commands are absent.	scripts/repo_shape.py shape-doctor.py adopt-project.py
Preserve the assembly validator's lockstep output explicitly.	Import REMEDIATION in the templated validate-pins.py. Append it only when the caught refusal has no remedy, preserving existing output and avoiding duplicate trailers with legacy repo_shape copies.	templates/assembly-root/scripts/validate-pins.py
Give family add operations the holder-specific .gitmodules refusal and remediation.	Translate git config failures into gitmodules-unreadable. Reuse the holder gate's wording and explain whether the unreadable file came from the index or HEAD when no working-tree copy exists. Apply the behavior to normal and dry-run add paths without changing exit status or rollback behavior.	scripts/family.py
Add regression coverage for default-remediation removal and tool-specific output.	Test Refusal formatting, shared reader refusals, family add and gate parity, index/HEAD restoration guidance, pin and manifest failures, validator compatibility, doctor rows, and adoption late failures. Verify lockstep output remains byte-for-byte stable for validate-pins.py and is not duplicated with older pinned repo_shape copies.	tests/test_refusal_default_remediation.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#370	Ensure family tools do not give holders assembly-root remediation instructions for refusals that have no appropriate remedy of their own.	✅
#370	Make family.py add report an unreadable .gitmodules with the same refusal code and remedy as the holder's family validator.	✅
#370	Preserve the assembly-root lockstep remediation where it is appropriate, in particular for validate-pins.py refusals.	✅

Possibly linked issues

• repo_shape.py's Refusal gives every refusal built without a remediation the assembly root's own (run git submodule update --init --recursive, then python3 scripts/validate-pins.py ... contracts/<leg>-pin.yaml), so in a family holder family.py add over an unparsable .gitmodules (git-failed), bump on a family.yaml of the wrong kind, and the holder's own validate-family.py on a short pin.commit each tell the operator to run a file no holder carries and to move a leg pin a holder does not have #370: The PR makes refusals without an explicit remedy print no assembly-root instructions, preserves that remedy in validate-pins.py, and aligns add’s .gitmodules refusal with the holder gate.

---

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-12T22:46:01Z) @codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-12T22:51:12.428568Z	9d313e7	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9d313e7ff1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Restore NEXT commands for remedy-free doctor findings

When a doctor check propagates a shared Refusal that does not explicitly supply remediation (for example, a git_out failure), this empty default flows through shape-doctor.py::run_checks as exc.remediation or None; the row remains a FINDING but has no NEXT command, and the new test explicitly locks in that result. Supply a doctor-specific fallback or contextual remediation rather than omitting NEXT, because the doctor contract requires every finding to carry the exact next command.

AGENTS.md reference: AGENTS.md:L226-L228

Useful? React with 👍 / 👎.

[brettheap]

(lane openRepoShape-3, 2026-10-12T23:47Z) An independent review checked this and does not take it, for four reasons:

1. Main's NEXT here was not a command. It was the assembly root's prose (run git submodule update --init --recursive, then validate-pins.py), and the catch-all runs for every kind of root. On a family holder or a non-root that script does not exist, and on an assembly root obeying it detaches the legs for an unrelated fault.
2. The doctor's own rulings prefer no NEXT to a wrong one (shape-doctor.py: the legs row's NEXT (and the members row's) runs <root>/scripts/bootstrap.py without asking whether the root has it, so a root that lost it pastes python3: can't open file, exit 2, and for an empty leg mount the legs NEXT would not cure the row even with the file there (bootstrap.py only prints Run git submodule update --init spec) #276, shape-doctor.py: validator_row reads a validator's exit 1 as "reports a finding" whatever caused it, so a validator that CRASHED (a : in the standard's path splits the PYTHONPATH the template fallback runs under, and validate-manifest.py dies on import repo_shape) is a FINDING row quoting ModuleNotFoundError, and a root whose manifest is valid goes from COMPLIANT, SHAPE BEHIND to INVALID (manifest) #278), and the open shape-doctor.py: a NEXT is only the command, and the sentence that ended twenty-five of them after # is the row's why, on a WHY line of its own and "why" in --json, so a NEXT pasted into an interactive zsh -- which reads that # as a word -- no longer hands the comment to the command as arguments, runs what follows its ;, or runs the make bootstrap in its backticks, and the template validator's line is env PYTHONPATH=... python3 ... (#277) #402 requires NEXT to be a bare command.
3. Twelve ordinary breakages of a scaffolded root (leg dir or .git removed, unparsable .gitmodules or pins, broken index, HEAD or objects in the root and the leg) never reach the catch-all, on main or on this head. Every row's NEXT is the same.
4. The catch-all only catches refusals nobody anticipated, so any generic fallback would be a made-up command.

Keeping exc.remediation or None.

[sourcery-ai]

Sourcery assessment

Approved.

[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