@@ -0,0 +1,6 @@
+---
+'@bradygaster/squad-sdk': patch
+'@bradygaster/squad-cli': patch
+---
+
+Mark the `cross-machine-coordination` skill template as a design proposal that is not implemented: no Squad release reads `.squad/cross-machine/` task files, the `cross_machine` config block, or `squad:machine-*` labels. The skill now points to `squad watch` work claims (`--claims git-ref`, ADR-002) for keeping several watchers off the same issue, and to `needs:*` capability routing for hardware-specific work.
@@ -0,0 +1,5 @@
+---
+'@bradygaster/squad-cli': patch
+---
+
+`squad watch` work-claim telemetry (ADR-002). With an excluding claim provider (`git-ref`), each round report adds a compact line such as `🔒 Claims (git-ref): won 2 · contended 1 · released 2 (completed 2)` when any claim counter is non-zero: acquired, contended (held elsewhere), unavailable, fenced, lost (not renewed before expiry), released by outcome (completed / cancelled / abandoned), and implausible-record takeovers. `squad watch --health` shows the totals since startup from the watch PID file, and the counters are emitted as OpenTelemetry counters `squad.watch.claims.*` (attributes `claim.provider`, `claim.outcome`) when `OTEL_EXPORTER_OTLP_ENDPOINT` or `SQUAD_TELEMETRY=1` is set. No issue numbers, hostnames, or actors are recorded. With `none`, watch output is unchanged.
@@ -0,0 +1,6 @@
+---
+'@bradygaster/squad-cli': patch
+'@bradygaster/squad-sdk': patch
+---
+
+When `squad watch` runs with an exclusive claim provider (for example `--claims git-ref`), the `execute` and `fleet-dispatch` prompts now tell the agent that the listed issues are claimed for it: work only on those issues, do not pick up, self-assign, or take over other issues, and stop on an issue it cannot complete (the watcher releases the claim when the session ends). With `--claims none` (the default) the prompts are unchanged. The `ralph-instructions.md` template gains a matching "Claimed Work" section stating that claims are authoritative and assignees and labels are informational mirrors (ADR-002). Existing `.squad/ralph-instructions.md` files are user-owned and are not changed by `squad upgrade`.
@@ -0,0 +1,5 @@
+---
+'@bradygaster/squad-cli': patch
+---
+
+`squad watch` work claims (ADR-002): never dispatch on a claim that went stale while the rest of the batch was being acquired. Claims are acquired one issue at a time, so a slow or unreachable remote could carry an early claim past its renew deadline (`expiresAt - skewMarginMs`) — or past the point where another watcher may take it over — before the agent started, and the agent briefly worked an issue another watcher held until its first renewal fenced it. `execute` and `fleet-dispatch` now renew such claims before dispatch and skip the issue when the renewal is fenced (counted as `fenced`) or fails (counted as `lost`).
@@ -0,0 +1,5 @@
+---
+'@bradygaster/squad-cli': minor
+---
+
+`squad watch` can claim issues before dispatching them, so several watchers (machines, pods, dev boxes) never work on the same issue (ADR-002). Opt in with `--claims git-ref` or `watch.claims` in `.squad/config.json` (`"git-ref"` or `{ "provider": "git-ref", "ttlMs", "skewMarginMs", "remote", "refPrefix" }`); the flag overrides the config provider. The default, `none`, keeps today's behavior. With claims on, `execute` and `fleet-dispatch` dispatch only issues they won, skip issues held elsewhere or when the claim remote is unreachable, renew every `ttlMs / 3` (default 15 min lease, 2 min skew), kill the agent when its claim is fenced, and release claims when the agent finishes. `execute` now also applies `needs:*` machine capability routing, and one watch round never dispatches an issue twice across `execute` and `fleet-dispatch` (hybrid mode), whatever provider is configured. `claims` is now a reserved `watch` config key; invalid values stop watch with an error instead of being ignored.
@@ -0,0 +1,5 @@
+---
+'@bradygaster/squad-sdk': minor
+---
+
+Add the work claim contract from ADR 002 as `@bradygaster/squad-sdk/ralph/claims`: `WorkClaimProvider` (with declared `guarantees`), `WorkKey` and canonical `workKeyToString`, `ExecutorIdentity` with `resolveExecutorIdentity` (`SQUAD_MACHINE_ID` > capabilities machine > `SQUAD_POD_ID` > hostname, one `instanceId` per process), `NoopClaimProvider` (no exclusion, today's behavior), and `InMemoryClaimProvider` (single-process leases, epochs, expiry takeover, and handle fencing). `getPodId()` now accepts an optional `env` argument.
@@ -0,0 +1,5 @@
+---
+'@bradygaster/squad-sdk': minor
+---
+
+Add `GitRefClaimProvider` as `@bradygaster/squad-sdk/ralph/claims-git`: a distributed `WorkClaimProvider` (ADR 002) that stores each claim as a JSON record in an empty-tree commit at `refs/squad/claims/<sha1(work key)>` on a shared remote and decides every race with `git push --force-with-lease` compare-and-swap. Acquire, renew (fast-forward, epoch + 1), expiry takeover with skew margin, and release (CAS delete) never touch the working tree or index. The remote, ref namespace (including the `refs/heads/squad-claims/` fallback), clock, and git transport are configurable; the default transport spawns `git` with argument arrays and no shell.
@@ -0,0 +1,6 @@
+---
+'@bradygaster/squad-sdk': patch
+'@bradygaster/squad-cli': patch
+---
+
+Harden ADR-002 work claims after security review. Lease timing is bounded (30 s ≤ `ttlMs` ≤ 24 h, `skewMarginMs` ≤ 1 h, `ttlMs` > 2 × `skewMarginMs`) so the renew timer can never spin; `squad watch` rejects other values at startup and refuses to run work under them. Claim records with an impossible epoch or time, a non-empty tree, several parents, or a body over 64 KiB are taken over as expired with a warning naming the ref, and git output read from claim refs is capped. Claim commits use a fixed `squad-claims <squad-claims@invalid>` identity and a UTC date, and a hostname-derived `machineId` is published as a salted pseudonym. Fenced agents are killed with their whole POSIX process group, never after they have exited, and a `.squad/config.json` that does not parse now stops `squad watch` instead of silently disabling claims.
@@ -52,6 +52,20 @@ MAXIMIZE PARALLELISM — spawn agents for ALL actionable issues simultaneously.
 Work on every open, unblocked, unassigned issue labeled `squad` or `squad:{member}`.
 Skip issues that are assigned to a human, blocked, or marked `status:on-hold`.
 
+### Claimed Work
+
+When `squad watch` runs with a claim provider (for example `--claims git-ref`), the
+issues listed in your prompt are claimed for this session (ADR-002):
+- Work ONLY on the claimed issues in your prompt. Do not pick up other issues, even if
+  they look actionable.
+- Claims are authoritative; assignees and labels are informational mirrors. Do not
+  self-assign or take over issues claimed or assigned elsewhere.
+- If you cannot complete a claimed issue, stop and comment why. The watcher releases
+  the claim when your session ends.
+
+With `--claims none` (the default) there is no cross-watcher exclusion and Issue
+Selection above applies as written.
+
 ### Post-Task Actions
 
 <!-- Uncomment and customize to add post-task hooks, e.g. Teams notifications:
 
@@ -1,8 +1,8 @@
 ---
 name: "cross-machine-coordination"
-description: "Enables squad agents on different machines to share work via git-based task queuing"
+description: "Design proposal, not implemented: git-based task queuing between squad machines. For competing watchers, use squad watch work claims (ADR-002)."
 domain: "orchestration"
-confidence: "medium"
+confidence: "low"
 source: "manual"
 ---
 
@@ -11,7 +11,26 @@ source: "manual"
 **Skill ID:** `cross-machine-coordination`
 **Owner:** Ralph (Work Monitor)
 **Squad Integration:** All agents
-**Status:** Specification (ready for implementation)
+**Status:** Design proposal — NOT implemented
+
+> ⚠️ **Not implemented.** No Squad release reads `.squad/cross-machine/`,
+> the `cross_machine` config block, or `squad:machine-{name}` labels. Ralph
+> and `squad watch` do not poll task files, run whitelisted commands, or
+> write result files. Everything below describes a proposed design, not
+> current behavior. Do not tell users it works, and do not create task files
+> expecting another machine to pick them up.
+>
+> **Use these instead:**
+>
+> - **Several machines or pods running `squad watch --execute` on one
+>   repository:** enable work claims (`squad watch --execute --claims
+>   git-ref`, or `watch.claims` in `.squad/config.json`). Claims are Git-ref
+>   leases that make sure only one watcher works on each issue. See ADR-002
+>   (`docs/specification/adr-002-work-claims-and-external-queues.md`) and the
+>   "Multi-Machine Watch with Work Claims" docs scenario
+>   (`docs/src/content/docs/scenarios/multi-machine-watch.md`).
+> - **Sending work to a machine with specific hardware:** use capability
+>   routing with `needs:*` issue labels and a machine capabilities file.
 
 ---
 
@@ -53,7 +72,7 @@ git commit -m "Cross-machine task: GPU voice cloning [squad:machine-devbox]"
 git push origin main
 ```
 
-Ralph on DevBox will:
+In this proposal (not implemented), Ralph on DevBox would:
 1. Pull the task on next cycle (5-10 min)
 2. Validate schema & command whitelist
 3. Execute the GPU workload
@@ -64,12 +83,12 @@ Ralph on DevBox will:
 
 ### For Task Executors (DevBox, Azure VMs)
 
-Ralph automatically watches `.squad/cross-machine/tasks/` for work targeted at this machine.
+In this proposal (not implemented), Ralph would watch `.squad/cross-machine/tasks/` for work targeted at this machine. Ralph does not do this today.
 
-**On each cycle (5-10 min):**
+**On each cycle (5-10 min), as proposed:**
 
 ```python
-# Pseudo-code (Ralph implementation)
+# Pseudo-code (proposed Ralph implementation; does not exist)
 1. git pull origin main
 2. Load all .yaml files in .squad/cross-machine/tasks/
 3. Filter for status=pending AND target_machine=HOSTNAME
@@ -96,7 +115,7 @@ gh issue create \
   --label "urgent"
 ```
 
-Ralph on DevBox will:
+In this proposal (not implemented), Ralph on DevBox would:
 1. Detect issue with `squad:machine-devbox` label
 2. Parse task from issue body
 3. Execute task
@@ -204,7 +223,7 @@ All tasks go through:
 
 ## Configuration
 
-Ralph reads config from `.squad/config.json`:
+Proposed `.squad/config.json` block. No Squad release reads it:
 
 ```json
 {
@@ -387,10 +406,10 @@ tail -f .squad/log/ralph-watch.log | grep "cross-machine"
 
 ## Integration with Ralph Watch
 
-Ralph automatically includes this pattern in its watch loop:
+Not implemented: `squad watch` does not include this pattern. The proposed watch loop was:
 
 ```
-Ralph Watch Cycle (every 5-10 min):
+Proposed Ralph Watch Cycle (every 5-10 min):
 1. Fetch GitHub issues with squad:machine-* labels
 2. Poll .squad/cross-machine/tasks/
 3. For each matching task:
@@ -402,7 +421,7 @@ Ralph Watch Cycle (every 5-10 min):
 5. Sleep until next cycle
 ```
 
-No manual Ralph configuration needed — just create task files or issues with the right labels.
+Until this is built, task files and `squad:machine-*` labels do nothing. To stop several watchers from picking the same issue, use work claims (`--claims git-ref`, ADR-002).
 
 ---
 
@@ -414,7 +433,7 @@ No manual Ralph configuration needed — just create task files or issues with t
 - user copies output back
 - user pastes result manually
 
-**After (with this pattern):**
+**After (if this proposal is built):**
 - Laptop Ralph writes task file → git push
 - DevBox Ralph auto-executes → git push result
 - Laptop Ralph auto-reads result
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@bradygaster/squad-cli': patch
 +---
++
 +`squad watch` work-claim telemetry (ADR-002). With an excluding claim provider (`git-ref`), each round report adds a compact line such as `🔒 Claims (git-ref): won 2 · contended 1 · released 2 (completed 2)` when any claim counter is non-zero: acquired, contended (held elsewhere), unavailable, fenced, lost (not renewed before expiry), released by outcome (completed / cancelled / abandoned), and implausible-record takeovers. `squad watch --health` shows the totals since startup from the watch PID file, and the counters are emitted as OpenTelemetry counters `squad.watch.claims.*` (attributes `claim.provider`, `claim.outcome`) when `OTEL_EXPORTER_OTLP_ENDPOINT` or `SQUAD_TELEMETRY=1` is set. No issue numbers, hostnames, or actors are recorded. With `none`, watch output is unchanged.