[chore] Use main-based worktrees (#24)

[ThreeLight2000]

Related issue

Fixes #24

Summary

• Change pnpm branch to create a dedicated worktree under .worktrees/<issue>-<slug>.
• Always base new task worktrees on origin/main without switching the canonical checkout.
• Warn about dirty canonical checkout changes while leaving them untouched.
• Document the main-first/worktree-only workflow in agent guidance, contributor guidance, and all Issue templates.
• Add repository tests covering base selection, worktree creation, branch naming, and dirty-checkout safety.

AS-IS

The branch CLI derives a new branch from whichever checkout is active and switches that checkout in place. A stale task checkout can therefore become the accidental base for new work and for reading repository instructions.

flowchart LR
    current_checkout[Current checkout] --> branch_command[pnpm branch]
    branch_command --> current_branch[Create branch from current branch]
    current_branch --> switch_checkout[Switch canonical checkout in place]

Loading

• Current behavior: pnpm branch runs git switch -c in the active checkout.
• Problem / limitation: a stale task branch can become the base for new work, and the canonical checkout no longer remains a stable main reference.

TO-BE

The primary checkout remains a synchronized main reference, and every task is implemented from an isolated worktree created from origin/main.

flowchart LR
    main_checkout[Canonical main checkout] --> sync[git fetch origin main]
    sync --> branch_command[pnpm branch]
    branch_command --> origin_main[origin/main]
    origin_main --> task_worktree[.worktrees/issue-slug]
    task_worktree --> implementation[Implementation and verification]

Loading

• Proposed behavior: pnpm branch <type> <issue-number> <slug> creates the branch and worktree without switching the canonical checkout.
• Expected outcome: new work consistently starts from origin/main, while unrelated dirty changes remain untouched.
• Migration / rollout notes: update the canonical checkout to main and use the new command for subsequent Issues.

Verification

• pnpm verify
• node --test scripts/new-branch.test.mjs scripts/issue-type.test.mjs scripts/cleanup-merged.test.mjs
• git diff --check

Commands completed successfully. pnpm verify passed repository tests, lint, typecheck, and builds.

User impact

• Affected clients, servers, packages: repository workflow, agent guidance, contributor guidance, and Issue templates.
• User-visible behavior: task creation now opens an isolated worktree and leaves the canonical checkout unchanged.
• Breaking changes: the command still uses pnpm branch with the same arguments, but it no longer switches the current checkout; users should work from the printed worktree path.

Metadata checklist

• PR title type and Issue number match source branch.
• Fixes #24 references the branch's Issue.
• Linked Issue uses native Type Task.
• Issue is in the Context OS Work Project with Priority: Medium.
• Mermaid diagrams document the changed workflow.

Screenshots recordings

Not applicable; this changes repository workflow and documentation only.