canopy-cli 3.1.0__tar.gz

canopy_cli-3.1.0/.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  python-tests:
+    name: pytest (Python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+
+      # Tests create real Git repos — give them a deterministic identity.
+      - name: Configure Git
+        run: |
+          git config --global user.email "ci@canopy.dev"
+          git config --global user.name  "Canopy CI"
+          git config --global init.defaultBranch main
+
+      - name: Install package (with dev extras)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run pytest
+        run: pytest tests/ -v --maxfail=5
+
+  extension-build:
+    name: VSCode extension build
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: vscode-extension
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: vscode-extension/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type-check
+        run: npx tsc --noEmit
+
+      - name: Bundle with esbuild
+        run: npm run build
+
+      - name: Package VSIX (sanity check)
+        run: npx vsce package --allow-missing-repository
+
+      - name: Upload VSIX artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: canopy-vsix
+          path: vscode-extension/*.vsix
+          if-no-files-found: error
+          retention-days: 14

canopy_cli-3.1.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # OIDC for PyPI trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Verify version matches tag
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION=$(python -c "import re,pathlib; print(re.search(r'__version__\s*=\s*\"([^\"]+)\"', pathlib.Path('src/canopy/__init__.py').read_text()).group(1))")
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag v$TAG_VERSION does not match __version__ ($PKG_VERSION)"
+            exit 1
+          fi
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

canopy_cli-3.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+pytest-cache-files-*/
+*.egg
+.venv/
+venv/
+.env
+.canopy/
+.worktrees/
+node_modules/
+.DS_Store
+random/

canopy_cli-3.1.0/AGENTS.md

@@ -0,0 +1,228 @@
+# Canopy — Contributor Guide for AI Agents
+
+This file is the "how to extend canopy without breaking module boundaries" guide.
+It is CLAUDE.md's sibling, not its replacement:
+
+- `CLAUDE.md` — what canopy is, architecture overview, key conventions, MCP tool list
+- `docs/concepts.md` — the four conceptual pillars (action framework, context contract, state machine, slot model, resume brief)
+- `docs/architecture.md` — formal module reference
+
+## Before You Start
+
+1. Read `CLAUDE.md`. It has the architecture diagram, slot model explanation, and all key conventions.
+2. Read `docs/concepts.md` if you need the vocabulary for the state machine or action framework.
+3. Run the test suite to confirm your baseline: `pytest tests/ -v` (857 tests, ~225s).
+4. If you are adding to the slot model or switch flow, read `actions/slots.py` and `actions/switch.py` first.
+
+## Module Boundaries
+
+These are hard rules. Do not break them.
+
+- **`git/repo.py` is the only file that calls `subprocess.run(["git", ...])`.**
+  New git operations belong here. Everything else calls functions from this module.
+
+- **`git/multi.py` handles cross-repo git operations.** It calls `git/repo.py` functions;
+  it does not shell out to git directly.
+
+- **`mcp/server.py` and `cli/main.py` are thin wrappers.**
+  Business logic lives in `actions/`, `features/coordinator.py`, `git/multi.py`,
+  and `workspace/`. Neither the MCP server nor the CLI should own logic.
+
+- **All actions live in `actions/`.** This is the most-modified directory. Each action
+  module owns one concern: `switch.py` owns slot focus, `slots.py` owns slot state
+  reads/writes, `drift.py` owns drift detection, `resume.py` owns the resume brief, etc.
+
+- **Actions raise `BlockerError` for precondition failures.**
+  Shape: `BlockerError(code, what, expected, actual, fix_actions, details)`.
+  CLI renders via `cli/render.py`. MCP returns `to_dict()`. Same shape, two consumers.
+
+- **Universal aliases — every read tool accepts multiple forms.**
+  Feature name, Linear ID, `<repo>#<n>`, PR URL, `<repo>:<branch>`, or slot id
+  (`worktree-N` → slot's current occupant). Always resolve via
+  `actions/aliases.py:resolve_feature`. Never reimplement alias resolution inline.
+
+- **Per-repo branches map — never assume branch == feature name.**
+  Use `lane.branch_for(repo)` or `repos_for_feature(workspace, feature)`.
+  `FeatureLane.repos` alone does not give you branch names for legacy features.
+
+- **All integrations go through `mcp/client.py` or the `gh` CLI fallback.**
+  Integration modules in `integrations/` never call external APIs directly.
+  `integrations/github.py` falls back to `gh api` / `gh pr` when no MCP server
+  is configured. If neither is available, raise `BlockerError(code='github_not_configured')`.
+
+- **`integrations/precommit.py` is the one exception to the MCP-only rule.**
+  It runs local hooks via subprocess. This is intentional — hooks run locally.
+
+## State Files
+
+All state is under `.canopy/state/`. OAuth tokens at `~/.canopy/mcp-tokens/`.
+
+| File | Owner | Notes |
+|---|---|---|
+| `heads.json` | `git/hooks.py` + post-checkout hook | Written by hook; read by `drift.py`, `historian.py` |
+| `slots.json` | `actions/slots.py` | Canonical + warm slot occupancy, `last_touched` LRU, `in_flight` marker |
+| `preflight.json` | `actions/preflight_state.py` | Records preflight result per feature |
+| `visits.json` | `actions/last_visit.py` | Per-feature `last_visit` / `previous_visit` ISO timestamps |
+| `thread_resolutions.json` | `actions/thread_resolutions.py` | Resolved GitHub review threads |
+| `bot_resolutions.json` | `actions/bot_resolutions.py` | Bot-comment resolutions addressed via `commit --address` |
+
+All state writes use atomic temp+rename (`tmp.replace(path)`) to prevent corruption
+from concurrent agents. See `actions/slots.py` for the canonical pattern.
+
+## Adding a New Action
+
+This is the most common change.
+
+1. Create `src/canopy/actions/<name>.py`. Raise `BlockerError` for preconditions.
+   Use existing fixtures and patterns; don't re-invent error shapes.
+
+2. Expose via CLI in `cli/main.py`:
+   - Add `cmd_<name>(args: argparse.Namespace) -> None`
+   - Add a subparser in `main()`
+   - Dispatch via the `commands` dict
+   - Support `--json` via `_print_json()`
+
+3. Expose via MCP in `mcp/server.py`:
+   - Add `@mcp.tool()` wrapper that calls the action function
+   - Write a clear docstring — it becomes the tool description agents see
+
+4. Add tests in `tests/test_<name>.py` using the `workspace_with_feature` fixture
+   (or another fixture from `tests/conftest.py`).
+
+5. If the action is user-facing:
+   - Update `docs/commands.md`
+   - Update `docs/mcp.md`
+   - Update the architecture box and MCP-tool-group listing in `CLAUDE.md`
+
+6. If agents need to know when to prefer the new tool, update
+   `~/.claude/skills/using-canopy/SKILL.md` and
+   `src/canopy/agent_setup/skills/using-canopy/SKILL.md`.
+
+## Adding a New CLI Command Only
+
+When a new subcommand wraps existing actions without needing a new action module:
+
+1. Add `cmd_<name>(args)` in `cli/main.py` calling existing action functions.
+2. Add subparser in `main()`, dispatch in the `commands` dict.
+3. Support `--json` via `_print_json()`.
+4. Human-readable output: 2-space indent, `─` for separators.
+5. Update `docs/commands.md`.
+
+## Adding a New MCP Tool Only
+
+When the action already exists and you just need to expose it:
+
+1. Add `@mcp.tool()` in `mcp/server.py`. Call the existing action function directly.
+2. Return dicts/lists (FastMCP handles JSON serialization).
+3. Write a docstring — it is the tool description.
+4. Update `docs/mcp.md` and the tool-group listing in `CLAUDE.md`.
+
+## Adding a New Git Operation
+
+1. Add the function to `git/repo.py` using `_run()` or `_run_ok()`.
+   Prefer `_run()` (raises on failure) for write operations.
+   `_run_ok()` (returns empty string on failure) is only safe for reads.
+2. Write a test in `tests/test_repo.py`.
+3. Do not call `subprocess.run(["git", ...])` anywhere else.
+
+## Adding a New State File
+
+1. Create `actions/<name>.py` with a module docstring naming the path
+   (e.g., `State file: .canopy/state/<name>.json`).
+2. Use the atomic temp+rename pattern from `actions/slots.py` or
+   `actions/thread_resolutions.py`:
+   ```python
+   tmp = path.with_suffix(".tmp")
+   tmp.write_text(json.dumps(data))
+   tmp.replace(path)
+   ```
+3. Update the state-files table in this file.
+4. Update the state-files line in `CLAUDE.md`.
+5. Update the state-files table in `docs/architecture.md` and
+   the state-files section in `docs/workspace.md`.
+
+## Adding a New Integration
+
+1. Add a module in `integrations/`.
+2. Use `mcp/client.py` to call the MCP server, or `gh` CLI as fallback.
+3. Check for server presence via `mcp.client.get_mcp_config()` before calling.
+4. Handle `McpClientError` gracefully — never fail the whole operation because
+   an integration is unavailable.
+5. If the integration is Linear or GitHub, link metadata into `features.json`
+   via `FeatureLane` fields rather than a separate sidecar file.
+6. Write tests that mock the MCP call but test the data flow end-to-end.
+
+## Adding a New Bundled Skill
+
+1. Create `src/canopy/agent_setup/skills/<name>/SKILL.md`.
+2. Default skills (always installed on `canopy setup-agent`) must be declared
+   in `agent_setup/__init__.py`.
+3. Opt-in skills install via `canopy setup-agent --skill <name>`.
+4. Document the new skill in `docs/agents.md` under the skills section.
+5. Foreign skills at the same install path are not overwritten without `--reinstall`.
+
+## Adding a New Augment Key
+
+1. Update `src/canopy/actions/augments.py`.
+   The resolver is intentionally lenient — unknown keys are silently preserved,
+   so adding a new key is backward-compatible.
+2. Consume the new key in whichever action or integration needs it via
+   `repo_augments(workspace, repo_name).get("<key>")`.
+3. Document the key in the recognized-keys table in
+   `src/canopy/agent_setup/skills/augment-canopy/SKILL.md`.
+4. Add a `canopy doctor` check if misconfiguration has a clear error form.
+
+## Testing Conventions
+
+- All tests use real temporary Git repos, not mocks. This catches real git behavior.
+- Fixtures are in `tests/conftest.py`. Key fixtures:
+  - `workspace_dir` — bare workspace with `api/` and `ui/` repos on main
+  - `workspace_with_feature` — workspace with `auth-flow` branches + commits in both repos
+  - `canopy_toml` — workspace with a canopy.toml already written
+- Test file naming: `test_<module>.py` or `test_<feature_area>.py`.
+- Worktree tests must clean up with `git worktree remove` when done.
+- Run: `pytest tests/ -v` from the `canopy/` directory.
+
+## JSON Output Contract
+
+Every `--json` command and MCP tool returns structured data. The shape is the contract
+and is defined in each action's docstring. CLI and MCP return identical bytes.
+
+Key shapes:
+
+| Tool / command | Root shape |
+|---|---|
+| `workspace_status` | `WorkspaceStatus` (see `Workspace.to_dict()`) |
+| `feature_list` | `list[FeatureLane.to_dict()]` |
+| `feature_status` | `FeatureLane.to_dict()` with `repo_states` |
+| `feature_state` | 9-state machine result + `summary` + `next_actions` |
+| `feature_resume` | `version: 1`, `since_last_visit`, `current_state`, `intent_hints` |
+| `slots(rich=True)` | `canonical` + per-slot enriched dashboard payload |
+| `triage` | priority-tiered cross-repo PR enumeration |
+
+## Context Detection
+
+`workspace/context.py` distinguishes four context types based on cwd:
+
+1. `feature_dir` — inside `.canopy/worktrees/worktree-N/` (slot root; all repos in scope)
+2. `repo_worktree` — inside `.canopy/worktrees/worktree-N/<repo>/` (single repo)
+3. `repo` — inside a normal workspace repo (feature = current branch if non-default)
+4. `workspace_root` — at the canopy.toml level (all repos in scope)
+
+Used by `canopy stage` and other context-sensitive commands.
+
+## Version Handshake
+
+When shipping a milestone:
+
+1. Bump `__version__` in `src/canopy/__init__.py`.
+2. Add a section to `CHANGELOG.md`.
+3. Doctor's `cli_stale` / `mcp_stale` checks compare against this version —
+   the handshake is only useful if the number actually moves.
+
+## Hooks Safety
+
+`git/templates/post-checkout.py` uses `fcntl.flock` and atomic rename so concurrent
+fires across repos in the same workspace don't race. It chains any pre-existing user
+hooks and is installed by `canopy init` (or `canopy hooks install`). Worktrees inherit
+hooks via the git `commondir` mechanism.

canopy_cli-3.1.0/CHANGELOG.md

@@ -0,0 +1,115 @@
+# Canopy CLI / MCP — Changelog
+
+Tracks the Python side (CLI + MCP server). The VSCode extension has its own [vscode-extension/CHANGELOG.md](vscode-extension/CHANGELOG.md).
+
+Versions follow semver. Pre-1.0 — minor bumps may add features or break behavior; the README is the source-of-truth contract.
+
+## 3.1.0 — 2026-05-30 (Plan 2 — Feature Resume)
+
+### Added
+- `canopy resume <alias>` (+ `mcp__canopy__feature_resume`): switch-aware
+  compound action. One call: alias → switch-if-needed → refresh GitHub + Linear →
+  compute structured brief with `intent_hints` for the most likely next actions.
+  See `docs/concepts.md#returning-to-a-feature`.
+- `canopy resolve <thread_id>` (+ `mcp__canopy__resolve_thread`): close a
+  GitHub review thread + log to `.canopy/state/thread_resolutions.json` for
+  attribution in the resume brief.
+- `canopy reply <thread_id> [--body | --body-file | stdin]`
+  (+ `mcp__canopy__reply_to_thread`): post a reply to a GH review thread.
+  `--resolve` (or `resolve_after=True`) closes the thread after posting.
+- `canopy commit --address <id> --resolve-thread`: optionally close the GH
+  review thread after the local commit. Augment
+  `auto_resolve_threads_on_address = true` in canopy.toml makes this the
+  default for the workspace. `--no-resolve-thread` overrides the augment
+  per-invocation.
+- New state files: `.canopy/state/visits.json` (per-feature last-visit anchor
+  `{feature: {last_visit, previous_visit}}`); `.canopy/state/thread_resolutions.json`
+  (canopy-driven GH thread closures `{thread_id: {resolved_by_canopy_at,
+  feature, via_command, via_commit_sha}}`).
+- `actions/last_visit.py` — get/mark/reset the per-feature visit anchor.
+- `actions/resume.py` — `feature_resume` compound action + `resume_summary`
+  (counts-only view embedded in `switch` return).
+- `actions/thread_actions.py` — `resolve_thread` + `reply_to_thread` wrappers
+  + local resolution log writer.
+- `actions/thread_resolutions.py` — load/record/filter_since for the
+  thread-resolutions log.
+- GraphQL thread API in `integrations/github.py`: `list_review_threads`,
+  `resolve_thread`, `unresolve_thread`, `reply_to_thread`. Every comment from
+  `get_review_comments` now carries a `thread_id` field (GraphQL-sourced when
+  available, `""` on REST fallback) and `author_type` from GraphQL `__typename`.
+- Bundled `using-canopy` skill now teaches `feature_resume` as the
+  session-start primitive and documents the "Closing out review threads"
+  workflow.
+
+### Changed
+- `switch(feature)` bumps `last_visit` on every successful switch and embeds
+  `since_last_visit_summary` in its return value — a counts-only view
+  (commits, threads, GH resolutions, draft replies) so the agent sees
+  "something changed" without a full `feature_resume` round-trip. Sets
+  `degraded: true` if GitHub is unreachable.
+- `get_review_comments` prefers GraphQL when available (single round-trip for
+  thread IDs + `author_type`); falls back to REST with `thread_id=""`.
+
+### Notes
+- `feature_resume` refreshes GitHub + Linear on every call — the brief is
+  never cached at the canopy layer.
+- Plan 1's slot model is the prerequisite. If upgrading from pre-3.0, run
+  `canopy migrate-slots` first.
+
+## 3.0.0 — 2026-05-28 (Wave 3.0)
+
+**Breaking — slot model.** Worktree directories are now generic numbered slots (`worktree-1`, `worktree-2`, ...) instead of feature-named. `max_worktrees` renamed to `slots` (default 2). State unified in `.canopy/state/slots.json`; `active_feature.json` deleted. Run `canopy migrate-slots` once per workspace.
+
+### Added
+- `canopy slots` / `mcp__canopy__slots` — inspect canonical + warm slot occupancy. `slots --rich` returns the full dashboard shape (branch, dirty, ahead/behind, PR, CI, bots, linear, last commit, feature_state per slot+canonical).
+- `canopy slot load <feature> [<slot-N>]` — warm a cold feature into a slot without changing canonical. Optional `--replace` evicts the occupant first.
+- `canopy slot clear <slot-N>` — evict a slot's occupant to cold with feature-tagged stash.
+- `canopy slot swap <slot-A> <slot-B>` — exchange the occupants of two slots (identical-scope features only in v1).
+- `canopy switch <feature> --evict-to <slot-N>` — pin the destination slot for the outgoing canonical.
+- `canopy switch --to-slot <slot-N>` — promote whatever feature occupies that slot.
+- `canopy migrate-slots` / `mcp__canopy__migrate_slots` — one-shot pre-3.0 → 3.0 migration (with dry-run preflight and rollback safety).
+- Slot id (`worktree-N`) is a universal alias form — any tool that takes a feature alias also accepts it.
+- Doctor categories: `slot_dir_orphan`, `slot_entry_orphan`, `slot_branch_mismatch`, `slot_detached_head` (info severity for the bisect/detached case).
+- Fast-path swap: when Y is already warm, `switch(Y)` is 5 git ops per repo + 1 JSON write. Closes issue #3.
+- Transaction safety: `slots.json.in_flight` marker recorded on partial multi-repo switch/swap failures so subsequent operations refuse to compound the damage.
+
+### Changed
+- `canopy.toml`: `[workspace] max_worktrees = N` → `[workspace] slots = N`. Default 2 (was 0 = unlimited).
+- Worktree layout: `.canopy/worktrees/<feature>/<repo>/` → `.canopy/worktrees/worktree-N/<repo>/`.
+- MCP tools `worktree_create`, `worktree_info`, `workspace_status` return slot-keyed shapes. `slots` MCP tool defaults to `rich=True`.
+- `slot_load` now requires the feature to be registered (`feature create` first) — no more silent "treat as all repos" fallback for unregistered names.
+
+### Removed
+- `actions/active_feature.py` (folded into `actions/slots.py`).
+- `actions/realign.py` (deprecated since 2.9).
+- Pre-2.9 lazy migration path inside `switch` (replaced by explicit `canopy migrate-slots` + a `pre_migration` BlockerError that points at it).
+
+## 0.7.0
+
+Five new top-level commands + a CI-aware state machine.
+
+- **`canopy ship`** takes a feature from "code is committed" to "PR is open across every repo." Per-repo recipe: ensure-pushed → ensure-PR-exists → cross-repo body refresh so each PR description links to its siblings. Idempotent (`up_to_date` on re-run); refuses to silently recreate closed PRs; surfaces force-push divergence as `diverged`. Exposed as `mcp__canopy__ship`.
+- **`canopy draft-replies <alias>`** walks each unresolved review comment's anchor sha through `git log -- <path>`. Addressed comments get a template-based draft (`Done — <subject>. (<sha>)` / `Addressed in <sha>: <subject>.` / `Addressed across N commits — <list>.`) with high/medium/low confidence based on commit count + keyword overlap. No LLM. Exposed as `mcp__canopy__draft_replies`.
+- **CI status integration.** `feature_state.repos[*].pr.ci_status` carries a rolled-up CI verdict from `gh pr checks`. The state machine gains `awaiting_ci` (approved + pending CI), and approved + failing CI now flips to `needs_work` instead of misleadingly reporting `approved`. New `canopy pr-checks <alias>` + `mcp__canopy__pr_checks` for the raw check list.
+- **`canopy worktree-bootstrap <feature>`** runs three optional steps per repo: copy `env_files` from main checkout into the worktree, run `install_cmd` (e.g. `uv sync` / `pnpm install`), and write `.canopy/workspaces/<feature>.code-workspace` when `[workspace] ide = "vscode"`. New per-repo `env_files` / `install_cmd` / `ide_settings` keys in canopy.toml; per-workspace `bootstrap_default` opt-in.
+- **`canopy conflicts`** pairwise intersects each active feature's changed-files per repo. `--lines` opts into a deeper `git diff --unified=0` parse for line-range overlap (downgrades to `medium` when files overlap but lines don't); generated/lockfile-style files auto-drop to `medium` with an "auto-mergeable" suggestion. Exposed as `mcp__canopy__conflicts`.
+
+MCP tools 54 → 59. Tests 651 → 712. Comment-shape adds `commit_id` so the file-history walk in draft-replies can anchor properly.
+
+## 0.5.0
+
+Catches the `__version__` constant up to ~6 months of shipped work. The handshake the doctor's staleness checks rely on is only useful when this number actually moves — this release fixes that drift.
+
+- **`canopy commit` + `canopy push`** — feature-scoped multi-repo commit and push with `wrong_branch` / `no_upstream` blockers and per-repo result classification.
+- **Provider-injection architecture** — `docs/architecture/providers.md` design doc for the issue-provider contract.
+- **`canopy doctor`** — single recovery primitive with 16 diagnostic categories (state-file integrity + install / version / mcp / skill / vsix). `--fix` for auto-repairable; severity tiers; structured JSON.
+- **Issue providers** — `IssueProvider` Protocol + registry under `canopy.providers.*`. Linear refactored into the contract; `GitHubIssuesProvider` via `gh` CLI. `[issue_provider]` block in canopy.toml; `issue_get` / `issue_list_my_issues` MCP tools (deprecated `linear_*` aliases retained).
+- **Augments** — per-workspace `[augments]` block in canopy.toml + per-repo overrides. `preflight_cmd` is the first consumer; `review_bots` and `test_cmd` reserved. Multi-skill installer; `augment-canopy` skill teaches the agent how to mutate canopy.toml safely.
+- **Bot-comment tracking** — per-comment resolution log at `.canopy/state/bot_resolutions.json`; `canopy commit --address <comment-id>` auto-suffixes the message and records the resolution; `canopy bot-status` rollup; new `awaiting_bot_resolution` state.
+- **Historian** — per-feature persistent memory at `.canopy/memory/<feature>.md`. Auto-read on `canopy switch` (response carries `memory: <markdown>`); 5 MCP tools (`historian_decide` / `historian_pause` / `historian_defer_comment` / `feature_memory` / `historian_compact`); 2 CLI commands (`canopy historian show` / `compact`); auto-mirror from `commit --address` and `github_get_pr_comments`.
+
+MCP tools 41 → 54. Tests ~400 → 624. State machine 8 → 9 (added `awaiting_bot_resolution`). Bundled skills 1 → 2 (`using-canopy` + opt-in `augment-canopy`).
+
+## 0.1.0
+
+Initial release: workspace discovery, feature lanes, post-checkout hook, drift detection, `switch` / `triage` / `feature_state` actions, MCP server, agent setup.

canopy_cli-3.1.0/CLAUDE.md

@@ -0,0 +1,162 @@
+# Canopy — Claude Code Context
+
+## What This Project Is
+
+Canopy is the **context contract** between an AI coding agent and a multi-repo workspace, plus a **drift-proof CLI** for the human. Every operation takes semantic context (`feature`, `repo`, alias) and resolves paths internally — the agent literally can't `cd` to the wrong directory because it never specifies a directory. Multi-repo drift is detected in real time via per-repo post-checkout hooks and surfaced as a structured `BlockerError`. PR review comments are temporally classified into `actionable_threads` vs `likely_resolved_threads`, so the agent's context budget goes to comprehension, not orchestration.
+
+**`canopy switch` is the focus primitive (Wave 3.0 slot model).** Each feature lives in one of three states: **canonical** (checked out in main repo — the only place code is meant to run), **warm** (occupies a numbered slot at `.canopy/worktrees/worktree-N/<repo>/`), **cold** (branch only). Slots are stable disk resources; features are transient tenants — a slot keeps its id (`worktree-1`, `worktree-2`, ...) across feature swaps. `switch(Y)` promotes Y to canonical; previously-canonical X either evacuates into a warm slot (active rotation, default — instant to switch back) or goes cold with a feature-tagged stash (wind-down via `--release-current`). Cap (`slots`, default 2) protects against unbounded growth via LRU eviction or a `worktree_cap_reached` BlockerError. See [docs/concepts.md §4](docs/concepts.md#4-the-slot-model).
+
+## Architecture
+
+```
+src/canopy/
+├── cli/main.py              # argparse entry point, all commands (thin wrapper)
+├── cli/render.py            # structured-error renderer
+├── workspace/
+│   ├── config.py            # canopy.toml parser
+│   ├── discovery.py         # auto-detect repos + worktrees, generate toml
+│   ├── context.py           # context detection (feature_dir, repo_worktree, repo, workspace_root)
+│   └── workspace.py         # Workspace class, RepoState dataclass
+├── git/
+│   ├── repo.py              # ALL git subprocess calls go here
+│   ├── multi.py             # cross-repo operations
+│   ├── hooks.py             # install/uninstall post-checkout hook + heads.json reader
+│   └── templates/post-checkout.py   # hook script (Python, fcntl-locked, never blocks git)
+├── features/coordinator.py   # FeatureLane, FeatureCoordinator (+ branches map for per-repo branches)
+├── actions/                 # WAVE 2+: action layer — completion-driven recipes
+│   ├── errors.py            # ActionError / BlockerError / FailedError / FixAction
+│   ├── aliases.py           # universal alias resolver (incl. worktree-N → slot occupant)
+│   ├── slots.py             # WAVE 3.0: slots.json reader/writer + path resolution + LRU
+│   ├── slot_load.py         # WAVE 3.0: slot_load / slot_clear / slot_swap primitives
+│   ├── slot_details.py      # WAVE 3.0: rich slots shape (PR/CI/bots/linear per slot+canonical)
+│   ├── migrate_slots.py     # WAVE 3.0: one-shot pre-3.0 → 3.0 layout migration
+│   ├── drift.py             # detect_drift + assert_aligned (cached path)
+│   ├── evacuate.py          # WAVE 2.9: per-repo evacuate primitive (stash → wt-add → pop)
+│   ├── feature_state.py     # 9-state machine, dashboard backend (live git, worktree-aware)
+│   ├── bot_resolutions.py   # M3: persistent log of bot comments addressed via `commit --address`
+│   ├── bot_status.py        # M3: per-feature bot-comment rollup
+│   ├── augments.py          # M2: per-workspace augment resolver (preflight_cmd, review_bots, ...)
+│   ├── bootstrap.py         # M6: env-file copy + install_cmd + IDE workspace gen for worktrees
+│   ├── conflicts.py         # M12: cross-feature file/line overlap detection
+│   ├── draft_replies.py     # M9: file-history-based addressed-comment classifier + reply templates
+│   ├── historian.py         # M4: cross-session feature memory at .canopy/memory/<feature>.md
+│   ├── ide_workspace.py     # M6: pure renderer for `.code-workspace` files
+│   ├── preflight_state.py   # records preflight result for state machine
+│   ├── reads.py             # 4 alias-aware read primitives
+│   ├── review_filter.py     # temporal classifier
+│   ├── ship.py              # M8: PR open/update orchestrator with cross-repo body links
+│   ├── stash.py             # feature-tagged stash save/list/pop
+│   ├── switch.py            # WAVE 3.0: slot-model focus primitive (+ --to-slot / --evict-to)
+│   ├── switch_preflight.py  # WAVE 3.0: predictable-failure detection for switch
+│   ├── triage.py            # cross-repo PR enumeration + priority tiers (slot-enriched)
+│   ├── last_visit.py        # per-feature last-visit anchor (visits.json get/mark/reset)
+│   ├── resume.py            # feature_resume compound action + resume_summary (counts-only)
+│   ├── thread_actions.py    # GH thread resolve/reply wrappers + local resolution log
+│   └── thread_resolutions.py  # thread_resolutions.json load/record/filter_since
+├── agent/
+│   └── runner.py            # canopy_run — directory-safe shell exec
+├── agent_setup/             # ships bundled skills + setup_agent installer
+│   ├── __init__.py          # install_skill / install_mcp / check_status
+│   └── skills/              # one SKILL.md per skill name
+│       ├── using-canopy/SKILL.md     # default, always installed
+│       └── augment-canopy/SKILL.md   # opt-in via --skill augment-canopy (M2)
+├── integrations/
+│   ├── linear.py            # Linear issue fetching (via mcp/client.py)
+│   ├── github.py            # GitHub PR + comments (MCP or gh CLI fallback)
+│   └── precommit.py         # detect + run pre-commit hooks
+└── mcp/
+    ├── server.py            # MCP server — 67 tools, stdio transport
+    └── client.py            # MCP client — stdio + HTTP+OAuth transports
+```
+
+## Key conventions
+
+- **`git/repo.py` is the only module that calls `subprocess.run(["git", ...])`.** Everything else routes through it. Keeps the git layer testable and replaceable.
+- **`mcp/server.py` and `cli/main.py` are thin wrappers.** Business logic lives in `actions/`, `features/coordinator.py`, `git/multi.py`, `workspace/`.
+- **All CLI commands support `--json`.** This is the contract between CLI, MCP, and any GUI. Same JSON shape across surfaces.
+- **Actions return structured errors.** `BlockerError(code, what, expected, actual, fix_actions, details)`. CLI renders via `cli/render.py`; MCP returns `to_dict()`. Same shape, two consumers.
+- **Universal aliases** — every read tool accepts feature name, Linear ID, `<repo>#<n>`, PR URL, `<repo>:<branch>`, or slot id (`worktree-N` → slot's current occupant). Resolved by `actions/aliases.py:resolve_feature` (with single-repo + per-repo-branch fallbacks).
+- **Per-repo branches map** — `FeatureLane.branches: dict[repo, branch]` overrides "branch == feature name" for legacy mismatched-naming features. Use `lane.branch_for(repo)` or `repos_for_feature(workspace, feature)` everywhere — never recompute as `[r for r in feature.repos]` with feature name as branch (regresses Gap 2).
+- **Feature lanes use real Git branches and worktrees.** No virtual branches.
+- **Feature metadata lives in `.canopy/features.json`. Worktrees in `.canopy/worktrees/worktree-N/<repo>/` (generic numbered slots).** A slot holds one feature at a time; a feature's repos sit as siblings inside its slot. Canonical (main repo dirs) is the only place to *run* code; worktrees are passive branch storage.
+- **State files** at `.canopy/state/heads.json` (post-checkout hook output), `.canopy/state/preflight.json` (preflight tracker), `.canopy/state/slots.json` (canonical + warm slot occupancy + `last_touched` LRU map + `in_flight` transaction marker), `.canopy/state/visits.json` (per-feature last-visit anchor: `{feature: {last_visit, previous_visit}}`), and `.canopy/state/thread_resolutions.json` (log of GH review threads canopy itself resolved: `{thread_id: {resolved_by_canopy_at, feature, via_command, via_commit_sha}}`). OAuth tokens at `~/.canopy/mcp-tokens/`.
+- **MCP client supports two transports.** Stdio (existing) for npm/python servers. HTTP+OAuth (new) for hosted servers like Linear's `mcp.linear.app`. Tokens cache per server.
+- **GitHub fallback to gh CLI.** When no `github` MCP server is configured, `integrations/github.py` falls back to `gh api` / `gh pr` for the same return shapes. If neither is available, raises `BlockerError(code='github_not_configured')` with platform-aware install hints.
+- **Single source of truth for state.** `feature_state` uses live git (not heads.json) so it's correct even when the hook hasn't fired. `drift` uses heads.json for the fast cached path.
+- **Feature-aware stash tagging** — `stash save --feature` writes `[canopy <feature> @ <ts>] <message>`. Parser tolerates git's `On <branch>: ` auto-prefix.
+
+## Build & Test
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v          # 401 tests, ~60s
+```
+
+## Test Fixtures
+
+Tests use real temporary Git repos created in `tests/conftest.py`:
+- `workspace_dir` — bare workspace with `api/` and `ui/` repos on main
+- `workspace_with_feature` — workspace with `auth-flow` branches + commits in both repos
+- `canopy_toml` — workspace with a canopy.toml already written
+
+For integration testing against real services, see `~/projects/canopy-test/` (memory: project_test_workspace).
+
+## Important Implementation Details
+
+- **Python 3.10+ compat:** `tomli` on 3.10, `tomllib` on 3.11+. See `config.py`.
+- **Drift detection:** post-checkout hook installed by `canopy init` (or `canopy hooks install`). Hook is Python; uses `fcntl.flock` + atomic rename so concurrent fires across repos don't race. Respects `core.hooksPath` (Husky-friendly). Chains pre-existing user hooks. Worktrees inherit hooks via `commondir` resolution.
+- **`--no-track` on branch creation:** `git/repo.py:create_branch` and `worktree_add` always pass `--no-track` so a `branch.autoSetupMerge=inherit` gitconfig doesn't accidentally set the new branch's upstream to `dev`.
+- **Slot limits:** `[workspace] slots = N` in canopy.toml caps the number of warm slots (default **2**, so 1 canonical + 2 warm = 3 live trees max). The pre-3.0 `max_worktrees` key now raises `ConfigError` pointing at `canopy migrate-slots`. See `actions/switch_preflight.py:warm_slot_cap`.
+- **Action contract:** `actions/protocol.py` (planned) will formalize the per-repo `{status, before, after, reason?}` shape. For now, each action returns it ad-hoc.
+- **Skill bundling:** Bundled skills live at `src/canopy/agent_setup/skills/<name>/SKILL.md`. `canopy setup-agent` copies them to `~/.claude/skills/<name>/SKILL.md`. The default `using-canopy` skill always installs; opt-in extras (e.g. `augment-canopy`) install via `--skill <name>` (repeatable). Foreign skills with the same path are not overwritten without `--reinstall`. The `_SKILL_SOURCE` constant remains as a backward-compat alias pointing at `using-canopy`'s source.
+- **Version bumps:** When shipping a milestone, bump `__version__` in [`src/canopy/__init__.py`](src/canopy/__init__.py) and add a section to [`CHANGELOG.md`](CHANGELOG.md). The version handshake (`canopy --version`, `mcp__canopy__version`, doctor's `cli_stale` / `mcp_stale` checks) is only useful when this number actually moves — drift was the bug 0.5.0 caught.
+
+## MCP Server (67 tools)
+
+Grouped by topic. Run with `canopy-mcp` (entry point) or `python -m canopy.mcp.server`.
+
+```
+Meta:         version, doctor              # 21-code / 12-category recovery primitive
+Workspace:    workspace_status, workspace_context, workspace_config, workspace_reinit
+Feature:      feature_create, feature_list, feature_status, feature_diff,
+              feature_changes, feature_merge_readiness, feature_paths, feature_done,
+              feature_link_linear, feature_state
+Slots:        slots, slot_load, slot_clear, slot_swap, migrate_slots   # WAVE 3.0
+Actions:      switch, triage, drift, conflicts   # switch is the slot-model focus primitive
+Reads:        linear_get_issue, github_get_pr, github_get_branch, github_get_pr_comments,
+              linear_my_issues, pr_checks         # pr_checks = M10 CI rollup
+Workflow:     ship, draft_replies, feature_resume  # M8 + M9 + Plan 2 — capstone + reply drafts + session resume
+Threads:      resolve_thread, reply_to_thread      # Plan 2 — GH review thread mutations + local log
+Run/Pre:      run, preflight, review_status, review_comments, review_prep
+Stash:        stash_save_feature, stash_list_grouped, stash_pop_feature,
+              stash_save, stash_pop, stash_list, stash_drop
+Worktree:     worktree_create, worktree_info, worktree_bootstrap   # bootstrap = M6
+Branch:       branch_list, branch_delete, branch_rename
+Misc:         log, checkout, sync
+```
+
+## MCP Client
+
+Two transports.
+
+**stdio** for npm/python servers:
+```json
+{ "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"],
+              "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."} } }
+```
+
+**HTTP + OAuth** for hosted servers like Linear:
+```json
+{ "linear": { "type": "http", "url": "https://mcp.linear.app/mcp", "oauth": true } }
+```
+
+Token cache at `~/.canopy/mcp-tokens/<server>.{client,tokens}.json`. First call opens browser; subsequent calls silent.
+
+## When working in this repo
+
+- Read `docs/concepts.md` if you need the action framework / state machine vocabulary.
+- Read `docs/agents.md` if you're implementing or using the agent integration.
+- New actions: stub in `src/canopy/actions/`, raise `BlockerError` for preconditions, expose via CLI in `cli/main.py` + MCP in `mcp/server.py`. Add tests in `tests/test_<action>.py` using the existing `workspace_with_feature` fixture.
+- New MCP tools: register an existing `actions/*.py` function under `@mcp.tool()` in `mcp/server.py`. Update `docs/mcp.md` and `docs/agents.md`.
+- New CLI commands: define a handler `cmd_<name>(args)`, add a subparser in `main()`, dispatch in the `commands` dict. Update `docs/commands.md`.
+- Adding a new ⨯ tool to canopy → also update `~/.claude/skills/using-canopy/SKILL.md` and `src/canopy/agent_setup/skills/using-canopy/SKILL.md` so the agent learns when to prefer it.