The documented worktree command cannot run from inside a worktree

[jacobdrees]

The defect

docs/agents/workflow.md → Branches opens the worktree recipe with this block:

git switch main && git pull                       # start from what production has
orca worktree create --name CAN-11-welcome-email-queue --linear-issue CAN-11

The first command cannot run from inside a worktree, which is where all work now happens:

$ git switch main
fatal: 'main' is already used by worktree at '/Users/jacobrees/orca/projects/CanonCore'

Because the two commands are joined by &&, the failure takes the orca worktree create after it
with it. So an agent following the documented recipe from inside a lane creates no worktree and gets
a fatal: it did not cause.

This was harmless while lanes were opened from the project checkout. It stopped being harmless on
16 August 2026, when lanes became how work is dispatched and an agent began living inside one.

The fix

git fetch origin is the correct preamble, and it works from anywhere. The local main ref is not
what a new worktree is based on: Orca bases it on refs/remotes/origin/main, confirmed on a live
lane via orca worktree show --worktree current --json → baseRef.

Orca also refreshes that ref itself on create, via a refreshLocalBaseRefOnWorktreeCreate setting
that returns a localBaseRefRefresh key in the create response. That is a per-machine setting, so
the explicit fetch is what keeps the document portable rather than redundant.

Acceptance criteria

• The preamble in docs/agents/workflow.md → Branches no longer runs git switch main, and
  what replaces it works from inside a lane.
• The comment beside it still says why the command is there, rather than being dropped silently.
• Verified by running the amended block from inside a worktree, not from the project checkout.
• node scripts/check-docs.ts passes, and its skips are read rather than assumed.

Evidence

CAN-131 Research where this repository and Orca do not meet, and settle the worktree workflow,
whose document is docs/research/orca-gaps-and-the-worktree-workflow.md → Question two: should*
**worktree-off-main be the documented default?*. The fatal: above was reproduced there, not inferred.

Not in scope

Everything else the same research recommends for that section: the dispatch form with --agent and
--prompt, the batch-independence rule, and lane hygiene. Those are one enhancement ticket, kept
separate so this one-line correction does not wait on it.