[brettheap]

Was stacked on #1270 (lane 1's, for #1163), which landed on main as a squash, 3bf35b22e, at 06:24:35Z on 2026-11-10. This PR was restacked onto main by three merges, with no rebase (see The restack after #1270's squash), and its base is main. It was made at #1270's head 8e54c32de, which adds Tree.is_link and Tree.text_through to scripts/shape_advisory.py. Against main the diff is this PR's own change: 2 files, +557/-4, from two commits of its own, 126165514 and the round after rv1295's review (0c3999d5a, tests only). The merge commits c6d9a9ab4 and 129f4dce8 (the restack) change no line of them.

Part of #1272

Goal

adopt-project.py plan and check read a project.yaml or a family.yaml that the commit holds as a symlink the way the doctor reads it on the disk. They also say plainly that they do not follow a single-repository.yaml held as one, so no it could not be read (YamlError) NOTE is printed over a record that can be read. Whether the record's link should be followed is a ruling not yet made (see The ruling left open), so this PR does not follow it.

What held at #1270's head (measured)

Measured with git 2.43.0 and CPython 3.12.3, in the probe environment: a stub gh first on PATH, a bogus GH_TOKEN, an empty GH_CONFIG_DIR, GIT_CONFIG_GLOBAL=/dev/null and GIT_SSH_COMMAND=false, with no network. Each fixture is a one-commit repository in a folder Atlas whose origin is acme/Orbit on github.com, never contacted, as #1272's are. Each got plan --source <Atlas> --project Orbit --org acme ..., then check --plan, then shape_advisory.read() of the commit and of the disk, in process. The same 15 cases gave the same answers at 8e54c32de and at b24382a87, and the same answers at this change on both bases.

committed as	the commit at #1270's head	the commit here	the disk (the doctor's)
single-repository.yaml -> docs/record.yaml, a record	advise, NOTE it could not be read (YamlError)	advise, the link's NOTE (below)	recorded-single
the same, spelled ./docs/record.yaml	the YamlError NOTE	the link's NOTE	recorded-single
a link to a file of another kind	the YamlError NOTE	the link's NOTE	advise, NOTE it declares kind 'release-config', ...
a link that dangles, or loops	the YamlError NOTE	the link's NOTE	advise, no NOTE
a link to the directory docs	the YamlError NOTE	the link's NOTE	advise, NOTE it is not a file
-> ../elsewhere/record.yaml, a record out of the commit	the YamlError NOTE	the link's NOTE	recorded-single
-> kind: single-repository-record (that is the PATH; it dangles)	recorded-single; entry leg: drop, rule ambiguous-single-repository-record; check exits 0	advise, the link's NOTE; entry leg: null, rule ambiguous-top-level-yaml; check exits 1	advise, no NOTE
a regular record (control)	recorded-single; leg: drop; check exits 0	the same	recorded-single
project.yaml -> docs/project.yaml, a Triad manifest	advise: the two triad lines	triad-root: no Triad line	triad-root
family.yaml -> docs/family.yaml, a holder's manifest	advise: the two triad lines	family-holder: no Triad line	family-holder
family.yaml -> kind: family-manifest (the PATH; it dangles)	family-holder	advise	advise
project.yaml -> ../elsewhere/project.yaml, a Triad manifest out of the commit	advise	advise	triad-root
project.yaml -> docs/project.yaml, committed dangling and written on the disk after	advise	advise	triad-root
a regular project.yaml (control)	triad-root	the same	triad-root

• In every record row but the spelled one, the plan entry and check are the same on both sides: leg: null, rule ambiguous-top-level-yaml, and check exits 1 with plan-unresolved. plan exits 0 in every row.
• Manifest rows exit 1 from check on both sides, link and control alike: a top-level project.yaml or family.yaml of the repository's own is an open question there. A linked project.yaml adds plan-root-symlink on both sides. Only the printed advisory differs.
• Row 2b of shape_advisory.py: a single-repository.yaml committed as a symlink is read as its path, so plan and check advise with a false (YamlError) NOTE where the doctor says recorded-single (#1163) #1272, the project.yaml link beside a regular spec leg's AGENTS.md, read leg-clone at shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's head, and plan and check printed the leg's NOTE. It reads triad-root here, with no NOTE (row [project-yaml-beside-a-leg-agents-md]).
• The doctor's audit of a leg's INDEX is unchanged. shape-doctor.py's placement row calls ask_about_a_record_only with Source(mount, None, "", ""), so the record is read through Tree(mount, ""). There git ls-tree --full-tree "" -- single-repository.yaml exits 128 ("fatal: Not a valid object name"), so is_link says no link. read_record over such an index gives ('silences-nothing', ['it could not be read (YamlError)']) for a link to a record in the leg, and ('silences', []) for the spelled link, at shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's head and here alike.

What changed

Only scripts/shape_advisory.py. adopt-project.py and shape-doctor.py are untouched.

• _read_mapping follows a manifest's link inside the commit, for project.yaml and family.yaml. It reads tree.text_through(rel) if tree.is_link(rel) else tree.text(rel), as shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's _leg_by_agents_md reads a leg's AGENTS.md.
  • The choice, stated in its docstring and pinned by rows: nothing that is a file inside the commit is a manifest this reading sees. A link that dangles, loops, runs through a file or leads to a directory gives None from text_through. One that leads out of the commit raises OutOfTheCommit. _read_mapping already swallows both, as it swallows every manifest it cannot read, so each reads as no manifest. The plan is written against the commit, and a manifest the commit does not hold declares nothing in it. The link's own path is never read as the manifest.
  • A regular file reads as before, and so does every reading of the disk, where is_link is always False.
• read_record does not follow the record's link, and names it. After kind() says "file", it asks tree.is_link(RECORD_FILE). A link silences nothing, with the new constant RECORD_LINK_NOT_FOLLOWED, for every link, whatever it leads to. plan and check print:

NOTE single-repository.yaml does not silence this: it is a symlink in the commit, which is not followed for this record, so whether it records that this project stays a single repository is not known here (its schema is openRepoShape's contracts/single-repository-record.yaml); nothing fails on its account.

• The sentence names no exception. It says "a symlink in the commit", so a later ruling to follow links inside the commit can narrow it to the links it still does not follow, such as one out of the commit (the constant's comment says so).
• ask_about_a_record_only asks only whether the record silences, so a linked record is still "no record" there: the general question, leg: null, and check exits 1, as before. The one exception is the spelled link (see Known limits).
• The docstrings of Tree and Tree.text_through say which readers follow a link now.
• Cost: each read(commit=...) makes one git ls-tree per manifest, and one more where a record is a file.

Rows

tests/test_advisory_record_symlink.py is new, with 39 ids (35 at 126165514, 4 added in the round after rv1295's review) beside #1270's tests/test_advisory_agents_md_symlink.py. It imports what it needs from the files that own it:

• from shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's file: committed, adopt_says, told_nothing and SINGLE;
• from shape_advisory.py and shape-doctor.py: a leg's AGENTS.md this user cannot read leaves whether it is a leg unknown, so the way in offers neither command and points at what is here, and the other way in and the Triad row are silent (#1110) #1159's: no_workspace and symlink;
• from test_shape_advisory.py: commit_all, doctor_json, record_text, rendered_leg_agents and repository;
• from test_adopt_single_repository_record.py: entry_of, leg_audited, GENERAL and RULE.

It imports no fixture. Its one builder, linked_here, links the name under test where #1270's linked_clone links AGENTS.md. Every case that needs a symlink makes one and skips where none can be made. The 9 controls of regular files make none and run everywhere: 4 in test_the_three_files_committed_as_regular_files_read_as_before, 3 in test_a_git_that_cannot_list_the_commit_reads_a_regular_file_as_before and 2 in test_a_git_that_cannot_follow_a_link_reads_a_regular_manifest_as_before.

The new file was run at #1270's production code: its untracked copy, in a detached tree at 8e54c32de, gave 18 failed and 17 passed (11.34 s). Every failure is the defect: the YamlError reason where the link's is asserted (11 rows), advise or leg-clone where the disk's state is asserted (5), family-holder for the spelled manifest link, and recorded-single for the spelled record link. At b24382a87, #1270's head now, the same 18 fail and 17 pass (9.90 s). At this head all 35 pass. The round after rv1295's review added 4 ids, all controls. With b24382a87's production file swapped in (sha256 e0b0ef03) the 39 give the same 18 failed and 21 passed (12.05 s), the 4 among the passes, and at this head all 39 pass.

row	#1270's head	here
test_a_manifest_linked_inside_the_commit_is_read_through_it: [project-yaml], [project-yaml-beside-a-leg-agents-md], [family-yaml], [project-yaml-dot-slash], [family-yaml-through-a-linked-folder]. These are #1272's rows 2a, 2b and 3: both readings, no Triad line or leg NOTE in plan or check, and check's findings	5 failed	5 passed
test_a_manifest_link_to_no_file_in_the_commit_is_no_manifest[spelled-as-a-manifest]	failed	passed
THE CHOICE, same file: [dangling], [loop], [a-directory], [through-a-file], [not-utf-8], [dangling-in-the-commit-there-on-the-disk], [out-of-the-commit], [out-of-the-commit-by-its-absolute-path]. The commit reads advise; where the disk reads triad-root, plan and check print the advisory	8 passed	8 passed
test_a_record_linked_to_a_record_in_the_commit_is_named_as_a_link. This is #1272's row 1: the exact NOTE line once in each of plan and check, no could not be read, the entry leg: null under ambiguous-top-level-yaml, check's one finding plan-unresolved, and the doctor's exit 2 with no Triad row	failed	passed
test_every_link_to_the_record_is_named_as_one_and_never_followed: [dot-slash], [through-a-linked-folder], [another-kind], [dangling], [loop], [a-directory], [through-a-file], [not-utf-8], [out-of-the-commit], [out-of-the-commit-by-its-absolute-path]	10 failed	10 passed
test_a_record_link_whose_path_is_spelled_as_a_record_is_no_record	failed	passed
CONTROLS test_the_doctors_audit_of_a_legs_index_reads_a_record_link_as_before: [to-a-record-in-the-leg] (the general question) and [spelled-as-a-record] (the record's), the link staged in the leg's index only, and [to-a-record-in-the-leg-committed-too], [spelled-as-a-record-committed-too], the same with the link committed in the leg as well (R5)	4 passed	4 passed
CONTROLS test_the_three_files_committed_as_regular_files_read_as_before: [project-yaml], [project-yaml-beside-a-leg-agents-md], [family-yaml], [single-repository-yaml]. These are #1272's controls 2a-c, 2b-c, 3c and 1c: the entry, and check's findings (none for the record)	4 passed	4 passed
CONTROLS test_a_git_that_cannot_list_the_commit_reads_a_regular_file_as_before (stand-in: ls-tree refused): [project-yaml], [family-yaml], [single-repository-yaml]	3 passed	3 passed
CONTROLS test_a_git_that_cannot_follow_a_link_reads_a_regular_manifest_as_before (stand-in: cat-file --follow-symlinks exits 128): [project-yaml], [family-yaml] (R3)	2 passed	2 passed
total	18 failed, 21 passed	39 passed

Mutants

19 mutants, 19 killed: the 13 of the first round (M1-M10), and rv1295's own six (R1-R6), of which R3 and R5 survived rv1295's run of the 35 ids and are killed by the new ids. All 19 were run again against this round's file. Each was applied alone in a detached tree (16bee386d with this round's test file laid in, its blob equal to 0c3999d5a's), and the new file's 39 ids were run, one run each. After each, the file was written back from the bytes saved before it and proved equal by sha256: scripts/shape_advisory.py 40a766ca7adf, adopt-project.py 6e2402aaeec3, shape-doctor.py 140100bcaae9. The counts of M6b, M8 and M10 grew by the new ids that also fail them; every other count is the first round's.

id	mutant	result	rows failed (first named)
M1	the link not followed in _read_mapping	KILLED	6: ..._read_through_it[project-yaml] and the other four, [spelled-as-a-manifest]
M1b	followed for project.yaml only, not family.yaml	KILLED	3: ..._read_through_it[family-yaml]
M2	a dangling link read as a manifest: a follow that finds no file falls back to the link's own blob	KILLED	1: ..._is_no_manifest[spelled-as-a-manifest]
M3	a link out of the commit read from the disk	KILLED	2: ..._is_no_manifest[out-of-the-commit], [...-by-its-absolute-path]
M4	the record's link followed inside the commit (#1272's way A)	KILLED	12: test_a_record_linked_to_a_record_in_the_commit_is_named_as_a_link, every test_every_link_..., the spelled record
M5	the NOTE carrying an exception name (... (OutOfTheCommit))	KILLED	the same 12
M5b	the NOTE as the old frame, it could not be read (Symlink)	KILLED	the same 12
M6a	ask_about_a_record_only gives a linked record the record's rule	KILLED	2: ..._named_as_a_link, the spelled record (leg: drop)
M6b	ask_about_a_record_only handed the disk's tree, which follows a link	KILLED	5: ..._named_as_a_link, the four leg-audit controls
M7	no link check in read_record (the link's path parsed, as before)	KILLED	the same 12 as M4
M8	the doctor's leg audit reads the leg's disk (Source(mount, None, "", None)), following where plan does not	KILLED	4: the four leg-audit controls
M9	the followed blob decoded with errors="replace" (r1163's R6)	KILLED	1: ..._is_no_manifest[not-utf-8]
M10	is_link says link where git cannot answer	KILLED	3: the stand-in's [single-repository-yaml], the leg-audit [spelled-as-a-record] and [spelled-as-a-record-committed-too]
R1	rv1295's: _read_mapping lets OutOfTheCommit escape, #1270's silence for a manifest out of the commit	KILLED	2: ..._is_no_manifest[out-of-the-commit], [...-by-its-absolute-path]
R2	rv1295's: a record's link read as no record at all, with no NOTE	KILLED	12: ..._named_as_a_link, every test_every_link_..., the spelled record
R3	rv1295's: _read_mapping follows every manifest, link or not	KILLED	2: test_a_git_that_cannot_follow_a_link_reads_a_regular_manifest_as_before[project-yaml] and [family-yaml], both new
R4	rv1295's: every committed link read from the disk	KILLED	3: ..._is_no_manifest[dangling-in-the-commit-there-on-the-disk], [out-of-the-commit], [...-by-its-absolute-path]
R5	rv1295's: is_link asks HEAD where the Tree reads the index (commit "")	KILLED	1: ..._reads_a_record_link_as_before[spelled-as-a-record-committed-too], new
R6	rv1295's: the record's NOTE only where the link's path does not parse	KILLED	1: the spelled record

• M9 survived the first round, run at 126165514's files on 8e54c32de, where 12 of the same 13 were killed. The [not-utf-8] manifest then put the byte 0xff after the manifest's last line. With errors="replace" that made a last line of its own, which does not parse, so the mutant read no manifest either. The row now puts the byte inside a value (name: Atlas<0xff>), and M9 fails it. All 13 were then run again at this head's files, with the table's result.

Runs

The gate ran at 0c3999d5a on git 2.43.0 and on git 2.47.1 (built from kernel.org's tarball), each leg in 8 calls of at most 78 ids (620 ids: the 616 of the first gate and the 4 added in the round after rv1295's review, collected at this head). It used CPython 3.12.3, pytest 9.1.1 and git-filter-repo 2.47.0 (CI's pin), in the probe environment, -rs alone, one basetemp per call, at most two calls at once, the tree clean. Each leg gave 618 passed and 2 skipped. The files are the new file, tests/test_advisory_agents_md_symlink.py, tests/test_shape_advisory.py, tests/test_adopt_single_repository_record.py, tests/test_doctor_recorded_answers.py, the hygiene five (test_agents_md_codes.py, test_cli_reference.py, test_path_guard_hygiene.py, test_pinned_copy_text.py, test_repo_hygiene.py) and tests/test_no_auto_maintenance.py.

call	ids	files (ids)	2.43.0	2.47.1
1	78	tests/test_advisory_record_symlink.py (39), tests/test_advisory_agents_md_symlink.py (27), tests/test_shape_advisory.py (12)	78 passed in 49.18 s	78 passed in 48.64 s
2	78	tests/test_shape_advisory.py (35), tests/test_adopt_single_repository_record.py (39), tests/test_doctor_recorded_answers.py (4)	78 passed in 39.15 s	78 passed in 39.00 s
3	78	tests/test_doctor_recorded_answers.py (25), tests/test_agents_md_codes.py (47), tests/test_cli_reference.py (6)	78 passed in 37.12 s	78 passed in 36.98 s
4	78	tests/test_cli_reference.py (17), tests/test_path_guard_hygiene.py (61)	78 passed in 24.43 s	78 passed in 24.39 s
5	78	tests/test_path_guard_hygiene.py (60), tests/test_pinned_copy_text.py (18)	78 passed in 8.60 s	78 passed in 8.62 s
6	78	tests/test_pinned_copy_text.py (69), tests/test_repo_hygiene.py (9)	78 passed in 4.10 s	78 passed in 3.96 s
7	78	tests/test_repo_hygiene.py (78)	78 passed in 1.02 s	78 passed in 0.98 s
8	74	tests/test_repo_hygiene.py (14), tests/test_no_auto_maintenance.py (60)	72 passed, 2 skipped in 5.61 s	72 passed, 2 skipped in 5.62 s

• The 2 skips in call 8 are tests/test_no_auto_maintenance.py:222: "the session began with GIT_CONFIG_GLOBAL set, and its file includes that one". The probe environment sets GIT_CONFIG_GLOBAL=/dev/null.
• Before this round the gate ran at 16bee386d (616 ids): 614 passed and 2 skipped on each git. rv1295 ran 815 ids there, which included 18 rows of tests/test_shape_doctor.py and the doctor's other rows that read shape_advisory: 813 passed and 2 skipped on both gits. scripts/shape_advisory.py and every other production file are unchanged in this round, so those were not run again.
• adopt-project.py is unchanged, so tests/test_shape_doctor.py and tests/test_scaffold_leg_path_collisions.py were not run. The Python 3.14 shim was not run.

Merges

Read fresh after the restack and before the push (git fetch of main, and gh pr list, read only, 30 open PRs): main 3bf35b22e, which is #1270's squash, and #1270 MERGED at its final head 0c19a3c77. This head contains both, so a merge of either adds nothing. No other open PR touches scripts/shape_advisory.py, tests/test_advisory_record_symlink.py or tests/test_advisory_agents_md_symlink.py. #1278 and #1171 touch tests/test_pinned_copy_text.py, which the gate runs and this PR does not change.

with	git merge-tree --write-tree
main 3bf35b22e	clean: tree e3ca2459c, this head's own tree (main is an ancestor)
#1270's final head 0c19a3c77	clean: tree e3ca2459c, this head's own tree (an ancestor)
#1270's squash 3bf35b22e	the same: it is main's tip

The 29 other open PRs: 19 of them touch adopt-project.py, shape-doctor.py or tests/conftest.py, which these rows run, and none touches this PR's two files. A change to check's findings for a root link would show in the rows that assert them.

The ruling left open

Whether a single-repository.yaml committed as a symlink to a file inside the commit should be followed. Followed, it would take the record rule ambiguous-single-repository-record, with the default drop that Brett Heap ruled on 2026-10-12 for a regular record (contracts/path-classification.yaml, adopt-project.py's ask_about_a_record_only, #528). This PR leaves every such link unfollowed, with a true NOTE. #1272's measurement 4 shows what following would do: recorded-single, leg: drop, and check exits 0, as for a regular record. What the ruling may weigh:

• What drop does to a link. drop removes the link single-repository.yaml. Its target (docs/record.yaml in shape_advisory.py: a single-repository.yaml committed as a symlink is read as its path, so plan and check advise with a false (YamlError) NOTE where the doctor says recorded-single (#1163) #1272's fixture) is its own path, under its own rule, and goes where that rule sends it: the spec leg, in the fixture. The rule's reason ("the file no longer describes the project it sits in") assumes the file is the record.
• The doctor's leg audit. It reads a leg's INDEX (Tree(mount, "")), where git ls-tree has nothing to list and is_link cannot answer. Following in plan alone would split plan from the doctor's audit of a leg (shape-doctor.py: the placement row asks a leg's top-level single-repository.yaml the staying-single record's question by its name alone, so a file that declares kind: release-config is told it records that the repository stays single, on every run of a project adopted before #617 #691, tests/test_doctor_recorded_answers.py), unless the audit moves too: through git ls-files -s, say, which is not used here.
• A link out of the commit, and one git cannot follow, still need the NOTE. It would be narrowed to them, as its comment says.
• The spelled link (Known limits) already reads differently in plan and in the leg audit, until the ruling settles both readers.

Not the record's ruling, but a choice for review: a manifest's link out of the commit reads as no manifest here, so plan advises where the doctor names the root. #1270 chose silence (not-answered) for a leg's AGENTS.md out of the commit. This PR reads such a manifest as _read_mapping reads any manifest it cannot read: as none. update-shape.py already refuses to re-pin a root whose manifest is a link (update-rewrite-symlink).

Known limits

• A record link whose PATH parses as a record is no longer read as the record by plan, but is by the doctor's leg audit. single-repository.yaml -> kind: single-repository-record read recorded-single at shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's head, with leg: drop and check exiting 0, from the path alone. Here it is the link's NOTE, the general question, and check exits 1, as for every other link. The doctor's audit of a leg's index still reads that path as a record, as it documents ("a link is read as its blob and never followed"). That is the only case where ask_about_a_record_only's answer moves. Both are pinned by rows.
• A manifest's link out of the commit, or one committed dangling and present on the disk, is advised where the doctor reads triad-root. This is the stated choice above.
• The restack after shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's squash is done. shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270 landed as a squash, and a plain merge of main alone would have conflicted in scripts/shape_advisory.py (rv1295 measured it). This PR was restacked by three merges, with no rebase: shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's final head 0c19a3c77, then its squash 3bf35b22e (the one conflicted file, scripts/shape_advisory.py, resolved to this branch's side), then main (already contained). See The restack after shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's squash.
• Measured with git 2.43.0 and CPython 3.12.3. The gates ran on git 2.43.0 and 2.47.1. CI runs Python 3.14, which was not run here.

The round after rv1295's review

rv1295 found this PR READY at 16bee386d, with no MUST or SHOULD and four NITs (#1295 issuecomment-6757105722). This round takes them as rv1295 measured them and changes nothing else: one commit, 0c3999d5a, in tests/test_advisory_record_symlink.py only. scripts/shape_advisory.py and every other production file are unchanged. #1270's head was read fresh and is still b24382a87, so no merge of it was needed.

• NIT 1, a false sentence. The module docstring and the Rows section said every case makes a symlink, and the controls of regular files make none. Both now say that every case that needs a symlink makes one and skips where none can be made, and name the 9 controls that make none.
• NIT 3, R5 survived (Tree.is_link asking HEAD where the Tree reads the index, which ls-tree "" refuses to list). The leg-audit control staged the link in the leg's index only, with a regular record in HEAD, so asking HEAD changed nothing. A row pins it, and no guard in read_record is needed: test_the_doctors_audit_of_a_legs_index_reads_a_record_link_as_before takes a new parameter, and the ids [to-a-record-in-the-leg-committed-too] and [spelled-as-a-record-committed-too] commit the link in the leg as well. Under R5, [spelled-as-a-record-committed-too] fails: the audit would ask the general question where it asks the record's. R5 is KILLED.
• NIT 4, R3 survived (_read_mapping following every manifest, link or not). The two readings differ only under a git that cannot follow. test_a_git_that_cannot_follow_a_link_reads_a_regular_manifest_as_before is a stand-in row like shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's test_a_git_that_cannot_follow_the_link_is_silence_not_advice, for a regular project.yaml and family.yaml: cat-file --follow-symlinks exits 128, and the commit must still say triad-root and family-holder. Under R3 both fail. R3 is KILLED.
• NIT 2, the landing note, is a bullet in Known limits and a row in Merges: when shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270 lands as a squash, restack by three merges.
• The 4 new ids are controls. They pass with shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's production file as they do here, so the rows failing at shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's head are still the 18. Their value is in the mutants: R3 and R5 each fail only the new ids.

The restack after #1270's squash

#1270 (lane 1's, for #1163) landed at 06:24:35Z on 2026-11-10 as the squash S70 = 3bf35b22e (parent de55beb03; #473 issuecomment-6760664498). Lane 1 had refreshed it first, so its final head H70 is 0c19a3c77 (b24382a87 plus a merge of main de55beb03), not the b24382a87 this PR's earlier text names. GitHub deleted #1270's branch and retargeted this PR to main, where it was CONFLICTING at 0c3999d5a. This round restacks it by three merges, by hand, with no rebase, and changes nothing else: no line of this PR's two files.

• Merge 1: H70 0c19a3c77 gave c6d9a9ab4. It was clean: the 29 files it brought are main's (lane 1's refresh merged main), none of them this PR's.
• Merge 2: S70 3bf35b22e gave 129f4dce8, with one conflict, in scripts/shape_advisory.py, the file shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270 and this PR both changed. It had two hunks, both in docstrings: the Tree class docstring (this PR's text says project.yaml and family.yaml are read through a link too, _read_mapping, shape_advisory.py: a single-repository.yaml committed as a symlink is read as its path, so plan and check advise with a false (YamlError) NOTE where the doctor says recorded-single (#1163) #1272, and that single-repository.yaml is not followed, read_record; the squash's text says only a leg's AGENTS.md is read so) and Tree.text_through's docstring ("as AGENTS.md and the two manifests are" against "as AGENTS.md is"). Both were resolved to this branch's side. The resolved blob 129a4c86b7ff equals 0c3999d5a's. S70's own copy of the file (9122f59bd22b) equals b24382a87's and H70's, so main changed nothing in it after shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's head. tests/test_advisory_agents_md_symlink.py merged without a conflict: S70's blob 62bf0a2220d4 equals this branch's. The merge commit's tree equals merge 1's.
• Merge 3: main 3bf35b22e, fetched fresh just before this step and again before the push, is S70 itself, and an ancestor of the head: Already up to date, no commit.
• Verify, at 129f4dce8:
  • git diff origin/main HEAD touches exactly scripts/shape_advisory.py and tests/test_advisory_record_symlink.py: 2 files, +557/-4;
  • its -U0 changed lines (561 of them, sha256 85cc8b101b02) are identical to those of git diff b24382a87 0c3999d5a, the reviewed change, with no difference;
  • git merge-tree --write-tree origin/main HEAD gives e3ca2459c, the head's own tree;
  • both of this PR's files are byte-equal to 0c3999d5a's: scripts/shape_advisory.py 129a4c86b7ff, tests/test_advisory_record_symlink.py 49630a405c18.
• The mutants were not run again. Both files are byte-equal to the ones they ran against. scripts/shape_advisory.py is still the Mutants section's sha256 40a766ca7adf, and so is shape-doctor.py, 140100bcaae9. Main changed adopt-project.py since (sha256 6e2402aaeec3 in the Mutants section, 2d5459ab2fee at this head, all main's), and M6a and M6b ran against the older file; the gate below runs every row against this head's.
• The gate ran at 129f4dce8, the tree clean, on git 2.43.0 and on git 2.47.1 (built from kernel.org's tarball), each leg in 8 calls of at most 78 ids (620 ids, the same list as the Runs section's, collected again at this head: 0 ids differ). It used CPython 3.12.3, pytest 9.1.1 and git-filter-repo 2.47.0 (CI's pin), in the probe environment, -rs alone, one basetemp per call, at most two calls at once. Each leg gave 618 passed and 2 skipped, in the same files as the Runs section. The 2 skips are tests/test_no_auto_maintenance.py:222 in call 8, "the session began with GIT_CONFIG_GLOBAL set, and its file includes that one" (the probe environment sets GIT_CONFIG_GLOBAL=/dev/null). adopt-project.py is unchanged by this PR, so tests/test_shape_doctor.py and tests/test_scaffold_leg_path_collisions.py were not run; the Python 3.14 shim was not run.

call	ids	files (ids)	2.43.0	2.47.1
1	78	tests/test_advisory_record_symlink.py (39), tests/test_advisory_agents_md_symlink.py (27), tests/test_shape_advisory.py (12)	78 passed in 55.22 s	78 passed in 54.71 s
2	78	tests/test_shape_advisory.py (35), tests/test_adopt_single_repository_record.py (39), tests/test_doctor_recorded_answers.py (4)	78 passed in 44.52 s	78 passed in 44.73 s
3	78	tests/test_doctor_recorded_answers.py (25), tests/test_agents_md_codes.py (47), tests/test_cli_reference.py (6)	78 passed in 43.01 s	78 passed in 42.85 s
4	78	tests/test_cli_reference.py (17), tests/test_path_guard_hygiene.py (61)	78 passed in 28.31 s	78 passed in 28.16 s
5	78	tests/test_path_guard_hygiene.py (60), tests/test_pinned_copy_text.py (18)	78 passed in 10.96 s	78 passed in 10.87 s
6	78	tests/test_pinned_copy_text.py (69), tests/test_repo_hygiene.py (9)	78 passed in 4.81 s	78 passed in 4.84 s
7	78	tests/test_repo_hygiene.py (78)	78 passed in 1.31 s	78 passed in 1.20 s
8	74	tests/test_repo_hygiene.py (14), tests/test_no_auto_maintenance.py (60)	72 passed, 2 skipped in 7.42 s	72 passed, 2 skipped in 7.43 s

Lane: openreposhape-5 (openRepoShape-5)

🤖 Generated with Claude Code

Summary by Sourcery

Handle committed YAML symlinks accurately in shape advisories by following manifests and clearly reporting record links that are intentionally not followed.

Bug Fixes:

• Read committed project.yaml and family.yaml symlinks through their targets when evaluating repository manifests.
• Report committed single-repository.yaml symlinks explicitly as un followed instead of incorrectly reporting YAML read failures.

Enhancements:

• Define consistent commit-based symlink handling for manifest and record advisory reads while preserving existing disk and leg-index behavior.

Tests:

• Add comprehensive coverage for manifest and record symlinks, including dangling, looping, out-of-commit, malformed, and control cases.

[sourcery-ai]

Reviewer's Guide

Implementation

Update manifest and record readers so committed project.yaml and family.yaml symlinks are followed within the commit, while single-repository.yaml symlinks are explicitly reported as not followed.

• scripts/shape_advisory.py L588-607, L860-871, L951-966 (+3 small edits)

Tests

Add regression and control coverage for committed manifest and record symlinks, including invalid or out-of-commit targets and unchanged doctor index behavior.

• tests/test_advisory_record_symlink.py L1-504

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[brettheap]

Independent review of #1295 (#1272) for lane openRepoShape-5, by rv1295 (opus), at 16bee38: READY

There are no MUST or SHOULD findings, and four NITs. One rule breach is mine, not the PR's: one of my mutant runs had 109 ids, over the 100 cap (details under Mutants).

What I measured

• Heads. I fetched fresh. Main is 930406996, shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's head is b24382a87, and shape_advisory.py: a project.yaml or family.yaml committed as a symlink is read through it inside the commit, and a linked single-repository.yaml gets a NOTE that says it is a symlink not followed, never could not be read (YamlError) (#1272) #1295's head is 16bee386d, all as the brief says. Both trees, /workspace/projects/openRepoShape-worktrees/rv1295-review and rv1295-mut, are detached at 16bee386d.
• The diff matches the body. Against both shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270 heads (8e54c32de and b24382a87) the diff is 2 files, +513/-4. Only scripts/shape_advisory.py changes in production.

1. The change against #1272's Goal and Verify list

• Manifests are read through their link inside the commit.

  • The new rows for shape_advisory.py: a single-repository.yaml committed as a symlink is read as its path, so plan and check advise with a false (YamlError) NOTE where the doctor says recorded-single (#1163) #1272's rows 2a, 2b and 3, plus the ./ spelling and a linked folder, read triad-root, triad-root (no longer leg-clone) and family-holder. plan and check print no Triad line and no leg NOTE.
  • A regular file reads as before. So does every disk reading, where is_link is always False.
  • The probe gave the same answers on git 2.43.0 and 2.47.1 (probe/probe1-243.out, -247.out).

• The record's NOTE is true and names no exception. The probe printed:
  single-repository.yaml does not silence this: it is a symlink in the commit, which is not followed for this record, so whether it records that this project stays a single repository is not known here (its schema is openRepoShape's contracts/single-repository-record.yaml); nothing fails on its account.

  • It is ASCII and holds no exception name.
  • It is reached only where is_link is True, which needs mode 120000 in git ls-tree of a real commit. So it is true for every link it is printed for.

• The record question is unchanged, except for the spelled link. ask_about_a_record_only reads only RECORD_SILENCES. At shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's head a link could silence only if its PATH parsed as a record mapping. So the spelled link is the only case whose answer moves, and the PR's claim holds by inspection and by rows.

• The Known limit is acceptable, not a SHOULD. For the link kind: single-repository-record the readers now say:

  reader	at shape_advisory.py: a project.yaml or family.yaml committed as a symlink is read through it inside the commit, and a linked single-repository.yaml gets a NOTE that says it is a symlink not followed, never could not be read (YamlError) (#1272) #1295's head	at shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's head
  commit (plan)	the link's NOTE, general question	recorded-single, leg: drop
  leg index (doctor's audit)	silences (record question)	the same
  disk	absent, so read() is advise	the same

  • Before, plan agreed with the leg audit and disagreed with the disk. Now it agrees with the disk.
  • The target text dangles on every disk, so the input is pathological.
  • The leg-audit control asserts classified_as None for both rules. So the remaining split only changes which question the doctor's placement review shows. It never produces a misplacement finding.
  • The body names it as a Known limit and in "The ruling left open".

• The doctor's audit of a leg's index reads as before. git ls-tree --full-tree "" -- exits 128 ("Not a valid object name") on 2.43.0 and 2.47.1. So is_link is False there, and the index Tree gives ('silences-nothing', ['it could not be read (YamlError)']) as before.

2. The choice put up for review: the PR's reading is right

• Dangling in the commit, present on the disk. shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270 makes the same choice. probe2 measured AGENTS.md -> docs/AGENTS.md, committed dangling and written on the disk afterwards: the commit reads advise and the disk leg-clone. The plan is about the commit, and the module's contract says an uncommitted file declares nothing (Tree and _print_triad_advisory docstrings). So the brief's "shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270 chose silence in the same case" holds only for the link out of the commit.
• A link out of the commit. shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270 treats OutOfTheCommit as "a file this user cannot read", and each reader answers that the way it answers an unreadable file:
  • _leg_by_agents_md (family.py, the family root's siblings.py, shape-doctor.py and shape_advisory.py: a name in the root that is a link into a folder this user cannot search is still read as absent at twelve sites (follow-up of #430 slice Z) #1110) answers NOT_ANSWERED;
  • _read_mapping's ratified contract says a manifest it cannot read is a manifest it does not see.
  • I measured that contract on the disk today: a project.yaml at mode 000, or one linked into a folder at 000, reads advise while the commit reads triad-root (P1a, P1b).
  • Silence for manifests out of the commit would add a new split inside the manifest reader. That would need _read_mapping's contract changed for every unreadable manifest, in its own issue.
• Stakes are low. check exits 1 on every manifest fixture (plan-unresolved, and plan-root-symlink for a linked project.yaml), and the advisory changes no exit status.
• It is pinned. My mutant R1, which gives shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's silence to a manifest out of the commit, is killed by the two out-of-the-commit rows.

3. The rows

• 18 fail at shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's head and pass here. With b24382a87's shape_advisory.py swapped into the mut tree (sha256 e0b0ef03, the same as 8e54c32de's), the new file gave 18 failed, 17 passed (logs/rv1295-base1.log). These are exactly the body's 18, and every first E line is the defect: 11 YamlError tuples, 4 advise, 1 leg-clone, family-holder for the spelled manifest, and recorded-single for the spelled record.
• The tree was restored. sha256sum -c passed for all four files and the tree is clean.
• Every row and control passes at the head, on both gits.
• Imports. Everything shared is imported: from conftest, from shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's, shape_advisory.py and shape-doctor.py: a leg's AGENTS.md this user cannot read leaves whether it is a leg unknown, so the way in offers neither command and points at what is here, and the other way in and the Triad row are silent (#1110) #1159's and adopt-project.py plan: ask about single-repository.yaml with its own drop-or-root rule, not the generic ambiguous-top-level-yaml question #528's files, and from test_shape_advisory.py.
  • The file defines its own adopter and doctor fixtures. That is right, because importing a module-scoped fixture would rerun it.
  • linked_here repeats about 11 lines of shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's linked_clone. linked_clone hard-codes AGENTS.md, and shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's file is lane 1's.
  • SonarCloud on the head: Quality Gate passed, 0 new issues, 0.0% duplication on new code.
• Skips. Every row that makes a link goes through symlink(), which skips where none can be made. There are no and/or asserts and no non-ASCII.

4. Mutants (25 runs: n1272's 13 and my 6, every file proved back at its sha256 after each)

• n1272's 13: all killed in my reproduction (logs/mutants-m1.out). The failed-row counts match the body's table: M1 6, M1b 3, M2 1, M3 2, M4/M5/M5b/M7 12 each, M6a 2, M6b 3, M8 2, M9 1, M10 2.
• My own six: four killed, two survived.
  • R1, _read_mapping lets OutOfTheCommit escape: killed by the 2 out-of-the-commit rows.
  • R2, a record link read as RECORD_ABSENT (no NOTE): killed by 12 rows.
  • R3, _read_mapping follows every manifest, link or not: survived (NIT 4).
  • R4, every committed link read from the disk: killed by 3 rows.
  • R5, is_link asks HEAD where the Tree reads the index: survived (NIT 3).
  • R6, the NOTE only where the link's path does not parse: killed by the spelled-record row.
• My rule breach. My first table ran R1 as one pytest run of 109 ids (35 + 47 + 27), and had R5 set to 103.
  • I stopped R3's pytest by PID, then the mutant script, then R5's orphaned run.
  • I restored scripts/shape_advisory.py from my saved head copy and checked it with sha256sum -c (all OK, tree clean).
  • I re-ran R1, R3, R5 and R6 in groups of 82/27, 82/52, 64/39 and 35 ids (mutants2.py, logs/mutants-m2.out). R4 had already run compliantly on 35 ids.

5. Gates at 16bee386d

• 11 calls per leg, 815 ids, each call at most 100 ids, -rs only.
• Files:
  • the new file;
  • test_adopt_single_repository_record.py, test_advisory_agents_md_symlink.py, test_shape_advisory.py, test_doctor_recorded_answers.py;
  • the doctor's rows that read shape_advisory: test_bom_reads.py, test_doctor_validator_verdicts.py, test_doctor_unsearchable_links.py, test_doctor_unreadable_paths.py, and 18 rows of test_shape_doctor.py;
  • the hygiene five, and test_no_auto_maintenance.py.
• git 2.43.0 (/usr/bin/git), git-filter-repo 2.47.0, CPython 3.12.3: 813 passed, 2 skipped (logs/gate-243-h1.out).
• git 2.47.1 (L/tools/git247/bin/git), the same filter-repo and Python: 813 passed, 2 skipped (logs/gate-247-h1.out).
• Skips: both legs skip tests/test_no_auto_maintenance.py:222 twice: "the session began with GIT_CONFIG_GLOBAL set, and its file includes that one".
• CI on the head: SonarCloud, package and tests-git-bash pass. tests (Python 3.14, full suite) was still running at 02:17:38Z, after starting at 01:50:29Z.

6. Merge-trees

• With main and shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270: main 930406996 (fresh) and shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's head b24382a87 both merge cleanly into tree 38e3b2a81, the head's own, because both are ancestors. git 2.47.1 gives the same tree for main.
• Open PRs touching the two files: only shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270, read fresh with gh pr list (41 open PRs).
• After shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270 lands as a squash: I simulated the squash as an unreferenced commit, commit-tree of b24382a87^{tree} on main (acbb3f2ad). merge-tree of that against the head exits 1 with a CONFLICT in scripts/shape_advisory.py (mt-squash.out). This is not a defect of the PR, but a plain merge of main will not do once shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270 is squashed: the stacked-after-squash route is needed.

7. The body's claims and counts

• It says Part of #1272, and closingIssuesReferences is [].
• A scan for any closing keyword followed by #N finds nothing, and body-guard exits 0.
• The body matches L/work/n1272/body.md up to its Lane line. After it come the lane-normal attribution line and the Sourcery block, as on adopt-project.py and update-shape.py: a revision git is asked about ends its argv in --, so a root file named HEAD no longer stops execute with exit 128 before that leg is pushed, nor blanks what apply --branch says it committed (#1215) #1294, repo_shape.py, path_classify.py, bump-leg.py, validate-repository-naming.py, update-shape.py and the root's validate-manifest.py: not-a-mapping and wrong-kind refusals name the file as shown_path does, so no U+202E, ESC or line feed is raw (#1279) #1284 and test_adopt_partial_clone_source.py: a partial clone whose recorded .git this user cannot read is pinned source-unreadable in check and execute, never source-partial-clone, with no gh call and no upload-pack run (#1262) #1289.
• All 35 ids, the 18/17 split, the mutant table, the 21 other PRs on adopt-project.py/shape-doctor.py/conftest.py, and the restore sha256 prefixes (40a766ca7adf, 6e2402aaeec3, 140100bcaae9) check out.

NITs

1. A false sentence in the test docstring and the body. tests/test_advisory_record_symlink.py lines 42-43, and the body's Rows section, say "Every case here makes a symlink, and skips where none can be made". The 7 control ids make none: the 4 in test_the_three_files_committed_as_regular_files_read_as_before and the 3 in test_a_git_that_cannot_list_the_commit_reads_a_regular_file_as_before. They need none and rightly run everywhere, so the sentence should say "every case that needs a symlink".
2. A landing note. When shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270 lands as a squash, a plain merge of main into fix/1272-record-symlink conflicts in scripts/shape_advisory.py (section 6). Use the stacked-after-squash route.
3. R5 survives. That the leg index "reads as before" rests on git refusing ls-tree "", and the leg-audit control stages the link only in the index, with a regular record in HEAD. Committing the link in the leg as well, or an explicit tree.commit guard in read_record, would pin it. Only the spelled link is affected. Optional.
4. R3 survives. No row pins that a regular manifest is read with text() rather than through --follow-symlinks. The two differ only under a git that refuses the follow. A stand-in row like shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's test_a_git_that_cannot_follow_the_link_is_silence_not_advice, for a regular project.yaml, would pin it. Optional.

Left behind: both trees are clean at 16bee386d; only pytest's ignored __pycache__ folders are there. No process of mine is running. Everything is in /workspace/projects/.lane-worktrees/openRepoShape-5/work/rv1295/: STATE.md, gate.sh, mutants.py, mutants2.py, probe1.py, probe2.py, the logs/ and probe/ folders, and mt-squash.out.

Lane: openreposhape-5 (openRepoShape-5)

[brettheap]

Delta check of #1295 (#1272) for lane openRepoShape-5, by rv1295b (sonnet), 16bee38..0c3999d: READY

I found no MUST, no SHOULD and no NIT in the delta. There are two observations below. I wrote nothing to GitHub: reads only (gh pr view, gh pr list, gh api GET). Everything I produced is under /workspace/projects/.lane-worktrees/openRepoShape-5/work/rv1295b/ (STATE.md, logs/, probes/, gate.sh, mutants3.py, mutants3b.py, base.py, mt.sh). Both review trees are detached at 0c3999d5a and clean, and the production files are at 40a766ca7adf (scripts/shape_advisory.py), 6e2402aaeec3 (adopt-project.py) and 140100bcaae9 (shape-doctor.py).

1. Nothing else changed

• git diff --stat 16bee386d..0c3999d5a lists one file: tests/test_advisory_record_symlink.py, +52/-8. The diff outside that file is 0 bytes, so no production file differs.
• Against shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's head b24382a87 the diff is 2 files, +557/-4. The body's first paragraph says the same.
• The commit subject is 240 characters. Its message has Part of #1272, the Lane line and Co-Authored-By, and no closing keyword. No commit in b24382a87..0c3999d5a has one.

2. NIT 1 (docstring and body sentence) is true

• I read all 39 ids. Every case that makes a link goes through linked_here or symlink(), which skips by name.
• Measurement: I loaded a plugin (probes/noslink_plugin.py) that makes Path.symlink_to and os.symlink raise OSError, and ran the file.
  • Result: 9 passed, 30 skipped (logs/noslink2.log). Every skip reads "no symlink here", from tests/test_doctor_unsearchable_links.py:173.
  • The 9 that pass are the controls: 4 of test_the_three_files_committed_as_regular_files_read_as_before, 3 of test_a_git_that_cannot_list_the_commit_reads_a_regular_file_as_before and 2 of test_a_git_that_cannot_follow_a_link_reads_a_regular_manifest_as_before.
• The module docstring and the body's Rows section name exactly those 9, so both are true.
• The 4 leg-audit controls (..._reads_a_record_link_as_before) are called "CONTROLS" in their docstring but need a link, so they skip. The module docstring does not count them among the controls that need none, so that is accurate.

3. R5, R3 and my rivals (the mut tree is rv1295-mut; each mutant was applied alone and restored from the saved bytes, with sha256 equal each time)

• R5 (is_link asks HEAD where the Tree reads the index): KILLED. It fails only test_the_doctors_audit_of_a_legs_index_reads_a_record_link_as_before[spelled-as-a-record-committed-too].
  • Run as 68 ids (the new file plus tests/test_doctor_recorded_answers.py): 1 failed, 67 passed.
  • Run on tests/test_adopt_single_repository_record.py: 39 passed.
  • So no row fails that should not.
• R3 (_read_mapping follows every manifest, link or not): KILLED. It fails exactly the two stand-in ids, test_a_git_that_cannot_follow_a_link_reads_a_regular_manifest_as_before[project-yaml] and [family-yaml].
  • Run as 86 ids (the new file plus tests/test_shape_advisory.py): 2 failed, 84 passed.
  • Run on tests/test_advisory_agents_md_symlink.py plus tests/test_bom_reads.py: 52 passed.
• My rivals for the new rows, each run on the new file's 39 ids:

rival	result
Q3c: family.yaml always read through the follow, link or not	KILLED by [family-yaml] of the stand-in alone (1 failed, 38 passed)
Q3d: project.yaml always read through the follow	KILLED by [project-yaml] of the stand-in alone (1 failed, 38 passed)
Q5: is_link falls back to HEAD when git refuses the listing	KILLED by [spelled-as-a-record-committed-too] alone (1 failed, 38 passed)
Q5f: read_record asks HEAD whether the record is a link	KILLED, 6 failed: 5 existing record rows and [spelled-as-a-record-committed-too]
Q5e: is_link says no link for an empty commit without asking git	SURVIVED, and it is an equivalent mutant: git refuses ls-tree "", so it behaves the same
Q3e: try the follow first for any manifest, fall back to the blob on Refusal	SURVIVED on 86 ids. For a regular manifest it behaves the same

• Each stand-in id pins its own manifest, and the [spelled-as-a-record-committed-too] id is the one that catches the R5 family.
• [to-a-record-in-the-leg-committed-too] kills nothing under R5, because the NOTE and the YamlError frame both give the general question. It is a pure control, and the docstring does not claim more.
• My first Q3c, Q3d and Q3e broke the disk reading (commit is None), so I redesigned them with a tree.commit is not None guard and reran. The numbers above are from the corrected versions.
• I also reran M6b, M8 and M10 on the new file (logs/mutants-m.out):

mutant	rows failed	what the body says
M6b	5	5
M8	4	4
M10	3	3

4. The 4 new ids are controls

• scripts/shape_advisory.py from b24382a87 (sha256 e0b0ef03f278, which equals 8e54c32de's) was swapped into the mut tree. I restored the head file and proved it equal.
• Result for the new file: 18 failed, 21 passed (logs/rv1295b-base1.log).
• The 4 new ids pass: [to-a-record-in-the-leg-committed-too], [spelled-as-a-record-committed-too] and both stand-in ids.
• The 18 failing ids are identical to L/work/n1272/base-failed.txt and to the failures in L/work/rv1295/logs/rv1295-base1.log.

5. Gates at 0c3999d5a

• Files: the new file, tests/test_advisory_agents_md_symlink.py, tests/test_shape_advisory.py, tests/test_adopt_single_repository_record.py, tests/test_doctor_recorded_answers.py, the hygiene five (test_agents_md_codes.py, test_cli_reference.py, test_path_guard_hygiene.py, test_pinned_copy_text.py, test_repo_hygiene.py) and tests/test_no_auto_maintenance.py.
• Ids: I collected 620 fresh. The list equals n1272b's gate-ids.txt (0 ids differ either way).
• Calls: 8 per leg, at most 78 ids each, -rs alone, two runs at once.
• git 2.43.0 (/usr/bin/git): 618 passed, 2 skipped (logs/gate-243-h1.out).
• git 2.47.1 (L/tools/git247/bin/git): 618 passed, 2 skipped (logs/gate-247-h1.out).
• Both legs used git-filter-repo 2.47.0, CPython 3.12.3 and pytest 9.1.1.
• Skips: on both legs tests/test_no_auto_maintenance.py:222 skips twice: "the session began with GIT_CONFIG_GLOBAL set, and its file includes that one".
• The per-call counts match the body's Runs table (78 ids per call, then 72 passed and 2 skipped in call 8).
• CI on the head, read just now: tests-git-bash, package and SonarCloud pass. tests (Python 3.14, full suite) was still IN_PROGRESS at my read.

6. Merge-trees (object-only, on git 2.43.0 and 2.47.1, with the same results)

• Main: fetched fresh.
  • Main was e720dad45 at the push. It is now 438cfad53 (adopt-project.py: a source whose refs this user cannot list is refused source-unreadable naming the directory, never source-default-branch-not-local "(its branches: none)" (#1219) #1252 landed since) and touched none of scripts/shape_advisory.py, tests/test_advisory_record_symlink.py or tests/test_advisory_agents_md_symlink.py.
  • The head merges cleanly with it, giving tree e285d24b6. At e720dad45 the tree was d128a0f2b, which is what the body states.
• shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's head, read fresh, is still b24382a87. The merge is clean and gives fad029fdb, the head's own tree, because it is an ancestor.
• Open PRs: 35 open, read fresh. Only shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270 touches scripts/shape_advisory.py or tests/test_advisory_agents_md_symlink.py, so no other PR touches this PR's two files. 20 other PRs touch adopt-project.py, shape-doctor.py or tests/conftest.py, as the body says.
• Predicted squash of shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270 on main (an unreferenced commit): merging it into the head gives CONFLICT in scripts/shape_advisory.py, as the body's Merges row and Known limits say.
• Three-merge route: I tried the body's route and it is mechanically clean. Merging the squash with -X ours, then merging main, gives tree e285d24b6, the same as head-with-main.

7. The record

• The body (logs: live-body.md, live-pr.json) is live at head 0c3999d5a, a draft on milestone v1.2.2, base fix/1163-agents-md-symlink at b24382a87.
• Part of #1272 appears once, closingIssuesReferences is [], a scan for any closing keyword followed by #N finds nothing, and body-guard exits 0.
• The body is n1272b/body.md plus the live Sourcery section. Everything above the Sourcery block is identical to n1272b/body.md, and the Sourcery section equals the capture n1272b took before posting.
• The new section "The round after rv1295's review" is true on every point I could measure:
  • rv1295's report is shape_advisory.py: a project.yaml or family.yaml committed as a symlink is read through it inside the commit, and a linked single-repository.yaml gets a NOTE that says it is a symlink not followed, never could not be read (YamlError) (#1272) #1295 issuecomment-6757105722 (GET: on shape_advisory.py: a project.yaml or family.yaml committed as a symlink is read through it inside the commit, and a linked single-repository.yaml gets a NOTE that says it is a symlink not followed, never could not be read (YamlError) (#1272) #1295, "by rv1295 (opus) ... READY").
  • One commit, tests only.
  • shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's head unchanged.
  • NIT 1 and the 9 controls verified in section 2.
  • R3 and R5 killed by the new ids only, and the 4 ids are controls passing at shape_advisory.py: a leg's AGENTS.md committed as a symlink is read through it inside the commit, and one out of the commit leaves whether it is a leg unknown, so adopt-project.py plan and check stop calling the leg a single repository (#1163) #1270's production, as in sections 3 and 4.
  • NIT 2 is a Known-limits bullet and a Merges row, both present.
• The Mutants table counts (19 killed, M6b 5, M8 4, M10 3, R3 2, R5 1) and the Runs table (620 ids, 618 passed, 2 skipped, 8 calls) agree with my measurements.

Observations (not findings)

1. The body names main e720dad45 and tree d128a0f2b. Both were true when it was written, and main has moved. The merge is still clean (section 6).
2. Rival Q3e survives. A manifest link under a git that cannot follow would, by inspection, read as its own blob if that fallback existed. No row pins "a manifest link under such a git advises". I did not measure that case, and the stakes are low: --follow-symlinks exists in every git this repository supports.

I started the mutant script once by mistake without DRY=1. It ran real mutants and was cut off by a closed pipe, after the tree had been restored. I verified the restore by sha256 and reran what was missing. No run exceeded 100 ids (the largest was 86), and nothing of mine is still running.

Lane: openreposhape-5 (openRepoShape-5)

[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