chore(dev): add universal checkout bootstrap

[galligan]

Summary

• add one provider-neutral scripts/bootstrap.sh entrypoint for human contributors, CI, Hermes, Codex, and Claude
• isolate dependency setup to the owning checkout's .venv, enforce the committed lock, and neutralize inherited Git/Python/uv selectors without installing global tools or touching live Dispatch state
• exercise the same bootstrap in Linux CI and a macOS smoke gate, including the release dependency graph
• verify ordinary clones, detached linked worktrees, source exports, stale locks, hostile environment selectors, Git hook/config isolation, and wheel/sdist boundaries

Test plan

• ./scripts/bootstrap.sh
• just check — Ruff, format, strict mypy, 1124 passed / 17 deselected, wheel/sdist build, package-content checks
• /bin/sh -n scripts/bootstrap.sh
• shellcheck --shell=sh scripts/bootstrap.sh
• git diff --check

Boundaries

• setup is explicit and zero-argument; it does not create or remove worktrees, install hooks or global tools, copy credentials/state, start daemons, or mutate Graphite
• POSIX shell support is documented for macOS and Linux
• contributor-only scripts/tests remain in the sdist and out of the runtime wheel

Coordination

Open PR #122 also touches README.md, docs/usage/README.md, and scripts/check_package_contents.py; this PR is based directly on current main and does not import that unmerged runtime/provider work.

[cursor]

PR Summary

Low Risk
Changes are limited to dev setup, CI, docs, and packaging validation—not runtime dispatch behavior or auth/data paths.

Overview
Introduces ./scripts/bootstrap.sh as the single contributor setup path (replacing ad hoc uv sync), with just setup as an alias. The script anchors to the physical checkout, requires pyproject.toml / uv.lock, refuses symlinked .venv, clears inherited Git/Python/uv selectors, and runs uv sync --locked --group dev without touching live Dispatch state or accepting arguments.

CI now bootstraps on Linux before the quality gate, adds a macOS smoke job (editable install + dispatch --help), and gates release on both jobs. Docs (README, AGENTS.md, usage) document the bootstrap contract and scoped verification; workspace environment examples point at separate workspace-setup / workspace-cleanup hooks, not this script.

Packaging checks ship bootstrap.sh and bootstrap tests in the sdist only (executable), while wheels reject contributor-only paths under tests/, scripts/, and .hermes/. .worktrees/ is gitignored. Large tests/test_bootstrap.py coverage exercises hostile env, clones/worktrees/archives, stale locks, and CI/doc invariants.

^{Reviewed by Cursor Bugbot for commit 8ec59e8. Configure here.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-13T17:37:11.489157Z	8ec59e8	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8ec59e8df8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".