adopt-project.py: a --work-dir that is a file or cannot be made ends plan, check and execute in a traceback, and --help says nothing of --work-dir or of where --org comes from #650

Lane: openreposhape-1 (openRepoShape-1)

plan, check and execute should refuse a --work-dir that is a file, or that cannot be made, by name and in one place, not end in a traceback. --help should say what --work-dir is and where --org comes from.

From lane 1's triage of 2026-10-15, D2, approved by Brett Heap at 2026-10-16T11:21:17Z ("Approve all (Recommended)"). One pull request covers the lines below.

Parent: #457. Milestone: v1.1.0.

Lands after: #594, which rewrites _work_root and main.

Effort: S. Platform: all.

Lane openRepoShape-1 claims it at filing; see its CLAIMED comment.

Why this is P2. Probed on 396c0ff, before any leg exists:

• plan --work-dir <a file> ends in FileExistsError, exit 1.
• plan --source acme/Atlas ends in PermissionError, exit 1, both with a work dir under a chmod 500 directory and with that directory itself.
• adopt-project.py and tests/conftest.py: a run without --work-dir removes the empty work directory it made, and a recorded clone that is gone is cloned again, so no empty openreposhape-adopt-* is left and no source-unclonable follows (#526) #594's head keeps _work_root's bare mkdir.

Read on 7ba64f0: _work_root still ends in a bare mkdir, and cmd_plan, cmd_check and cmd_execute each call it with no handler. #524 (#581) made check and execute refuse an unwritable directory by name. What is left is plan, and a directory that cannot be made.

One pull request covers it:

• one refusal by name, in all three commands;
• except (OSError, Refusal) in cmd_check (L1-21);
• the work-dir question asked before the "is cloned again" NOTE (L1-28);
• help text for --work-dir and --org (L1-25, L1-49), so docs/cli.md is regenerated once.

Lane 2's L2-55 on #457 (issuecomment-6202569293) sits in the same lines: flag-only refusals asked before _work_root. It could join this issue.

Lines

• L1-19 (P2): a --work-dir that cannot be made, or is a file, gives a PermissionError or FileExistsError traceback from _work_root's mkdir in plan, check and execute, before any leg. Where: _work_root. On 396c0ff, probed: plan --work-dir <a file> ends in FileExistsError, exit 1. Read again on 7ba64f0: the mkdir is bare, and the three commands call _work_root with no handler. The line measured it on 17dd55c. (source)
• L1-20 (P2): plan --source <org/repo> with an unwritable --work-dir ends in a PermissionError traceback at source-readonly; check and execute now refuse the same case. On 396c0ff, probed: plan --source acme/Atlas ends in PermissionError, exit 1. The line measured it on 17dd55c. (source)
• L1-25 (P2): --work-dir has no help text on plan, check or execute, and docs/cli.md does not say where the default lands or that it is removed when empty. On 396c0ff, read: no help=. Read again on 7ba64f0: --work-dir and --org still have no help=. The line saw it on 652b686. (source)

Rides along (backlog; tick it here if the same change covers it)

• L1-21: with an unwritable --work-dir and an unopenable --source, check refuses source-unresolvable and execute refuses adopt-work-dir-unwritable. cmd_check converts only OSError, so except (OSError, Refusal): would align them. On 396c0ff, read: except OSError only. Read again on 7ba64f0: unchanged. The line measured it on 17dd55c. (source)
• L1-28: with adopt-project.py: check finds, and execute refuses before any leg exists, a path the root keeps at the shape's own pin and a --work-dir this user cannot write in, so contracts/shape-pin.yaml kept in the root and a chmod 500 work directory no longer pass check and fail only after both legs are pushed (#524) #581 merged, an unwritable --work-dir plus a gone recorded clone makes check print the "is cloned again" NOTE and then refuse adopt-work-dir-unwritable, while execute refuses with no NOTE. Fix: ask the work-dir question before the NOTE. On be808a7, adopt-project.py and tests/conftest.py: a run without --work-dir removes the empty work directory it made, and a recorded clone that is gone is cloned again, so no empty openreposhape-adopt-* is left and no source-unclonable follows (#526) #594's head, read: the NOTE is adopt-project.py and tests/conftest.py: a run without --work-dir removes the empty work directory it made, and a recorded clone that is gone is cloned again, so no empty openreposhape-adopt-* is left and no source-unclonable follows (#526) #594's. The line probed it on 652b686 merged with adopt-project.py: check finds, and execute refuses before any leg exists, a path the root keeps at the shape's own pin and a --work-dir this user cannot write in, so contracts/shape-pin.yaml kept in the root and a chmod 500 work directory no longer pass check and fail only after both legs are pushed (#524) #581's head edaaae4. (source)
• L1-49: AGENTS.md's adoption step and plan --help's --org never say that --org defaults to the organisation of a url origin, or that a path origin needs it. On 396c0ff, read: adopt-project.py:10336. Read again on 7ba64f0: --org still has no help=. The line read it on 182389e. (source)

Each line above is a line of #457's checklist comment (issuecomment-6200110061). Tick it there too when this closes.