@paths.design/caws-cli 10.1.0 → 10.2.0

package/templates/.claude/rules/worktree-isolation.md

@@ -10,9 +10,27 @@ When multiple agents are working on this project, each agent MUST work in its ow
 ## Before starting work
 
 1. Check if worktrees exist: `caws worktree list` shows all active worktrees with last commit time and owner
-2. If worktrees are active and you are on the base branch, switch to your assigned worktree
-3. If no worktree exists for you, create one with `caws worktree create <name>` or `caws parallel setup <plan-file>`
-4. **Never touch a worktree you did not create.** Do not destroy, prune, stash, or "clean up" another agent's worktree — even if it looks stale. Another agent may be actively working in it. If you think a worktree is abandoned, leave it alone and let the user decide.
+2. Check who's actually working: `caws agents list` shows registered sessions and their bound worktree/spec, formatted as `<sessionId>:<platform>`
+3. If you're inside a worktree, run `caws status` — the Claim panel shows the current owner, last heartbeat, and any session-log path under `tmp/<sessionId>/`
+4. If worktrees are active and you are on the base branch, switch to your assigned worktree
+5. If no worktree exists for you, create one with `caws worktree create <name>` or `caws parallel setup <plan-file>`
+6. **Never touch a worktree you did not create.** Do not destroy, prune, stash, or "clean up" another agent's worktree — even if it looks stale. Another agent may be actively working in it. If you think a worktree is abandoned, leave it alone and let the user decide.
+
+## Foreign-claim soft-block
+
+`caws worktree bind`, `merge`, and `claim` refuse to mutate a worktree whose `worktrees.json:owner` is a session id different from the current session — unless `--takeover` is supplied. The refusal prints a structured warning naming the claimer, the heartbeat age, any session-log pointer under `tmp/<sessionId>/`, and the exact `--takeover` command:
+
+```
+Worktree 'wt-foo' is claimed by 8be65780-...:claude-code
+   Last heartbeat: 2026-04-27T17:04:00Z (23 min ago)
+   Session log:    tmp/8be65780-72e0-4fc7-a989-4ebac148c18d
+                   15 turns, last turn 2026-04-27T17:26:49Z
+   To proceed:     caws worktree claim wt-foo --takeover
+```
+
+**Decision-gating uses session-id equality only.** A stale heartbeat is NOT authorization to take over — paused sessions are not ended sessions. Read the session log under `tmp/<sessionId>/` for context first. Take over only when you have explicit user authorization.
+
+`--takeover` writes a durable `prior_owners` audit on the worktree entry (sessionId, platform, lastSeen-at-takeover, takenOver_at) so the handoff is traceable in `worktrees.json`, not just in agent memory.
 
 ## Forbidden operations when worktrees are active
 

package/templates/CLAUDE.md

@@ -102,6 +102,12 @@ caws scope show
 
 # Fix a broken binding
 caws worktree bind <spec-id>
+
+# Inspect the agent registry — who is currently working what
+caws agents list
+
+# Inspect a specific worktree's claim (read-only by default)
+caws worktree claim <name>
 ```
 
 **Recovery checklist** (when the scope guard blocks you unexpectedly):
@@ -110,6 +116,22 @@ caws worktree bind <spec-id>
 3. If authoritative but still blocked: the file is genuinely outside your spec's scope. Update your spec's `scope.in` if the file should be in scope, or request a waiver
 4. Do NOT modify another spec's `scope.out` to unblock yourself — that defeats the isolation
 
+### Agent Claims & Multi-Agent Coordination
+
+Each session gets registered in `.caws/agents.json` automatically (via the session-log hook and on every CAWS lifecycle CLI invocation). Worktree session ownership is tracked in `.caws/worktrees.json:owner` as a session id.
+
+`caws worktree bind`, `merge`, and `claim` will refuse to mutate a worktree owned by a different session id without explicit `--takeover`. The refusal prints a structured warning naming the claimer as `<sessionId>:<platform>`, the heartbeat age, and any matching `tmp/<sessionId>/` session-log path so you can read context before deciding.
+
+**Decision-gating uses session-id equality only.** TTL pruning of `agents.json` is registry hygiene; it does NOT authorize takeover. A stale heartbeat doesn't mean the prior session is dead — it may be paused.
+
+`--takeover` writes a durable `prior_owners` audit on the worktree entry (sessionId, platform, lastSeen-at-takeover, takenOver_at) so handoffs are traceable in `worktrees.json`, not just in agent memory.
+
+### Spec lifecycle: archive
+
+Use `caws specs archive <id>` to move a closed spec to the canonical `.caws/specs/.archive/` directory. The directory is filesystem-authoritative — `caws specs list` reports any file under `.archive/` as `status: archived` regardless of the YAML literal. This means manually-moved legacy specs (no registry entry) are correctly classified.
+
+If you try to `caws specs create <id>` for an id that already exists in `.archive/`, the command refuses without `--force`. With `--force`, the archived YAML is removed and a fresh draft is created — useful for resurrecting an old id with new intent.
+
 > **Budget note**: `change_budget:` in a spec is informational documentation only. CAWS
 > derives the enforced budget from `policy.yaml` keyed on `risk_tier`. The field in the
 > spec is not used by `caws validate` for enforcement.

package/templates/agents.md

@@ -59,6 +59,32 @@ caws worktree bind <spec-id>
 3. If authoritative but blocked: update your spec's `scope.in`
 4. Do NOT edit another spec's `scope.out` to unblock yourself
 
+## Multi-Agent Claims
+
+Each session is registered in `.caws/agents.json` automatically. Worktree session ownership is recorded in `.caws/worktrees.json:owner` as a session id. `caws worktree bind`, `merge`, and `claim` will refuse to mutate a worktree owned by a different session id without `--takeover`.
+
+```bash
+# See registered agents (composite <sessionId>:<platform> format)
+caws agents list
+
+# Inspect a worktree's claim — read-only by default
+caws worktree claim <name>
+
+# Take over a foreign claim (writes prior_owners audit)
+caws worktree claim <name> --takeover
+```
+
+When a refusal fires, the warning includes the claimer's session id, heartbeat age, and a pointer to any `tmp/<sessionId>/` session-log directory — read that log for context before deciding to take over. A stale heartbeat does NOT mean the prior session is dead; it may be paused.
+
+## Spec Lifecycle: Archive
+
+```bash
+# Move a closed spec to the canonical archive
+caws specs archive <spec-id>
+```
+
+The `.caws/specs/.archive/` directory is filesystem-authoritative — `caws specs list` reports any file under it as `archived` regardless of YAML status. `caws specs create` refuses ids that collide with archived files unless `--force` is supplied (which removes the archived copy and writes a fresh draft).
+
 ## Key Rules
 
 1. **Stay in scope** -- only edit files listed in `scope.in`, never touch `scope.out`