@rallycry/conveyor-skills 1.0.11 → 1.0.13

package/skills/conveyor-build/SKILL.md

@@ -102,6 +102,12 @@ task binding and no user account.
   stack) is the entire value of local execution, and worktrees have none of it.
   A dirty `git status` before any branch switch is a hard stop: report and let
   the user commit or stash. Do not solve it with a second checkout.
+- **Take turns on the checkout.** Another local session can share this
+  checkout, and a clean tree does not prove it is idle. Hold the checkout
+  claim from before the card claim until the finish line, and never switch
+  branches while another session holds it — the protocol, commands, and what
+  each result means are in
+  [references/checkout-claim.md](references/checkout-claim.md). A pod skips it.
 - The dev database and dev-server ports are shared with the user's own
   sessions. No destructive experiments, never reset the dev DB, and reuse a
   running dev stack rather than fighting over ports.
@@ -149,10 +155,13 @@ say why.
 
 ## Claim
 
-Re-confirm the card is still claimable, then `mcp__conveyor__update_task` →
+Re-confirm the card is still claimable. **Locally**, take the checkout claim
+first (`checkout acquire --card <slug>`,
+[references/checkout-claim.md](references/checkout-claim.md)); `held` means
+flag and wait, not claim. Then `mcp__conveyor__update_task` →
 `status: "InProgress"`, then `mcp__conveyor__post_to_chat` with a claim marker
 naming where you are running. Status changed under you → someone else took it;
-stop.
+release the checkout claim and stop.
 
 **A pack parent is claimed differently** — see the pack path. The parent stays
 parked and the chat marker IS the claim.
@@ -204,7 +213,14 @@ runner: the pod can sleep mid-run and nothing will wake you.
 **A UI-visible change needs visual proof before the PR**, in both environments:
 capture a screenshot (static) or a short recording (interaction) with the host
 repo's own tooling and attach it with `mcp__conveyor__upload_attachment`, then
-embed the returned URL in the PR body. A UI PR without it is incomplete.
+embed the returned URL in the PR body. A UI PR without it is incomplete. Pass
+`showcase: true` for the capture that shows the finished result (the after
+shot, the final recording); leave it off for before shots and scoping captures.
+Showcase files post to chat, render first on the card, and land in the PR body
+under `## Showcase`. A re-capture of something already on the card (a new cut
+of the same recording) passes `supersedes: "<old fileId>"` from
+`list_task_files`: the new file takes the old one's star and tags, and the old
+one collapses under it as history instead of showing twice.
 
 **Manual tests are for human eyes, and few.** Before the PR, record with
 `mcp__conveyor__set_manual_tests` only what a person must see in the running
@@ -262,10 +278,12 @@ Instead: post the answer, config, or findings with
 `mcp__conveyor__upload_attachment` (any file type, up to 25MB), and complete
 the card directly with `force_update_task_status("Complete")` — there is no PR
 or review step for a no-code task. Never publish a deliverable as an off-card
-link; the card is where it belongs. When a revision supersedes an earlier
-upload, remove the old copy with `mcp__conveyor__delete_attachment` (permanent,
-`fileId` from `list_task_files`) so the Files list shows one current version
-of each deliverable.
+link; the card is where it belongs. When a revision replaces an earlier
+upload, upload it with `supersedes: "<old fileId>"` (the id from
+`list_task_files`) so the card shows one current version of each deliverable
+with the history collapsed under it. Reach for
+`mcp__conveyor__delete_attachment` (permanent) only for a copy that should not
+survive at all.
 
 When unsure, check the diff: a real diff means open a PR, no diff means finish
 in chat and mark it Complete.
@@ -276,7 +294,10 @@ Refresh against the card's base first, then gate, then open — in that order, s
 nothing invalidates the verification you just did:
 
 1. `git fetch origin <base> && git merge origin/<base> --no-edit`
-2. One verification pass, scoped to the diff.
+2. One verification pass, scoped to the diff. **Locally**, run
+   `checkout verify --card <slug>` before the pass, each commit and push, and
+   the PR call; anything but `ok` means stop (see
+   [references/checkout-claim.md](references/checkout-claim.md)).
 3. `mcp__conveyor__create_pull_request`, naming the base branch **explicitly**.
    **The two surfaces spell these differently and unknown keys are silently
    dropped, not rejected** — locally it is `head:` / `base:`; in a pod it is
@@ -289,6 +310,8 @@ nothing invalidates the verification you just did:
    should look at, and anything you did NOT do.
 
 Then confirm CI actually started (read-only `gh pr checks`). Do not wait on it.
+**Locally**, that is the finish line for the checkout too:
+`checkout release --card <slug>`.
 
 **Do not re-merge the base and do not re-run a gate that already passed.** If
 the base moved while the gates ran, open the PR anyway — CI validates against
@@ -323,8 +346,9 @@ After two genuinely different failed approaches, or on a decision only the user
 can make: post the reason AND the specific question to chat, set the card back
 to `"Open"`, restore the tree (locally, `git checkout dev` — leaving a shared
 checkout parked on an abandoned feature branch is how the next session starts
-from the wrong base), and stop. A vague "this is hard" is not a handoff; the
-question is what makes it one.
+from the wrong base), release the checkout claim locally
+(`checkout release --card <slug>`), and stop. A vague "this is hard" is not a
+handoff; the question is what makes it one.
 
 **A thin plan is a different case, and it does not stop a pack.** A card whose
 plan fails the context-free-reader bar: post what is missing to its chat and

package/skills/conveyor-build/references/checkout-claim.md

@@ -0,0 +1,98 @@
+# Checkout claim — local sessions take turns on one checkout
+
+The protocol behind every "hold the checkout claim" line in
+[conveyor-build](../SKILL.md), its [task path](task-path.md) and
+[pack path](pack-path.md), [conveyor-local-loop](../../conveyor-local-loop/SKILL.md),
+and local fixes in [conveyor-review](../../conveyor-review/SKILL.md).
+
+**Why.** The card claim (`InProgress` plus a chat marker) stops two sessions
+working ONE card. It does nothing about two sessions working two cards in ONE
+checkout. A clean tree passes the "dirty `git status` → stop" rule even while
+another session is mid-task, so `git checkout -B <branch>` succeeds and switches
+the branch underneath it. The checkout claim closes that gap: one session holds
+the working tree at a time, and every other session waits.
+
+**Scope: local only.** A pod has its own checkout and never runs this. Skip
+every checkout-claim step when you are in a pod.
+
+## How to call it
+
+The helper is the `checkout` subcommand of the `conveyor-skills` bin. Pick the
+form once per session:
+
+```bash
+[ -x node_modules/.bin/conveyor-skills ] && echo local || echo npx
+```
+
+- `local` → `node_modules/.bin/conveyor-skills checkout <command> …`
+- `npx` → `npx -y -p @rallycry/conveyor-skills@latest conveyor-skills checkout <command> …`
+- The local bin answers `unknown command 'checkout'` (an older branch or an old
+  install) → use the `npx` form.
+
+Write the chosen form out literally in every call. Never store it in a shell
+variable and run `$VAR checkout …`: zsh does not word-split it.
+
+`--card` is the card you are working. Inside a pack it is ALWAYS the pack
+parent's slug, for the whole run. Identity comes from `CONVEYOR_SESSION_ID`, then
+`CLAUDE_CODE_SESSION_ID`. A runtime that sets neither passes a stable
+`--session <id>` on every call; without it the identity falls back to
+`card:<slug>`, which still works but frees a dead holder only after the TTL.
+
+The claim is one file, `<git dir>/conveyor-checkout-claim.json`. It is never
+committed and never shows in `git status`. Each command prints ONE line of
+JSON on stdout (`{"command","state","head","dirty",…}`) and a hint on stderr.
+
+## When
+
+| Moment | Command |
+| --- | --- |
+| Before the first git write or card status write (before the claiming `update_task`) | `acquire --card <slug>` |
+| After every branch create or switch | `acquire --card <slug> --branch <branch>` |
+| Before each gate, commit, push, and `create_pull_request`; at the start of every wake while you hold the claim | `verify --card <slug>` (also refreshes the heartbeat) |
+| Finish line reached (PR open, CI started), parked, blocked, or the card claim lost — after restoring the tree | `release --card <slug>` |
+
+## What each result means
+
+| Command | State (exit) | Do this |
+| --- | --- | --- |
+| `acquire` | `acquired`, `refreshed` (0) | Carry on. |
+| `acquire` | `took-over` (0) | The previous holder was dead or stale. If `dirty` is true, the tree holds that claim's unfinished work for THIS card: audit it before you continue. |
+| `acquire` | `held` (3) | Another session holds the checkout. Touch nothing — no checkout, no status write, no commit. Flag it (below), then wait. |
+| `acquire` | `dirty` (5) | The tree is dirty and no live claim covers it. Hard stop: report it. The user commits or stashes, never you. |
+| `verify` | `ok` (0) | Carry on. |
+| `verify` | `branch-moved` (4) | HEAD is not the claimed branch — someone switched it, or your own checkout failed and left you on the previous branch. Do not commit or push. Report it and stop. |
+| `verify` | `lost` (3) | You no longer hold the claim. Stop touching the tree and `acquire` again, then follow that result. |
+| `release` | `released`, `none` (0) | Done. |
+| `release` | `held` (3) | The claim is not yours. Leave it. |
+| any | `error` (1) | Usage error or not a git repo. Read the stderr line. |
+
+**Flag, then wait.** On `held`, tell the user which card, branch and host hold
+the checkout (the `holder` field has all three). A standalone build also posts
+one line to its card's chat, for example
+`[build] waiting — checkout held by <card> on <branch>`. Then wait:
+
+```bash
+node_modules/.bin/conveyor-skills checkout wait --timeout 1740   # or the npx form
+```
+
+In Claude Code, launch it with Bash `run_in_background: true` and end the
+turn. Its completion notification is the wake. In Codex, hold the command
+session open until it returns. The result is advisory, like `conveyor-wait`:
+`free`, `stale`, or `own` → run `acquire` again; `timeout` → arm ONE new wait.
+Never arm a second wait while one is running.
+
+## Rules that go with the claim
+
+- **Stage by path, never `git add -A`.** In a shared checkout an untracked file
+  can belong to another session.
+- **No claim, dirty tree → refuse.** `acquire` enforces the old "dirty tree is
+  a hard stop" rule deterministically. It also covers ad-hoc sessions that
+  never take a claim.
+- **A stale claim is taken over only on a clean tree, or when it names the
+  same card.** A holder is stale when its pid is dead on this host, when the
+  same pid now runs a different session (a `/clear`), or when its heartbeat is
+  older than the TTL (7200s; `CONVEYOR_CHECKOUT_CLAIM_TTL_SECONDS` or `--ttl`
+  overrides it).
+- **Human override.** `checkout status` shows the holder and never changes
+  anything. `checkout release --force` drops someone else's claim, or a claim
+  file that does not parse. Run it only when the user tells you to.

package/skills/conveyor-build/references/pack-path.md

@@ -24,6 +24,13 @@ alternative is where pack incidents come from.
    IMMEDIATELY record it: `mcp__conveyor__update_task` with
    `githubBranch: <branch>`.
 
+   **Locally, take the checkout claim before any of this** —
+   `checkout acquire --card <parent-slug>` before you cut or check out the
+   pack branch, then `acquire --card <parent-slug> --branch <pack>` once you
+   are on it ([checkout-claim.md](checkout-claim.md)). The pack holds the
+   claim for the WHOLE run: `--card` stays the parent's slug through every
+   child, and `--branch` follows each child-branch and pack-branch switch.
+
    That write is load-bearing, not bookkeeping. Identification mints a
    competing `conveyor/*` branch name onto any branchless card it processes,
    and every pack-child merge handler keys on the card's recorded branch
@@ -121,6 +128,10 @@ state and is a no-op. This is NOT the "insurance wakeup" the pod prompt
 forbids: that rule is about a background job's own completion notification,
 which does fire. Nothing at all notifies a pack between children, so the
 heartbeat is the only guaranteed wake a Claude pack has. Do not delete it.
+Locally, every wake — heartbeat or not — starts with
+`checkout verify --card <parent-slug>` before it touches the tree, and a
+result other than `ok` stops the pack (see
+[checkout-claim.md](checkout-claim.md)).
 
 **Codex CLI.** There is no `ScheduleWakeup` and no `/loop`. The thread goal
 created per the SKILL.md *Goal and finish line* section is the continuation:
@@ -153,7 +164,10 @@ parent chat, skip that child, and take the next ready one.
 Then follow [task-path.md](task-path.md), with one substitution: the child
 branches from the **pack branch**, not `dev`, and its PR's base is the pack
 branch. Name that base explicitly — the default is `dev`, and the two surfaces
-spell the argument differently (`base:` locally, `baseBranch:` in a pod).
+spell the argument differently (`base:` locally, `baseBranch:` in a pod). The
+pack already holds the checkout claim, so the task path's claim steps become
+`acquire --card <parent-slug> --branch <child-branch>` after you cut the child
+branch, and there is no release at the child's finish line.
 
 > **Environment — a pod has no child branches and no child PRs.** Everything
 > above describes the LOCAL model, where each child gets its own branch and its
@@ -261,7 +275,8 @@ leave the branch pushed, and stop.
    `base:` `dev`. The parent moves to ReviewPR. Post the pack summary: what
    shipped per child, how it was verified, what reviewers should look at.
 4. Confirm CI started. **Never approve or merge this PR** — it is the one that
-   gets independent review.
+   gets independent review. Locally, release the checkout:
+   `checkout release --card <parent-slug>`.
 
 ## Parked protocol
 
@@ -269,4 +284,6 @@ After two genuinely different failed approaches on a child, or a decision only
 the user can make: post the reason and the specific question to the child AND
 parent chats, set the child back to `Open`, restore the tree, and take the next
 child whose dependency chain does not run through the parked one. Everything
-remaining blocked → report and stop; the user's reply is the un-park signal.
+remaining blocked → restore the tree, release the checkout claim locally
+(`checkout release --card <parent-slug>`), report, and stop; the user's reply
+is the un-park signal, and the resumed run acquires again.

package/skills/conveyor-build/references/task-path.md

@@ -13,11 +13,14 @@ Re-confirm via `mcp__conveyor__get_task` that the card is still claimable —
 `Open` (or whatever status the user explicitly overrode), no assignee you do
 not expect, no active session. Then:
 
-1. `mcp__conveyor__update_task` → `status: "InProgress"`
-2. `mcp__conveyor__post_to_chat` → `[build] claimed — <where you are running>`
+1. **Locally only:** `checkout acquire --card <slug>` — the checkout claim from
+   [checkout-claim.md](checkout-claim.md). `held` → touch nothing, flag it, and
+   wait; `dirty` → hard stop. A pod skips this step.
+2. `mcp__conveyor__update_task` → `status: "InProgress"`
+3. `mcp__conveyor__post_to_chat` → `[build] claimed — <where you are running>`
 
 If the status changed under you between the read and the write, someone else
-took it. Stop rather than compete.
+took it. Release the checkout claim and stop rather than compete.
 
 ## 2. Branch from the card's base — never blindly `dev`
 
@@ -29,6 +32,10 @@ git fetch origin <base>
 git checkout -B <feat|fix|chore>/<slug> origin/<base>
 ```
 
+Locally, record the branch on the checkout claim straight after the checkout:
+`checkout acquire --card <slug> --branch <feat|fix|chore>/<slug>`. Do the
+same after any later branch switch.
+
 Two cases that are not a fresh branch:
 
 - **The card already has a `githubBranch` with commits on origin.** Resume THAT
@@ -39,7 +46,8 @@ Two cases that are not a fresh branch:
   absent even though the branch exists on the remote. Fetch it explicitly
   (`git fetch origin <branch>`) rather than concluding the branch is missing —
   and note that a failed `checkout` leaves you on your PREVIOUS branch, where a
-  follow-up `git push` will push the wrong thing.
+  follow-up `git push` will push the wrong thing. Locally, `checkout verify`
+  reports exactly that as `branch-moved`.
 
 Reinstall dependencies if the lockfile changed.
 
@@ -62,6 +70,8 @@ Chat at milestones, not per step.
 These are identical to the SKILL.md sections of the same names. In particular:
 sync the base BEFORE the verification pass, pass `base:` explicitly to
 `mcp__conveyor__create_pull_request`, and confirm CI started without waiting on
-it.
+it. Locally, `checkout verify --card <slug>` before the gate, each commit and
+push, and the PR call.
 
 Finish line: the card in ReviewPR with CI started. You do not merge it.
+Locally, `checkout release --card <slug>` once CI has started.

package/skills/conveyor-local-loop/SKILL.md

@@ -47,12 +47,27 @@ adds only selection, claiming, cadence, and local-machine hygiene.
   Clean tree before any branch switch is still a hard rule: dirty
   `git status` at iteration start → touch nothing, report, and idle — the
   resolution is the user committing or stashing, not a second checkout.
+- **Hold the checkout claim while you use the tree.** WIP = 1 is per loop,
+  not per checkout: two loops, or a loop plus an interactive session, can
+  share this checkout, and a clean tree does not prove it is idle. Every tier
+  that touches git takes the claim first and gives it back at the finish line —
+  protocol in [conveyor-build's checkout-claim reference](../conveyor-build/references/checkout-claim.md).
 - **Push early.** There is no pod WIP-autosync locally; committed-and-pushed is
   the only durable state. Push the branch (`-u origin`) as soon as it exists.
 
 ## Iteration order
 
-Each invocation does the FIRST of these that produces work, then paces:
+Each invocation does the FIRST of these that produces work, then paces.
+
+**Checkout first.** Start every iteration with `checkout status`. `live` or
+`corrupt` means another session holds this checkout: skip Recover, Babysit
+fixes, and Claim (all three touch the tree), arm ONE background
+`checkout wait` (see *Waking on board events*), and pace. Otherwise, each tier
+below runs `checkout acquire --card <slug>` for its card before its first git
+command or status write; `held` → stop that tier and arm the wait. The chat
+marker names only the host, so a second loop on this host also matches
+"my" marker in Recover — the checkout claim is what keeps it off a card another
+live loop is still working.
 
 1. **Recover** — a card with my `[local-loop] claimed` chat marker still
    InProgress without a PR? Resume it. The branch may already exist locally or
@@ -89,13 +104,14 @@ Each invocation does the FIRST of these that produces work, then paces:
    Skip `followParentStatus` mirror children. A blocker counts as met only
    when merged-or-beyond (ReviewDev/ReviewLive/Complete) or Cancelled — a
    blocker sitting in ReviewPR is NOT met until its PR merges.
-2. Claim: re-confirm via `get_task` it is still Open, then
-   `mcp__conveyor__update_task` → `status: "InProgress"`, then
+2. Claim: re-confirm via `get_task` it is still Open, take the checkout claim
+   (`checkout acquire --card <slug>`; `held` → do not claim, arm the wait),
+   then `mcp__conveyor__update_task` → `status: "InProgress"`, then
    `mcp__conveyor__post_to_chat`: `[local-loop] claimed — working locally on
    <hostname>`. Claiming a PACK is different — never set the parent
    InProgress: leave it Open and post the pack claim marker instead (see Pack
-   mode). Status changed under you → someone else took it; next
-   candidate.
+   mode). Status changed under you → someone else took it; release the
+   checkout claim and take the next candidate.
 3. Plan missing or failing the context-free-reader bar → don't wing it: post
    what's missing to chat, leave the card Open, skip it.
 
@@ -115,15 +131,18 @@ This section adds only what the LOOP changes:
   re-check the parent's status; if it went InProgress or ReviewPR, post
   `[local-loop] parked: pack coordinator active — yielding`, leave the branch
   pushed, and let the coordinator take over.
-- **Do not wait on CI.** Confirm it started (read-only `gh pr checks`) and end
-  the iteration — the Babysit tier owns it from there. This is the loop's one
-  real departure from a standalone build, which stays with its PR.
+- **Do not wait on CI.** Confirm it started (read-only `gh pr checks`),
+  `checkout release --card <slug>`, and end the iteration — the Babysit tier
+  owns it from there. This is the loop's one real departure from a standalone
+  build, which stays with its PR. A Babysit fix re-acquires with that card and
+  releases again once the fix is pushed. A pack child's PR is the exception:
+  the pack keeps the claim until its finale PR opens.
 
 **Parked protocol** — after 2 genuinely different failed approaches, or on a
 decision only the user can make: post `[local-loop] parked: <reason + the
 specific question>`, set status back to `"Open"`, restore the tree
-(`git checkout dev`), move on. The user's next chat reply is the un-park
-signal.
+(`git checkout dev`), `checkout release --card <slug>`, move on. The user's
+next chat reply is the un-park signal.
 
 ## Pack mode
 
@@ -136,9 +155,9 @@ dev→pack sync after every merge, cross-reference, then the finale parent PR
 into dev. That reference is the source of truth for the procedure; this section
 only defines how it embeds in the loop:
 
-- The pack occupies the loop's single WIP slot from claim until the finale PR
-  opens. Do not interleave unrelated cards mid-pack — that thrashes branch
-  state.
+- The pack occupies the loop's single WIP slot — and holds the checkout
+  claim under the parent's slug — from claim until the finale PR opens. Do not
+  interleave unrelated cards mid-pack — that thrashes branch state.
 - Claim marker goes to the PARENT chat: `[local-loop] claimed — driving this
   pack locally on <hostname>, pack branch <branch>`. The parent's status
   stays Open (parked); the marker is the claim.
@@ -208,9 +227,12 @@ On wake, run a normal iteration and re-enumerate with
 `mcp__conveyor__list_tasks`. By then the card may be claimed, cancelled, or
 blocked by a dependency — never claim straight from the wait payload.
 
-**Never arm a second wait.** On a wake where a wait process is still in flight
-and the queue is still empty, re-arm the fallback `ScheduleWakeup` and end the
-turn.
+**Never arm a second wait.** At most ONE background wait of either kind —
+`conveyor-wait` or `checkout wait` — runs at a time. On a wake where a wait
+process is still in flight and nothing else changed, re-arm the fallback
+`ScheduleWakeup` and end the turn. When the checkout is held, the
+`checkout wait` is the one to arm: the board wait cannot tell you when the
+checkout frees up.
 
 ## Pacing (dynamic /loop only)
 
@@ -219,7 +241,7 @@ Under `/loop` with no interval, end EVERY iteration with exactly one
 
 | State | Delay | Reason should say |
 |-------|-------|-------------------|
-| A background gate/agent/conveyor-wait is in flight — its completion notification is the real wake | 1200–1800s fallback | "fallback while <gate> runs — its notification wakes me sooner" |
+| A background gate/agent/conveyor-wait/checkout wait is in flight — its completion notification is the real wake | 1200–1800s fallback | "fallback while <gate> runs — its notification wakes me sooner" |
 | ANY actionable work exists: claimable cards or packs, a pack child to implement/merge, a PR still to open, red/pending CI, review comments | 60–90s | queue depth / which item is next |
 | Queue enumerated as empty THIS iteration, all loop PRs green and quiet | 1200–1800s | queue empty; conveyor-wait armed, so this is only the fallback |
 | Loop-fatal: MCP dead after 2 tries, dirty tree, broken repo | notify the user (PushNotification if available), then 1800s — or `stop: true` if continuing is unsafe | what is wrong |
@@ -249,7 +271,8 @@ depth each iteration so the user can offload manually.
 - Not a pod: no sandbox, no WIP snapshots, and the dev DB + dev-server ports
   are shared with the user's interactive sessions — no destructive
   experiments, never reset the dev DB, reuse a running dev stack rather than
-  fighting over ports.
+  fighting over ports. The git checkout is shared the same way, which is why
+  the loop takes turns on it through the checkout claim.
 - Not a parallel executor: one card (or one pack) at a time is the point (the
   full machine per gate). Backlogged? That is what claudespaces — or the
   offload valve — are for.