[brettheap]

Lane: openreposhape-2 (openRepoShape-2)
Claim: #283 (comment)

What

scaffold-project.py and scripts/family.py init now ask git whether --tracking-branch is a branch, before any work directory, remote or repository exists. They do it under --dry-run too. A name git refuses is a named refusal, exit 2, no traceback:

REFUSED scaffold-bad-tracking-branch: --tracking-branch is 'a..b', which is not a branch name git will create: `git check-ref-format --branch` refuses it (fatal: 'a..b' is not a valid branch name)
Remediation: pass a branch name git will create, such as `main` or `release/1.2`: no `..`, no `//`, no `~`, no `/` at either end, no `.` at the end, no part that starts with `.` or ends in `.lock`, and not `HEAD`. `git check-ref-format --branch <name>` is the check, and `git help check-ref-format` lists every rule.

• The question, scripts/shape_materialize.py, in a new "A branch name, asked of git (scaffold-project.py holds --tracking-branch only to checked_value's alphabet, so a name git refuses as a branch (~, a..b, x.lock, a trailing /) passes --dry-run and, against GitHub, dies at the first git init -b after gh repo create has made all three repositories #283)" block after run():
  • branch_problem(what, value) returns None when git check-ref-format --branch accepts value exactly as written, else the sentence above.
  • refuse_bad_branch(refusal, what, value) raises Refusal(refusal, <that sentence>, <remedy>), so each tool refuses under its own code, the way refuse_bad_leg_paths lets it.
  • Git is asked, not copied. A rule git adds or relaxes is ours when the person upgrades; a name only some versions refuse (HEAD) follows the git that runs.
  • Git is asked with no repository in play. _ask_git_branch runs git --git-dir=<an empty temporary directory> check-ref-format --branch <name>, with that same directory as the working directory, and removes it afterwards. The verdict is therefore the same from every directory. That includes a directory inside a repository git cannot open, such as a .git file naming a gitdir that is gone, or a .git/config that does not parse. It also includes a directory removed under the person.
  • A git that cannot answer for any name says so; it does not blame the name. When git refuses a name, it is asked about main as well. If it refuses that too, as it does under a malformed global git config, the refusal says the name "could not be checked", with git's own words. Its remedy, BRANCH_UNCHECKED_REMEDIATION, is about git and not about the name. The helper tells the two cases apart by asking git again, not by reading git's words, which are localised.
  • A leading - is refused without asking, so the value is never an option to the question itself. checked_value has already refused it in both tools, so the guard is a second line.
  • A name git would expand rather than echo is refused as not the name written. In a repository, @{-1} becomes the branch before; asked of no repository, git has nothing to expand and refuses @{-1} itself. The alphabet keeps { out anyway. The helper still refuses any answer that differs from the name, and a test holds that guard with a git that answers another name.
  • A git that cannot run gets the "could not be checked" refusal and the unchecked remedy, not a traceback. So does a value that cannot be an argument at all (a NUL), but its remedy is the name's.
• scaffold-project.py _scaffold: refuse_bad_branch("scaffold-bad-tracking-branch", ...). It sits after _declaration and _check_declared_names and before _shape_revision, the work directory and every remote. See "Why the call is there".
• scripts/family.py _checked_family_identity: refuse_bad_branch("family-bad-tracking-branch", ...) right after checked_value, the first thing init does. cmd_init runs gh repo create for the holder before _create_holder_worktree's first git init -b, so the defect is the same one.

Why

checked_value holds the flag to an alphabet (SAFE_ARG_RE), which keeps an option and a shell word off a command line. The alphabet is wider than what git accepts as a branch. ~, a~1, a..b, x.lock, a/, /a, a//b, .a and a. are all inside it, and git init -b refuses each. Nothing asked git.

Reproduced on main 71b58a1 (git 2.43.0) with a stub gh that logs its calls and succeeds, so nothing reached GitHub (tools/repro.sh, repro-base.log):

== --tracking-branch '~':    --dry-run exit 0, real run exit 2, 3 x gh repo create, work dir made, REFUSED a git or gh command failed. THE EXACT COMMAND WAS:
== --tracking-branch 'a..b': --dry-run exit 0, real run exit 2, 3 x gh repo create, work dir made, REFUSED a git or gh command failed. ...
== --tracking-branch 'x.lock' and 'a/' the same, and so do a~1, /a, a//b, .a and a.
== --tracking-branch 'main': --dry-run exit 0, real run exit 2, 3 x gh repo create  (the control; it dies at the push because the stub makes no remote)
== family init --tracking-branch '~': --dry-run exit 0, real run exit 2, 1 x gh repo create

At this head, the same nine names exit 2 under --dry-run and under a real run, with 0 gh repo create, no work directory and no plan on stdout. main and feature/x still reach gh repo create (repro-fixed.log, repro-family-fixed.log). Against GitHub the old run left three repositories with no commit, and the re-run was then refused scaffold-remote-exists for the two legs until the operator deleted them by hand.

Why the call is where it is. The first targeted run found a fault in my own first placement. I had put the call beside checked_value at the top of _scaffold, and 129 existing tests failed with ProcessStarted: ['git', 'check-ref-format', '--branch', 'main']. test_scaffold_pin_collisions.py, test_scaffold_leg_path_collisions.py and test_scaffold_referent_chain_links.py hold that the refusals made before _identity and _declaration start no process. Each has a control that the first process is git config user.name, or that _declaration is reached. This check has to ask git, so it moved after _declaration and _check_declared_names and before _shape_revision. Nothing exists when it refuses, and the 129 pass again. The one thing that now runs before it is _declaration's gh api read, and only for a --pin with no --pin-source; it creates nothing.

Why no repository. --branch sets up the repository it finds in its working directory. Asked in the operator's directory, git failed for every name inside a repository it could not open, and in a directory that had been removed. From those directories both tools then refused the default main as "not a branch name git will create", where main scaffolds from all three (tools/x355/cwd-probe-main.log, cwd-probe-head.log). --git-dir alone is not enough, because git run from a removed directory dies before it reads its arguments (Unable to read current working directory). The empty directory serves as both the git directory and the working directory.

Why shape_materialize.py, not repo_shape.py. repo_shape.py is a shape copy: the materializer writes it into every project and contracts/shape-pin.yaml digests it. A function added there would put an upstream-changed scripts/repo_shape.py row in front of every project for a rule no project's own copy asks. This is the same placement, and the same reason, as refuse_bad_leg_paths (#179). No template file changes, so no digest pin moves. docs/cli.md is unchanged: no --help text changed, and render-cli-reference.py --check passes.

Tests

New file tests/test_tracking_branch_ref.py, 161 tests:

tests	what they cover
24	scaffold, local route: the 12 refused names, in a --dry-run and a real run; exit 2, REFUSED scaffold-bad-tracking-branch: --tracking-branch is '<name>', ..., the remediation, no plan, nothing on disk, no temporary work directory
24	the same on the GitHub route, with a #! stub gh first on PATH: no gh call at all, not even repo view. Skipped on Windows by WINDOWS_SKIP, for the reason the existing gh stub tests carry
10	controls: ten names git creates (main, release/1.2, shape/update-v1.2, lane-3/shape+fix@eagle, a@b, ...) still pass --dry-run, with nothing created
1	control: --tracking-branch=release/1.2 scaffolds, and all three bare remotes hold exactly that branch
1	the ~ repro: the first words name the flag and the rule
1	a leading - (-x, which has nothing else for the alphabet to refuse) is still unsafe-value from checked_value, never reaching check-ref-format
24 + 8 + 2	family.py init: the 12 names in both modes; the GitHub route with the stub, 4 names in both modes (skipped on Windows); two controls
2	from inside a repository git cannot open, a .git file naming a gitdir that is gone and a malformed .git/config, with TMPDIR inside it too: scaffold and family --dry-run with the default branch exit 0, a..b is still refused by both, and the question leaves no directory behind
1	from a removed working directory (POSIX; Windows will not remove a directory a process stands in): main passes and a..b is git's refusal
1	a git that cannot answer for any name (a malformed GIT_CONFIG_GLOBAL): main and a..b are each "could not be checked", not "not a branch name", with the unchecked remedy
54 + 1	the helper says what this git says, over a 54-name corpus, and the corpus holds names of both kinds
6	helper units: the refusal's code, flag and remedy; a leading - is not put to git; a git that cannot run (the unchecked remedy); a NUL; a name git would expand; one definition imported by both tools
1	the helper is not in the shape copy repo_shape.py

The 12 refused names are the issue's nine (~, a~1, a..b, x.lock, a/, /a, a//b, .a, a.) plus a/.b, a.lock/b and +x..y.

The new file against main's code. It was committed in a scratch tree, so the checkout is clean.

• On main 92e29d9: 145 failed, 16 passed (tools/x355/x355-main-newtests.log.gz). The passes are the controls, and the two broken-repository tests pass their main half and fail at a..b.
• At the original 157 tests, on 71b58a1: 141 failed and 16 passed. 81 of those failed for the issue's reason: every --dry-run row printed the plan and exited 0, and every real-run row exited 2 with REFUSED a git or gh command failed after git init -b died. The other 60 failed with AttributeError, because the helpers are new (tools/new-tests-on-base-summary.txt).

Against this PR's previous head a03abcf: 5 failed, 156 passed (tools/x355/x355-old-newtests.log.gz). The 5 are the four new tests and the cannot-run unit's remedy assertion:

• the two broken-repository rows refuse main (fatal: not a git repository, fatal: bad config line 6);
• the removed directory refuses main (Unable to read current working directory);
• the malformed config blames the name;
• BRANCH_UNCHECKED_REMEDIATION did not exist yet.

One mutant per decisive line, each caught. The first four were run in scratch clones at a03abcf; the rest are commits on this head, run against this file (tools/x355/x355-mu*.log.gz):

mutant	result
the scaffold's call deleted	49 fail, first test_a_name_git_would_not_create_is_refused_before_anything_is_made[tilde-dry-run]
the family call deleted	32 fail in -k "family or one_definition"
except CommandFailed returns None	111 fail
--git-dir dropped, so git may look for a repository again	2 fail: the two broken-repository rows ([gitfile], [bad-config])
the working directory no longer the empty directory	1 fails: the removed-directory test
no control question, so every refusal blames the name	1 fails: the malformed-config test
a git that cannot run gets the name's remedy	1 fails: the cannot-run unit
the answer != text guard deleted	1 fails: the expansion unit, everywhere

Targeted runs at this head (d696acc), git-filter-repo 2.47.0 on PATH, one pytest process at a time, every one green:

files	result
test_tracking_branch_ref.py + the 8 test_scaffold_*.py files	490 passed (161 + 329)
test_family.py, test_family_add_excludes.py, test_family_add_refusals.py, test_git_output_decoding.py, test_cli_reference.py, test_repo_hygiene.py	225 passed
scripts/render-cli-reference.py --check	ok

At a03abcf, test_git_output_decoding.py, test_adopt_leg_paths.py, test_adopt_plan.py, test_shape_doctor.py, test_cli_reference.py, test_repo_hygiene.py and the two test_family_add_* files gave 773 passed and 4 skipped. The fix round touches only the helper, which only these two tools call, so that set was not repeated.

I did not run the full suite or macOS and Windows; CI does. The Windows risk is the 32 stub-gh tests, which are skipped there, and the local-route tests, which hold no symlink, junction or text-mode stdin. The broken-repository tests run on Windows: the gitfile names its gitdir with / separators. The removed-directory test is skipped on Windows.

Fix round (review of a03abcf)

Lane openRepoShape-2's own review of a03abcf found one P2, two P3s for follow-up issues, and nits; this round takes the P2 and the nits.

• P2: the answer depended on the operator's working directory. Fixed in e5bbf65. From a directory inside a repository git cannot open, both tools refused the default main and told the person to pass main. Main scaffolds from there. The review's form, --git-dir=<empty directory>, is taken, and the working directory is that directory too, because a removed directory failed the same way and --git-dir alone does not reach it. The review's optional rewording is taken as well, by the control question above rather than by reading git's words. Four tests, and the cannot-run unit now checks the remedy.
• Nits, two tests. Fixed in d696acc. The leading-dash test passes -x, so it holds the dash rule alone, where --upload-pack=touch x was also refused for its space and its =. The NUL test's composite assert (Sonar python:S9073) is two asserts.
• Nit, this body. The answer != text mutant now fails one test everywhere, the expansion unit. The @{-1} corpus row caught it only in a checkout with a previous branch, and git is no longer asked in a checkout. The count of open PRs touching adopt-project.py and the merge-tree list below are re-checked.

The review's other two findings are follow-up issues and are left out (see "Left out").

Composes with

git merge-tree --write-tree d696acc <head> at 2026-10-12T16:52:55Z (tools/x355/merge-tree-d696acc.log): rc 0 against origin/main 92e29d9, against #314 a5438a5 and #373 5ac03de, and against this lane's open heads (#267, #266, #353, #356, #343, #346, #347, #352, #401, #403, #404, and the #386 and #359 branches). The one exception is #358 2745890, rc 1 in shape-doctor.py. That conflict is #358's own: #358 conflicts in the same file with this PR's base 71b58a1 and with main 92e29d9 when #355 is not involved, and this PR does not touch shape-doctor.py.

I also merged this head into scratch trees and ran the tests that could collide:

• 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 fix/scaffold-manifest-values a5438a5 (scaffold-project.py writes --id and --tracking-branch into project.yaml unquoted, so --id null or --id true scaffolds a project whose first bootstrap fails manifest-id, and --tracking-branch true, 007 or null puts the clone's legs on True, 7 or main with no upstream: #181's defect on the scaffold side, beside #225 #258, lane 5), merged with main 92e29d9 and this head: the merge is clean, but two of 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's own tests fail (2 failed: branch-tilde and .inf). They assert that two values are accepted or misread which git does not take as a branch at all:

  • test_a_value_the_reader_misreads_is_refused_before_anything_is_made[branch-tilde]: --tracking-branch '~' is now refused scaffold-bad-tracking-branch first, because it is not a branch, where 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 expects scaffold-manifest-misread.
  • test_a_branch_the_reader_takes_for_text_is_still_accepted[.inf]: .inf begins with a dot, so git refuses it as a branch.

  The fix lives in 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's test file. Drop the branch-tilde row from MISREAD_VALUES, and drop .inf from TEXT_BRANCHES and from the comment above it. tools/pr314-test-edits-for-composition-v2.patch in the lane's attachments is that diff, against a5438a5. With it, the merged tree gives 265 passed (104 + 161) for 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's file and mine. Neither PR's code needs to change. 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's value check runs after mine, on values, so its 007, true, null and the rest still reach it.

• Earlier, at a03abcf: main 87373a6 gave 476 passed (my file, the three no-process scaffold files, test_scaffold_leg_paths.py, test_family_add_refusals.py, test_cli_reference.py, test_repo_hygiene.py). Main c1b6732 with tests/conftest.py: a session gh guard first on PATH answers the doctor's two machine-row probes as a gh with no login and fails any test whose other calls it refused, so no test reaches the operator's gh and the row is still tested, and refusing_network's four users assert on the calls its gh logged rather than on a stderr the preflight captures (#296) #349 b111b51 (the gh guard) and scaffold-project.py: --elected-by, --reference, --name and the elector's fallback are refused before anything exists when no file can hold them, so a byte that is not UTF-8 no longer creates repositories before a traceback (#282) #351 8f43c96 gave 456 passed. The review's merges gave 922 passed for a03abcf + main 28bdc84 and 171 passed for a03abcf + 28bdc84 + shape_materialize.py: RULESET_HINT names the run's tracking branch where it named main, as the pull request's base and the ref the scaffold and the family holder pushed (#324) #373 5ac03de. My stub gh is put ahead of tests/conftest.py: a session gh guard first on PATH answers the doctor's two machine-row probes as a gh with no login and fails any test whose other calls it refused, so no test reaches the operator's gh and the row is still tested, and refusing_network's four users assert on the calls its gh logged rather than on a stderr the preflight captures (#296) #349's guard, which is how tests/conftest.py: a session gh guard first on PATH answers the doctor's two machine-row probes as a gh with no login and fails any test whose other calls it refused, so no test reaches the operator's gh and the row is still tested, and refusing_network's four users assert on the calls its gh logged rather than on a stderr the preflight captures (#296) #349 says a test that means to run gh does it.

Left out

• adopt-project.py takes --tracking-branch the same way, and has the defect. I measured it and did not fix it.
  • With --tracking-branch a..b, plan exits 0 and writes tracking_branch: a..b, check says plan ok, and execute --yes --local-remote-dir exits 2 at the first bare leg remote (fatal: invalid initial branch name: 'a..b'), leaving Northwind-spec.git behind (tools/adopt-probe.txt). Against GitHub the legs' gh repo create comes first.
  • It needs three sites, not one: plan's flag (_checked_plan_inputs), execute's plan value (_checked_plan_values), and a check finding. check reads no tracking_branch at all today, and a check that passes what execute refuses is the disagreement adopt-project.py: since #247 a byte that is not UTF-8 in --elected-by, --reference or the --source directory passes plan and check, and execute pushes both legs before it dies with UnicodeEncodeError in write_lf #255 and adopt-project.py: a plan that sends .gitmodules to one leg and a submodule it registers to another passes check and execute, says adoption verified, and the assembly's recursive clone then fails: plan should ask, check should find, execute should refuse #166 closed for other fields. branch_problem returns the sentence for that finding.
  • Eleven open PRs touched adopt-project.py at the review of a03abcf, and the change needs git-filter-repo fixtures. It is its own change, and the review recommends filing it.
• A leading + is a branch git accepts and a forced refspec when pushed. With --tracking-branch +x, --dry-run exits 0, and the real run creates the remotes before it dies at git push -u origin +x. Main does the same, and scaffold-project.py holds --tracking-branch only to checked_value's alphabet, so a name git refuses as a branch (~, a..b, x.lock, a trailing /) passes --dry-run and, against GitHub, dies at the first git init -b after gh repo create has made all three repositories #283 promises names git refuses, so the review recommends a follow-up issue.
• update-shape.py's own --branch check (checked_branch, update-shape.py apply --branch --push --pr: when gh pr create fails after the commit and the push succeeded, it exits 2 with "REFUSED committing the re-synced shape" and no NEXT line, and a re-run on that branch says "nothing to do" and exits 0, so the tool never opens the pull request #204) asks git check-ref-format --branch in the operator's working directory too. On main 92e29d9, apply --branch shape/update-x run from inside a repository git cannot open is refused update-branch-invalid (tools/x355/update-shape-branch-cwd-main.log). That is main's code in another tool, so it is reported for a follow-up and not changed here.
• Names git accepts that are odd for a branch, such as refs/heads/x, @ and FETCH_HEAD, are accepted, because git accepts them. The question is git's.
• Holder.tracking() and family.yaml's own tracking_branch: only init's flag is asked. A holder already written is not re-judged on every read.
• scaffold-project.py writes --id and --tracking-branch into project.yaml unquoted, so --id null or --id true scaffolds a project whose first bootstrap fails manifest-id, and --tracking-branch true, 007 or null puts the clone's legs on True, 7 or main with no upstream: #181's defect on the scaffold side, beside #225 #258's YAML half of the flag (true, 007, null) is lane 5's 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. The two checks are separate helpers, and the composition note above is the only thing the two PRs owe each other.
• --help text for --tracking-branch is unchanged, so this PR does not touch docs/cli.md or the argparse line 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 and AGENTS.md, README and scaffold-project.py --help: say that a --spec-path or --code-path that is, holds or lies inside a file the shape writes, and a --pin of spec, code or shape or of one product twice, are refused before anything is created, and name those three in the pin refusal's remediation, so an agent briefed from AGENTS.md can say so before it runs the scaffold (#288) #309 also edit.

Closes #283

🤖 Generated with Claude Code

Summary by Sourcery

Validate tracking branch names with Git before any scaffold or family resources are created, and fail clearly when the name is invalid or Git cannot verify it.

New Features:

• Validate scaffold and family tracking branch names with Git's branch-format rules before creating workspaces, remotes, or GitHub repositories, including during dry runs.
• Provide consistent, tool-specific refusals and remediation for invalid or unchecked branch names.,

Bug Fixes:

• Prevent invalid tracking branches from reaching repository initialization after partial local or remote resources have already been created.
• Make branch validation independent of the caller's working directory or repository state.

Enhancements:

• Centralize branch validation in the materialization utilities and distinguish invalid names from failures to query Git.

Tests:

• Add comprehensive coverage for invalid and accepted branch names, dry-run behavior, local and GitHub routes, broken working directories, Git failures, and shared helper behavior.

[brettheap]

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

[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-12T17:16:38.028745Z	d696acc	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: Didn't find any major issues. Swish!

Reviewed commit: a03abcf0f8

ℹ️ 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".

[brettheap]

(lane openRepoShape-2, 2026-10-12T16:42Z)

This lane reviewed its own PR #355 at a03abcf, read-only in its own detached worktrees, and authored nothing.

CHANGES NEEDED. One finding is for the fix round. Nothing has to land first.

Findings

1. P2, fix in this PR. scripts/shape_materialize.py:812 runs git check-ref-format --branch in the operator's working directory. Run from inside a repository git cannot open, both tools exit 2 and refuse the default main as "not a branch name git will create" (fatal: not a git repository). The case seen was a .git file naming a missing gitdir, or a malformed .git/config. Main scaffolds from the same directory. Asking git --git-dir=<empty temporary directory> check-ref-format --branch gives the same answer from every directory, and the PR's 157 tests still pass.
2. P3, follow-up issue. --tracking-branch +x is a branch git accepts. --dry-run exits 0, then the real run creates the remotes and dies at git push -q -u origin +x, because a leading + means force. The cause is scaffold-project.py:1024, :1139 and family.py:796, and main does the same.
3. P3, follow-up issue, not folded in. adopt-project.py --tracking-branch is never asked of git. plan and check pass a..b. scaffold-project.py holds --tracking-branch only to checked_value's alphabet, so a name git refuses as a branch (~, a..b, x.lock, a trailing /) passes --dry-run and, against GitHub, dies at the first git init -b after gh repo create has made all three repositories #283 promises the scaffold, and eleven open PRs touch adopt-project.py.
4. nits.
   • tests/test_tracking_branch_ref.py:244 does not isolate the dash rule.
   • :384 is a composite assert.
   • The PR body's "2 fail" for the answer != text mutant is 1 outside a checkout with a previous branch.

Tests

• Head: 710 passed, 1 failed. That failure is test_the_scaffold_refuses_with_no_elector, which is intermittent. It passed in a second head run and in four isolation runs, and this PR does not touch it.
• a03abcf + 28bdc84: 922 passed. A clean head rerun was clean up to 81%, where a usage checkpoint stopped it. The fix round's head is tested instead.
• The new file against main: 141 failed, 16 passed. 81 fail for the issue's reason and 60 on the missing helper.
• Mutants: three of mine and four of the implementer's, all killed.

Merges. git merge-tree of a03abcf against main 28bdc84 and every open head that touches its files is rc 0. Those heads are #314, #266, #373, #374, #376, #380, #381, #394 and #395. #314 needs the composition note's two-line test edit: with it, 261 passed. #373 composed gives 171 passed.

Full report: opensoft/brett-wip handoffs/xFactory/attachments/lane-openRepoShape-2/review355-a03abcf/final-report.md.

[brettheap]

(lane openRepoShape-2, 2026-10-12T17:01Z)

Fix round for the review of a03abcf, pushed as d696acc.

• P2 fixed (e5bbf65). Git is now asked git --git-dir=<empty temporary directory> check-ref-format --branch <name>, from that same directory. The default main therefore scaffolds again from inside a repository git cannot open (a .git file naming a gone gitdir, or a malformed .git/config). It also scaffolds from a removed directory, which --git-dir alone does not reach. A git that cannot answer for any name, such as under a malformed global config, now says the name "could not be checked", with a remedy about git. The helper finds this by asking git about main too, not by reading git's localised words.
• Test nits fixed (d696acc).
• Follow-ups, as the review asked: +x as a forced refspec, and adopt's --tracking-branch.

Tests: the new file is 161 tests. At a03abcf's code it gives 5 failed and 156 passed. At d696acc it gives 490 passed and 225 passed across the review's 15 files, and five new mutants are each killed by their own test. merge-tree is rc 0 against main 92e29d9 and #314 a5438a5. #314 still needs the composition note's edit, now pr314-test-edits-for-composition-v2.patch: 265 passed (104 + 161).

[brettheap]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d696acc920

ℹ️ 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]

Reject branch components whose lockfile exceeds NAME_MAX

For a single-component branch name of 251–255 characters (the new corpus explicitly includes 255), git check-ref-format --branch <branchname-shorthand> exits successfully, but the first commit after git init -b fails with fatal: cannot lock ref 'HEAD' because Git must create <name>.lock, which exceeds the common 255-byte component limit. Both GitHub workflows create their remote repository or repositories before that commit, so these accepted inputs still leave the empty remotes this change is intended to prevent. Validate by actually creating/locking the ref in the temporary repository, or reject components that cannot accommodate the .lock suffix.

Useful? React with 👍 / 👎.

[brettheap]

(lane openRepoShape-2, 2026-10-12T17:57Z)

This lane re-verified the fix round on its own PR #355 at d696acc, read-only in its own detached worktrees, and authored nothing.

MERGEABLE WITH NITS. CI is green on all three OSes at d696acc. Whichever of #314 and #355 lands second applies pr314-test-edits-for-composition-v2.patch.

Fix list

• The P2 is fixed. The new tests fail at a03abcf's code for the finding's reason (5 failed, 156 passed). In 12 of 13 probed environments (a missing gitdir, a bad config, a removed directory, a caller's GIT_DIR or GIT_WORK_TREE, no HOME), both tools exit as main does. Over 5,218 names, verdicts match a03abcf's, and nothing git init -b refuses is accepted.
• The test nits are fixed.
• Items 2 and 3 are follow-ups, as asked.

Nits (optional)

1. scripts/shape_materialize.py:864-868: a mkdtemp failure is refused as git "could not be run", with a remedy about git. Seen with a removed directory and a relative TMPDIR.
2. Two body claims are unpinned (the NUL's remedy, the control question's OSError); neither is reachable from the command line.
3. The body's "Composes with" heads are stale: 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 is now c6f441b, and shape_materialize.py: RULESET_HINT names the run's tracking branch where it named main, as the pull request's base and the ref the scaffold and the family holder pushed (#324) #373 is 741cbf2.

Tests

• With main 92e29d9 (19 files): 996 passed. With main 45e01f4 (8 files): 465 passed.
• Plus 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 c6f441b and the v2 patch: 265 passed (2 failed unpatched).
• Plus shape_materialize.py: RULESET_HINT names the run's tracking branch where it named main, as the pull request's base and the ref the scaffold and the family holder pushed (#324) #373 741cbf2: 178 passed.

Merges. merge-tree is rc 0 against main 45e01f4 and 36 of 37 open heads. #358's conflict in shape-doctor.py is its own.

Report: opensoft/brett-wip handoffs/xFactory/attachments/lane-openRepoShape-2/review355-a03abcf/reverify-d696acc.md.

[brettheap]

(lane openRepoShape-2, 2026-10-12T18:28Z)

Merged main after #314 landed: 6fdbe3d (main 3ef059c, merged with no textual conflict). As this PR's composition note planned, the merge commit also removes #314's branch-tilde and .inf rows from tests/test_scaffold_manifest_values.py (pr314-test-edits-for-composition-v2.patch). Both rows name a tracking branch that git refuses, and this PR now asks git. On the unpatched merge, those 2 rows fail and 104 pass.

Tests at 6fdbe3d

• The PR's test file, both manifest-values files and the scaffold files: 786 passed.
• The family files, decoding, test_cli_reference.py, test_repo_hygiene.py, test_gh_guard.py and test_agents_md_codes.py: 454 passed.
• tests/test_shape_doctor.py: 265 passed, 3 skipped.
• render-cli-reference.py --check is ok.

The body's "Composes with" section still describes #314 as open. This comment supersedes that row.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
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