switchman-dev 0.1.1 → 0.1.3

package/README.md

@@ -23,6 +23,80 @@ npm install -g @switchman-dev
 
 ---
 
+## First successful run: 3 agents on one repo
+
+If you only try one thing, try this.
+
+### 1. Create a test repo and three agent worktrees
+
+```bash
+cd my-project
+switchman setup --agents 3
+```
+
+This gives you:
+- one shared Switchman database in `.switchman/`
+- three linked worktrees
+- local `.mcp.json` files so Claude Code can discover Switchman automatically
+
+### 2. Add three small, separate tasks
+
+```bash
+switchman task add "Implement auth helper" --priority 9
+switchman task add "Add auth tests" --priority 8
+switchman task add "Update auth docs" --priority 7
+```
+
+Use real tasks from your repo. If a task looks broad enough to fan out across many files or shared areas, Switchman will warn and suggest using `switchman pipeline start` instead.
+
+### 3. Open one Claude Code window per worktree
+
+Open each generated worktree folder in its own Claude Code window.
+
+If Claude Code sees the local `.mcp.json`, each agent can use Switchman without extra setup.
+
+### 4. Tell each agent to work through Switchman
+
+Use this exact instruction:
+
+```text
+Use Switchman for all task coordination in this repo.
+
+1. Run `switchman lease next --json` to get your task and lease.
+2. Before editing anything, run `switchman claim <taskId> <worktree> <files...>`.
+3. Only edit files you have claimed.
+4. If a claim is blocked, do not use --force. Pick a different file or different approach.
+5. When finished, run `switchman task done <taskId>`.
+
+Do not read or write `.switchman/switchman.db` directly.
+Do not bypass Switchman for file coordination.
+```
+
+### 5. Watch the run
+
+In the repo root:
+
+```bash
+switchman status
+switchman scan
+```
+
+What a good first run looks like:
+- all three tasks end in `done`
+- `switchman scan` reports no conflicts
+- `switchman gate ci` passes
+
+### 6. If you want a built-in local demo instead
+
+```bash
+bash examples/setup.sh
+bash examples/walkthrough.sh
+```
+
+That runs the included 3-agent demo against the example API in [examples/README.md](/Users/ned/Documents/GitHub/switchman/examples/README.md).
+
+---
+
 ## Pick your setup
 
 ### Option A — Claude Code (recommended)
@@ -40,7 +114,9 @@ That's it. Switchman creates three isolated workspaces, one per agent, and initi
 
 **Step 2 — Add Switchman to Claude Code**
 
-Add this to `~/.claude/claude_desktop_config.json`:
+`switchman setup` now writes a project-local `.mcp.json` into the repo root and each generated worktree, so Claude Code can discover Switchman automatically when you open those folders.
+
+If you prefer a global fallback, add this to `~/.claude/claude_desktop_config.json`:
 
 ```json
 {
@@ -53,7 +129,7 @@ Add this to `~/.claude/claude_desktop_config.json`:
 }
 ```
 
-Then restart Claude Code.
+Then restart Claude Code. The project-local `.mcp.json` is the preferred path because it travels with the repo and the generated worktrees.
 
 **Step 3 — Copy CLAUDE.md into your repo root**
 
@@ -61,7 +137,7 @@ Then restart Claude Code.
 curl -O https://raw.githubusercontent.com/switchman-dev/switchman/main/CLAUDE.md
 ```
 
-This tells your agents how to use Switchman. Without it they won't know to coordinate.
+This tells your agents how to use Switchman. Without it they may bypass Switchman entirely, so keep it in the repo root and do not let agents talk to `.switchman/switchman.db` directly.
 
 **Step 4 — Add your tasks**
 
@@ -73,7 +149,7 @@ switchman task add "Update README" --priority 2
 
 **Step 5 — Open Claude Code in each workspace**
 
-Open a separate Claude Code window in each folder that `switchman setup` created. Each agent will automatically pick up a task, lock the files it needs, and release them when it's done.
+Open a separate Claude Code window in each folder that `switchman setup` created. Each agent should automatically see the local MCP config, pick up a task, lock the files it needs, and release them when it's done.
 
 **Step 6 — Check before merging**
 
@@ -107,10 +183,11 @@ Paste this into your agent at the start of each session:
 
 ```
 Before starting any work:
-1. Run `switchman task next --json` to get your assigned task
+1. Run `switchman lease next --json` to get your assigned task and lease
 2. Run `switchman claim <taskId> <worktreeName> <files...>` to lock the files you'll edit
    - If a file is already claimed, pick a different approach or different files
-3. When finished, run `switchman task done <taskId>`
+3. If the task runs for a while, refresh the lease with `switchman lease heartbeat <leaseId>`
+4. When finished, run `switchman task done <taskId>`
 
 Never edit a file you haven't claimed. If a claim fails, do not use --force.
 ```
@@ -129,16 +206,16 @@ Here's what a normal session looks like with Switchman running:
 
 ```
 # Agent 1 picks up a task
-switchman task next
-✓  Assigned: "Add rate limiting to all routes"  [task-abc-123]
+switchman lease next
+✓  Lease acquired: "Add rate limiting to all routes"  [task-abc-123 / lease-xyz-123]
 
 # Agent 1 locks its files
 switchman claim task-abc-123 agent1 src/middleware/auth.js src/server.js
 ✓  2 files locked — no conflicts
 
 # Agent 2 picks up a different task
-switchman task next
-✓  Assigned: "Add validation to POST /tasks"  [task-def-456]
+switchman lease next
+✓  Lease acquired: "Add validation to POST /tasks"  [task-def-456 / lease-xyz-456]
 
 # Agent 2 tries to claim a file already locked by Agent 1
 switchman claim task-def-456 agent2 src/middleware/auth.js
@@ -156,12 +233,74 @@ switchman status
 
 ---
 
+## If something goes wrong
+
+Start here before digging into the internals.
+
+### `switchman status`
+
+Use this first when a run feels stuck.
+
+It answers:
+- what is running
+- what is blocked
+- what failed
+- what needs attention next
+
+### `switchman scan`
+
+Use this before merge, or any time you suspect agents overlapped.
+
+It tells you:
+- changed files per worktree
+- unclaimed or unmanaged changes
+- conflict signals across worktrees
+
+### `switchman gate ci`
+
+Use this as the final repo-level check.
+
+```bash
+switchman gate ci
+```
+
+If it fails, Switchman has detected unmanaged changes, stale state, or merge-governance problems.
+
+### Common recovery cases
+
+`A file claim is blocked`
+- another task already owns that file
+- do not use `--force`
+- choose a different file or let the other task finish first
+
+`A task is still in progress but the agent is gone`
+- inspect with `switchman status`
+- if the lease is stale, run:
+
+```bash
+switchman lease reap
+```
+
+`A pipeline task failed`
+- run:
+
+```bash
+switchman pipeline status <pipelineId>
+```
+
+Switchman now prints:
+- `why:` what failed
+- `next:` what to do next
+
+---
+
 ## Commands
 
 ### `switchman setup`
 One-command setup — creates agent workspaces and initialises the database.
 - `--agents 3` — number of workspaces to create (default: 3, max: 10)
 - `--prefix switchman` — branch name prefix (default: switchman)
+- Writes `.mcp.json` to the repo root and each generated worktree so Claude Code can attach the Switchman MCP server automatically
 
 ### `switchman init`
 Initialise in the current git repo without creating worktrees. Creates `.switchman/switchman.db` and auto-detects existing worktrees.
@@ -175,15 +314,32 @@ Add a task to the queue.
 List all tasks. Filter with `--status pending|in_progress|done|failed`.
 
 ### `switchman task next`
-Get and assign the next pending task. Use `--json` for agent automation.
+Get and assign the next pending task. This is a compatibility shim over the lease workflow. Use `--json` for agent automation.
 - `--worktree <name>` — worktree to assign to (defaults to current folder name)
 - `--agent <name>` — agent identifier for logging
 
+### `switchman lease next`
+Acquire the next pending task as a first-class lease. Use `--json` for agent automation.
+- `--worktree <name>` — worktree to assign to (defaults to current folder name)
+- `--agent <name>` — agent identifier for logging
+
+### `switchman lease list`
+List active and historical leases. Filter with `--status active|completed|failed|expired`.
+
+### `switchman lease heartbeat <leaseId>`
+Refresh the heartbeat timestamp for a long-running lease so it does not get treated as stale.
+
+### `switchman lease reap`
+Expire stale leases, release their claims, and return their tasks to `pending`.
+- `--stale-after-minutes <n>` — staleness threshold (default: 15)
+
 ### `switchman task done <taskId>`
-Mark a task complete and release all file claims.
+Mark a task complete and automatically release all file claims.
+When the task has an active lease, Switchman finalises the execution through that lease so provenance stays tied to the live session.
 
 ### `switchman task fail <taskId>`
-Mark a task failed and release all file claims.
+Mark a task failed and automatically release all file claims.
+When the task has an active lease, Switchman records the failure against that lease so execution history stays lease-first.
 
 ### `switchman claim <taskId> <worktree> [files...]`
 Lock files before editing. Warns immediately if any file is already claimed by another agent.
@@ -193,9 +349,10 @@ Release all file claims for a task.
 
 ### `switchman scan`
 Check all worktrees for conflicts — both uncommitted file overlaps and branch-level merge conflicts. Run this before merging.
+By default, common generated paths such as `node_modules/`, `dist/`, `build/`, and `coverage/` are ignored.
 
 ### `switchman status`
-Full overview: task counts, active tasks, locked files, and a quick conflict scan.
+Full overview: task counts, active leases, stale leases, locked files, a quick conflict scan, and readable failure explanations.
 
 ### `switchman worktree list`
 List all git worktrees with their registered agents and status.
@@ -205,6 +362,159 @@ Re-sync git worktrees into the Switchman database (useful if you add worktrees a
 
 ---
 
+## Pipelines and PRs
+
+Switchman can now take a backlog item through planning, governed execution, review, and PR handoff.
+
+### Happy-path pipeline flow
+
+```bash
+switchman pipeline start "Harden auth API permissions" \
+  --description "Update login permissions for the public API and add migration checks"
+
+switchman pipeline exec pipe-123 "/path/to/your-agent-command"
+switchman pipeline status pipe-123
+switchman pipeline pr pipe-123
+switchman pipeline publish pipe-123 --base main --draft
+```
+
+The intended operator loop is:
+1. start the pipeline
+2. run it
+3. inspect `pipeline status` if anything blocks
+4. review the PR artifact or publish the PR
+
+### Create a pipeline from one issue
+
+```bash
+switchman pipeline start "Harden auth API permissions" \
+  --description "Update login permissions for the public API and add migration checks"
+```
+
+This creates structured subtasks with task specs, dependencies, and suggested worktrees.
+
+### Run the pipeline
+
+```bash
+switchman pipeline exec pipe-123 "/path/to/your-agent-command"
+```
+
+This dispatches dependency-ready tasks, launches agents with `SWITCHMAN_*` task context, applies retries/timeouts from the task spec, and runs review follow-ups until the pipeline is ready or blocked.
+
+### Generate a reviewer-facing PR summary
+
+```bash
+switchman pipeline pr pipe-123
+switchman pipeline pr pipe-123 --json
+```
+
+Use this to inspect the current PR-ready summary, gate results, risk notes, and provenance.
+Completed work provenance now includes the lease that executed the work, not just the task and worktree.
+
+### Export a PR bundle
+
+```bash
+switchman pipeline bundle pipe-123 .switchman/pr-bundles/auth-hardening
+```
+
+This writes:
+
+- `pr-summary.json`
+- `pr-summary.md`
+- `pr-body.md`
+
+The exported reviewer bundle includes lease-aware provenance, so a reviewer can see which execution session produced each completed task.
+
+### Publish a GitHub PR
+
+```bash
+switchman pipeline publish pipe-123 --base main --draft
+```
+
+This uses `gh pr create` with the generated PR title and body. Requirements:
+
+- GitHub CLI (`gh`) installed
+- `gh auth login` already completed
+- the pipeline worktree branch pushed or otherwise available as the PR head branch
+
+---
+
+## CI and GitHub Actions
+
+Switchman can publish CI-friendly gate output and install a ready-to-run GitHub Actions workflow.
+
+### Run the repo gate in CI
+
+```bash
+switchman gate ci
+switchman gate ci --json
+switchman gate ci --github
+```
+
+`switchman gate ci` fails non-zero when the repo contains unmanaged changes, stale compliance problems, or merge-governance issues.
+
+When run under GitHub Actions with `--github`, Switchman writes:
+
+- a step summary markdown report
+- `GITHUB_OUTPUT` values such as `switchman_ok=true|false`
+
+You can also point these explicitly:
+
+```bash
+switchman gate ci \
+  --github-step-summary /path/to/summary.md \
+  --github-output /path/to/output.txt
+```
+
+### Install the GitHub Actions workflow
+
+```bash
+switchman gate install-ci
+```
+
+This writes `.github/workflows/switchman-gate.yml`, which runs the Switchman CI gate on pushes and pull requests.
+
+---
+
+## Tamper-evident audit trail
+
+Switchman now keeps a signed audit trail for governed work.
+
+Every audit event is:
+- appended with a monotonic sequence number
+- chained to the previous event with `prev_hash`
+- hashed into its own `entry_hash`
+- signed with a per-project audit key stored at `.switchman/audit.key`
+
+That means Switchman can detect if someone edits stored audit history after the fact.
+
+### Verify the audit trail
+
+```bash
+switchman audit verify
+switchman audit verify --json
+```
+
+Use this when you want proof that the recorded history still matches the project audit key and the stored event chain.
+
+What a successful verification means:
+- every event is still in the expected sequence
+- every `prev_hash` still matches the prior event
+- every event payload still matches its stored `entry_hash`
+- every signature still matches the project audit key
+
+If verification fails, Switchman exits non-zero and reports the reason, for example:
+- `sequence_gap`
+- `prev_hash_mismatch`
+- `entry_hash_mismatch`
+- `signature_mismatch`
+
+This is different from normal CI:
+- `switchman gate ci` answers whether the repo is safe and governed right now
+- `switchman audit verify` answers whether the recorded audit history has been tampered with
+
+---
+
 ## MCP tools (Claude Code)
 
 | Tool | What it does |
@@ -214,6 +524,7 @@ Re-sync git worktrees into the Switchman database (useful if you add worktrees a
 | `switchman_task_claim` | Claim files before editing (conflict check) |
 | `switchman_task_done` | Mark task complete, release file claims |
 | `switchman_task_fail` | Mark task failed, release file claims |
+| `switchman_lease_heartbeat` | Refresh a long-running lease heartbeat |
 | `switchman_scan` | Scan all worktrees for conflicts |
 | `switchman_status` | Full system overview |
 
@@ -222,7 +533,7 @@ Re-sync git worktrees into the Switchman database (useful if you add worktrees a
 ## Roadmap
 
 - [ ] Merge queue — serialize worktree→main merges with auto-retry
-- [ ] Agent health monitoring — reclaim tasks from dead/stalled agents
+- [ ] Automatic stale-lease policies — configurable heartbeat/reap behaviour
 - [ ] Cursor and Windsurf native MCP integration
 - [ ] Web dashboard
 - [ ] `brew install switchman`
@@ -240,4 +551,4 @@ Building this in public — if you're running parallel agents and hit something
 
 ## License
 
-MIT — free to use, modify, and distribute.
+MIT — free to use, modify, and distribute.

package/examples/README.md

@@ -25,6 +25,8 @@ examples/
 
 ## Quick start
 
+This is the fastest way to understand Switchman as a new user.
+
 Make sure Switchman is installed globally first:
 ```bash
 npm install -g .   # from the switchman repo root
@@ -36,16 +38,30 @@ bash examples/setup.sh
 bash examples/walkthrough.sh
 ```
 
+If you want the shortest path:
+- `setup.sh` creates the repo, worktrees, and seed tasks
+- `walkthrough.sh` shows one complete 3-agent happy path, including a real claim conflict
+
 ## What the walkthrough shows
 
 1. **3 worktrees created** — simulating 3 parallel Claude Code instances each on their own branch
-2. **Agent 1 picks up a task** — `switchman task next` returns the highest-priority item
+2. **Agent 1 picks up a task** — `switchman lease next` returns the highest-priority item and lease
 3. **Agent 1 claims files** — declares which files it will edit before touching them
 4. **Agent 2 picks up a task** — takes the next item from the queue
 5. **Agent 2 tries to claim a conflicting file** — Switchman blocks it
 6. **Agent 2 adapts** — claims only the safe files instead
 7. **Agent 1 finishes** — marks task done, releases file claims
-8. **Final status** — queue updated, no lingering conflicts
+
+Under the hood, Switchman now treats the lease as the execution record. That means reviewer artifacts and audit history can point back to the exact lease that performed the work, not just the task title.
+8. **Final status** — queue updated, readable status output, no lingering conflicts
+
+## What a good demo run looks like
+
+At the end of the walkthrough, you want to see:
+- tasks moving from `pending` -> `in_progress` -> `done`
+- one agent blocked from claiming a file already owned by another
+- `switchman scan` showing no unclaimed changes
+- `switchman status` giving a clean overview of what happened
 
 ## The taskapi project
 

package/examples/walkthrough.sh

@@ -2,7 +2,7 @@
 # examples/walkthrough.sh
 #
 # Walks through the Switchman workflow step by step.
-# Simulates 3 agents working in parallel — including a real conflict.
+# Simulates 3 agents working in parallel, including a real file-claim conflict.
 #
 # Run AFTER setup.sh:
 #   bash examples/walkthrough.sh
@@ -51,11 +51,11 @@ read -r
 # ── Step 2: Agent 1 picks up a task ──────────────────────────────────────────
 
 step "2. Agent 1 picks up the highest-priority task"
-agent "agent-rate-limiting" "calling: switchman task next --json"
+agent "agent-rate-limiting" "calling: switchman lease next --json"
 echo ""
 
-TASK1=$(switchman task next --json 2>/dev/null || echo "null")
-TASK1_ID=$(echo "$TASK1" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['id'])" 2>/dev/null || echo "")
+TASK1=$(switchman lease next --json --worktree agent-rate-limiting --agent claude-code 2>/dev/null || echo "null")
+TASK1_ID=$(echo "$TASK1" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['task']['id'])" 2>/dev/null || echo "")
 
 if [ -z "$TASK1_ID" ]; then
   echo "  No pending tasks found. Run setup.sh first."
@@ -63,9 +63,7 @@ if [ -z "$TASK1_ID" ]; then
 fi
 
 echo "$TASK1" | python3 -m json.tool 2>/dev/null || echo "$TASK1"
-echo ""
-switchman task assign "$TASK1_ID" agent-rate-limiting --agent claude-code
-ok "Task assigned to agent-rate-limiting"
+ok "Task + lease assigned to agent-rate-limiting"
 
 read -r
 
@@ -86,14 +84,12 @@ read -r
 # ── Step 4: Agent 2 picks up a task ──────────────────────────────────────────
 
 step "4. Agent 2 picks up the next task"
-agent "agent-validation" "calling: switchman task next --json"
+agent "agent-validation" "calling: switchman lease next --json"
 echo ""
 
-TASK2=$(switchman task next --json 2>/dev/null || echo "null")
-TASK2_ID=$(echo "$TASK2" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['id'])" 2>/dev/null || echo "")
-
-switchman task assign "$TASK2_ID" agent-validation --agent cursor
-ok "Task assigned to agent-validation"
+TASK2=$(switchman lease next --json --worktree agent-validation --agent claude-code 2>/dev/null || echo "null")
+TASK2_ID=$(echo "$TASK2" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['task']['id'])" 2>/dev/null || echo "")
+ok "Task + lease assigned to agent-validation"
 
 read -r
 
@@ -145,7 +141,7 @@ step "8. Agent 1 finishes — marks task done and releases files"
 agent "agent-rate-limiting" "Rate limiting implemented and committed."
 echo ""
 
-switchman task done "$TASK1_ID" --release-files
+switchman task done "$TASK1_ID"
 ok "Task done. src/middleware/auth.js and src/server.js are now free."
 
 read -r
@@ -161,11 +157,11 @@ echo ""
 echo -e "${GREEN}✓ Walkthrough complete.${RESET}"
 echo ""
 echo "What you saw:"
-echo "  • 2 agents picked up tasks from the shared queue"
+echo "  • 2 agents picked up tasks from the shared queue with real leases"
 echo "  • Agent 2 was blocked from claiming a file already owned by Agent 1"
 echo "  • Agent 2 adapted by claiming different files"
 echo "  • Agent 1 completed and released its claims"
-echo "  • The queue updated in real time throughout"
+echo "  • switchman status and switchman scan stayed readable throughout"
 echo ""
 echo "To reset and run again:"
 echo "  bash examples/teardown.sh && bash examples/setup.sh"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchman-dev",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Route your AI agents so they don't collide",
   "type": "module",
   "main": "src/index.js",