@ikon85/agent-workflow-kit 0.34.1 → 0.34.3

package/.agents/skills/diagnose/SKILL.md

@@ -11,6 +11,41 @@ A discipline for hard bugs. Skip phases only when explicitly justified.
 
 When exploring the codebase, read `CONTEXT.md` (if it exists) to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
 
+## Phase 0 — Claim the tracked issue
+
+Applies only when the bug arrives as a tracked issue. A bug reported in chat has
+nothing to claim; go straight to Phase 1.
+
+<!-- issue-claim:start -->
+**Claim the issue before you build.** A worktree, branch, or PR check only sees
+this machine, and only once someone has pushed — the claim on the issue itself
+is the only signal a second session, a second machine, or a cloud agent can
+read.
+
+1. **Check first.** Read the issue's assignee and its claim comments. An
+   `<!-- agent-claim: ... -->` marker you did not plant, or an assignee that is
+   not you, is a **foreign claim**: **STOP**, report the claimed branch and
+   worktree, and ask the user how to proceed. Take the issue over only on their
+   word, and never delete a foreign claim. A claim whose branch and worktree no
+   longer exist is stale — say that and let the user decide; do not assume it is
+   dead.
+2. **Plant your claim, before the first edit.** Assign the issue to yourself
+   where the tracker supports it, and post the claim marker as a comment:
+   `<!-- agent-claim: branch=<branch>; worktree=<absolute-path>; date=<YYYY-MM-DD> -->`
+   Branch and worktree are the payload — without them a colliding session sees
+   the collision but cannot find the work in progress.
+3. **Release.** A PR that references the issue **supersedes** the claim, so
+   landing needs no extra step. If you abandon or hand back the work, remove
+   your own claim (unassign plus a one-line `claim released` comment) before you
+   stop.
+
+The concrete commands are your tracker's — `docs/agents/issue-tracker.md`,
+§Pickup claim. If that layer documents no claim convention, fall back to the two
+generic operations above: self-assign, plus the marker comment.
+<!-- issue-claim:end -->
+
+Building the Phase-1 loop is already work: claim before it, not after.
+
 ## Phase 1 — Build a feedback loop
 
 **This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug — one that goes red on _this_ bug — you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.

package/.agents/skills/implement/SKILL.md

@@ -6,6 +6,39 @@ disable-model-invocation: true
 
 Implement the work described by the user in the PRD or issues.
 
+## Pickup — claim the issue first
+
+Applies whenever the work comes from a tracked issue. Work handed over as plain
+text or a local plan has nothing to claim; skip this section then.
+
+<!-- issue-claim:start -->
+**Claim the issue before you build.** A worktree, branch, or PR check only sees
+this machine, and only once someone has pushed — the claim on the issue itself
+is the only signal a second session, a second machine, or a cloud agent can
+read.
+
+1. **Check first.** Read the issue's assignee and its claim comments. An
+   `<!-- agent-claim: ... -->` marker you did not plant, or an assignee that is
+   not you, is a **foreign claim**: **STOP**, report the claimed branch and
+   worktree, and ask the user how to proceed. Take the issue over only on their
+   word, and never delete a foreign claim. A claim whose branch and worktree no
+   longer exist is stale — say that and let the user decide; do not assume it is
+   dead.
+2. **Plant your claim, before the first edit.** Assign the issue to yourself
+   where the tracker supports it, and post the claim marker as a comment:
+   `<!-- agent-claim: branch=<branch>; worktree=<absolute-path>; date=<YYYY-MM-DD> -->`
+   Branch and worktree are the payload — without them a colliding session sees
+   the collision but cannot find the work in progress.
+3. **Release.** A PR that references the issue **supersedes** the claim, so
+   landing needs no extra step. If you abandon or hand back the work, remove
+   your own claim (unassign plus a one-line `claim released` comment) before you
+   stop.
+
+The concrete commands are your tracker's — `docs/agents/issue-tracker.md`,
+§Pickup claim. If that layer documents no claim convention, fall back to the two
+generic operations above: self-assign, plus the marker comment.
+<!-- issue-claim:end -->
+
 Use /tdd where possible, at pre-agreed seams.
 
 Run typechecking regularly, single test files regularly, and the full test suite once at the end.

package/.agents/skills/kit-release/SKILL.md

@@ -23,11 +23,20 @@ never publishes to a registry or creates a GitHub release directly.
    recommend Major, additions recommend Minor, and changed content recommends
    Patch.
 
-2. Ask the user to confirm exactly one target Semver. Do not change release
-   metadata before confirmation. A recommendation is advice; the confirmed
-   target is authority.
+2. Resolve authority for exactly one target Semver:
 
-3. Prepare that exact version:
+   - Normally, ask the user to confirm the target before changing release
+     metadata. A recommendation is advice; the confirmed target is authority.
+   - When the caller carries an **explicit AFK end-to-end mandate** whose scope
+     includes release preparation, accept the deterministic recommendation as
+     the target for **reversible metadata preparation** and record that choice.
+     Do not turn a narrower build-only or single-action request into this
+     authority.
+
+   Both routes authorize one prepared target only. Neither authorizes
+   publication.
+
+3. Prepare that authorized exact version:
 
    ```sh
    npm run release:prepare -- --version <confirmed-version>
@@ -45,8 +54,9 @@ never publishes to a registry or creates a GitHub release directly.
 
 5. After merge, report the exact integrated version and commit as
    `awaiting-tag`. Merging integrates the prepared release; it cannot start
-   publication. Ask the user for a second, explicit confirmation to publish
-   that exact `v<version>`. The earlier Semver confirmation authorized metadata
+   publication. Creating and pushing the annotated `v<version>` tag requires a
+   **separate explicit confirmation** to publish that exact version. The
+   earlier Semver confirmation or AFK preparation mandate authorized metadata
    preparation, not publication.
 
 6. After that confirmation, verify that the package version on current

package/.agents/skills/orchestrate-wave/SKILL.md

@@ -62,6 +62,16 @@ node scripts/readiness.mjs check --skill orchestrate-wave --json
   change — current gate, last green milestone, next step, visible blocker/risk. A
   still-running tool session is stated as such; never wait silently for the final
   result.
+- **Authorization scope is sticky and gates are local.** A single-Wave mandate
+  authorizes only that Wave. A later explicit whole-Program mandate authorizes all
+  planned Waves in that Program and overrides a default per-Wave authorization
+  sentence in the Program-PRD; record that scope once and **Do not re-ask at each
+  Wave boundary**. A manual or irreversible gate pauses only the gated action:
+  continue every dependency-safe reversible or read-only step inside the
+  authorized scope, including preparation for later Waves. A persistent goal
+  must not be marked `blocked` while meaningful authorized safe work remains
+  anywhere in that scope. None of this carries authorization into the gated
+  irreversible action itself.
 - **Degrade by subtraction, never by improvisation.** The defined failure paths:
   - **Slice stays red after escalation** (2-strikes rule, see Routing): pull the
     slice — do not merge it (or revert its merge), pull every dependent that
@@ -180,6 +190,14 @@ Before each slice, bind **(a) inline vs delegate** and **(b) tier + effort** und
 Standing rules. Tiny mechanical work may stay inline.
 For Path A/B, create one worktree per agent from wave HEAD, using `§Setup` or
 `git worktree add <path> -b feat/<anchor>-<slug>`.
+- **Claim each slice issue at builder launch — the wave claim is not a slice
+  claim.** It guards the anchor on this machine only; the slice issue is the
+  grabbable unit a second machine or cloud agent sees. Before dispatch, skip and
+  report any slice already carrying a foreign claim (assignee or
+  `<!-- agent-claim: ... -->` comment this run did not plant) — never overwrite
+  one. Otherwise assign it to yourself and post
+  `<!-- agent-claim: branch=<slice-branch>; worktree=<builder-worktree>; date=<YYYY-MM-DD> -->`
+  so the claim names the WIP. Commands: `docs/agents/issue-tracker.md`, §Pickup claim.
 - **Build the prompt from [`references/builder-contract.md`](references/builder-contract.md)**
   — fill the slots with the slice's VERBATIM What+AC, plan decision, recon
   file:line map and consume-only lines; never paraphrase (paraphrase drift has
@@ -190,7 +208,8 @@ For Path A/B, create one worktree per agent from wave HEAD, using `§Setup` or
 
 **Done when:** every dispatched slice reported back with commit SHA + green
 package tests + green fast gate (`§Builder Commands`) — or a STOP item you resolved
-(answered / re-dispatched) before integration.
+(answered / re-dispatched) before integration · every dispatched slice issue
+carries this run's claim, every foreign-claimed slice skipped and reported.
 
 ## Phase 3 — Serial integration
 
@@ -302,6 +321,9 @@ written · merge order documented.
   `wave-active/<anchor>`, call `releaseWaveClaim` with this run's owner after
   success or abort; its owner check, not a broad `wave-active/*` pattern,
   authorizes cleanup, and a foreign marker is left untouched.
+- **Release this run's slice claims.** A landed slice's PR supersedes its claim;
+  for a pulled or abandoned slice remove the claim this run planted (unassign +
+  `claim released` comment) so it stays grabbable. Foreign ones stay untouched.
 - **Before removing any slice worktree, read its `ANNAHMEN.md`** (an assumptions
   log, gitignored at worktree-root) and propagate each build-time assumption marker
   to the sibling issue it carries. A hand-driven multi-PR / migration landing does
@@ -331,7 +353,8 @@ written · merge order documented.
 - Leave slice worktrees for the user to inspect, or note they're
   post-merge-removable.
 
-**Done when:** no orphan process · this run's claim removed · ANNAHMEN propagated ·
+**Done when:** no orphan process · this run's wave claim removed · this run's
+unlanded slice claims released · ANNAHMEN propagated ·
 anchor reconciled + leaf closes verified · anchor closure decided and documented ·
 Program-PRD propagation completed or explicitly skipped · final report lists
 landed/pulled slices as **X of Y**.

package/.agents/skills/setup-workflow/issue-tracker-github.md

@@ -23,6 +23,17 @@ Create a GitHub issue.
 
 Run `gh issue view <number> --comments`.
 
+## Pickup claim
+
+Used by `/implement`, `/diagnose`, and `/orchestrate-wave`: the visible claim
+that keeps a second session, machine, or cloud agent off an issue already being
+built. The marker carries the WIP location, the assignee makes the claim visible
+in list views.
+
+- **Check** (before any edit): `gh issue view <n> --json assignees,comments --jq '{assignees: [.assignees[].login], claims: [.comments[].body | select(contains("<!-- agent-claim:"))]}'` — a foreign assignee or a marker this session did not plant is a foreign claim: stop and report it, never overwrite or delete it.
+- **Claim**: `gh issue edit <n> --add-assignee @me`, then post the marker as a comment — `gh issue comment <n> --body '<!-- agent-claim: branch=<branch>; worktree=<absolute-path>; date=<YYYY-MM-DD> -->'`.
+- **Release**: a PR referencing the issue supersedes the claim — no extra step when the work lands. On abandon: `gh issue edit <n> --remove-assignee @me` plus `gh issue comment <n> --body "claim released"`.
+
 ## Wayfinding operations
 
 Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.

package/.agents/skills/setup-workflow/issue-tracker-gitlab.md

@@ -22,6 +22,17 @@ Create a GitLab issue.
 
 Run `glab issue view <number> --comments`.
 
+## Pickup claim
+
+Used by `/implement`, `/diagnose`, and `/orchestrate-wave`: the visible claim
+that keeps a second session, machine, or cloud agent off an issue already being
+built. The marker carries the WIP location, the assignee makes the claim visible
+in list views.
+
+- **Check** (before any edit): `glab issue view <n> --comments` (or `-F json`) — a foreign assignee, or an `<!-- agent-claim: ... -->` note this session did not plant, is a foreign claim: stop and report it, never overwrite or delete it.
+- **Claim**: `glab issue update <n> --assignee @me`, then post the marker as a note — `glab issue note <n> --message '<!-- agent-claim: branch=<branch>; worktree=<absolute-path>; date=<YYYY-MM-DD> -->'`.
+- **Release**: a merge request referencing the issue supersedes the claim — no extra step when the work lands. On abandon, drop yourself with the `/unassign @<your-user>` quick action (`glab issue note <n> --message "/unassign @<your-user>"`) and post a `claim released` note.
+
 ## Wayfinding operations
 
 Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.

package/.agents/skills/setup-workflow/issue-tracker-local.md

@@ -18,6 +18,17 @@ Create a new file under `.scratch/<feature-slug>/` (creating the directory if ne
 
 Read the file at the referenced path. The user will normally pass the path or the issue number directly.
 
+## Pickup claim
+
+Used by `/implement`, `/diagnose`, and `/orchestrate-wave`: the visible claim
+that keeps a second session, machine, or cloud agent off an issue already being
+built. There is no assignee field here, so the marker line carries the whole
+claim — commit it, otherwise no other checkout can see it.
+
+- **Check** (before any edit): read the issue file and grep it for `<!-- agent-claim:`. A marker this session did not plant is a foreign claim: stop and report it, never overwrite or delete it.
+- **Claim**: set `Status: claimed` and add one marker line directly under it — `<!-- agent-claim: branch=<branch>; worktree=<absolute-path>; date=<YYYY-MM-DD> -->` — then commit and push the issue file so other checkouts see the claim.
+- **Release**: a PR referencing the issue supersedes the claim. On abandon, delete your own marker line, reset `Status:` to its pre-pickup role, and commit.
+
 ## Wayfinding operations
 
 Used by `/wayfinder`. The **map** is a file with one **child** file per ticket.

package/.claude/skills/diagnose/SKILL.md

@@ -11,6 +11,41 @@ A discipline for hard bugs. Skip phases only when explicitly justified.
 
 When exploring the codebase, read `CONTEXT.md` (if it exists) to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
 
+## Phase 0 — Claim the tracked issue
+
+Applies only when the bug arrives as a tracked issue. A bug reported in chat has
+nothing to claim; go straight to Phase 1.
+
+<!-- issue-claim:start -->
+**Claim the issue before you build.** A worktree, branch, or PR check only sees
+this machine, and only once someone has pushed — the claim on the issue itself
+is the only signal a second session, a second machine, or a cloud agent can
+read.
+
+1. **Check first.** Read the issue's assignee and its claim comments. An
+   `<!-- agent-claim: ... -->` marker you did not plant, or an assignee that is
+   not you, is a **foreign claim**: **STOP**, report the claimed branch and
+   worktree, and ask the user how to proceed. Take the issue over only on their
+   word, and never delete a foreign claim. A claim whose branch and worktree no
+   longer exist is stale — say that and let the user decide; do not assume it is
+   dead.
+2. **Plant your claim, before the first edit.** Assign the issue to yourself
+   where the tracker supports it, and post the claim marker as a comment:
+   `<!-- agent-claim: branch=<branch>; worktree=<absolute-path>; date=<YYYY-MM-DD> -->`
+   Branch and worktree are the payload — without them a colliding session sees
+   the collision but cannot find the work in progress.
+3. **Release.** A PR that references the issue **supersedes** the claim, so
+   landing needs no extra step. If you abandon or hand back the work, remove
+   your own claim (unassign plus a one-line `claim released` comment) before you
+   stop.
+
+The concrete commands are your tracker's — `docs/agents/issue-tracker.md`,
+§Pickup claim. If that layer documents no claim convention, fall back to the two
+generic operations above: self-assign, plus the marker comment.
+<!-- issue-claim:end -->
+
+Building the Phase-1 loop is already work: claim before it, not after.
+
 ## Phase 1 — Build a feedback loop
 
 **This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug — one that goes red on _this_ bug — you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.

package/.claude/skills/implement/SKILL.md

@@ -6,6 +6,39 @@ disable-model-invocation: true
 
 Implement the work described by the user in the PRD or issues.
 
+## Pickup — claim the issue first
+
+Applies whenever the work comes from a tracked issue. Work handed over as plain
+text or a local plan has nothing to claim; skip this section then.
+
+<!-- issue-claim:start -->
+**Claim the issue before you build.** A worktree, branch, or PR check only sees
+this machine, and only once someone has pushed — the claim on the issue itself
+is the only signal a second session, a second machine, or a cloud agent can
+read.
+
+1. **Check first.** Read the issue's assignee and its claim comments. An
+   `<!-- agent-claim: ... -->` marker you did not plant, or an assignee that is
+   not you, is a **foreign claim**: **STOP**, report the claimed branch and
+   worktree, and ask the user how to proceed. Take the issue over only on their
+   word, and never delete a foreign claim. A claim whose branch and worktree no
+   longer exist is stale — say that and let the user decide; do not assume it is
+   dead.
+2. **Plant your claim, before the first edit.** Assign the issue to yourself
+   where the tracker supports it, and post the claim marker as a comment:
+   `<!-- agent-claim: branch=<branch>; worktree=<absolute-path>; date=<YYYY-MM-DD> -->`
+   Branch and worktree are the payload — without them a colliding session sees
+   the collision but cannot find the work in progress.
+3. **Release.** A PR that references the issue **supersedes** the claim, so
+   landing needs no extra step. If you abandon or hand back the work, remove
+   your own claim (unassign plus a one-line `claim released` comment) before you
+   stop.
+
+The concrete commands are your tracker's — `docs/agents/issue-tracker.md`,
+§Pickup claim. If that layer documents no claim convention, fall back to the two
+generic operations above: self-assign, plus the marker comment.
+<!-- issue-claim:end -->
+
 Use /tdd where possible, at pre-agreed seams.
 
 Run typechecking regularly, single test files regularly, and the full test suite once at the end.

package/.claude/skills/kit-release/SKILL.md

@@ -23,11 +23,20 @@ never publishes to a registry or creates a GitHub release directly.
    recommend Major, additions recommend Minor, and changed content recommends
    Patch.
 
-2. Ask the user to confirm exactly one target Semver. Do not change release
-   metadata before confirmation. A recommendation is advice; the confirmed
-   target is authority.
+2. Resolve authority for exactly one target Semver:
 
-3. Prepare that exact version:
+   - Normally, ask the user to confirm the target before changing release
+     metadata. A recommendation is advice; the confirmed target is authority.
+   - When the caller carries an **explicit AFK end-to-end mandate** whose scope
+     includes release preparation, accept the deterministic recommendation as
+     the target for **reversible metadata preparation** and record that choice.
+     Do not turn a narrower build-only or single-action request into this
+     authority.
+
+   Both routes authorize one prepared target only. Neither authorizes
+   publication.
+
+3. Prepare that authorized exact version:
 
    ```sh
    npm run release:prepare -- --version <confirmed-version>
@@ -45,8 +54,9 @@ never publishes to a registry or creates a GitHub release directly.
 
 5. After merge, report the exact integrated version and commit as
    `awaiting-tag`. Merging integrates the prepared release; it cannot start
-   publication. Ask the user for a second, explicit confirmation to publish
-   that exact `v<version>`. The earlier Semver confirmation authorized metadata
+   publication. Creating and pushing the annotated `v<version>` tag requires a
+   **separate explicit confirmation** to publish that exact version. The
+   earlier Semver confirmation or AFK preparation mandate authorized metadata
    preparation, not publication.
 
 6. After that confirmation, verify that the package version on current

package/.claude/skills/orchestrate-wave/SKILL.md

@@ -70,6 +70,16 @@ node scripts/readiness.mjs check --skill orchestrate-wave --json
   change — current gate, last green milestone, next step, visible blocker/risk. A
   still-running tool session is stated as such; never wait silently for the final
   result.
+- **Authorization scope is sticky and gates are local.** A single-Wave mandate
+  authorizes only that Wave. A later explicit whole-Program mandate authorizes all
+  planned Waves in that Program and overrides a default per-Wave authorization
+  sentence in the Program-PRD; record that scope once and **Do not re-ask at each
+  Wave boundary**. A manual or irreversible gate pauses only the gated action:
+  continue every dependency-safe reversible or read-only step inside the
+  authorized scope, including preparation for later Waves. A persistent goal
+  must not be marked `blocked` while meaningful authorized safe work remains
+  anywhere in that scope. None of this carries authorization into the gated
+  irreversible action itself.
 - **Degrade by subtraction, never by improvisation.** The defined failure paths:
   - **Slice stays red after escalation** (2-strikes rule, see Routing): pull the
     slice — do not merge it (or revert its merge), pull every dependent that
@@ -188,6 +198,14 @@ Before each slice, bind **(a) inline vs delegate** and **(b) tier + effort** und
 Standing rules. Tiny mechanical work may stay inline.
 For Path A/B, create one worktree per agent from wave HEAD, using `§Setup` or
 `git worktree add <path> -b feat/<anchor>-<slug>`.
+- **Claim each slice issue at builder launch — the wave claim is not a slice
+  claim.** It guards the anchor on this machine only; the slice issue is the
+  grabbable unit a second machine or cloud agent sees. Before dispatch, skip and
+  report any slice already carrying a foreign claim (assignee or
+  `<!-- agent-claim: ... -->` comment this run did not plant) — never overwrite
+  one. Otherwise assign it to yourself and post
+  `<!-- agent-claim: branch=<slice-branch>; worktree=<builder-worktree>; date=<YYYY-MM-DD> -->`
+  so the claim names the WIP. Commands: `docs/agents/issue-tracker.md`, §Pickup claim.
 - **Build the prompt from [`references/builder-contract.md`](references/builder-contract.md)**
   — fill the slots with the slice's VERBATIM What+AC, plan decision, recon
   file:line map and consume-only lines; never paraphrase (paraphrase drift has
@@ -198,7 +216,8 @@ For Path A/B, create one worktree per agent from wave HEAD, using `§Setup` or
 
 **Done when:** every dispatched slice reported back with commit SHA + green
 package tests + green fast gate (`§Builder Commands`) — or a STOP item you resolved
-(answered / re-dispatched) before integration.
+(answered / re-dispatched) before integration · every dispatched slice issue
+carries this run's claim, every foreign-claimed slice skipped and reported.
 
 ## Phase 3 — Serial integration
 
@@ -310,6 +329,9 @@ written · merge order documented.
   `wave-active/<anchor>`, call `releaseWaveClaim` with this run's owner after
   success or abort; its owner check, not a broad `wave-active/*` pattern,
   authorizes cleanup, and a foreign marker is left untouched.
+- **Release this run's slice claims.** A landed slice's PR supersedes its claim;
+  for a pulled or abandoned slice remove the claim this run planted (unassign +
+  `claim released` comment) so it stays grabbable. Foreign ones stay untouched.
 - **Before removing any slice worktree, read its `ANNAHMEN.md`** (an assumptions
   log, gitignored at worktree-root) and propagate each build-time assumption marker
   to the sibling issue it carries. A hand-driven multi-PR / migration landing does
@@ -339,7 +361,8 @@ written · merge order documented.
 - Leave slice worktrees for the user to inspect, or note they're
   post-merge-removable.
 
-**Done when:** no orphan process · this run's claim removed · ANNAHMEN propagated ·
+**Done when:** no orphan process · this run's wave claim removed · this run's
+unlanded slice claims released · ANNAHMEN propagated ·
 anchor reconciled + leaf closes verified · anchor closure decided and documented ·
 Program-PRD propagation completed or explicitly skipped · final report lists
 landed/pulled slices as **X of Y**.

package/.claude/skills/setup-workflow/issue-tracker-github.md

@@ -23,6 +23,17 @@ Create a GitHub issue.
 
 Run `gh issue view <number> --comments`.
 
+## Pickup claim
+
+Used by `/implement`, `/diagnose`, and `/orchestrate-wave`: the visible claim
+that keeps a second session, machine, or cloud agent off an issue already being
+built. The marker carries the WIP location, the assignee makes the claim visible
+in list views.
+
+- **Check** (before any edit): `gh issue view <n> --json assignees,comments --jq '{assignees: [.assignees[].login], claims: [.comments[].body | select(contains("<!-- agent-claim:"))]}'` — a foreign assignee or a marker this session did not plant is a foreign claim: stop and report it, never overwrite or delete it.
+- **Claim**: `gh issue edit <n> --add-assignee @me`, then post the marker as a comment — `gh issue comment <n> --body '<!-- agent-claim: branch=<branch>; worktree=<absolute-path>; date=<YYYY-MM-DD> -->'`.
+- **Release**: a PR referencing the issue supersedes the claim — no extra step when the work lands. On abandon: `gh issue edit <n> --remove-assignee @me` plus `gh issue comment <n> --body "claim released"`.
+
 ## Wayfinding operations
 
 Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.

package/.claude/skills/setup-workflow/issue-tracker-gitlab.md

@@ -22,6 +22,17 @@ Create a GitLab issue.
 
 Run `glab issue view <number> --comments`.
 
+## Pickup claim
+
+Used by `/implement`, `/diagnose`, and `/orchestrate-wave`: the visible claim
+that keeps a second session, machine, or cloud agent off an issue already being
+built. The marker carries the WIP location, the assignee makes the claim visible
+in list views.
+
+- **Check** (before any edit): `glab issue view <n> --comments` (or `-F json`) — a foreign assignee, or an `<!-- agent-claim: ... -->` note this session did not plant, is a foreign claim: stop and report it, never overwrite or delete it.
+- **Claim**: `glab issue update <n> --assignee @me`, then post the marker as a note — `glab issue note <n> --message '<!-- agent-claim: branch=<branch>; worktree=<absolute-path>; date=<YYYY-MM-DD> -->'`.
+- **Release**: a merge request referencing the issue supersedes the claim — no extra step when the work lands. On abandon, drop yourself with the `/unassign @<your-user>` quick action (`glab issue note <n> --message "/unassign @<your-user>"`) and post a `claim released` note.
+
 ## Wayfinding operations
 
 Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.

package/.claude/skills/setup-workflow/issue-tracker-local.md

@@ -18,6 +18,17 @@ Create a new file under `.scratch/<feature-slug>/` (creating the directory if ne
 
 Read the file at the referenced path. The user will normally pass the path or the issue number directly.
 
+## Pickup claim
+
+Used by `/implement`, `/diagnose`, and `/orchestrate-wave`: the visible claim
+that keeps a second session, machine, or cloud agent off an issue already being
+built. There is no assignee field here, so the marker line carries the whole
+claim — commit it, otherwise no other checkout can see it.
+
+- **Check** (before any edit): read the issue file and grep it for `<!-- agent-claim:`. A marker this session did not plant is a foreign claim: stop and report it, never overwrite or delete it.
+- **Claim**: set `Status: claimed` and add one marker line directly under it — `<!-- agent-claim: branch=<branch>; worktree=<absolute-path>; date=<YYYY-MM-DD> -->` — then commit and push the issue file so other checkouts see the claim.
+- **Release**: a PR referencing the issue supersedes the claim. On abandon, delete your own marker line, reset `Status:` to its pre-pickup role, and commit.
+
 ## Wayfinding operations
 
 Used by `/wayfinder`. The **map** is a file with one **child** file per ticket.

package/README.md

@@ -387,6 +387,28 @@ the old way. Decision record:
 
 ## Release notes
 
+### 0.34.3
+
+- changed: `.agents/skills/diagnose/SKILL.md`
+- changed: `.agents/skills/implement/SKILL.md`
+- changed: `.agents/skills/orchestrate-wave/SKILL.md`
+- changed: `.agents/skills/setup-workflow/issue-tracker-github.md`
+- changed: `.agents/skills/setup-workflow/issue-tracker-gitlab.md`
+- changed: `.agents/skills/setup-workflow/issue-tracker-local.md`
+- changed: `.claude/skills/diagnose/SKILL.md`
+- changed: `.claude/skills/implement/SKILL.md`
+- changed: `.claude/skills/orchestrate-wave/SKILL.md`
+- changed: `.claude/skills/setup-workflow/issue-tracker-github.md`
+- changed: `.claude/skills/setup-workflow/issue-tracker-gitlab.md`
+- changed: `.claude/skills/setup-workflow/issue-tracker-local.md`
+
+### 0.34.2
+
+- changed: `.agents/skills/kit-release/SKILL.md`
+- changed: `.agents/skills/orchestrate-wave/SKILL.md`
+- changed: `.claude/skills/kit-release/SKILL.md`
+- changed: `.claude/skills/orchestrate-wave/SKILL.md`
+
 ### 0.34.1
 
 - changed: `.agents/skills/kit-release/SKILL.md`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.34.1",
+  "kitVersion": "0.34.3",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -137,7 +137,7 @@
       "ownerSkill": "diagnose",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "38ae64634933b42a6fea8b480c1962fc494a2dc08d7b07b0ab9a114eaeaa631e",
+      "sha256": "8a6b1036968146beff15a03e03c7b0f7d71ab65a666201ee8e1588c484f32ce6",
       "mode": 420,
       "origin": "kit"
     },
@@ -267,7 +267,7 @@
       "ownerSkill": "implement",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "5b55552c4a0d90fe15c9ee44abce4498faa03b73e332024e30ab69c2b7065770",
+      "sha256": "dff8c4bd4a1cfd376bc5fdd9d97641301d61055fd9155bde50c1e9634a6015d2",
       "mode": 420,
       "origin": "kit"
     },
@@ -367,7 +367,7 @@
       "ownerSkill": "kit-release",
       "surface": "codex",
       "installRole": "maintainer",
-      "sha256": "168879858199f19f124e8bc3722f430f65b44b1fb6409d9c2112e6ec02d9b561",
+      "sha256": "7e08d5115d34f36da08491fa3bb8d5f4ca45e2908560e8f8c924cf3fd619d7f9",
       "mode": 420,
       "origin": "kit"
     },
@@ -447,7 +447,7 @@
       "ownerSkill": "orchestrate-wave",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "3a281805aee83a771675f8f80b9bd9dee3c1b2f2b2ca58001b37d8565a7d9d7d",
+      "sha256": "4c40d95e773649ba87e5010740180b66682a18cdf98ba7d8b7907397ea212ed0",
       "mode": 420,
       "origin": "kit"
     },
@@ -627,7 +627,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "5f5ceed4ec89d8eae8f1199d08b4948e9627eef7ce128e1858b208511c726e52",
+      "sha256": "6c896543b1a1a50ca3f591d63e364a3f0d624b8ae02ef93183e3665a27248d3c",
       "mode": 420,
       "origin": "kit"
     },
@@ -637,7 +637,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "7a72f72bc4c42401e6bfefb1253d87a2970b633d5f9e9bf975c5d486813cacd2",
+      "sha256": "be08d8e86f4573049c9cd809cde9417a334d364f3e823548bcd54136b1da4b01",
       "mode": 420,
       "origin": "kit"
     },
@@ -647,7 +647,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "e0dd9835e3658909132058e9a5fdd851e972220bbadaf78a57e3c6220d470922",
+      "sha256": "b4bf369b9c7791b9b9c76438aaa4cd9a07a0860fcc6bb9b52eebe12c6427ccbb",
       "mode": 420,
       "origin": "kit"
     },
@@ -1359,7 +1359,7 @@
       "ownerSkill": "diagnose",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "2cdcb0ff5699dfeda8f8f9f487a8290d97d44176ddb6942638f4a9a32ecbaaad",
+      "sha256": "44edd6a5af6429fd711ddbb3a4123b51a9c497573c147c2fc7b874e6e2a1336c",
       "mode": 420,
       "origin": "kit"
     },
@@ -1579,7 +1579,7 @@
       "ownerSkill": "implement",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "5b55552c4a0d90fe15c9ee44abce4498faa03b73e332024e30ab69c2b7065770",
+      "sha256": "dff8c4bd4a1cfd376bc5fdd9d97641301d61055fd9155bde50c1e9634a6015d2",
       "mode": 420,
       "origin": "kit"
     },
@@ -1679,7 +1679,7 @@
       "ownerSkill": "kit-release",
       "surface": "claude",
       "installRole": "maintainer",
-      "sha256": "168879858199f19f124e8bc3722f430f65b44b1fb6409d9c2112e6ec02d9b561",
+      "sha256": "7e08d5115d34f36da08491fa3bb8d5f4ca45e2908560e8f8c924cf3fd619d7f9",
       "mode": 420,
       "origin": "kit"
     },
@@ -1759,7 +1759,7 @@
       "ownerSkill": "orchestrate-wave",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "fb244997866b4ad01db7c7de8a22467d4c8399f030d236a517b6b9cc958d9177",
+      "sha256": "24c90d6048f04df29c0031cd6b643ab433536c8a176dd4983111c6be6e0fcb19",
       "mode": 420,
       "origin": "kit"
     },
@@ -1959,7 +1959,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "5f5ceed4ec89d8eae8f1199d08b4948e9627eef7ce128e1858b208511c726e52",
+      "sha256": "6c896543b1a1a50ca3f591d63e364a3f0d624b8ae02ef93183e3665a27248d3c",
       "mode": 420,
       "origin": "kit"
     },
@@ -1969,7 +1969,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "7a72f72bc4c42401e6bfefb1253d87a2970b633d5f9e9bf975c5d486813cacd2",
+      "sha256": "be08d8e86f4573049c9cd809cde9417a334d364f3e823548bcd54136b1da4b01",
       "mode": 420,
       "origin": "kit"
     },
@@ -1979,7 +1979,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "e0dd9835e3658909132058e9a5fdd851e972220bbadaf78a57e3c6220d470922",
+      "sha256": "b4bf369b9c7791b9b9c76438aaa4cd9a07a0860fcc6bb9b52eebe12c6427ccbb",
       "mode": 420,
       "origin": "kit"
     },

package/docs/adr/0004-release-intent-is-a-version-tag.md

@@ -2,6 +2,10 @@
 
 Status: accepted (2026-07-22, issue #204)
 
+Clarified 2026-07-25 by issue #239: an explicit AFK end-to-end mandate may
+authorize deterministic reversible release preparation, but never the
+publication tag itself.
+
 The release workflow currently publishes whenever a merge to `main` changes
 `package.json`. That keeps the canonical branch and npm close together, but it
 also makes an ordinary merge an irreversible public action whose consequence is
@@ -36,7 +40,12 @@ We decided that integration and publication are separate transitions:
 ## Consequences
 
 - A prepared version may temporarily exist on `main` in an `awaiting-tag` state.
-- An AFK wave may create its own tag after all pre-authorized landing gates pass;
-  the next program wave still requires separate authorization.
+- An explicit AFK Wave/Program mandate may cover the deterministic reversible
+  metadata preparation and landing that it names. It never by itself authorizes
+  creating or pushing the publication tag; that irreversible action requires a
+  separate explicit confirmation.
+- A single-Wave mandate does not authorize the next Program Wave. A later
+  explicit whole-Program mandate does authorize all planned Waves and remains in
+  force across their boundaries.
 - Reruns reconcile the same tag and never infer that a red workflow means
   nothing was published.

package/docs/agents/issue-tracker.md

@@ -10,3 +10,14 @@ Issues and PRDs for this repo live in `iKon85/agent-workflow-kit` as GitHub issu
 - Route board writes, status/wave/cluster field edits, dependencies, and sub-issue links through `scripts/board-sync.py`, not bare `gh project` commands.
 - Board state is authoritative for workflow status; GitHub issues remain the durable content source.
 
+## Pickup claim
+
+Used by `/implement`, `/diagnose`, and `/orchestrate-wave` before the first
+edit. Board status `In Progress` is the human-facing signal; the claim below is
+the machine-readable one, and it is the only one that names the branch and
+worktree a colliding session would have to find.
+
+- **Check**: `gh issue view <n> --json assignees,comments --jq '{assignees: [.assignees[].login], claims: [.comments[].body | select(contains("<!-- agent-claim:"))]}'` — a foreign assignee or a marker this session did not plant is a foreign claim: stop, report the claimed branch/worktree, and leave it alone.
+- **Claim**: `gh issue edit <n> --add-assignee @me`, then `gh issue comment <n> --body '<!-- agent-claim: branch=<branch>; worktree=<absolute-path>; date=<YYYY-MM-DD> -->'`. Board status stays a `scripts/board-sync.py` write, never a bare `gh project` call.
+- **Release**: the slice PR (`closes #<n>` / `Part of #<anchor>`) supersedes the claim, so `/wrapup` needs no extra step. On abandon: `gh issue edit <n> --remove-assignee @me` plus a `claim released` comment.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.34.1",
+  "version": "0.34.3",
   "description": "Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.",
   "type": "module",
   "bin": {

package/scripts/kit-release.test.mjs

@@ -184,6 +184,18 @@ test('both release skill surfaces name only the owned scoped npm package', async
   }
 });
 
+test('an explicit AFK scope can authorize reversible preparation but never publication', async () => {
+  const claude = await readFile(join(REPO, '.claude/skills/kit-release/SKILL.md'), 'utf8');
+  const codex = await readFile(join(REPO, '.agents/skills/kit-release/SKILL.md'), 'utf8');
+  assert.equal(codex, claude);
+  for (const body of [claude, codex]) {
+    assert.match(body, /explicit AFK end-to-end mandate/i);
+    assert.match(body, /deterministic recommendation/i);
+    assert.match(body, /reversible metadata preparation/i);
+    assert.match(body, /annotated `v<version>` tag[\s\S]*separate explicit confirmation/i);
+  }
+});
+
 test('maintainer docs and the accepted ADR agree that merge integrates and an annotated tag publishes', async () => {
   const paths = [
     'CLAUDE.md',

package/scripts/test_issue_claim_contract.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""Issue-claim-on-pickup contract (#231).
+
+A skill that ACCEPTS a tracked issue for building must leave a claim on the
+issue itself before it builds — the local worktree/branch/PR guard only sees
+the same machine, and only until someone pushes. The claim is what a second
+session, a second machine, or a cloud agent can actually see.
+
+Enforced here:
+
+- `implement` and `diagnose` carry one byte-identical claim block on both
+  surfaces, and it sits before their first build instruction.
+- The block covers all three legs: check for a foreign claim (STOP), plant a
+  claim naming branch + worktree, release it.
+- `orchestrate-wave` claims each slice issue at builder-launch time and
+  releases only its own slice claims.
+- Every tracker seed and this repo's own tracker layer document the concrete
+  claim / check / release operations, so the tracker-neutral skill prose
+  resolves to real commands.
+
+Run: python3 scripts/test_issue_claim_contract.py
+"""
+from __future__ import annotations
+
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SURFACES = (".claude/skills", ".agents/skills")
+PICKUP_SKILLS = ("implement", "diagnose")
+START = "<!-- issue-claim:start -->"
+END = "<!-- issue-claim:end -->"
+MARKER = "<!-- agent-claim:"
+TRACKER_DOC = "docs/agents/issue-tracker.md"
+TRACKER_SEEDS = (
+    "setup-workflow/issue-tracker-github.md",
+    "setup-workflow/issue-tracker-gitlab.md",
+    "setup-workflow/issue-tracker-local.md",
+)
+# The first instruction that already assumes the build has started.
+FIRST_BUILD_ANCHOR = {
+    "implement": "Use /tdd where possible",
+    "diagnose": "## Phase 1 — Build a feedback loop",
+}
+
+
+def skill_body(surface: str, skill: str) -> str:
+    return (ROOT / surface / skill / "SKILL.md").read_text(encoding="utf-8")
+
+
+def claim_block(body: str) -> str:
+    return body.split(START, 1)[1].split(END, 1)[0]
+
+
+def section(body: str, heading: str) -> str:
+    """Return one second-level Markdown section, excluding the next one."""
+    start = body.index(heading) + len(heading)
+    end = body.find("\n## ", start)
+    return body[start:] if end == -1 else body[start:end]
+
+
+class ClaimBlockContract(unittest.TestCase):
+    def test_pickup_skills_carry_exactly_one_claim_block_on_both_surfaces(self):
+        for skill in PICKUP_SKILLS:
+            for surface in SURFACES:
+                with self.subTest(skill=skill, surface=surface):
+                    body = skill_body(surface, skill)
+                    self.assertEqual(body.count(START), 1)
+                    self.assertEqual(body.count(END), 1)
+                    self.assertLess(body.index(START), body.index(END))
+
+    def test_claim_block_is_byte_identical_across_skills_and_surfaces(self):
+        blocks = {
+            (skill, surface): claim_block(skill_body(surface, skill))
+            for skill in PICKUP_SKILLS
+            for surface in SURFACES
+        }
+        first = blocks[(PICKUP_SKILLS[0], SURFACES[0])]
+        for key, block in blocks.items():
+            with self.subTest(key=key):
+                self.assertEqual(block, first)
+
+    def test_claim_block_covers_check_plant_and_release(self):
+        block = claim_block(skill_body(SURFACES[0], PICKUP_SKILLS[0]))
+        # Check leg — a foreign claim stops the pickup, and is never removed.
+        self.assertIn("foreign claim", block)
+        self.assertIn("STOP", block)
+        self.assertIn("never delete a foreign claim", block)
+        # Plant leg — the marker must carry branch AND worktree, or a colliding
+        # session cannot find the work in progress.
+        self.assertIn(MARKER, block)
+        self.assertIn("branch=", block)
+        self.assertIn("worktree=", block)
+        # Release leg — the PR supersedes it; an abandoned claim is removed.
+        self.assertIn("supersedes", block)
+        self.assertIn("abandon", block)
+
+    def test_claim_block_resolves_through_the_tracker_layer_with_a_fallback(self):
+        block = claim_block(skill_body(SURFACES[0], PICKUP_SKILLS[0]))
+        self.assertIn(TRACKER_DOC, block)
+        self.assertIn("fall back", block)
+
+    def test_claim_is_planted_before_the_first_build_instruction(self):
+        for skill in PICKUP_SKILLS:
+            for surface in SURFACES:
+                with self.subTest(skill=skill, surface=surface):
+                    body = skill_body(surface, skill)
+                    self.assertLess(
+                        body.index(END), body.index(FIRST_BUILD_ANCHOR[skill])
+                    )
+
+
+class OrchestrateWaveSliceClaimContract(unittest.TestCase):
+    def test_dispatch_claims_each_slice_issue_at_builder_launch(self):
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                dispatch = section(
+                    skill_body(surface, "orchestrate-wave"),
+                    "## Phase 2 — Dispatch one wave in parallel",
+                )
+                self.assertIn(MARKER, dispatch)
+                self.assertIn("slice issue", dispatch)
+                self.assertIn("branch=", dispatch)
+                self.assertIn("worktree=", dispatch)
+
+    def test_wave_claim_is_not_treated_as_a_slice_claim(self):
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                dispatch = section(
+                    skill_body(surface, "orchestrate-wave"),
+                    "## Phase 2 — Dispatch one wave in parallel",
+                )
+                self.assertIn("wave claim", dispatch)
+
+    def test_cleanup_releases_only_this_runs_slice_claims(self):
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                cleanup = section(
+                    skill_body(surface, "orchestrate-wave"),
+                    "## Phase 6 — Cleanup + close",
+                )
+                self.assertIn("slice claim", cleanup)
+                self.assertIn("this run", cleanup)
+
+
+class TrackerLayerClaimOperations(unittest.TestCase):
+    def documents(self) -> dict[str, str]:
+        docs = {TRACKER_DOC: (ROOT / TRACKER_DOC).read_text(encoding="utf-8")}
+        for surface in SURFACES:
+            for seed in TRACKER_SEEDS:
+                path = ROOT / surface / seed
+                docs[str(path.relative_to(ROOT))] = path.read_text(encoding="utf-8")
+        return docs
+
+    def test_every_tracker_layer_defines_claim_check_and_release(self):
+        for name, body in self.documents().items():
+            with self.subTest(document=name):
+                self.assertIn("## Pickup claim", body)
+                claim = section(body, "## Pickup claim")
+                self.assertIn(MARKER, claim)
+                self.assertIn("branch=", claim)
+                self.assertIn("worktree=", claim)
+                # a read side (detect a foreign claim) and a release side
+                self.assertIn("Check", claim)
+                self.assertIn("Release", claim)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/scripts/test_orchestrate_wave_contract.py

@@ -95,6 +95,14 @@ BEHAVIORAL_PARITY = {
         "Program-PRD",
         "program sync",
     ),
+    "program authorization continuity": (
+        "explicit whole-Program mandate",
+        "all planned Waves",
+        "Do not re-ask at each Wave boundary",
+        "gated action",
+        "meaningful authorized safe work",
+        "must not be marked `blocked`",
+    ),
 }
 
 
@@ -175,7 +183,11 @@ class OrchestrateWaveContract(unittest.TestCase):
         ):
             self.assertIn(fragment, self.skill)
 
-        self.assertLessEqual(len(self.skill.splitlines()), 345)
+        # Skeleton-size ratchet: detail belongs in references/, not here. 345 ->
+        # 360 carried the sticky Program-authorization rule; 360 -> 368 adds the
+        # per-slice pickup claim (#231). Both are phase-level responsibilities
+        # the reference files cannot carry — they gate dispatch itself.
+        self.assertLessEqual(len(self.skill.splitlines()), 368)
 
     def test_registry_ownership_distinguishes_safe_from_eager_registries(self):
         prose = " ".join(self.skill.split())