[brettheap]

Lane: openreposhape-1 (openRepoShape-1)
Claim: #189 (comment)

The answers this records come from #166: plan asks which leg holds each source submodule, and check and execute hold the plan to that answer. Three things this builds on are on main:

• 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, as e4decfb (adopt-project.py: a plan that sends a source's .gitmodules to one leg and a submodule it registers to another, or keeps either in the root, is now a check finding and an execute refusal, and plan asks the one-leg question on .gitmodules itself (#166) #194).
• shape-doctor.py flags a submodule kept in a leg under a root-ruled path (.cursor, .specify/vendored) as MISPLACED, though #166 requires a leg for it #176's doctor read side, as 4ce9cb0 (shape-doctor.py: a submodule a leg keeps is a note naming it, never root by rule, so a #166 assembly with a submodule at .cursor or .specify/vendored is no longer MISPLACED (#176) #186).
• adopt-project.py plan writes a plan its own loader cannot parse when a source name holds a line break (the macOS Icon\r file), so check refuses the whole plan as yaml-unparsable with no entry to edit #199's escape table, as 4835fb4 (adopt-project.py: the plan writer escapes every character that is not printable from the one table repo_shape's reader resolves, so a source holding the macOS Icon\r no longer writes a plan check refuses, and a non-UTF-8 name no longer empties the plan (#199) #247).

This branch has merged main at 437a360, so its diff against main is #189 alone: 13 files, +1701 −158.

Head: b88a36e, gh pr update-branch's clean merge of main 437a360 into 71d3ce2. 71d3ce2 is gh pr update-branch's clean merge of main ec4a7a0 into 7adcc84. 7adcc84 is gh pr update-branch's clean merge of main 8782333 into 7db009e. 7db009e is gh pr update-branch's clean merge of main 6c2a371 into 120d6ed, and the re-verify found 120d6ed and 7db009e ready for their code and tests. 120d6ed is gh pr update-branch's clean merge of main d6df36b into 60a1a34. 60a1a34 is the merge of main 75052cb, which landed #188, into 136a37f. 136a37f is gh pr update-branch's clean merge of main dd8d0ea into 78034e7, and 78034e7 is the merge of main 53bee5b into 563ea16, which the re-verify found ready for its code and tests. 563ea16 and 3b7cb8f are gh pr update-branch's merges of main 3ef059c into 3b7cb8f and of 45e01f4 into 4b00597. 4b00597 is the merge of main 1f90a0f into 48bdbf9, and 48bdbf9 is gh pr update-branch's merge of main 28bdc84 into 70f4d29, which the re-verify found ready before that. Lane openRepoShape-2 reviewed e167d8b, and a second review covered 3e86200. The fix round since e167d8b is thirty-one commits, twenty-two of them merges of main; the Reviews section maps each finding to its commit.

Ruling

Brett Heap ruled that #189 goes ahead as a code change, with no OpenSpec change first: "merge #189 once its review passes and it's green". It had been held for that ruling, because it adds a submodules: record to every adopted project's project.yaml.

The record's schema is documented where this repository documents project.yaml:

• field by field, in the project's own validate-manifest.py, which checks it;
• in AGENTS.md, which says what execute writes and how the doctor judges by it.

What

Under #166, a human answers in the adoption plan which leg holds each submodule of the source. The plan is committed nowhere, so the assembly kept no trace of that answer. After #176, shape-doctor.py could only note a kept gitlink, as kept or as unverifiable, and a submodule added by hand looked exactly like one a person had placed. Now the answer is written into the assembly, and the doctor holds each submodule to it.

adopt-project.py: execute records the answer.

• submodule_record builds a submodules: block, and _commit_the_split appends it to the split's project.yaml, in the split commit.
  • It is built inside adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188's late-failure reporting, under the committing the split step. A failure while it is built, or after it is appended, is reported as any failure of that step is: one REFUSED line, what failed, and one notice of what the run left.
• One row per gitlink the plan keeps in a leg:
  • path: its path in the leg, which git filter-repo keeps from the source;
  • leg;
  • resolution:, the covering entry's reason, when it has one;
  • source_commit.
• The rows come from _answered_legs, the reading check already holds the plan to. By the time this runs, _refuse_what_check_finds has refused any gitlink that is uncovered, covered twice, unanswered or answered root.
• A gitlink answered drop is in no leg, so it gets no row.
• A comment above the block says where the record came from and that it confers nothing.
• Every path and reason is double-quoted by repo_shape.double_quoted, the writer adopt-project.py plan writes a plan its own loader cannot parse when a source name holds a line break (the macOS Icon\r file), so check refuses the whole plan as yaml-unparsable with no entry to edit #199 gave the reader. These all read back as themselves:
  • a submodule at null, true or 0001;
  • a name holding a no-break, ideographic or zero-width space, NEL, U+2028 or a carriage return;
  • a name holding a byte that is not UTF-8.
• A source with no submodule kept in a leg gets "": the project.yaml and the split it always got.

templates/assembly-root/scripts/validate-manifest.py: the record is checked, because something reads it.

• submodules is optional. When present it is a list of mappings, one per submodule a leg keeps.
• path is named by one row only, and is spelled the one way Git records a path (repo_shape.path_spelling_fault): relative, / between segments, and no segment empty, . or ...
  • ./x, x/, a//b and a/./b are findings. git update-index refuses each as Invalid path, so no submodule is ever at one.
  • A backslash and a drive letter are accepted. On POSIX each is a character of a name Git records (vendor/a\b, C:/x), and an adoption records a submodule at one, so refusing them would make execute's own manifest INVALID.
  • Non-ASCII names such as café, and names with a space such as my lib, are names too.
• leg is spec or code. resolution is optional text. source_commit is optional, and 40 hex when present.
• New finding codes: manifest-submodules, manifest-submodule-path, manifest-submodule-leg, manifest-submodule-resolution, manifest-submodule-commit.
• The docstring documents the record's schema, field by field.

scripts/repo_shape.py and scripts/shape_materialize.py: one spelling rule for both.

• path_spelling_fault is the segment half of scaffold-project.py accepts a non-canonical leg path such as --spec-path spec/, writes a stray submodule.spec/.url beside a registration that points at the work directory, and the new repository's recursive clone fails once the work directory is gone: #169's bug on the scaffold side #179's leg-path rule. It moves into repo_shape.py because a project carries that file and not shape_materialize.py.
• _spelling_reason asks it for the segments and keeps its own sentences, in its own order. At 4b00597 it gives main 1f90a0f's answer, byte for byte, for 87,482 strings, 33 named spellings among them, and tests/test_adopt_leg_paths.py and tests/test_scaffold_leg_paths.py pass unchanged.
• double_quoted's docstring now names the record among its writers.

shape-doctor.py: the placement row holds every submodule a leg keeps to the record.

• recorded_submodules reads project.yaml under adopt's own SUBMODULE_RECORD key, so the writer and the reader spell it once.
• The first row naming a path decides. That is how the project's validator reads the record: it accepts the first row and names the second recorded twice. A row whose leg: the validator refuses decides nothing, and the manifest row names it instead.
• In the leg recorded, the submodule is recorded, which counts as placed. The row is ok when every leg was read, every name in each could be read, nothing else is misplaced or in question, and every submodule is recorded.
• In the other leg, the submodule is misplaced. It is an entry in misplaced with rule: null, confidence: recorded, and a reason that names the record and carries the plan's resolution:. So:
  • the row is a FINDING;
  • it counts in MISPLACED (n path...), exit 1;
  • the placement plan lists it under paths:, where adopt-project.py's own _leg_findings accepts it.
• The leg's .gitmodules. Rule ambiguous-gitmodules asks which leg owns the submodules a .gitmodules registers.
  • Where the record places every submodule a leg keeps in that leg, the record is the answer. The file is placed, the leg's entry lists it under answered, and the row's reason says the record answered it. So a real adoption reads ok, where it read a note naming its own .gitmodules.
  • Beside a submodule no row names, or one the record puts in the other leg, the file stays the question it was. So it does in a leg holding a name the doctor cannot read, one with a control character or a byte that is not UTF-8. The doctor sets such a name aside before it reads its mode, so a submodule kept under one was never held to a row.
• Where no row names the gitlink, it keeps shape-doctor.py: a submodule a leg keeps is a note naming it, never root by rule, so a #166 assembly with a submodule at .cursor or .specify/vendored is no longer MISPLACED (#176) #186's kept or unverifiable note, word for word. A plan in which no row names any submodule keeps shape-doctor.py: a submodule a leg keeps is a note naming it, never root by rule, so a #166 assembly with a submodule at .cursor or .specify/vendored is no longer MISPLACED (#176) #186's legend.
• --json and the plan's submodules: block carry recorded_leg: on any submodule a row names.

AGENTS.md gains two passages, and tests/test_repo_hygiene.py moves its cap from main's 482 to 490 lines, with the paragraph that says why:

• "Adopting an existing repository" says execute writes the record.
• "Checking" point 4 says a submodule is judged by the record (rule: null, confidence: recorded), and that one moved on purpose stays MISPLACED, its row the human's to change.

Pinned files. scripts/repo_shape.py and templates/assembly-root/scripts/validate-manifest.py are copies a project pins.

• Every assembly root, and every family holder for repo_shape.py, reads upstream-changed for them in update-shape.py check until its estate re-pins with apply, as for The two copies of "is this the same repository" become ONE definition in scripts/repo_shape.py, and #149's case rule lands with the move (#155) #156 and repo_shape.py: load_yaml refuses a YAML file holding a non-UTF-8 byte as REFUSED yaml-unreadable naming the byte, so adopt-project.py check and execute and the validators no longer die with a UnicodeDecodeError traceback and exit 1 on a hand-edited plan or manifest (#192) #193. This repository holds no digest of either to update.
• apply copies every upstream-changed row together, and rolls back if the project's validators go red. So the new validator never lands beside an older repo_shape.py. If a local repo_shape.py is kept with apply --accept-local scripts/repo_shape.py, the new validator runs once, fails its import, and apply refuses as update-validators-red and rolls back.

What did not change. The proof is under Tests.

• A project with no submodule gets byte-identical doctor output.
• A project whose submodules no record names gets byte-identical doctor output, with or without a .gitmodules the policy asks about. That covers every assembly adopted before this change, and every submodule added by hand.
• A source with no submodule gets a byte-identical split, project.yaml and adoption plan.

Where the record lives. The issue offered two homes: a submodules: block in project.yaml, or a new contracts/submodule-placement.yaml. This uses project.yaml, for three reasons:

• AGENTS-shape.md calls the manifest "this project's own content". It is not pinned.
• visibility: (Accept internal visibility; resolve --pin under opensoft by default #6) was added the same way, as one optional field with a validator check. A new file would need a new kind: registered with the doctor, and a validator copied into every root, which every existing project would see as upstream-added.
• The record confers nothing, as every field of the manifest confers nothing.

Why (repro on main)

Measured on main 75052cb and on this branch at 60a1a34. The output is the same as at each earlier pair this round measured, back to main 4835fb4 and 2a93da8.

On main 75052cb the doctor has no way to consult an answer. Take a scaffolded project whose code leg keeps docs/theme as a gitlink; rule spec-governance puts that path in spec. A hand-written submodules: record changes nothing:

record=None  rc=0 verdict='COMPLIANT' placement=note docs/theme=unverifiable
record=code  rc=0 verdict='COMPLIANT' placement=note docs/theme=unverifiable
record=spec  rc=0 verdict='COMPLIANT' placement=note docs/theme=unverifiable

On this branch:

record=None  rc=0 verdict='COMPLIANT' placement=note docs/theme=unverifiable
record=code  rc=0 verdict='COMPLIANT' placement=ok docs/theme=recorded
record=spec  rc=1 verdict='MISPLACED (1 path)' placement=FINDING docs/theme=misplaced

On main 75052cb, an adoption records nothing. The source has .cursor as a registered submodule, and the plan answers both it and .gitmodules code. execute succeeds (adoption verified) and the split's project.yaml has no record. The doctor on the recursive clone says:

[as adopted]                     exit 0  COMPLIANT  placement note  submodules {'code/.cursor': 'kept'}
[plus vendor/lib added by hand]  exit 0  COMPLIANT  placement note  submodules {'code/.cursor': 'kept', 'code/vendor/lib': 'kept'}

Both rows also ask about code/.gitmodules. The answered submodule and the one nobody answered are indistinguishable.

On this branch the split's project.yaml ends:

submodules:
  - path: ".cursor"
    leg: code
    resolution: "editor rules the code leg's tooling reads"
    source_commit: "<the source commit>"

and the doctor says:

[as adopted]                     exit 0  COMPLIANT           placement ok       submodules {'code/.cursor': 'recorded'}
[plus vendor/lib added by hand]  exit 0  COMPLIANT           placement note     submodules {'code/.cursor': 'recorded', 'code/vendor/lib': 'kept'}
[record edited to leg: spec]     exit 1  MISPLACED (1 path)  placement FINDING  submodules {'code/.cursor': 'misplaced'}

• As adopted, the row's reason ends "project.yaml's submodules: answers the question the policy asks of code/.gitmodules: which leg owns the submodules it registers".
• Beside vendor/lib, which no row names, code/.gitmodules is a question again.

Tests

New and changed tests against main (26). Those marked ✱ are new or changed in the fix round.

• tests/test_shape_doctor.py:
  • test_a_submodule_in_the_leg_its_record_names_is_placed: recorded, row ok.
  • test_a_submodule_in_the_other_leg_from_its_record_is_misplaced ✱: FINDING, MISPLACED (1 path), exit 1, and a plan entry adopt-project.py's _leg_findings(plan, None) accepts.
  • test_a_submodule_no_record_names_is_still_the_note: shape-doctor.py: a submodule a leg keeps is a note naming it, never root by rule, so a #166 assembly with a submodule at .cursor or .specify/vendored is no longer MISPLACED (#176) #186's note.
  • test_a_record_row_the_validator_refuses_decides_nothing: a row saying leg: root is a manifest-submodule-leg FINDING and places nothing.
  • test_where_two_rows_name_one_path_the_first_decides ✱ (3 orders): the first row decides, the validator names submodules[1], and the verdict is red.
  • test_the_record_answers_the_question_about_the_gitmodules_beside_it ✱ (3 cases):
    • recorded in this leg: ok, no question, the clause;
    • recorded in the other leg: FINDING, still asked;
    • no record: note, still asked.
  • test_the_question_stays_where_the_record_does_not_place_every_submodule ✱ (3 cases): beside a hand-added or a misplaced submodule, or one whose name holds a control character (POSIX only), the .gitmodules is still asked.
  • test_a_name_the_record_spells_with_an_escape_still_names_its_submodule ✱: six names spelled with an escape are recorded, then MISPLACED (6 paths) once moved.
  • test_a_recorded_name_with_a_backslash_is_valid_and_placed ✱ (POSIX only).
  • End to end through adopt-project.py execute and a recursive clone:
    • test_an_adopted_submodule_is_recorded_and_placed ✱: COMPLIANT, and the row is ok with no question left.
    • test_an_adopted_submodule_whose_record_is_edited_is_misplaced.
    • test_a_submodule_added_by_hand_after_adoption_is_the_note.
• tests/test_adopt_submodules.py:
  • test_the_record_names_each_submodule_a_leg_keeps_with_its_answer.
  • test_a_source_with_no_submodule_kept_gets_no_record (2 cases).
  • test_a_recorded_name_reads_back_as_that_name ✱ (21 names, 10 of them new). Every record is whole lines.
  • test_a_name_that_is_not_utf8_is_spelled_and_still_written ✱: the name is written as \udce9 and reads back as itself.
  • test_adopt_moves_existing_gitmodules_with_its_dependency (changed): it asserts the record.
• tests/test_adopt_e2e.py: test_a_source_with_no_submodule_gets_no_submodule_record.
• tests/test_manifest_validator.py:
  • test_a_submodule_record_is_accepted.
  • test_a_submodule_record_row_that_says_nothing_is_a_finding ✱ (14 cases, 5 new spellings).
  • test_a_submodule_record_that_is_not_a_list_is_a_finding.
  • test_a_recorded_path_git_never_records_says_why ✱.
  • test_a_recorded_path_git_records_is_accepted ✱ (5 cases: backslash, drive letter, non-ASCII, code-point escape, space).
  • test_the_recorded_path_rule_refuses_what_git_will_not_record ✱ (13 paths, 2 POSIX only): the rule is held to git update-index itself.
• tests/test_windows_paths.py: test_a_double_quoted_scalar_resolves_one_escape_at_a_time ✱, with 8 rows for the escapes the record relies on.
• tests/test_repo_hygiene.py: test_agents_md_is_short_enough_to_be_read ✱, the cap at 490.
• tests/test_adopt_late_failure.py, adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188's: its split_arguments hands _commit_the_split a SplitPlan(), a dict with entries = (), where it handed {}, which has no entries for the record to be built from. Its sources keep no submodule, so no test of it changes, and its 86 tests pass with git-filter-repo on PATH.

Revert table, fix round. Each mutation was applied alone, to a fresh clone of 60a1a34, and all 15 tests the round added or changed (83 cases) were run against it. Every case gives the same outcome at 4b00597, and did at 70f4d29 and a557f2a: 2,241 outcomes (27 runs of 83 cases) each time, none different. The 82 cases and 26 mutations it shares with the table at 27d039b give the same outcome there. They do so at 3e86200, f38d543, e334f50, a01ab02 and 2f5cda9 too, and at 2a93da8 before that. Each time 2,132 outcomes (26 runs of 82 cases) were compared, and none differed. F1's case and its revert, M29, are new.

• Unmutated: 83 passed.
• Every case the round added fails under at least one mutation.
• The cases those tests had before the round are the ones the first table, below, covers.

Mutation	Fails
M1 P2-1 reverted: the test calls _leg_findings without tree	..._other_leg_from_its_record_is_misplaced
M2 the reader without code-point escapes (dbf8887's)	15 cases: the reader table's 4 code-point rows, the 8 unprintable record names, the not-UTF-8 name, the doctor's escaped names, the validator's code-point-escape row
M3 the writer spells as dbf8887's _quoted did (ascii(), \xe9)	..._not_utf8_is_spelled_and_still_written
M4 the reader resolves an escape with too few digits	reader row \x4
M5 the reader does not check the digits are hex	reader row \xzz
M6 the reader resolves past U+10FFFF	reader row \U00110000
M7 code points resolved in a second pass	reader rows \\x41 and \U00110000; record name \x41
M8 the validator's path check back to e167d8b's	the 5 new spellings; ..._says_why
M9 the rule accepts an empty or . segment	4 new spellings; ..._says_why; git paths ./x, x/, a//b, a/./b
M10 the rule accepts an absolute path	absolute-path; git path /x
M11 the rule accepts the top itself	the-leg-itself; git path .
M12 the rule accepts ..	dotdot-path; git path a/../b
M13 the rule refuses a backslash or a drive letter	accepted backslash and drive-letter; git paths a\b and C:/x; the doctor's backslash test
M14 the rule refuses a non-ASCII name or a space	accepted non-ascii, code-point-escape and space; git paths my lib and café; the doctor's escaped names
M15 the rule refuses every path	21 cases, among them git paths x and vendor/x
M16 MU12: the last row decides	all 3 orders
M17 e167d8b's reading: a refused-leg row skipped before it claims the path	refused-leg-then-code
M18 P3-3 reverted	recorded-in-this-leg; the end-to-end adopted test
M19 90608b8's ANY	all 3 cases of ..._does_not_place_every_submodule
M20 a leg's .gitmodules answered whenever it keeps a submodule	recorded-in-the-other-leg and no-record; all 3 cases of ..._does_not_place_every_submodule
M21 the answered clause never said	recorded-in-this-leg; the end-to-end adopted test
M22 the writer leaves NEL and U+2028 raw	record names nel\x85x and line\u2028sep; the doctor's escaped names
M23 the AGENTS.md cap back at main's 482	the cap test
M24 the record spelled by y	record names null and true
M25 the writer leaves a carriage return raw	record name cr\rx
M29 F1 reverted: the record answers a leg's .gitmodules beside a name the doctor could not read	one-whose-name-cannot-be-read

Revert table, first round (at e167d8b, the 16 tests the record first came with). Each mutation was applied alone; with none, 36 passed.

Mutation	Fails
M1 shape-doctor.py's change reverted	6: every doctor test but the validator-refused row
M2 adopt-project.py's change reverted	24: every doctor test, every record test in test_adopt_submodules.py, and the dependency test
M3 validate-manifest.py's change reverted	11: the validator-refused row, the 9 row cases, and the not-a-list case
M4 held_clauses emits an empty clause	the other-leg MISPLACED test (reason ended ; with nothing)
M5 an empty record written for a source with none kept	..._kept_gets_no_record (2), ..._gets_no_submodule_record (e2e)
M6 path written unquoted	..._reads_back_as_that_name (2 of 11), ..._not_utf8_...
M7 the doctor accepts a row with any leg:	the validator-refused row
M8 the validator refuses a text resolution:	6: the placed, adopted and hand-added doctor tests, the dependency test (2), ..._record_is_accepted
M9 a misplaced submodule is not counted	both MISPLACED tests
M10 a recorded row is never ok	the placed test

Round trip at 60a1a34, against main's reader. Every name went through submodule_record and back through repo_shape.parse_yaml, path and reason both:

• 905 characters: every code point to U+02FF, the nine line breaks str.splitlines takes, and the 128 surrogates a byte that is not UTF-8 is kept as.
• Five shapes each, so 4,525 names: 0 mismatches.
• Seven more characters (U+2029, U+3000, U+200B, U+FEFF, U+1F600, U+E0001, U+10FFFF), five shapes each: 0 mismatches.
• 48 names aimed at what scripts/repo_shape.py reads ? a: b in a flow mapping as the literal key ? a, where the block reader refuses explicit keys, and refuses {a: } and {a:} as not a flow collection: '' instead of reading {'a': None} #252 and scripts/repo_shape.py: the double-quoted reader that #247 adds (fix/adopt-plan-linebreak-names, not yet on main) resolves \x00 inside a block-scalar KEY, and _parse_mapping splits the NUL-joined sentinel record, so "a\x00b": | reads as the key a with the body b<NUL>text where main reads the literal key a\x00b #248 changed in the reader since 39ac59c, five shapes each, so 240 records: 0 mismatches. They include ? a, {? a: b}, {a: }, |, a: |, a NUL, and the old block-scalar sentinel.
• 39 names aimed at where scripts/repo_shape.py treats a quote character in the MIDDLE of a plain scalar as opening a quote, so k: [it's, a] reads ["it's, a"] where its block twin reads ["it's", "a"], k: it's fine # note keeps the comment in the value, and #244 turns k: [a"b\", c] from right (by accident) into one item #249 and scripts/repo_shape.py _scalar takes any text that starts and ends with a quote for a quoted scalar and anything else for plain text, so an unterminated "abc reads as "abc, - "a\" reads as a\, and "a" b "c" reads as a" b "c, where PyYAML refuses each #250 now start and end a quoted scalar, five shapes each, so 195 records: 0 mismatches. They include it's, a"b, "abc, a" b "c, a' b 'c, "a\", a\, [it's, a], note "[1]" and "Brett Heap.

Byte identity, this branch against main 75052cb. One committed standard; only shape-doctor.py and adopt-project.py are swapped between runs.

doctor clean                  text      rc=0  identical=True
doctor clean                  --json    rc=0  identical=True
doctor clean                  plan-run  rc=0  identical=True
doctor clean                  plan-file rc=-  identical=True
doctor misplaced+question     text      rc=1  identical=True
doctor misplaced+question     --json    rc=1  identical=True
doctor misplaced+question     plan-run  rc=1  identical=True
doctor misplaced+question     plan-file rc=-  identical=True
doctor submodules,no-record   text      rc=1  identical=True
doctor submodules,no-record   --json    rc=1  identical=True
doctor submodules,no-record   plan-run  rc=1  identical=True
doctor submodules,no-record   plan-file rc=-  identical=True
doctor +gitmodules,no-record  text      rc=1  identical=True
doctor +gitmodules,no-record  --json    rc=1  identical=True
doctor +gitmodules,no-record  plan-run  rc=1  identical=True
doctor +gitmodules,no-record  plan-file rc=-  identical=True
split tree new=c547daf55e0bd35ce62413dc9ba1efd9382762ba old=c547daf55e0bd35ce62413dc9ba1efd9382762ba identical=True
split project.yaml identical=True (sha256 new 353c86800390eaf6)
adoption plan identical=True

submodules,no-record stages .cursor, docs/theme and vendor/lib gitlinks in the code leg with no record, which are #186's cases. +gitmodules,no-record adds the leg's .gitmodules.

The last nineteen merges of main were a01ab02, of 5751460; e334f50, of d94d155; f38d543, of c3a9645; 3e86200, of 6d8d88b; 27d039b, of 71b58a1; a557f2a, of a1b3a4b; 70f4d29, of f795cf7; 48bdbf9, of 28bdc84, made by gh pr update-branch; 4b00597, of 1f90a0f; 3b7cb8f, of 45e01f4, and 563ea16, of 3ef059c, both made by gh pr update-branch; 78034e7, of 53bee5b; 136a37f, of dd8d0ea, made by gh pr update-branch; 60a1a34, of 75052cb; and 120d6ed, of d6df36b, 7db009e, of 6c2a371, 7adcc84, of 8782333, 71d3ce2, of ec4a7a0, and b88a36e, of 437a360, all five made by gh pr update-branch. Among what they brought are:

• adopt-project.py: a .gitmodules with a key with no value passes check when the tip holds no submodule but the history does, and execute dies in git fast-export after both legs are pushed #195's .gitmodules refusal, and adopt-project.py check accepts a .gitmodules value git's submodule reader rejects (update = bogus, update =, update = !cmd, shallow = maybe, fetchRecurseSubmodules = bogus), so plan ok is followed by execute dying in git filter-repo after both leg remotes exist, whether the tip or only the history holds the gitlink #215's for a value git's submodule reader refuses;
• adopt-project.py check accepts plan paths execute refuses as unsafe-value (a space or a non-ASCII character), so plan ok is followed by a refusal and #166's split instructions can name entries execute will refuse #196's plan-unsafe-path, for an entry path execute would not extract as it stands, and adopt-project.py check passes a plan that keeps a plain file at a directory the shape writes into (.github, contracts, scripts), and execute dies in a NotADirectoryError or FileExistsError traceback after both legs are pushed #263's plan-root-blocks-shape and adopt-project.py check passes a plan that keeps the source's own shape/ in the root, and place() then writes the shape's collision copy onto it after both legs are pushed: a real shape/README.md is overwritten while execute prints "nothing was overwritten" and ends adopt-lost, and a shape/Makefile/ directory or a file named shape is a traceback #262's plan-root-blocks-shape-copy, for a path the plan keeps in the root where the shape writes;
• 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's plan-unwritable-value and adopt-unwritable-value, for a value execute writes into a file that a file cannot hold;
• scripts/repo_shape.py reads ? a: b in a flow mapping as the literal key ? a, where the block reader refuses explicit keys, and refuses {a: } and {a:} as not a flow collection: '' instead of reading {'a': None} #252's, scripts/repo_shape.py: the double-quoted reader that #247 adds (fix/adopt-plan-linebreak-names, not yet on main) resolves \x00 inside a block-scalar KEY, and _parse_mapping splits the NUL-joined sentinel record, so "a\x00b": | reads as the key a with the body b<NUL>text where main reads the literal key a\x00b #248's, scripts/repo_shape.py treats a quote character in the MIDDLE of a plain scalar as opening a quote, so k: [it's, a] reads ["it's, a"] where its block twin reads ["it's", "a"], k: it's fine # note keeps the comment in the value, and #244 turns k: [a"b\", c] from right (by accident) into one item #249's and scripts/repo_shape.py _scalar takes any text that starts and ends with a quote for a quoted scalar and anything else for plain text, so an unterminated "abc reads as "abc, - "a\" reads as a\, and "a" b "c" reads as a" b "c, where PyYAML refuses each #250's reader;
• shape-doctor.py reads only project.yaml at a root that also carries a family.yaml, so an assembly root whose family.yaml declares two unmounted members is COMPLIANT, and its manifest kinds row says that kind has a registered validator, which is never run #211's manifest kinds finding;
• adopt-project.py plan raises UnicodeEncodeError in its terminal report, after the plan file is written, for a printable name stdout cannot encode (日本.md under cp1252, as on a redirected Windows stdout), so plan exits 1 before plan written to #214's stdout escaping;
• adopt-project.py check and execute print a source path raw in a FINDING, so a \r, \n, \x85, U+2028 or ESC in a name overwrites, splits or escapes the line on a terminal, where plan's questions spell the same path with _spelled #212's finding spelling;
• shape-doctor.py calls an assembly root whose project.yaml does not parse (a merge conflict) NOT A SHAPE ROOT, exit 2, and its NEXT line tells the reader to adopt that assembly root in place while the Triad row calls it a single repository #205's verdict for a manifest that does not load;
• shape-doctor.py validator_row falls back to the standard's TEMPLATE validator when a root carries no copy of its own, and prints that path as the NEXT command without the PYTHONPATH it runs it under, so pasting the manifest, pins or family row's NEXT dies with ModuleNotFoundError: No module named 'repo_shape' and exit 1, the code a validator uses for a finding #238's and shape-doctor.py: after #238 the doctor runs a root's OWN validator with the operator's PYTHONPATH still in the child's environment, so for an operator who exports one that reaches a repo_shape.py the manifest row of a root that lost its own scripts/repo_shape.py says ok ... passes again, the false pass #238 removed, where the project's own gate in CI fails on ModuleNotFoundError: No module named 'repo_shape' #306's PYTHONPATH for a validator, printed in its row's next step and given to its child, and bump-leg.py (a real bump) and update-shape.py apply run the project's own validators as children that cannot print its display name on a cp1252 stdout, so a project named 日本 is refused and rolled back as bump-leg-validators-red or update-validators-red under PYTHONIOENCODING=cp1252:surrogateescape, and the refusal blames the validators #254's PYTHONIOENCODING for a project's validators;
• adopt-project.py execute clones the source with the operator's init.templateDir applied, so a template holding modules/spec and modules/code makes the leg mounts' --force (#200) reactivate those planted stores: both gitlinks pushed on the split branch are a stranger's commit, the VERIFICATION still says adoption verified because it checks a mount is present and not which commit, and the recursive clone of the result exits 128 #243's assembly cloned with no git template, and its adopt-mount-commit verification;
• adopt-project.py plan's cross_leg_references passes a spec directory's name to git grep -F with no -e and the code entries as glob pathspecs, so a spec directory named -notes or a code entry named :cache silently drops the follow-up, a code entry named * names files that are not in the code leg, a name outside ASCII is printed in git's quoted spelling, and a spec directory named -O<cmd> is run as git grep's pager when a tracked file holds the planned commit's hash #216's literal paths in plan's follow-up git grep, and adopt-project.py and scaffold-project.py substitute the template placeholders one after another, so a free-text value holding another placeholder's token is expanded (--elected-by '{{SPEC_PATH}}' is recorded as elected_by: "spec") or, after the legs are pushed, refused as template-unsubstituted with "a defect in the substitution table of the tool you ran" #260's one-pass render;
• 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's AGENTS.md lines on the scaffold's two path-collision refusals;
• adopt-project.py keeps a source submodule's relative url = ../x unchanged in the leg, where git resolves it against the leg's remote, so execute says adoption verified and the assembly's recursive clone fails unless the dependency happens to sit beside the leg #190's check of a relative .gitmodules url a leg keeps, refused before any leg exists where the source's remote and the leg's resolve it differently;
• AGENTS.md step 7 tells an agent that a non-zero adopt-project.py execute exit is to fix the plan and re-run into fresh legs, but in GitHub mode execute exits 2 with the split pushed when gh pr create is refused, and exits 2 after adoption verified when the topic will not set, so following step 7 abandons a pushed adoption whose own exit is a command to run by hand #304's verification before execute exits on a refused gh pr create, and step 7 keyed to the exit it prints;
• 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's legs and members NEXT, a script-free git submodule update;
• update-shape.py rewrite_shape_pin and bump-leg.py rewrite_pin find tree_sha256: by exactly two leading spaces and replace whole lines, so a contracts/<role>-pin.yaml whose digests: child is indented four is refused as hand-edited, and a trailing comment on a commit: or tree_sha256: line is dropped by every pin rewrite, rewrite_manifest included #323's pin rewrites, which keep each line's own layout;
• adopt-project.py plan writes leg: spec with no question for a source path that execute will refuse (-notes.md), so the answer check or execute then rejects is one plan chose for the person, and root or drop is offered for that entry nowhere #319's plan question about every source path execute will not extract as it is named;
• shape-doctor.py: manifest kinds counts a contracts/*.yaml that declares a registered kind as validated though that kind's validator never runs on this kind of root, so a contracts/family.yaml in an assembly root, or a contracts/project.yaml in a family holder, is ok and COMPLIANT where the same bytes at the root are a FINDING #327's manifest kinds, which counts a registered kind validated only on a kind of root that runs its check;
• update-shape.py apply --branch --pr re-run: _awaits_its_pull_request reads the pin from HEAD while the "nothing to do" test reads the working tree, so a re-run over a tree that an in-place apply --at C already wrote pushes HEAD and titles the pull request with C #333's --pr re-run, family.py add does not ask whether the member's project.yaml id is one the family already pins, so adding a repository renamed at the forge (same id, new name) commits a holder that validate-family.py then refuses as member-duplicate-id #330's member-duplicate-id and family.py _checked_member's MEMBER_RE admits an owner or a project that begins with ., _ or - (testorg/_Zed, testorg/.Zed, testorg/-Zed, _org/Zed, .org/Zed), which the holder's own validate-family.py refuses with its QUALIFIED_RE, so add exits 0 with a commit whose new row its gate then reports as member-repository #366's member-malformed;
• tests: nothing ties a refusal code AGENTS.md spells to the tool that prints it, so now that #309 has landed (7491530), a misspelt scaffold-leg-path-collides or scaffold-pin-collides in AGENTS.md, or either code renamed in scaffold-project.py, passes every test, and an assistant briefed from AGENTS.md relays a code no tool prints #348's tests/test_agents_md_codes.py, which holds every code-shaped name in AGENTS.md to a string a shipped tool prints;
• 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 and adopt-project.py and scaffold-project.py accept values the new project's own validate-manifest.py refuses (a blank --elected-by or --reference, --elected-on 2026-W41-6 or 20261011 on Python 3.11+, --org test+org, a plan's visibility: secret), so adoption verified or a scaffold exit 0 is followed by a failed first bootstrap; and plan admits a 251-255-character --project that check refuses #261's plan-manifest-invalid, which asks the project's validate-manifest.py about the manifest's values before anything exists;
• repo_shape.py: a flow collection with an unmatched ] or } is read, not refused, so k: {a"]:} reads {'a"]': None} since #284 (a quote toggle used to swallow the :}) and k: [a]] reads ['a]'], where PyYAML refuses both #301's refusal of a bracket in a plain flow scalar, and validate-manifest.py accepts a display name holding a lone surrogate (name: "a\ud83db") and then raises UnicodeEncodeError printing it, so make validate and shape-doctor.py fail on a traceback instead of a finding while bump-leg.py and update-shape.py apply pass the same project once #254 lands #280's finding for a name: holding a lone surrogate;
• the validator rows of 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, shape-doctor.py: the pins row says "ok ... the project's own scripts/validate-pins.py passes" for a project that pins a neutral product though that validator SKIPPED the product's digest after a real gh api call, so the command documented to fetch nothing fetched from GitHub, and a digest nobody rechecked reads as ok under a COMPLIANT verdict #297 and shape-doctor.py: for a root whose project.yaml does not load AND whose scripts/repo_shape.py is gone, the manifest row's NEXT promises its validator "refuses it the same way until it loads", but pasted it dies on ModuleNotFoundError: No module named 'repo_shape', exit 1, so the person is sent to a command that cannot say what the row quoted #298, which say when a validator crashed;
• 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's refusal of a leg pin or workflow file that is not UTF-8, and 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's of one this user cannot open;
• shape_materialize.py force_stage's docstring says it has TWO CALLERS and that only update-shape.py apply --add calls it alone, and stage_written's says the same, though since #242 family.py's _commit_one (every add, bump and remove commit) and cmd_bump call it alone too, so the next change to its contract is reasoned about with half of its alone-callers missing #369's contract for force_stage and stage_written, family.py bump (and add, remove) take no --dry-run, though the file's exit-code paragraph says a dry run prints and exits 0 and bump-leg.py has one, so the only way to see what a bump would pin is to run it: fetch, check the member out at --to and rewrite family.yaml #326's add --dry-run, and adopt-project.py: _elector and _remote_repository read git config user.name and the origin URL through git_out, which decodes strictly, so a name or URL that is not UTF-8 ends plan (and, for the URL, check and execute) in a UnicodeDecodeError traceback, exit 1, naming neither the git setting nor the flag that avoids it #292's _elector and _remote_repository for a user.name or an origin URL that is not UTF-8;
• shape-doctor.py check_shape_currency takes every refusal update-shape.py prepare raises over the ROOT's own contracts/shape-pin.yaml (a merge conflict, a commit: that is not 40 hex, a deleted file) for this checkout failing to ask, so the verdict is CANNOT ANSWER, exit 3, outranking INVALID, and its NEXT git -C <standard> fetch --all blames the standard for a fault in the repository #237's INVALID for a root's own contracts/shape-pin.yaml that does not read as a pin, and The assembly root's scripts/validate-pins.py ends in a FileNotFoundError traceback, exit 1, a finding's code, when git is not on PATH, because recorded_gitlink reaches repo_shape.git_out and nothing catches OSError, where the file's own exit codes give 1 to drift and 2 to a question that could not be asked: the sibling of #368, whose fix is ruled into validate-family.py only #412's git-not-runnable;
• adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188's, adopt-project.py execute exits 2 with nothing on stderr when git filter-repo fails, after both leg remotes exist: _build_the_legs swallows CommandFailed on the premise that run already reported it, and run only raises #171's and RULESET_HINT advises push -u origin ... from an extracted leg whose origin filter-repo removed, and says "listed above" of lines a combined log prints after it #177's late-failure reporting: once a leg repository exists, every failure flushes stdout, then prints REFUSED <step>., what failed and one notice of what the run left;
• templates/assembly-root/scripts/bootstrap.py and templates/family-root/scripts/bootstrap.py: main prints the manifest's name with a plain print before any step runs, so name: "a\ud83db" (a lone surrogate) ends make bootstrap in a UnicodeEncodeError traceback, exit 1 (make: 2), and the validator that names the problem is never reached; a valid name the stdout cannot encode ends the same way #391's escaping in both roots' scripts/bootstrap.py, through spelled and escape_unencodable_stdout, which it adds to scripts/repo_shape.py: make bootstrap no longer ends in a traceback when a manifest value holds a lone surrogate or a character its stdout cannot encode;
• update-shape.py read_pin and the pinned validate-pins.py and validate-family.py: iterate pin.get("files") or [] without asking for a list, so a shape pin with files: 5 or files: true ends shape-doctor.py, update-shape.py check and apply and the project's own validator in TypeError: ... is not iterable, exit 1, with no refusal naming the pin #290's refusal of a shape pin whose files: is not a list: update-shape.py refuses it as update-pin-row, both roots' pinned validators report shape-pin-row, and shape-doctor.py reads it as pinning nothing, where files: 5 ended check, apply, the doctor and a project's validator in a TypeError.

plan-manifest-invalid validates the template manifest, rendered with the plan's values, before anything exists, and execute appends the record to the split's project.yaml only later, in _commit_the_split, so that check never sees the record.

There were eight conflicts, and each kept both sides:

• shape-doctor.py's EXIT CODES, where each side had added a clause to exit 1's list. Only the docstring's first line reaches --help.
• scripts/shape_materialize.py's from repo_shape import, where scripts/repo_shape.py treats a quote character in the MIDDLE of a plain scalar as opening a quote, so k: [it's, a] reads ["it's, a"] where its block twin reads ["it's", "a"], k: it's fine # note keeps the comment in the value, and #244 turns k: [a"b\", c] from right (by accident) into one item #249 and scripts/repo_shape.py _scalar takes any text that starts and ends with a quote for a quoted scalar and anything else for plain text, so an unterminated "abc reads as "abc, - "a\" reads as a\, and "a" b "c" reads as a" b "c, where PyYAML refuses each #250 import double_quoted and this branch imports path_spelling_fault and its codes.
• adopt-project.py's module docstring, where adopt-project.py execute clones the source with the operator's init.templateDir applied, so a template holding modules/spec and modules/code makes the leg mounts' --force (#200) reactivate those planted stores: both gitlinks pushed on the split branch are a stranger's commit, the VERIFICATION still says adoption verified because it checks a mount is present and not which commit, and the recursive clone of the result exits 128 #243 ends the execute paragraph with "each at the commit pushed to its leg" and this branch adds its sentence about the record. Both stand, adopt-project.py execute clones the source with the operator's init.templateDir applied, so a template holding modules/spec and modules/code makes the leg mounts' --force (#200) reactivate those planted stores: both gitlinks pushed on the split branch are a stranger's commit, the VERIFICATION still says adoption verified because it checks a mount is present and not which commit, and the recursive clone of the result exits 128 #243's first. The docstring is not in --help.
• tests/test_repo_hygiene.py's AGENTS.md cap. 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 moved it from 464 to 477 and this branch from 464 to 472, each with a paragraph saying why. AGENTS.md merged cleanly at 485 lines, main's 477 and this branch's eight. So the cap is 485: 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's paragraph is kept word for word, and this branch's follows it as "477 -> 485".
• tests/test_repo_hygiene.py's AGENTS.md cap again, in 4b00597. AGENTS.md step 7 tells an agent that a non-zero adopt-project.py execute exit is to fix the plan and re-run into fresh legs, but in GitHub mode execute exits 2 with the split pushed when gh pr create is refused, and exits 2 after adoption verified when the topic will not set, so following step 7 abandons a pushed adoption whose own exit is a command to run by hand #304 moved it from 477 to 481 for its four lines in step 7, and this branch's eight lines make the merged AGENTS.md 489. AGENTS.md step 7 tells an agent that a non-zero adopt-project.py execute exit is to fix the plan and re-run into fresh legs, but in GitHub mode execute exits 2 with the split pushed when gh pr create is refused, and exits 2 after adoption verified when the topic will not set, so following step 7 abandons a pushed adoption whose own exit is a command to run by hand #304's paragraph is kept word for word, this branch's follows it as "481 -> 489", and the cap is 489. Step 7 and this branch's paragraph after it are both true as they stand together.
• tests/test_manifest_validator.py's imports, in 78034e7. repo_shape.py: a flow collection with an unmatched ] or } is read, not refused, so k: {a"]:} reads {'a"]': None} since #284 (a quote toggle used to swallow the :}) and k: [a]] reads ['a]'], where PyYAML refuses both #301's and validate-manifest.py accepts a display name holding a lone surrogate (name: "a\ud83db") and then raises UnicodeEncodeError printing it, so make validate and shape-doctor.py fail on a traceback instead of a finding while bump-leg.py and update-shape.py apply pass the same project once #254 lands #280's tests add import os, import subprocess and import sys, and this branch had added import os and import sys. The merge keeps all three, once each.
• adopt-project.py's _commit_the_split, in 60a1a34. adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188 puts every step after the legs exist inside one try, with a step name and its late-failure report, and this branch appends the record there. The merge takes adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188's function whole and builds the record inside its try, under the committing the split step, where the materializer is handed what to append. Nothing else in the function differs from main's. tests/test_adopt_late_failure.py's split_arguments passes a SplitPlan() where it passed {}, as An adopted assembly records nothing about which leg a human chose for a source submodule, so shape-doctor.py cannot verify a kept gitlink's placement and can only note it; adopt should write the plan's submodule answers into the assembly #189's first review planned for whichever of the two landed second.
• tests/test_repo_hygiene.py's AGENTS.md cap a third time, in 60a1a34. adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188 moved it from 481 to 482 for its line in step 7, and AGENTS.md merged cleanly at 490 lines, main's 482 and this branch's eight. AGENTS.md step 7 tells an agent that a non-zero adopt-project.py execute exit is to fix the plan and re-run into fresh legs, but in GitHub mode execute exits 2 with the split pushed when gh pr create is refused, and exits 2 after adoption verified when the topic will not set, so following step 7 abandons a pushed adoption whose own exit is a command to run by hand #304's and adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188's paragraphs are kept word for word, this branch's follows them as "482 -> 490", and the cap is 490. Step 7, as adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188 words it, and this branch's paragraph after it read true together.

Seven checks:

• The doctor's judgement by the record is unchanged. The check uses one standard, and swaps only shape-doctor.py and adopt-project.py between the commits compared. It covers a code leg's docs/theme with no row, and with a row saying code, spec or root. It covers .cursor beside the .gitmodules that registers it, recorded in code, then with vendor/lib added by hand, then recorded in spec. And it covers a real adoption: as adopted, with vendor/lib, and with its row edited to spec. The text, --json and --placement-plan output are byte-identical in all 40 comparisons, for each merge that changes either file: 2f5cda9 to a01ab02, a01ab02 to e334f50, e334f50 to f38d543, 3e86200 to 27d039b, e0df56e to a557f2a, a557f2a to 70f4d29, 70f4d29 to 48bdbf9, 48bdbf9 to 4b00597, 4b00597 to 3b7cb8f, 3b7cb8f to 563ea16, 563ea16 to 78034e7, 78034e7 to 136a37f, 136a37f to 60a1a34, 60a1a34 to 120d6ed, 120d6ed to 7db009e, 7db009e to 7adcc84, and 71d3ce2 to b88a36e. The merge from f38d543 to 3e86200 changes neither file, but it does change the reader. So for it, scripts/repo_shape.py and scripts/shape_materialize.py are swapped as well, and the placement row and the plan file are compared: identical in all 20 comparisons. Every merge since then but 3b7cb8f, 60a1a34, 7adcc84 and b88a36e changes scripts/repo_shape.py or scripts/shape_materialize.py, so those 20 were compared for each of the fifteen merges since then, those four included. Both files were swapped, with update-shape.py, scripts/bump-leg.py and scripts/family.py, which import scripts/shape_materialize.py: identical in all 20 each time.

• adopt-project.py: a .gitmodules with a key with no value passes check when the tip holds no submodule but the history does, and execute dies in git fast-export after both legs are pushed #195's, adopt-project.py check accepts a .gitmodules value git's submodule reader rejects (update = bogus, update =, update = !cmd, shallow = maybe, fetchRecurseSubmodules = bogus), so plan ok is followed by execute dying in git filter-repo after both leg remotes exist, whether the tip or only the history holds the gitlink #215's, adopt-project.py check accepts plan paths execute refuses as unsafe-value (a space or a non-ASCII character), so plan ok is followed by a refusal and #166's split instructions can name entries execute will refuse #196's, adopt-project.py check passes a plan that keeps a plain file at a directory the shape writes into (.github, contracts, scripts), and execute dies in a NotADirectoryError or FileExistsError traceback after both legs are pushed #263's and 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's refusals and the record agree. Eleven sources went through plan, check and execute, under main 1f90a0f and under 4b00597, and again under main 75052cb and under 60a1a34. check and execute pass and refuse the same sources, with the same findings, in both:

  • adopt-project.py: a .gitmodules with a key with no value passes check when the tip holds no submodule but the history does, and execute dies in git fast-export after both legs are pushed #195's own shape; a tip submodule beside ignore with no value; and adopt-project.py check accepts a .gitmodules value git's submodule reader rejects (update = bogus, update =, update = !cmd, shallow = maybe, fetchRecurseSubmodules = bogus), so plan ok is followed by execute dying in git filter-repo after both leg remotes exist, whether the tip or only the history holds the gitlink #215's update = bogus beside a tip submodule and shallow = maybe beside one only the history holds: all refused, with no leg and no split;
  • a tip submodule answered code beside a file contracts the plan keeps in the root, where the shape writes a directory, the same submodule beside -notes.md answered code, and the same with the plan's elected_by edited to hold a byte that is not UTF-8: refused as plan-root-blocks-shape, plan-unsafe-path and plan-unwritable-value, with no leg and no split;
  • a history-only submodule beside a readable .gitmodules: adopted, with no record;
  • a tip submodule answered code, the same answered spec, and one beside another that only the history holds: adopted, and only the branch writes the record. It names the tip's submodule alone. adopt-project.py execute clones the source with the operator's init.templateDir applied, so a template holding modules/spec and modules/code makes the leg mounts' --force (#200) reactivate those planted stores: both gitlinks pushed on the split branch are a stranger's commit, the VERIFICATION still says adoption verified because it checks a mount is present and not which commit, and the recursive clone of the result exits 128 #243's new check, that each mount is at the commit pushed to its leg, passes every adopted case on both.

  check and the record both read the kept submodules as _kept_in_a_leg(_answered_legs(...)) over the tip's gitlinks. execute refuses each of these findings before any leg exists and before the record is written. The doctor's placement plan carries the submodules: rows and has a legs: list. adopt-project.py check passes a plan that keeps the source's own shape/ in the root, and place() then writes the shape's collision copy onto it after both legs are pushed: a real shape/README.md is overwritten while execute prints "nothing was overwritten" and ends adopt-lost, and a shape/Makefile/ directory or a file named shape is a traceback #262's and adopt-project.py check passes a plan that keeps a plain file at a directory the shape writes into (.github, contracts, scripts), and execute dies in a NotADirectoryError or FileExistsError traceback after both legs are pushed #263's check is asked only beside a legs: mapping, so _leg_findings(plan, None) still accepts that plan, as test_a_submodule_in_the_other_leg_from_its_record_is_misplaced asserts.

• AGENTS.md step 7 tells an agent that a non-zero adopt-project.py execute exit is to fix the plan and re-run into fresh legs, but in GitHub mode execute exits 2 with the split pushed when gh pr create is refused, and exits 2 after adoption verified when the topic will not set, so following step 7 abandons a pushed adoption whose own exit is a command to run by hand #304's exits keep the record. _commit_the_split writes the record into the split commit before the split is pushed, and it is the same text at 70f4d29, 48bdbf9 and 4b00597. AGENTS.md step 7 tells an agent that a non-zero adopt-project.py execute exit is to fix the plan and re-run into fresh legs, but in GitHub mode execute exits 2 with the split pushed when gh pr create is refused, and exits 2 after adoption verified when the topic will not set, so following step 7 abandons a pushed adoption whose own exit is a command to run by hand #304 changed only what execute does once the split is pushed. A source with a submodule at vendor/b, answered code, was adopted in GitHub mode with a stub gh, under main 1f90a0f and under 4b00597, and again under main 75052cb and under 60a1a34:

  • with gh pr create refused, both exit 2 and print adoption verified before Open the pull request by hand;
  • with gh repo edit refused, both exit 2 and print Set the topic by hand;
  • with nothing refused, both exit 0.

  In all three, only the branch's pushed split carries the record.

• adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188's late failures keep their one account. A source with .cursor answered code was adopted with a pre-receive hook in the source refusing the split branch, so the run got as far as committing the split with the record in it, and then failed to push it. Under main 75052cb and under 60a1a34 the merged stdout and stderr are the same, byte for byte with paths and hex masked: exit 2, the run's stdout first, then one REFUSED pushing the split branch., the command and its output, and one notice. Neither prints a traceback or adoption verified. Only 60a1a34's split commit, left in the work directory, carries the record.

• shape-doctor.py calls an assembly root whose project.yaml does not parse (a merge conflict) NOT A SHAPE ROOT, exit 2, and its NEXT line tells the reader to adopt that assembly root in place while the Triad row calls it a single repository #205 waits for a record that does not load. A conflict marker, a tab or a byte that is not UTF-8 inside the submodules: block makes project.yaml fail to load. The verdict is then INVALID (manifest), exit 1. The placement row is n/a and waits on the manifest row, so no submodule is judged. --placement-plan refuses, exit 3, and writes nothing. shape-doctor.py calls an assembly root whose project.yaml does not parse (a merge conflict) NOT A SHAPE ROOT, exit 2, and its NEXT line tells the reader to adopt that assembly root in place while the Triad row calls it a single repository #205's gate runs in check_placement before the record is read.

• No path the record work names can break a line. The record work adds no finding, refusal or print to adopt-project.py, so adopt-project.py check and execute print a source path raw in a FINDING, so a \r, \n, \x85, U+2028 or ESC in a name overwrites, splits or escapes the line on a terminal, where plan's questions spell the same path with _spelled #212 has nothing of it to respell. The project's validate-manifest.py writes every recorded value in its findings with repr. The doctor writes a row's names through ascii_text, and reports a name holding a control character or a byte that is not UTF-8 by repr, never judging it. A code leg kept submodules named with a carriage return, a line feed, an ESC, U+0085, U+2028, a no-break space, a backtick and a backslash, with a record putting each in the other leg. No carriage return, ESC, U+0085 or U+2028 reached the validator's output, the doctor's text, its --json, its placement-plan run or the plan file raw. The names holding a carriage return, a line feed or an ESC were listed by repr and not judged. The other five were judged MISPLACED, and the plan carries them exactly.

• The record keeps double_quoted. submodule_record is the same text at 2f5cda9, a01ab02, e334f50, f38d543, 3e86200, 27d039b, a557f2a, 70f4d29, 48bdbf9, 4b00597, 3b7cb8f, 563ea16, 78034e7, 136a37f and 60a1a34, and M24, the record spelled by y, is killed.

Targeted runs at 60a1a34 (67 files).

tests/test_shape_doctor.py tests/test_adopt_submodules.py tests/test_adopt_e2e.py
tests/test_cli_reference.py tests/test_repo_hygiene.py tests/test_manifest_validator.py
tests/test_adopt_verify.py tests/test_adopt_leg_path_collisions.py
tests/test_adopt_mount_ignored.py tests/test_adopt_leg_paths.py
tests/test_scaffold_leg_paths.py tests/test_windows_paths.py
tests/test_pin_validator.py tests/test_neutral_pin_validator.py
tests/test_adopt_plan_escapes.py tests/test_yaml_flow_quotes.py
tests/test_load_yaml_refusals.py tests/test_adopt_plan.py tests/test_update_shape.py
tests/test_scaffold_leg_path_collisions.py tests/test_scaffold_mount_ignored.py
tests/test_scaffold_ignored_shape_files.py tests/test_update_shape_add.py
tests/test_update_shape_add_ignored.py
tests/test_adopt_history_gitlinks.py tests/test_git_output_decoding.py
tests/test_stdout_encoding.py tests/test_update_shape_pr_base.py
tests/test_yaml_flow_mappings.py tests/test_yaml_block_scalar_keys.py
tests/test_adopt_finding_spelling.py tests/test_adopt_execute_refusals.py
tests/test_adopt_ignored_shape_files.py tests/test_adopt_gitmodules_values.py
tests/test_yaml_quote_boundaries.py tests/test_template_quoted_values.py
tests/test_adopt_entry_paths.py tests/test_adopt_root_shape_paths.py
tests/test_validator_child_encoding.py tests/test_adopt_literal_names.py
tests/test_adopt_clone_template.py tests/test_template_values_single_pass.py
tests/test_adopt_template_values.py
tests/test_family_add_excludes.py tests/test_family_member_path.py
tests/test_bump_leg_rollback.py tests/test_update_shape_add_symlink.py
tests/test_adopt_github_exits.py tests/test_doctor_legs_members_next.py
tests/test_pin_rewrite_layout.py tests/test_bump_leg.py
tests/test_adopt_manifest_values.py tests/test_scaffold_manifest_values.py
tests/test_yaml_flow_brackets.py tests/test_doctor_validator_rows.py
tests/test_family_member_name.py tests/test_agents_md_codes.py
tests/test_bump_leg_unreadable.py
tests/test_adopt_late_failure.py tests/test_adopt_filter_repo_failure.py
tests/test_bump_leg_unopenable.py tests/test_validate_pins_without_git.py
tests/test_adopt_git_reads.py tests/test_family_dry_run.py
tests/test_family_add_refusals.py tests/test_family_add_member_id.py
tests/test_update_shape_landing.py

• With git-filter-repo on PATH: 4116 passed, 9 skipped.

• With it hidden: 3957 passed, 168 skipped. 159 of the skips are git filter-repo is not installed.

• Each run is the same 4,125 tests. The other nine skips, in both runs, are:

  • tests/test_adopt_plan.py's MedxEHR-backed test (SHAPE_MEDXEHR_CLONE is unset);
  • a tests/test_stdout_encoding.py case about Windows' own default;
  • three tests/test_shape_doctor.py cases about the PowerShell line;
  • three tests/test_update_shape_add_symlink.py cases about Windows junctions;
  • a tests/test_bump_leg.py case that needs a disk that ignores case.

  The last eight run only on Windows, or, for the disk that ignores case, on macOS and Windows.

Four of the files reach scripts/repo_shape.py and scripts/shape_materialize.py only through scripts/family.py, scripts/bump-leg.py or update-shape.py: tests/test_family_add_excludes.py, tests/test_family_member_path.py, tests/test_bump_leg_rollback.py and tests/test_update_shape_add_symlink.py. tests/test_adopt_github_exits.py, tests/test_doctor_legs_members_next.py, tests/test_pin_rewrite_layout.py and tests/test_bump_leg.py are main's new or changed tests from #304, #276 and #323, which changed adopt-project.py, shape-doctor.py and scripts/shape_materialize.py. The seven after them are main's tests, from the merges since 4b00597, of what reaches this branch's files: #258's and #261's manifest values, #301's flow brackets, the validator rows of #278, #297 and #298, #366's member names, #348's AGENTS.md codes and #289's unreadable pins. The last nine are #188's tests/test_adopt_late_failure.py and tests/test_adopt_filter_repo_failure.py, and main's tests of #292's git reads, #326's dry run and refusals, #330's member ids, #333's landing, #383's unopenable files and #412's validate-pins.py without git. Each of these reaches adopt-project.py, scripts/repo_shape.py or scripts/shape_materialize.py through the file it tests.

tests/test_shape_doctor.py is in the set because the doctor feeds placement plans through adopt's Plan and _leg_findings. tests/test_cli_reference.py, also in the set, fails when docs/cli.md and scripts/render-cli-reference.py disagree.

CI passed at 48bdbf9 and at 563ea16 on Linux, macOS and Windows. b88a36e is a new head, so CI runs again on it. Besides the runs above, at 60a1a34:

• the round trips gave 0 mismatches again: 4,525 and 35 names, 240 and 195 records;
• the doctor's judgement by the record was unchanged from 136a37f, 40/40 and 20/20.

The re-verify ran 52 files at 563ea16 with git-filter-repo: 3414 passed, 8 skipped. tests/test_agents_md_codes.py, new in 45e01f4, passes: #189's AGENTS.md passages backtick no code-shaped token.

Reviews

Lane openRepoShape-2 reviewed e167d8b: CHANGES NEEDED on one test argument, and mergeable with nits once that was fixed (0 P1, 1 P2, 3 P3).

Finding	Answer
P2-1 _leg_findings() missing tree (TypeError) after main a5b09c3	dbf8887: the merge passes None, as main's other placement-plan callers do. Its revert is M1.
P3-1 names with NBSP, U+3000, ZWSP and the like never match their row	cd2a622: the reader resolves YAML's code-point escapes, and the writer spells by them. Since #199 landed first, 04c4e14 takes #199's escape section and 2a93da8 spells the record with repo_shape.double_quoted, deleting _quoted.
P3-2 (validator half) ./x, x/, a//b, a\b accepted	379763c: path_spelling_fault, in repo_shape.py, refuses ./x, x/, a//b and a/./b. a\b is accepted, against the review, with evidence. Git records vendor/a\b on POSIX, a real adoption records it and the doctor holds the gitlink to that row (recorded, then MISPLACED once moved), so refusing it would make execute's own manifest INVALID. leg_path_problem is not reused, because it refuses café.
P3-2 (maintenance half) stale rows silent; a deliberate move stays MISPLACED	Not designed here, as the round was told; see Not in this PR. AGENTS.md (c16be62) now says the row is the human's to change.
P3-3 the placement row is never ok on a real adoption	90608b8: the record answers the policy's question about the leg's .gitmodules. 9b2c36f corrects it to answer only where the record places EVERY submodule the leg keeps. At 90608b8 a submodule added by hand beside a recorded one dropped the question, and the row said the record answered it. e0df56e also requires that the doctor read every name in the leg (F1 of the second review, below). No verdict moves.
Nit 1 AGENTS.md not updated	c16be62.
Nit 2 _verify does not cross-check the rows against the legs	Not taken: see Not in this PR.
Nit 3 test_shape_doctor.py:3714 does not assert the row's status	90608b8: the end-to-end test asserts ok, no question, and the clause.
Nit 4 / MU12 the last duplicate row wins, untested	15f9b69: first-row-wins, pinned by a test. The validator already names the second row recorded twice. A first row whose leg: the validator refuses now decides nothing, and the second does not stand in for it. Its reverts are M16 and M17.
Sequencing with #199	Done here: #199 landed first (4835fb4). See P3-1.
Sequencing with #188	Done in 60a1a34, after #188 landed first. Its one conflict hunk in adopt-project.py was _commit_the_split: the merge takes #188's function whole and builds the record inside its try, under the committing the split step, and test_adopt_late_failure.py's split_arguments now hands it a SplitPlan() with entries = () where it handed plan={}.

Also in the fix round: 400812a spells the test's escaped names by their code points (\u00a0, \u3000, \u200b, \u00ad, \u2028), where five were raw invisible characters. The values are unchanged.

The second review, of 3e86200, found one BLOCKER and eight nits. Every finding of the first review is fixed or deferred, as above.

Finding	Answer
F1 the record answers a leg's .gitmodules beside a submodule whose name the doctor cannot read	e0df56e: gitmodules_the_record_answers answers nothing for a leg holding such a name. The doctor sets a name with a control character, or a byte that is not UTF-8, aside before it reads its mode, so a submodule kept under one was never held to a row. In the review's probe, such a submodule with no row, with a row saying spec, and with a row saying code each made the row print the answered clause and drop the question. Each keeps the question now, as main does. A leg holding such a name is a note either way, so no verdict moves. Its revert is M29.
N1–N3 three body sentences	Corrected above: the legend #186's plan keeps, "never lands beside" an older repo_shape.py, and what the row needs to be ok.
N4–N8	Not changed in this PR. They concern AGENTS.md's wording of point 4, a code comment on bytes, a test docstring, a question for the follow-up issue, and a Sonar count.

Not in this PR

• Keeping the record current (P3-2's maintenance half). Nothing writes a row after the adoption, so a stale row is silent, and a submodule moved on purpose stays MISPLACED until somebody edits the manifest. A follow-up issue should decide:

  1. what the record is: the adoption's answer, or a standing declaration that must be kept current;
  2. who changes a row when a submodule changes legs, and in which commit: a tool, or a sanctioned edit in the moving pull request that AGENTS.md then names;
  3. what the doctor says about a row that names no gitlink;
  4. whether a submodule added after the adoption can be recorded;
  5. whether any of that needs an OpenSpec change, which would be Brett's to rule.

• _verify cross-checking the rows (nit 2). On every path execute takes, the rows and the split come from one _answered_legs reading of one plan, and git filter-repo keeps paths. So the rows match the legs by construction. A check would need:

  • the manifest's landing path plumbed into _verify;
  • a YAML read of it;
  • per-leg gitlinks;
  • a finding code;
  • a fault-injection test.

  The doctor run AGENTS.md prescribes after every procedure already reports a mismatch as MISPLACED.

• Pre-existing on main, found while settling nit 2. Take a source whose own project.yaml is answered root:

  • its file stays at the root;
  • the shape's manifest is written to shape/project.yaml;
  • execute still prints adoption verified;
  • the doctor calls the result NOT A SHAPE ROOT, exit 2.

  Measured on 54aa69a and on 4835fb4. The record goes with the shape's manifest, wherever that lands.

• scripts/repo_shape.py: the double-quoted reader that #247 adds (fix/adopt-plan-linebreak-names, not yet on main) resolves \x00 inside a block-scalar KEY, and _parse_mapping splits the NUL-joined sentinel record, so "a\x00b": | reads as the key a with the body b<NUL>text where main reads the literal key a\x00b #248 (an escaped NUL in a block-scalar key split the reader's sentinel record) is fixed on main by c3f4987 (scripts/repo_shape.py: a block scalar's record carries its key and its body as a pair instead of NUL-joined text, so "a\x00b": | no longer reads as the key a with the body b<NUL>text, and a line that begins with a raw NUL and BLOCK no longer reads as a block scalar nobody wrote (#248) #265), which this branch has merged. The record writes no key from data, and it reads back through that reader (see the round trip under Tests).

Closes #189

🤖 Generated with Claude Code