[brettheap]

Lane: openreposhape-4 (openRepoShape-4)
Claim: #410 (comment)
Claim: #448 (comment)
Claim: #447 (comment)

What changed and why

This PR applies one rule to every child the doctor reads. It comes from the v1.1.0 triage on #410 (comment), which Brett Heap approved at 14:31:28Z on 2026-10-14:

A verdict is a printed FINDING or REFUSED. Any other non-zero exit is a crash. A WARNING or note line on a pass makes the row a note.

The change is in shape-doctor.py only.

• crashed() (shape-doctor.py, after #357's crashed(), still reads a validator killed by a signal (a negative exit, -9 or -15) or one that left by os._exit(1) with nothing printed as one that "reports a finding", because crashed() needs a traceback line, so a root's own gate ended by the OOM killer or a timeout's SIGTERM is a FINDING about the project, and the standard's template killed the same way is not CANNOT ANSWER #447). It no longer needs a Traceback (most recent call last): line. A non-zero exit with no FINDING or REFUSED line anywhere in the output is a crash. Each of these used to read "reports a finding" or "refuses":

  • a signal (exit -9 or -15);
  • os._exit(1) with nothing printed;
  • merge-conflict markers (a SyntaxError, which prints no traceback header);
  • can't open file;
  • an argparse usage: error (exit 2).

  The quoted line is the output's last line. With no output, it says so and names the signal. A FINDING printed before the child died still stands, as shape-doctor.py: a validator that crashed says it crashed instead of "reports a finding", and is CANNOT ANSWER when it is the standard's template, which a standard whose path holds the PYTHONPATH separator no longer runs at all; a neutral product's digest validate-pins.py skipped is a note naming the product, from a child that can no longer reach gh or a proxy; and a root whose manifest does not load and whose scripts/repo_shape.py is gone is told to restore that file before its gate (#278, #297, #298) #357 ruled. The verb a verdict row picks by its code ("refuses" for 2) is now reached only by a child that printed one of the two words.

• The naming rows (shape-doctor.py's two naming rows read only the naming script's exit code, so a crash of the STANDARD's own validate-repository-naming.py is a FINDING about the project (INVALID (naming), exit 1, where #357 makes a crashed template CANNOT ANSWER), and a directory whose name is not UTF-8 gets naming FINDING Atl?as: UnicodeEncodeError: ..., the script's traceback quoted as a fact about the name #410). Both rows ask crashed(). The naming script is always this checkout's, so a crash carries detail.crashed and detail.environment, as a crashed template validator does:

  • in an assembly root the verdict is CANNOT ANSWER, exit 3. The reason ends "that script is this checkout's, not the project's, so nothing here is a statement about the project";
  • in a directory that is not a root, the verdict stays NOT A SHAPE ROOT, exit 2, because verdict_for decides that before cannot_answer;
  • the NEXT is the script's own --explain line, as before, and the why is a crash row's;
  • one addition the rule forced: report() prints its REFUSED shape-doctor-cannot-answer lines only under a CANNOT ANSWER verdict. Without that, the not-a-root case printed a cannot-answer refusal under NOT A SHAPE ROOT (exit 2).

  check_naming keeps --quiet. The manifest row now carries validate-manifest.py's WARNING about the same chain link, so the fact is said once.

• A pass that warned or noted (shape-doctor.py's manifest row says ok ... passes when the project's own validate-manifest.py exits 0 after printing WARNING naming-referent-chain: ... not reachable here, and the warning appears nowhere in the text or --json report, so a referent chain nothing on this disk could check reads as checked under COMPLIANT: the class of the skip #357 makes a note, in the form #357 still drops #448, Tracking: shape-doctor.py, reporting a repository's compliance #460's pins-note line). On exit 0, validator_row reads the skip, WARNING and note blocks with one reader, reported(). Each kind goes into its own detail key: skipped, warnings or notes. The reason quotes them in the order printed, after "passes, but".

  • The row is a note, so it moves no verdict, and it has no NEXT.
  • REPORT_ITEM learns note and is the reader's only definition of an item, so a note printed after a skip is no longer read as that skip's text.
  • skipped() stays, as reported()'s skips. A row that only skipped reads exactly as before.

• The quoted line of a red row (shape-doctor.py's manifest row says ok ... passes when the project's own validate-manifest.py exits 0 after printing WARNING naming-referent-chain: ... not reachable here, and the warning appears nowhere in the text or --json report, so a referent chain nothing on this disk could check reads as checked under COMPLIANT: the class of the skip #357 makes a note, in the form #357 still drops #448, decision 4). run_validator quotes the first FINDING or REFUSED line, else the first WARNING, else the last line. A red manifest row no longer quotes an earlier leg's WARNING as its reason.

• What else was checked:

  • with_gitlink_repairs and with_merged_away_rows read the whole output with FINDING_LINE and return a crashed row untouched. The wider crash rule keeps them only off rows that printed no finding. The quoted-line change only alters the row.reason they extend, which now quotes a finding.
  • The machine row's quote is unchanged, because the preflight prints no WARNING line.
  • AGENTS.md :222-231 stays true, and no README or handbook statement becomes false.
  • No --help text changed, so docs/cli.md did not either.

Measured: #410's case (1) is not gone on main

The brief expected the stock naming script to classify a name that is not UTF-8 without a traceback. On 5ed3e5d here (Python 3.12.3, LC_ALL=C.UTF-8, and the PYTHONIOENCODING=utf-8 the doctor gives every child), the result was:

• scripts/validate-repository-naming.py --explain -- $'Atl\xffas' exits 1 with UnicodeEncodeError: 'utf-8' codec can't encode character '\udcff'. Its --explain block prints the name to a strict stdout.
• main's doctor gave naming: FINDING | Atl?as: UnicodeEncodeError: ....

With this PR, that row is the crash row (detail.crashed, detail.environment, "crashed before reaching a verdict"), and the verdict is still NOT A SHAPE ROOT. The script itself is unchanged: the brief rules out editing it, and #441 (lane 5) does not touch its printing. So #410's decision 3 (the script's own crash) is still open and needs an owner. The regression test accepts either true row: the crash row now, or the naming-unclassified FINDING once the script prints such a name. It never accepts the exception quoted as a finding.

Tests

New file tests/test_doctor_validator_verdicts.py, built on #357's harness (tests/test_doctor_validator_rows.py), with its fixtures imported. It has 22 tests:

• shape-doctor.py, after #357's crashed(), still reads a validator killed by a signal (a negative exit, -9 or -15) or one that left by os._exit(1) with nothing printed as one that "reports a finding", because crashed() needs a traceback line, so a root's own gate ended by the OOM killer or a timeout's SIGTERM is a FINDING about the project, and the standard's template killed the same way is not CANNOT ANSWER #447:
  • the root's own validate-pins.py ended by SIGKILL or SIGTERM (POSIX only), os._exit(1), merge-conflict markers, or an argparse usage: error. Each row is a crash row with detail.crashed and the expected exit; the verdict is DRIFTED, exit 1; the NEXT is the root's own gate.
  • the standard's template ended by SIGKILL (POSIX only) or os._exit(1) is detail.environment, CANNOT ANSWER, exit 3.
  • a unit test of crashed() on constructed outputs.
• shape-doctor.py's two naming rows read only the naming script's exit code, so a crash of the STANDARD's own validate-repository-naming.py is a FINDING about the project (INVALID (naming), exit 1, where #357 makes a crashed template CANNOT ANSWER), and a directory whose name is not UTF-8 gets naming FINDING Atl?as: UnicodeEncodeError: ..., the script's traceback quoted as a fact about the name #410:
  • a checkout whose naming script raises, asked about a compliant project: CANNOT ANSWER, exit 3, with the control ok. The NEXT run shows the exception, and the text report prints the refusal.
  • the same checkout asked about a directory that is not a root: NOT A SHAPE ROOT, exit 2, the crash row, and no cannot-answer refusal.
  • a name that is not UTF-8 (POSIX only).
• shape-doctor.py's manifest row says ok ... passes when the project's own validate-manifest.py exits 0 after printing WARNING naming-referent-chain: ... not reachable here, and the warning appears nowhere in the text or --json report, so a referent chain nothing on this disk could check reads as checked under COMPLIANT: the class of the skip #357 makes a note, in the form #357 still drops #448:
  • the issue's chain descendant, cloned away from openXdox: the manifest row is a note quoting naming-referent-chain, detail.warnings holds it, and the verdict is COMPLIANT, exit 0 (POSIX only: the layer's gh api needs shape-doctor.py: a validator that crashed says it crashed instead of "reports a finding", and is CANNOT ANSWER when it is the standard's template, which a standard whose path holds the PYTHONPATH separator no longer runs at all; a neutral product's digest validate-pins.py skipped is a note naming the product, from a child that can no longer reach gh or a proxy; and a root whose manifest does not load and whose scripts/repo_shape.py is gone is told to restore that file before its gate (#278, #297, #298) #357's shebang stub).
  • control with SHAPE_PIN_SOURCE_OPENXDOX (all platforms): ok.
  • the spec leg's naming.role set to code: the row quotes FINDING naming-role and not the WARNING (POSIX only). The test first checks that the validator printed the WARNING before the FINDING.
  • run_validator's quoted line on constructed outputs (all platforms).
• The pins note:
  • note and a two-line skip in each order, from a stub validator, each land in their own key and neither swallows the other;
  • a unit test of reported() and passed_but().

One existing test changed in place: tests/test_pin_source_env_collisions.py::test_a_project_declaring_a_colliding_pair_takes_a_shape_update. It asserted that the pins row stays ok over a validator that passes and prints the neutral-pin-source-collides note. Before and after the update, that row is now a note with the note in detail.notes and quoted in the reason. The verdict still equals the control's.

Targeted run (Linux, py-bench, pytest 9.1.1, frvenv first on PATH), over 430c13f:

pytest tests/test_doctor_validator_verdicts.py tests/test_doctor_validator_rows.py tests/test_doctor_gitlink_repairs.py tests/test_doctor_next_is_a_command.py tests/test_pin_source_env_collisions.py tests/test_manifest_validator.py tests/test_naming_policy.py tests/test_shape_doctor.py tests/test_repo_hygiene.py tests/test_cli_reference.py tests/test_agents_md_codes.py -q
1072 passed, 3 skipped in 503.58s (0:08:23)

Mutants, each run against its target tests and then restored, all killed:

mutant	fails
restore the Traceback requirement in crashed()	the 5 own-copy endings, the 2 template endings, the crashed() unit test
drop the WARNING collection	the #448 note test, the reported() unit test
quote WARNING before FINDING	the decision-4 test, 2 run_validator quoted-line cases
drop environment from the naming crash	the CANNOT ANSWER test, the not-a-root test
print the cannot-answer refusal under any verdict	the not-a-root test
REPORT_ITEM without note	both note/skip orders, the reported() unit test

Shared files

git merge-tree --write-tree of this head with each of these exits 0 (clean):

• origin/main 5ed3e5d;
• lane 3's shape-doctor.py: a git repository is told of both ways in, the adoption and the scaffold, and the adoption line ends --org <your-org> where its origin names no organisation plan can read, so pasting it is no longer refused adopt-no-org (#545) #553, l3-545-doctor-way-in c436bb4. It inserts origin_org above def check_not_a_root_naming; this PR leaves that def line and its docstring alone and starts at the run_validator call;
• lane 3's shape-doctor.py: the machine row of a machine that is not ready names the preflight checks that failed, in the [!!] lines the preflight printed, so its reason no longer ends on this machine is not ready yet (see above). with nothing above it (#549) #552, l3-549-doctor-machine-row bf00f1a. It edits check_what_is_here's tail and check_machine, which this PR does not touch;
• lane 3's Tests: about a dozen fixtures still clone a just-pushed local bare remote by plain path (the #440-class macOS flake), with small test-only fixes alongside #544, l3-544-test-hygiene 7135da6. This PR does not edit tests/test_doctor_validator_rows.py, and Tests: about a dozen fixtures still clone a just-pushed local bare remote by plain path (the #440-class macOS flake), with small test-only fixes alongside #544 keeps clone_just_pushed, which the new file imports.

Lane 4's P1 (fix/doctor-next-detached-commits, #413/#414) owns submodule_update_next, check_legs, members_verdict and detached, and this PR edits none of them. P1 is not on origin yet, so there is no merge-tree result for it.

v1.1.0: lands only after the v1.0.0 tag.

Closes #410
Closes #448
Closes #447

Lane 3, as #460's keeper: this PR closes #460's pins-note line (comment 6136245436); please tick it there when this lands.

🤖 Generated with Claude Code

Summary by Sourcery

Make shape-doctor validator verdict handling reflect explicit child output, distinguishing findings, crashes, and informational notes accurately.

New Features:

• Classify validator children by printed FINDING or REFUSED verdicts, treating all other non-zero exits as crashes.
• Surface warnings and notes from successful validators as non-verdict notes with structured details.
• Treat crashes in the standard's naming script as environment failures that produce CANNOT ANSWER when applicable.

Bug Fixes:

• Prevent crash output, naming-script exceptions, and warning lines from being misreported as project findings.
• Ensure red validator rows quote their actual finding or refusal before earlier warnings.
• Avoid emitting CANNOT ANSWER refusals under NOT A SHAPE ROOT verdicts.

Enhancements:

• Improve crash diagnostics for signal termination, empty output, syntax errors, and argument parsing failures.
• Preserve and report validator skip, warning, and note blocks in printed order.

Tests:

• Add comprehensive coverage for validator crash modes, naming-script failures, warning and note handling, verdict-line selection, and pins-note reporting.

[sourcery-ai]

Reviewer's Guide

The PR centralizes child-validator interpretation around printed verdict lines: non-zero runs without FINDING or REFUSED are crashes, naming-script crashes become environment/CANNOT ANSWER results where appropriate, successful warnings and notes become visible non-verdict rows, and failing rows quote the relevant verdict instead of an earlier warning.

Sequence diagram for child validator crash handling

sequenceDiagram
    participant Doctor
    participant Validator
    Doctor->>Validator: run_validator()
    Validator-->>Doctor: exit code and output
    Doctor->>Doctor: crashed(code, output)
    alt FINDING or REFUSED printed
        Doctor->>Doctor: Keep validator verdict
        Doctor-->>Doctor: Create finding or refusal row
    else Non-zero without verdict
        Doctor->>Doctor: Mark detail.crashed
        Doctor->>Doctor: Quote last line or signal_name()
        Doctor-->>Doctor: Create crash row with CRASH_WHY
    end

Loading

Flow diagram for validator verdict classification

flowchart TD
    A["Run child validator"] --> B{"Exit code is 0?"}
    B -->|Yes| C["reported(): read skip, WARNING, and note blocks"]
    C --> D{"Reports found?"}
    D -->|No| E["OK row"]
    D -->|Yes| F["NOTE row with details and quoted reports"]
    B -->|No| G{"Output contains FINDING or REFUSED?"}
    G -->|Yes| H["Verdict row; quote first verdict line"]
    G -->|No| I["Crash row; quote last output line or signal"]

Loading

Flow diagram for naming-script crash classification

flowchart TD
    A["Run naming script"] --> B["crashed(code, output)"]
    B -->|"No crash"| C["Use naming verdict"]
    B -->|"Crash"| D["naming_crashed_row()"]
    D --> E["Set detail.crashed and detail.environment"]
    E --> F{"Assembly root?"}
    F -->|Yes| G["CANNOT ANSWER"]
    F -->|No| H["NOT A SHAPE ROOT"]
    G --> I["Report CANNOT ANSWER refusal"]
    H --> J["Do not print cannot-answer refusal"]

Loading

Flow diagram for successful validator reports

flowchart TD
    A["Validator exits 0"] --> B["reported(output)"]
    B --> C{"skip, WARNING, or note blocks?"}
    C -->|No| D["OK row"]
    C -->|Yes| E["Store skipped, warnings, or notes"]
    E --> F["passed_but() builds quoted reason"]
    F --> G["NOTE row with no NEXT and no verdict movement"]

Loading

Flow diagram for selecting a failing row's quoted line

flowchart TD
    A["run_validator() receives output"] --> B{"Any FINDING or REFUSED line?"}
    B -->|Yes| C["Quote first FINDING or REFUSED"]
    B -->|No| D{"Any WARNING line?"}
    D -->|Yes| E["Quote first WARNING"]
    D -->|No| F["Quote last non-empty line"]

Loading

File-Level Changes

Change	Details	Files
Defines validator verdicts from emitted output rather than exit codes alone, classifying all other non-zero exits as crashes.	Replaces traceback-dependent crash detection with FINDING/REFUSED line detection. Handles signal termination, silent exits, syntax errors, missing files, and argparse failures with crash details and signal-aware messages. Preserves verdicts when a finding or refusal was printed before a later crash. Updates validator row handling and crash explanations.	shape-doctor.py tests/test_doctor_validator_verdicts.py
Propagates naming-script crashes as environment failures and prevents misleading cannot-answer refusals.	Routes both naming checks through crash detection and marks failures with crashed and environment details. Reports CANNOT ANSWER for a naming-script crash at a shape root while preserving NOT A SHAPE ROOT precedence elsewhere. Prints the cannot-answer refusal only under a CANNOT ANSWER verdict. Adds regression coverage for raised scripts and non-UTF-8 names.	shape-doctor.py tests/test_doctor_validator_verdicts.py
Retains informational output from successful validators as structured note rows.	Adds unified parsing for skip, WARNING, and note blocks, preserving multiline content and print order. Treats note as an item boundary so adjacent notes and skips do not absorb one another. Stores each category in its corresponding detail field and formats grouped pass explanations without changing verdicts. Updates pin-source collision expectations from ok to note.	shape-doctor.py tests/test_doctor_validator_verdicts.py tests/test_pin_source_env_collisions.py
Makes failing validator rows quote an actual verdict before earlier warnings.	Prioritizes the first FINDING or REFUSED, then the first WARNING, then the last output line. Ensures red manifest rows identify the finding that caused failure rather than a preceding warning. Adds unit and integration coverage for quote selection.	shape-doctor.py tests/test_doctor_validator_verdicts.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#410	Treat a non-zero exit from the checkout’s naming script as a crash when it printed neither FINDING nor REFUSED, rather than as a finding about the project.	✅
#410	For an assembly root or holder, mark a crashed naming script as an environment failure so the doctor returns CANNOT ANSWER (exit 3), not INVALID (naming).	✅
#410	For a directory that is not a shape root, keep the NOT A SHAPE ROOT verdict while ensuring a naming-script crash—such as a UnicodeEncodeError for a non-UTF-8 name—is not reported as a finding about the directory’s name.	✅
#447	Treat validators terminated by a signal as crashes rather than as reporting a finding or refusal; identify the signal in the crash reason, including for the standard's template.	❌	Signal-terminated validators are classified as crashes, and template crashes become CANNOT ANSWER. However, the signal name is included only when the child printed nothing. If it printed output before being killed, the reason quotes the last output line instead and does not identify the signal.
#447	Treat nonzero exits without a printed FINDING or REFUSED verdict as crashes, including exit 1 without output, syntax errors, and interpreter or argparse failures.	✅
#447	Apply the same crash detection to the naming rows so a crash in the standard's naming script is not reported as a project finding.	✅
#448	When a validator exits 0 after printing a WARNING or note, report that information in the doctor's output as a note without changing the overall verdict.	✅
#448	When a validator exits non-zero with both an earlier WARNING and a later FINDING, make the row quote the FINDING rather than the WARNING.	✅
#460	Make the doctor reliably report repository compliance and explain findings, refusals, and cases where it cannot answer.	✅
#460	Deliver the issue's v1.0.0 scope: core flows working end to end on Linux, macOS, and Windows, with the listed in-scope blockers resolved before release.	❌	This PR targets #410, #448, and #447 and explicitly says it lands only after the v1.0.0 tag. It does not resolve the listed v1.0.0 issues #237, #277, #291, or #424, so it does not fulfill the tracking issue's release objective.

Possibly linked issues

• shape-doctor.py, after #357's crashed(), still reads a validator killed by a signal (a negative exit, -9 or -15) or one that left by os._exit(1) with nothing printed as one that "reports a finding", because crashed() needs a traceback line, so a root's own gate ended by the OOM killer or a timeout's SIGTERM is a FINDING about the project, and the standard's template killed the same way is not CANNOT ANSWER #447: The PR directly fixes the issue’s core cases: negative signal exits and verdict-free exits such as os._exit(1) now classify as crashes.

---

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.

[sonarqubecloud]

Quality Gate passed

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

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