[brettheap]

Lane: openreposhape-2 (openRepoShape-2)
Claim: #286 (comment)
Merged main after #269 landed. #269 landed as the squash c1b6732, so this PR's base is main. The branch merged #269's final head 8a460e8 (merge 5cf81bb, no conflict), then origin/main a1b3a4b (merge e965ab0). The second merge conflicted in update-shape.py and tests/test_update_shape_add_symlink.py only: the squash carries 8a460e8's content of both files under a different history (git diff 8a460e8 origin/main on them is empty). Both were resolved to this branch's own version of the whole file, so git diff HEAD^1 HEAD on them is empty and git diff --stat origin/main HEAD listed only this PR's seven files. shape-doctor.py and tests/test_shape_doctor.py merged without a conflict. Main is not merged again by the fix round below; each count says the head it was run at.

Fix round (review of e965ab0)

The lane's review of e965ab0 found one P2 (codex's open P2, discussion_r4247927074, reproduced), one P3 left for a follow-up issue, and two nits. Two commits on top of e965ab0, head 9423361:

• Item 1 (P2), 8869f5e. A root that kept contracts/shape-pin.yaml, the contracts directory above it, or its manifest as a committed symlink made shape-doctor.py say CANNOT ANSWER, exit 3, with NEXT git -C <standard> fetch --all, which changes nothing; main read through the link and said COMPLIANT. The doctor filed every refusal prepare raised as environment, and this PR had added update-rewrite-symlink to them. Now:
  • update-shape.py has one function, linked_record(root, kind), for the first of the pin and the kind's manifest that is a symlink or sits under one. read_pin and prepare refuse over its answer; the refusal and its text are unchanged.
  • shape-doctor.py's check_shape_currency asks linked_record_row FIRST, before anything reads the pin or opens the standard as the upstream. The row is a finding with no environment: update-shape.py cannot re-pin this root: REFUSED update-rewrite-symlink: <detail>, detail {error, path, link, points}, and a NEXT that says the refusal's remedy: replace the link with the file or directory it points at, commit that, run the doctor again. The verdict is INVALID (shape-currency), exit 1. The split is by which question raised, not by refusal codes, and it comes before shape-doctor.py: a root's own contracts/shape-pin.yaml that does not read as a pin (a merge conflict, a non-UTF-8 byte, a commit: that is not 40 hex, a deleted file) is INVALID, exit 1, with the git command that puts back the last pin a tool wrote as its NEXT, instead of CANNOT ANSWER, exit 3, sending the reader to git fetch --all in the standard (#237) #267's read_pin pass whichever of the two lands second (see Composes with).
  • Following that NEXT by hand (remove the link, copy what it pointed at into its place, commit) gives COMPLIANT, exit 0, for the pin, the contracts directory and project.yaml (tools/x347/x347-probe-wt.log).
  • No other refusal prepare raises is newly misfiled: read_pin's older ones are 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, fixed by shape-doctor.py: a root's own contracts/shape-pin.yaml that does not read as a pin (a merge conflict, a non-UTF-8 byte, a commit: that is not 40 hex, a deleted file) is INVALID, exit 1, with the git command that puts back the last pin a tool wrote as its NEXT, instead of CANNOT ANSWER, exit 3, sending the reader to git fetch --all in the standard (#237) #267; open_upstream's and an unresolvable revision really are this checkout; classify raises nothing for a link.
• Item 3 (nit), 9423361. The confirm-window test also covers project.yaml, and a contracts DIRECTORY link, arriving while apply waits. Both were already refused and rolled back; now they are pinned.
• Item 4 (nit). This description. "Left out" no longer calls the doctor's answer "the 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 class": on main those roots read COMPLIANT, so the CANNOT ANSWER was new with this PR, and it is fixed above. The compose table names update-shape.py: apply --add refuses a path under a file the root keeps as update-add-not-a-directory before it writes anything, and a write that fails after the copies is update-write-failed, rolled back, so neither leaves a rewritten copy and an unmoved pin behind a traceback (#285) #346 at 818db36 and is re-measured at 9423361.
• Item 2 (P3), not in this PR. A HARD-linked copy, pin or manifest is still rewritten through its other name. It is a follow-up issue (see Left out).

What

update-shape.py apply refuses, before it writes anything, to rewrite a file that is a symlink in the root or sits under one. That covers the three files it overwrites: a pinned copy, contracts/shape-pin.yaml and the manifest. It reuses #269's symlink_on_the_way walk and is_link_info, so a Windows junction counts as a link here too.

• A pinned copy: _classify_row gives the row a verdict of its own, copy-is-link, counted with the conflicts. The detail names the link and where it points. check prints the row, counts it and names it in REFUSAL AHEAD. apply refuses every such row at once (_refuse_linked_copies), ahead of update-conflict, whose merge and --accept-local remedy does not fit a link. --accept-local on such a path is refused the same way.
• The pin: read_pin refuses it. The link is checked before is_file(), so a dangling one is named as the link it is, not as a pin that "does not exist".
• The manifest: prepare refuses it, right after the pin. Both are refused before the upstream is opened, so check refuses them too (exit 2), as it does any pin it cannot use. Both ask linked_record, the one function that names a linked record.
• A link that arrives while confirm waits: Rollback.write walks the path again before it opens it. A link found there is refused by name, and cmd_apply's refusal arm puts back what was already written. This is what update-shape.py: a path the root holds a symlink or a Windows junction at, dangling or live, or under one, is present and apply --add refuses it as update-add-symlink before it writes anything, and the ledger creates an addition exclusively, so a dangling link no longer has the standard's file written through it outside the root, and a red validator no longer deletes the operator's link (#239) #269's exclusive create does for --add.
• One refusal, update-rewrite-symlink, the rewrite counterpart of --add's update-add-symlink:
  • one path gives one line: "apply would rewrite , but in this root is a symlink[, on the way to ], pointing at ''. A rewrite goes THROUGH a link …";
  • several copy-is-link rows give a list, one path per line, as update-conflict lists its own;
  • link_said is the one phrase every link refusal and verdict prints, update-shape.py: a path the root holds a symlink or a Windows junction at, dangling or live, or under one, is present and apply --add refuses it as update-add-symlink before it writes anything, and the ledger creates an addition exclusively, so a dangling link no longer has the standard's file written through it outside the root, and a red validator no longer deletes the operator's link (#239) #269's included.
• update-shape.py: a path the root holds a symlink or a Windows junction at, dangling or live, or under one, is present and apply --add refuses it as update-add-symlink before it writes anything, and the ledger creates an addition exclusively, so a dangling link no longer has the standard's file written through it outside the root, and a red validator no longer deletes the operator's link (#239) #269's sentence is the whole command's again: "this command never writes through a symlink". It says symlink, not link, because a hard-linked copy is still rewritten through its other name (see Left out).
• The control holds: a DANGLING link at a pinned copy is still copy-missing, refused as update-conflict before any write. A root reached THROUGH a link still updates.

shape-doctor.py. Two answers:

• A linked pinned copy: drifted_file_reasons names copy-is-link, so the verdict reads DRIFTED (1 copy-is-link), as copy-missing does. The row was already drifted through is_conflict, but copy-is-link was not among the states the verdict line names, so DRIFTED had no reason to print and the verdict fell through to the catch-all INVALID (shape-currency). A mutant run without the tuple entry gives exactly that.
• A linked pin, contracts directory or manifest (project.yaml, or a holder's family.yaml): INVALID (shape-currency), exit 1, quoting update-shape.py's refusal, with its remedy as NEXT (the fix round's item 1). The NEXT is said, not spelled as a command: what the link points at may be shared with other trees, and removing a link, a junction above all, is a person's call.

--help is unchanged, so docs/cli.md is too (render-cli-reference.py --check ok).

Why

Rollback.write opens the file it rewrites r+b, which follows a link at the path or above it. Reproduced with the issue's steps on main a1b3a4b, which holds #269 as the squash c1b6732 (tools/repro-main-a1b3a4b.log), and before #269 landed on its head ca68458, with the same three results. Every repository was local, and gh was a shim that was never called.

• AGENTS-shape.md committed as a link to a file outside the root:
  • check said upstream-changed.
  • apply --yes --branch shape/update exited 0 and rewrote the outside file (8694c502cdfd → 9e88c8e59159).
  • It printed committed on shape/update: AGENTS-shape.md, contracts/shape-pin.yaml, project.yaml, but the commit holds only contracts/shape-pin.yaml | 6 and project.yaml | 4.
• The pin committed as a link outside: exit 0, and the outside pin was rewritten (6fc45ef78a23 → 1dd574789177). The commit holds AGENTS-shape.md and project.yaml, not the pin.
• scripts as a directory link to a copy outside:
  • the copies were written through the link;
  • the validators resolved their own location through the link and failed with REFUSED not-a-git-repo at the outside directory;
  • update-validators-red;
  • ROLLED BACK, writing the old bytes back through the same link.

At the merge head e965ab0 (tools/repro-head-e965ab0.log) the three runs each exit 2 with REFUSED update-rewrite-symlink. In every case the file at the link's end is unchanged, HEAD is the operator's commit, and no branch was created.

Tests

• tests/test_update_shape_rewrite_symlink.py (new, 29 tests; the link tests carry the suite's WINDOWS_SKIP; the junction cases run everywhere by handing the walk what lstat gives for a junction):
  • (a) check reports copy-is-link. apply refuses, with and without --branch × validators green and red, plus --accept-local. The link's end, the whole tree (bytes, modes, links, HEAD, branches, index, status) and the directories beside the root are unchanged.
  • (b) The pin as a link, the pin under a contracts directory link, and the manifest as a link. For each: check refuses on one REFUSED line, and apply refuses with and without --branch. A dangling pin link is named as a link.
  • (c) scripts as a directory link. Every copy under it is copy-is-link, and apply --branch refuses before the validators run.
  • (d) Controls: a dangling link at a pinned copy stays copy-missing / update-conflict. A root reached through a link, with an unrelated link inside it, updates and stays green.
  • Ledger:
    • a link arriving while confirm waits, at a pinned copy, at the pin, at the manifest, or as a contracts directory link above the pin, is refused, and what was written before it is restored;
    • Rollback.write alone refuses a link at the path or above it;
    • it still rewrites a plain file.
  • Junctions: a junction above a pinned copy, above the pin and at the manifest.
• tests/test_shape_doctor.py: +5.
  • AGENTS-shape.md kept as a committed link gives DRIFTED (1 copy-is-link), exit 1, with counts {copy-is-link: 1, unchanged: 10} and conflicts [AGENTS-shape.md].
  • The pin, the contracts directory and project.yaml (parametrised), and a family holder's family.yaml, each kept as a committed link: INVALID (shape-currency), exit 1, no environment in the row, error update-rewrite-symlink, the link named in the reason, no fetch in NEXT, and no other row red. All four fail on e965ab0's code with CANNOT ANSWER, exit 3 (tools/x347/x347-item1-head-doc.log).
• tests/test_update_shape_add_symlink.py: update-shape.py: a path the root holds a symlink or a Windows junction at, dangling or live, or under one, is present and apply --add refuses it as update-add-symlink before it writes anything, and the ledger creates an addition exclusively, so a dangling link no longer has the standard's file written through it outside the root, and a red validator no longer deletes the operator's link (#239) #269's wording asserts follow the widened sentence.
• tests/test_update_shape.py, tests/test_update_shape_add.py: the STATES tuples ("every verdict check can print") learn copy-is-link.

Against main's code: main 92e29d9's update-shape.py and shape-doctor.py with this branch's test files (tools/x347/x347-mb-own.log, tools/x347/x347-mb-doc.log). The earlier measurements on a1b3a4b and ca68458 gave the same reasons for the 27 tests the file had then.

• The new file: 26 failed, 3 passed. The 3 that pass are the controls. The decisive lines:
  • "the standard's bytes were written THROUGH the link, outside the root";
  • "a record was rewritten THROUGH the link, outside the root";
  • "the refusal came after a write, and the run rolled back", for validators red, and for the pin under a contracts link with --branch, where git's own commit refuses a path beyond a link;
  • check exit 1 where 2 is expected, and check calling a linked copy upstream-changed where copy-is-link is expected;
  • DID NOT RAISE for the ledger and the four confirm-window cases;
  • 'already-at-target' == 'copy-is-link' and 'update-upstream-unresolvable' == 'update-rewrite-symlink' for the junctions;
  • REFUSED update-pin-missing for the dangling pin.
• The doctor tests: 5 failed, every verdict COMPLIANT.
• update-shape.py: a path the root holds a symlink or a Windows junction at, dangling or live, or under one, is present and apply --add refuses it as update-add-symlink before it writes anything, and the ledger creates an addition exclusively, so a dangling link no longer has the standard's file written through it outside the root, and a red validator no longer deletes the operator's link (#239) #269's file: the 8 parametrised wording asserts fail at the new sentence (measured on a1b3a4b, tools/base-main-a1b3a4b-link-tests.log).

Mutants:

• _classify_row's link check removed: 8 of the new tests fail. The ledger guard still refused, but only after writing scripts/validate-manifest.py and rolling it back, which "before any write" catches.
• copy-is-link dropped from the doctor's tuple: the doctor test fails with INVALID (shape-currency).
• At 9423361 (tools/x347/x347-mutants-driver.log), every one killed:

mutant	killed by
Rollback.write's walk removed	the 4 confirm-window cases, the 2 new ones included (DID NOT RAISE Refusal)
the doctor's linked_record_row call removed	the 4 new doctor tests (CANNOT ANSWER, exit 3)
the doctor asks about the pin alone	the project.yaml and family.yaml doctor tests
the doctor asks about project.yaml on every kind of root	the family.yaml doctor test
linked_record ignores the kind (no manifest)	6: the two manifest doctor tests, check and apply (× --branch) on a linked manifest, and the junction at the manifest
the row keeps environment: True	the 4 new doctor tests (CANNOT ANSWER)

Targeted runs (git-filter-repo on PATH):

run	result
at 9423361: test_update_shape.py, _add, _add_ignored, _add_symlink, _landing, _pr_base, _rewrite_symlink, test_cli_reference.py, test_repo_hygiene.py	310 passed, 3 skipped (NTFS-only junctions)
at 9423361: tests/test_shape_doctor.py	259 passed, 3 skipped (the PowerShell line, Windows-only)
at 9423361: scripts/render-cli-reference.py --check	ok
at e965ab0 (merge head, before the fix round): the same update-shape set	308 passed, 3 skipped
at e965ab0: tests/test_shape_doctor.py	255 passed, 3 skipped

Composes with

git merge-tree --write-tree 9423361 <head>, with the heads as this lane's object store holds them (not re-fetched):

head	rc	conflicts
origin/main 92e29d9	0	—
#267 8badae0 (fix/doctor-root-shape-pin-unreadable)	0	—
#346 818db36 (fix/update-shape-add-not-a-directory, lane-mate, issue #285)	0	—
#343 9e6caeb, #352 797c96b, #353 96ff0c7, #355 a03abcf, #356 0aff5ae, #266 3410be7	0	—
#401 6124cb4, #403 e2c78ee, #404 f9d420a, and the branches for #386 (d53602b) and #359 (6eb8e4e), which have no PR yet	0	—
#354 604e2d7, #357 8ad856f, lane 3's fix/update-shape-pr-rerun-pin-source f1dcd2a	0	—
#358 2745890	1	shape-doctor.py, 4 hunks in check_manifest_kinds: the same 4 hunks #358 meets against main 92e29d9 alone, so not this PR's

Merged trees, tested:

• With shape-doctor.py: a root's own contracts/shape-pin.yaml that does not read as a pin (a merge conflict, a non-UTF-8 byte, a commit: that is not 40 hex, a deleted file) is INVALID, exit 1, with the git command that puts back the last pin a tool wrote as its NEXT, instead of CANNOT ANSWER, exit 3, sending the reader to git fetch --all in the standard (#237) #267 ((9423361 + 8badae0) + 92e29d9 = 5ed50c6). check_shape_currency there asks this PR's linked_record_row first, then shape-doctor.py: a root's own contracts/shape-pin.yaml that does not read as a pin (a merge conflict, a non-UTF-8 byte, a commit: that is not 40 hex, a deleted file) is INVALID, exit 1, with the git command that puts back the last pin a tool wrote as its NEXT, instead of CANNOT ANSWER, exit 3, sending the reader to git fetch --all in the standard (#237) #267's read_pin pass, then prepare, so a linked pin, contracts directory or manifest is this PR's row and a pin that does not read is shape-doctor.py: a root's own contracts/shape-pin.yaml that does not read as a pin (a merge conflict, a non-UTF-8 byte, a commit: that is not 40 hex, a deleted file) is INVALID, exit 1, with the git command that puts back the last pin a tool wrote as its NEXT, instead of CANNOT ANSWER, exit 3, sending the reader to git fetch --all in the standard (#237) #267's. tests/test_shape_doctor.py: 286 passed, 3 skipped (the PowerShell line, Windows-only). _rewrite_symlink + _add_symlink: 67 passed, 3 skipped (NTFS junctions). Without that order, shape-doctor.py: a root's own contracts/shape-pin.yaml that does not read as a pin (a merge conflict, a non-UTF-8 byte, a commit: that is not 40 hex, a deleted file) is INVALID, exit 1, with the git command that puts back the last pin a tool wrote as its NEXT, instead of CANNOT ANSWER, exit 3, sending the reader to git fetch --all in the standard (#237) #267 answers a contracts directory link with a history restore of the pin alone, which leaves the other three files deleted and the root DRIFTED, and leaves a linked manifest CANNOT ANSWER.
• With update-shape.py: apply --add refuses a path under a file the root keeps as update-add-not-a-directory before it writes anything, and a write that fails after the copies is update-write-failed, rolled back, so neither leaves a rewritten copy and an unmoved pin behind a traceback (#285) #346 ((9423361 + 818db36) + 92e29d9 = c34c519): _rewrite_symlink, _add_symlink, _add_not_a_directory, test_update_shape.py, _add: 179 passed, 3 skipped (NTFS junctions). The fix round keeps linked_record beside rewrite_link_refusal rather than after symlink_on_the_way, where update-shape.py: apply --add refuses a path under a file the root keeps as update-add-not-a-directory before it writes anything, and a write that fails after the copies is update-write-failed, rolled back, so neither leaves a rewritten copy and an unmoved pin behind a traceback (#285) #346 adds not_a_directory_on_the_way and the two would conflict.
• update-shape.py: apply --add refuses a path under a file the root keeps as update-add-not-a-directory before it writes anything, and a write that fails after the copies is update-write-failed, rolled back, so neither leaves a rewritten copy and an unmoved pin behind a traceback (#285) #346's ledger.writing() turns an OSError from the writes into update-write-failed. This branch's guard raises a Refusal, which passes through that wrapper to the same rollback arm.

Left out

• Hard links. A pinned copy, the pin or the manifest that is a HARD link is still rewritten through its other name (Rollback.write opens it r+b). Only the README refuses one (README_HARDLINK). That is why the restored sentence says "symlink". It is a follow-up issue.
• Docs. README.md is capped and docs/handbook.html pins its blob. Its verdict list does not name copy-missing either. The verdict, the refusal and the doctor's answer are described in update-shape.py's and shape-doctor.py's docstrings and code.
• Two residual windows.
  • A link that arrives in the instant between Rollback.write's walk and its open. O_NOFOLLOW would close it for the last component on POSIX; it was not used because of Windows text-mode risk on an os.open path.
  • A written file replaced by a link before an undo writes it back. update-shape.py: a path the root holds a symlink or a Windows junction at, dangling or live, or under one, is present and apply --add refuses it as update-add-symlink before it writes anything, and the ledger creates an addition exclusively, so a dangling link no longer has the standard's file written through it outside the root, and a red validator no longer deletes the operator's link (#239) #269's write_added has the matching above-path window.
• A choice beyond the issue. A dangling link at the pin is refused as update-rewrite-symlink and not as update-pin-missing, because ls shows something there and the old remediation sent the operator to adopt-project.py.

Closes #286

🤖 Generated with Claude Code

Summary by Sourcery

Refuse shape rewrites through symlinks and report linked repository records clearly before any writes occur.

New Features:

• Prevent shape updates from writing through symlinks or junctions for pinned copies, the shape pin, and root manifests.
• Report linked pinned copies as copy-is-link conflicts and refuse affected updates with a dedicated update-rewrite-symlink error.
• Have shape-doctor identify linked pins and manifests as actionable shape-currency findings rather than environment errors or CANNOT ANSWER.

Bug Fixes:

• Prevent updates and rollbacks from modifying files outside the repository through links, including links introduced while confirmation is pending.
• Preserve existing handling for dangling pinned-copy links and roots reached through links.

Enhancements:

• Unify linked-record detection and link refusal messaging across update and doctor workflows.
• Extend symlink coverage to directory links and Windows junctions.

Tests:

• Add comprehensive coverage for linked copies, pins, manifests, directory links, late-arriving links, rollback protection, and junctions.
• Update state and wording assertions for the new copy-is-link status and command-wide symlink safety guarantee.

[brettheap]

@codex review

[chatgpt-codex-connector]

Codex Review Summary

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

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-12T17:55:14.032524Z	9423361	Manual request

ℹ️ About Codex in GitHub

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

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

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

[sourcery-ai]

Sorry @brettheap, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 2 days and 6 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Reviewer's Guide

The PR closes the rewrite-through-link safety gap by classifying linked pinned copies, refusing linked pins/manifests and late-arriving links before writes, and adding rollback-aware protections with consistent diagnostics; it also exposes the new state in shape-doctor and expands regression coverage across symlinks and junctions.

Sequence diagram for refusing rewrites through symlinks

sequenceDiagram
    participant Apply as cmd_apply
    participant Prepare as prepare
    participant Pin as read_pin
    participant Classify as _classify_row
    participant Guard as _refuse_linked_copies
    participant Ledger as Rollback.write

    Apply->>Prepare: prepare(args)
    Prepare->>Pin: read_pin(root)
    Pin-->>Prepare: linked pin refusal
    Prepare-->>Apply: update-rewrite-symlink

    Prepare->>Classify: classify pinned copies
    Classify-->>Prepare: copy-is-link rows
    Apply->>Guard: _refuse_linked_copies(rows)
    Guard-->>Apply: update-rewrite-symlink

    Apply->>Ledger: write(path, data)
    Ledger-->>Apply: recheck path and parents
    Ledger-->>Apply: update-rewrite-symlink if link arrived

Loading

Flow diagram for linked-copy classification and apply refusal

flowchart TD
    A["Pinned path is evaluated"] --> B{"is_file() succeeds?"}
    B -- "no" --> C["copy-missing / update-conflict"]
    B -- "yes" --> D{"symlink_on_the_way finds a link?"}
    D -- "no" --> E["Compare with upstream"]
    D -- "yes" --> F["copy-is-link"]
    F --> G["Count as a conflict"]
    G --> H["_refuse_linked_copies"]
    H --> I["REFUSED update-rewrite-symlink"]
    E --> J["Normal verdict and apply handling"]

Loading

File-Level Changes

Change	Details	Files
Prevent update-shape from writing through symlinks or junctions during rewrites.	Detect links at pinned copies and paths above them, classify non-dangling copies as copy-is-link, and count them as conflicts. Reject linked pins and manifests before opening upstream data, with a shared update-rewrite-symlink refusal and consistent link-target messaging. Recheck paths in Rollback.write to handle links introduced while confirmation waits, preserving rollback behavior for prior writes. Keep the root itself traversable through a symlink and retain copy-missing behavior for dangling pinned-copy links.	update-shape.py
Make shape-doctor surface linked pinned copies as a specific drift reason.	Include copy-is-link in the named drift-reason states so verdicts report DRIFTED (N copy-is-link) instead of falling through to INVALID (shape-currency).	shape-doctor.py
Add comprehensive coverage for rewrite-link safety and update existing state and wording assertions.	Test check/apply refusal, pin and manifest links, directory links, junctions, links introduced during confirmation, rollback integrity, --accept-local, and unaffected controls. Verify doctor output, state lists, and the command-wide symlink wording.	tests/test_update_shape_rewrite_symlink.py tests/test_shape_doctor.py tests/test_update_shape.py tests/test_update_shape_add.py tests/test_update_shape_add_symlink.py

Possibly linked issues

• update-shape.py apply rewrites a pinned copy, contracts/shape-pin.yaml or the manifest THROUGH a symlink the root keeps at that path (Rollback.write opens it r+b), so the standard's bytes land at the link's end, outside the root if that is where it points, with exit 0, and --branch reports a commit holding a file that commit does not contain #286: PR directly fixes issue update-shape.py apply rewrites a pinned copy, contracts/shape-pin.yaml or the manifest THROUGH a symlink the root keeps at that path (Rollback.write opens it r+b), so the standard's bytes land at the link's end, outside the root if that is where it points, with exit 0, and --branch reports a commit holding a file that commit does not contain #286 by preventing symlink-following rewrites and adding copy-is-link conflict handling.

---

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.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2c9b516ba3

ℹ️ About Codex in GitHub

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

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

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

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

[chatgpt-codex-connector]

Classify linked records as repository findings

When shape-doctor.py checks a root whose manifest (or, via the analogous new read_pin check, shape pin) is a symlink, this new refusal is caught by check_shape_currency's generic except Refusal and unconditionally tagged environment: True, with remediation to fetch the standard. The doctor consequently reports CANNOT ANSWER/exit 3 even though the checkout can answer and the problem is entirely in the inspected repository; handle update-rewrite-symlink as a repository finding rather than an environment failure.

AGENTS.md reference: AGENTS.md:L197-L203

Useful? React with 👍 / 👎.

[brettheap]

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

Fixed in 8869f5e (head 9423361). A pin, a contracts directory or a manifest kept as a committed symlink is now a statement about the repository: INVALID (shape-currency), exit 1, not CANNOT ANSWER.

• update-shape.py has one function, linked_record, that names the linked record. read_pin and prepare refuse over its answer.
• shape-doctor.py asks the same function first, before anything reads the pin or opens the standard. The row has no environment, quotes REFUSED update-rewrite-symlink: …, and its NEXT is the refusal's remedy: replace the link with what it points at, commit, run the doctor again. No fetch.
• tests/test_shape_doctor.py covers the pin, contracts, project.yaml and a holder's family.yaml. All four fail on e965ab0 with CANNOT ANSWER, exit 3. Six mutants were killed.

[brettheap]

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

This lane reviewed its own PR #347 at e965ab0, read-only, in its own detached worktrees. Nothing was authored.

CHANGES NEEDED. Fix item 1 here. The doctor must answer a linked pin or manifest before #267's read_pin pass, whichever of the two lands second.

1. P2 (codex's thread, reproduced). If contracts/shape-pin.yaml, contracts/ or project.yaml is a committed symlink, the doctor says CANNOT ANSWER, exit 3, with NEXT git fetch --all. Main says COMPLIANT.
   • Cause: shape-doctor.py:1637-1650 tags the new update-rewrite-symlink refusals (update-shape.py:418, :1621) as environment.
   • It should be INVALID (shape-currency), exit 1, quoting the refusal, with a NEXT that replaces the link with its target and commits.
   • shape-doctor.py: a root's own contracts/shape-pin.yaml that does not read as a pin (a merge conflict, a non-UTF-8 byte, a commit: that is not 40 hex, a deleted file) is INVALID, exit 1, with the git command that puts back the last pin a tool wrote as its NEXT, instead of CANNOT ANSWER, exit 3, sending the reader to git fetch --all in the standard (#237) #267's history restore does not cover this: for a contracts/ link it brings back only the pin, which leaves the root DRIFTED.
   • No other prepare refusal is newly misfiled.
2. P3, follow-up. A hard-linked copy, pin or manifest is still rewritten through its other name (update-shape.py:2105). This is documented in the PR, and no issue exists for it yet.
3. nit. The confirm-window test (tests/test_update_shape_rewrite_symlink.py:470) could add the manifest and a directory link. Both are already refused.
4. nit. The PR body calls item 1 "the 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 class", but it is new here. The body also names update-shape.py: apply --add refuses a path under a file the root keeps as update-add-not-a-directory before it writes anything, and a write that fails after the copies is update-write-failed, rolled back, so neither leaves a rewritten copy and an unmoved pin behind a traceback (#285) #346's old head.

All four new guards' mutants are killed. Against main's code, the new file gives 24 failed and 3 passed, for the right reasons.

tree	update-shape set	doctor
e965ab0	308 passed, 3 skipped	255 passed, 3 skipped
merged with main ab623dd	308 passed, 3 skipped	255 passed, 3 skipped
merged with #346 818db36	172 passed, 3 skipped	not run

The doctor run merged with a newer main never finished: a usage checkpoint stopped it. The fix round's head will be tested against main instead. CI is green on all three OSes, and render-cli-reference.py --check is ok.

git merge-tree is rc 0 for main 28bdc84, #245, #267, #343, #346, #354 and #357. #358 is rc 1, and the same conflict appears against main alone.

Report: handoffs/xFactory/attachments/lane-openRepoShape-2/review347-e965ab0/final-report.md in opensoft/brett-wip.

[sourcery-ai]

Sourcery assessment

Approved.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
1.4% Duplication on New Code

See analysis details on SonarQube Cloud

[brettheap]

(lane openRepoShape-2, 2026-10-13T14:06Z)

SonarCloud failed this PR at 1001588 on one finding, pythonsecurity:S8705 at update-shape.py:3192 (issue AaE1ixbCnmZ6Sl3VWyVf). The head before the main merge, c2c5f3b, passed. This lane marked the finding False Positive on Brett Heap's word ("Mark FP, then land", 2026-10-13T14:05Z), and the PR's quality gate now reads OK.

Why it is a false positive:

• The flagged line builds the NEXT line that the landing's refusal PRINTS: shlex.join(["git", "-C", str(root), "push", "-u", "--", "origin", branch]). Nothing runs it.
• -- comes before origin and the branch, so git would read the branch as a name and never as an option.
• checked_value("--branch", branch) (update-shape.py:2217) already refuses a branch that begins with -.

The source Sonar names is the command line (update-shape.py:3815, parse_args). The person running the tool supplies it, and every step on the path checks it.