[brettheap]

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

Branch fix/528-adopt-single-repository-question, head 19ffe4a, on main 7d9bec9 (merged as 0d8336e).

What changed, and why

plan asked about a source's own single-repository.yaml under ambiguous-top-level-yaml: "a declaration the project has DECIDED (spec), configuration the implementation reads (code), or project-level wiring (root)". The file is none of those. It is this standard's optional record that a project STAYS one repository (contracts/single-repository-record.yaml), so a repository that carries one and is adopted into the Triad holds a record of the decision the adoption reverses. Its one reader, the Triad advisory, is silent in an assembly root whatever the file holds, so neither leg has any use for it.

The record is asked its own question, drop or root, and drop is written in as the default. Brett Heap ruled on 2026-10-12 (18:15:05Z, the A7 line of #457), choosing "Ask; default drop (Recommended)": "The default answer is drop". He did not choose "Ask; no default" ("the person must answer drop or root").

• contracts/path-classification.yaml: ambiguous-single-repository-record, above ambiguous-top-level-yaml, names the file, asks drop or root, and carries default: drop. The policy header says that a rule that asks may name a default, and only drop.
• plan writes the entry as leg: drop, with review_required: true, the rule and the question. check passes it. execute drops the file unless a person writes root, and the split commit names it among the paths it dropped. plan prints the default and its question just before the unresolved paths, and the plan's header says execute takes it as written.
• scripts/path_classify.py: Verdict carries the default beside the question and keeps leg None. The doctor's placement row walks a leg with adopt-project.py's own walk and calls a path misplaced when its leg names another leg (walked_findings), so a leg's copy stays a question there. A default is refused when the policy loads (path-policy-default) on a rule that does not ask, or as anything but drop. root unanswered would keep a path in the assembly root that nobody chose to keep, and a rule that answers spec or code says so in leg:.
• adopt-project.py: the default is written into an entry after both re-asks. ask_about_submodules and ask_about_refused_paths ask questions of their own, so they carry no default, and ask_about_refused_paths passes over a path that is already answered drop.
• Nothing refuses root, unlike ambiguous-project-yaml (adopt-project.py check passes a plan that keeps the source's own project.yaml in the root, and execute writes the shape's manifest beside it as shape/project.yaml and says adoption verified, so shape-doctor.py calls the adopted assembly NOT A SHAPE ROOT and its first make bootstrap fails #305): the file blocks nothing the shape writes, and no validator, gate or doctor row reads it. spec and code are not offered, and a hand edit to them is not refused either, because nothing breaks.

kind: decides, not the name. A file of that name declaring another kind, one that is not a mapping, and one that does not parse are not the record. The advisory says so in a NOTE in the same plan run. plan now reads the file at the commit it plans, through shape_advisory.read_record(Tree(path, commit)). Where the file is not the record, it gets the general question and leg: null, as before this rule. An uncommitted record does not count, as the advisory says too. release.yaml, a record spelled .yml and a nested single-repository.yaml keep the rule they had.

Docs. AGENTS.md step 2 gains one sentence: an entry whose leg: is its rule's default also carries a question, and execute takes it as written. The AGENTS.md cap moves from 490 to 492, with its dated reason in tests/test_repo_hygiene.py. No --help text changed, and scripts/render-cli-reference.py --check passes.

Tests

tests/test_adopt_single_repository_record.py (30 tests, run with git-filter-repo 2.47.0 on PATH):

• the rule, its place above the general question, and adopt-project.py's RECORD_RULE;

• the verdict: leg None, review_required, default == "drop";

• plan writes leg: drop with review_required: true, the rule and the question, and prints it apart from the unresolved paths;

• check passes the default unanswered, and execute gets past every plan refusal with it;

• execute adopts it with the record in no repository and named in the split commit's dropped list, and root keeps the source's blob at the assembly root;

• each non-record body is asked the general question; a record that leaves out a field is still the record; an uncommitted record is not;

• a default other than drop, or on a rule that does not ask, is refused (6 cases); a folded directory keeps its default;

• neither re-ask carries a default, and in plan a default over a name execute will not extract is not written in;

• the doctor's own walked_findings reads a leg's copy as a question.

• On the old head (60a258f's code, merged with main): 23 of the 30 fail, each for the reason its name gives. There is no Verdict.default, Entry.default or RECORD_RULE; a bad default is not refused; plan writes leg: null for the record; a file that is not the record still gets the record's question; and execute refuses plan-unresolved. The other 7 are guards that hold there too: the rule's order, the question's words, both answers passing check, root kept, the doctor's reading, and no default over a name execute will not extract.

• Mutants: 16, all caught (one to nine tests each). They are: the default filling Verdict.leg (drop as a class, which the doctor then calls misplaced); with_defaults doing nothing; it running before ask_about_refused_paths; either re-ask carrying a default; review_required written as leg is None; the policy naming no default; classify_file dropping it; a folded directory losing it; no validation; no printed default; with_its_default dropping the question; the record check reading nothing, reading the working tree, or taking any file present for the record; and skip ignored.

Targeted runs, 46 files: every tests/test_adopt_*.py, plus test_shape_doctor.py, test_scaffold_leg_path_collisions.py, test_cli_reference.py, test_repo_hygiene.py, test_doctor_next_is_a_command.py, test_stdout_encoding.py, test_shape_advisory.py and test_agents_md_codes.py.

• On the main merge 0d8336e: 3912 passed, 5 skipped, 0 failed.
• On the head 19ffe4a: 3930 passed, 5 skipped, 0 failed. That is the merge's 3912 plus the 18 new tests. gh was stubbed and never called.

The full suite and the three-OS CI run were not run here.

README follow-up (#519 has landed; this waits for its own README turn)

README.md:776-779 says that entries the policy cannot call "get leg: null, review_required: true and the QUESTION; execute refuses while any remain, because an unanswered question is never an implicit root". One sentence could follow it, with its mirror in docs/handbook.html: "One question comes answered: a source's own single-repository.yaml record is written leg: drop, its rule's default, still review_required: true with its question beside it, and execute drops it unless a person writes root." The paragraph is still true without the sentence, but it is incomplete.

docs/release-notes/v1.0.0.md lists this as a known limit ("a dedicated rule ... is planned (#528)"). That line belongs to the v1.0.0 notes and is left as written.

Closes #528

🤖 Generated with Claude Code

Summary by Sourcery

Handle a source repository’s own single-repository.yaml as a dedicated, reviewable adoption decision that defaults to dropping the record.

New Features:

• Add dedicated classification and adoption handling for a source repository’s own single-repository.yaml record, defaulting it to drop while retaining an explicit root option.
• Read the record’s kind at the planned commit so only genuine single-repository records receive the specialized question.

Bug Fixes:

• Prevent adopt-project.py plan from incorrectly asking whether the single-repository record is specification, code, or root-level wiring.

Enhancements:

• Support validated rule-level defaults for questions while preserving review requirements and ensuring follow-up questions do not inherit unrelated defaults.
• Make plan reporting and execution honor defaulted answers, including dropping the record from split repositories unless the plan is changed.
• Keep doctor placement analysis treating defaulted classifications as questions rather than finalized leg assignments.

Documentation:

• Clarify that entries carrying a rule default remain questions and that execution uses the default unless changed.

Tests:

• Add comprehensive coverage for record detection, default validation, plan/check/execute behavior, alternate answers, non-record files, commit-state reads, re-asked paths, and doctor placement handling.

Chores:

• Update repository hygiene limits to account for the expanded adoption guidance.

[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 1 day and 22 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Reviewer's Guide

The PR implements the policy entirely as a path-classification data change: the source’s own top-level single-repository.yaml receives a dedicated drop-or-root question, while preserving explicit-answer semantics and existing handling for other files. A comprehensive test module validates rule precedence, plan/check/execute behavior, and the resulting repository contents for both answers.

Sequence diagram for single-repository record adoption decisions

sequenceDiagram
    actor Person
    participant Plan as adopt-project.py
    participant Classification as path-classification.yaml
    participant Execute as execute
    participant Assembly as AssemblyRoot

    Person->>Plan: plan
    Plan->>Classification: ambiguous-single-repository-record
    Classification-->>Plan: drop or root (drop is the default)
    Plan-->>Person: single-repository.yaml with leg: null

    Person->>Plan: check
    Plan-->>Person: plan-unresolved
    Person->>Execute: execute
    Execute-->>Person: plan-unresolved

    alt Person answers drop
        Person->>Plan: answer drop
        Person->>Execute: execute
        Execute-->>Assembly: omit single-repository.yaml
    else Person answers root
        Person->>Plan: answer root
        Person->>Execute: execute
        Execute-->>Assembly: write single-repository.yaml at assembly root
    end

Loading

File-Level Changes

Change	Details	Files
Adds a dedicated path-classification rule for a repository’s top-level single-repository.yaml, separating it from the generic top-level YAML question.	Matches exactly the advisory’s RECORD_FILE name and places the rule before the general YAML rule. Classifies the file as an unresolved ambiguous path with a drop-first question offering only drop or root. Documents that the displayed default does not populate leg, so unanswered plans remain unresolved and execution still requires an explicit decision.	contracts/path-classification.yaml
Adds focused coverage for classification, planning, validation, and execution behavior of the single-repository record.	Verifies rule identity, precedence, wording, default ordering, and exclusion of spec and code. Confirms other YAML files, .yml records, and nested records retain their existing classification. Checks that unresolved plans fail while either explicit answer passes validation. Verifies drop removes the record from all output repositories, while root preserves the source blob only at the assembly root.	tests/test_adopt_single_repository_record.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#528	Add a dedicated path-classification rule for a source repository’s top-level single-repository.yaml, so adopt-project.py plan asks whether to drop it or keep it at the assembly root, with drop stated as the default instead of using the generic ambiguous-top-level-yaml question.	✅

Possibly linked issues

• Tracking: adopt-project.py, converting an existing repository in place #457: The PR implements A7 by adding ambiguous-single-repository-record above the generic YAML rule, with drop-or-root choices and drop as the default.

---

Tips and commands

Interacting with Sourcery

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

Customizing Your Experience

Access your dashboard to:

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

Getting Help

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

[brettheap]

(lane openRepoShape-2, 2026-10-14T23:55Z)

Lane openRepoShape-2 reviewed its own PR #566 at 60a258f, read-only in its own detached worktrees, and authored nothing.

CHANGES NEEDED. A fix round follows on this branch. The PR lands only on Brett Heap's word.

1. P2: the person must answer drop or root. At contracts/path-classification.yaml:434-437 and tests/test_adopt_single_repository_record.py:141-165, plan writes leg: null and execute refuses plan-unresolved. On 2026-10-12 Brett Heap chose "Ask; default drop" ("The default answer is drop") over "Ask; no default" ("the person must answer drop or root"). Fix: a rule default that plan writes as leg: drop, keeping review_required: true, the question and Verdict.leg None (scripts/path_classify.py:38, adopt-project.py:1302). execute then drops the file unless someone writes root. Otherwise, get Brett's word for the data-only reading.
2. P3: a top-level single-repository.yaml with another kind gets the record's question (:454-461). In the same plan run, the advisory says it "does not silence this". Default and word it only for kind: single-repository-record.
3. Nit: the PR body misquotes README.md:779 ("never an implicit root").

Tests at 60a258f: 3851 passed, 5 skipped across 45 targeted files, with git-filter-repo and no real gh. On bfed143 the new file gives 5 failed and 7 passed, each failure for its named reason, and every guard catches a mutant.

Merges: clean with main bfed143, #567 (bdcf300), #570 (79dfd33) and fix/522 (9ddb7ef).

The full report is in opensoft/brett-wip at handoffs/xFactory/attachments/lane-openRepoShape-2/review566-60a258f/final-report.md.

[brettheap]

(lane openRepoShape-2, 2026-10-15T13:35Z)

Lane openRepoShape-2 re-verified its own PR #566 at 19ffe4a, read-only in its own detached worktrees, and authored nothing.

MERGEABLE WITH NITS. F1, F2 and F3 are fixed. The PR lands on Brett Heap's word, after a refresh on main.

1. P3, follow-up on Tracking: shape-doctor.py, reporting a repository's compliance #460: shape-doctor.py:4492 walks a leg by name only, so a leg's single-repository.yaml that declares another kind gets the record's question in a note row. On main it got the general question.
2. Nit: README.md:776-779 still says every ambiguous entry gets leg: null. docs/handbook.html: stop every README PR rewriting the handbook's README blob and line cap, so open README PRs stop conflicting with each other #519 has landed, so the sentence can go in now or be filed.

Tests at 19ffe4a: 3930 passed, 5 skipped and 0 failed across 46 targeted files, with no real gh. On the predicted merge with main dd3f23a: 713 passed and 5 skipped in 9 files. Against the old code, the new file gives 23 failed and 7 passed, each failure for its named reason.

Merges: clean with main 64fc9a8 and dd3f23a (AGENTS.md 492, cap 492), #572 (9ddb7ef, 22ce69b) and #570 (b1db67c).

The full report is in opensoft/brett-wip at handoffs/xFactory/attachments/lane-openRepoShape-2/review566-60a258f/reverify-19ffe4a.md.

[sonarqubecloud]

Quality Gate passed

Issues
3 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