baldart 4.23.0 → 4.24.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.24.0] - 2026-06-10
+
+**Atomic backlog-ID allocator — no FEAT/BUG collisions across parallel worktrees.** When several `/prd` (or `/new`/`new2` follow-up) sessions run in parallel on sibling worktrees, each branched from the same trunk, the old `max(^id: FEAT-) + 1` scan made them all land on the **same next integer**: the other session's card was in flight on an unmerged sibling branch, invisible to both the local backlog and the trunk merge-base — so two epics both became `FEAT-0024` and conflicted at rebase/merge. The `git fetch` + merge-base scan only ever covered *already-merged* IDs, never in-flight ones. A new allocator anchors a lock + per-prefix high-water mark in `$MAIN/.worktrees/` (the shared coordination point every worktree already reaches via `git rev-parse --git-common-dir`, gitignored like `registry.json`), so a reservation is atomic across every worktree **on the same machine**. The high-water mark bumped under the lock is the correctness anchor; `max()` against the real backlog + sibling-worktree backlogs + reservations log + trunk merge-base makes it **self-healing**. **MINOR** (additive capability on the `worktree-manager` skill; opt-in — callers fall back to the inline merge-base scan + `[ID-RACE-RISK]` note when the script is absent, so older installs and cross-machine cloud agents are unaffected. **No `baldart.config.yml` key** — the allocator reuses `paths.backlog_dir` + the gitignored `.worktrees/` convention, so the schema-change propagation rule does not apply).
+
+### Added
+
+- **`framework/.claude/skills/worktree-manager/scripts/allocate-id.sh`** — prefix-parametric (`FEAT`/`BUG`/`UI`/`DOC`/`PERF`/…) atomic ID allocator. `reserve <PREFIX> <slug>` prints the next free integer zero-padded to 4 digits; `release <worktree-path>` prunes a finished worktree's reservations. Cross-process mutex via atomic `mkdir` (stale-stolen after 30s via the lock dir's own mtime — a directory, not a git ref, so it never touches the shared `refs/stash` that `git stash` in worktrees is forbidden over). The slow `git fetch` runs **before** the lock, keeping the critical section local-FS-only (sub-second). Reads `paths.backlog_dir` + `git.trunk_branch` from `baldart.config.yml` and resolves `$MAIN` at runtime — no hardcoded project facts (passes the framework-edit-gate). Same-machine scope; the trunk merge-base scan is the best-effort cross-machine guard.
+
+### Changed
+
+- **`framework/.claude/skills/worktree-manager/SKILL.md`** — new section **"ID Allocation"** documenting the allocator, the shared `.id-alloc.lock/` / `.id-hwm-<PREFIX>` / `id-reservations.jsonl` files, the same-machine scope + opt-in fallback contract, and the gap-tolerant monotonic-counter design. `release` is wired into the cleanup paths of `/mw` (step 7), `mw-docs` (step 6), and `/cw` (step 4).
+- **`framework/.claude/agents/prd-card-writer.md`** — § "FEAT-XXXX numbering" + Pre-Generation Checklist item 1 now reserve the integer via the allocator (primary path), with the trunk fetch + merge-base scan + `[ID-RACE-RISK]` note as the documented fallback when the script is absent. Applies to any prefix the writer mints.
+- **`framework/.claude/agents/prd.md`** — § 4.1 NAMING CONVENTIONS prefers the allocator (any prefix) over the plain backlog scan, with the same documented fallback.
+
 ## [4.23.0] - 2026-06-09
 
 **Functional Traceability Gate — no orphan UI affordances from mockups.** Handed-off mockups (Claude Design / Figma / the internal generators) routinely add interactive-looking chrome — buttons, icons, menu entries — that no requirement backed. Implementing a mockup **1:1 for fidelity** materialised that chrome into real markup + dead handlers + unused icon imports, and the cruft propagated forever. A new **unconditional** gate (independent of `features.has_design_system`) now requires every interactive or iconographic artifact to trace to a function before it becomes code: each artifact is classified **backed** (implement) / **decorative** (static-render, `aria-hidden`) / **orphan** (drop or escalate — never silent). The oracle is the PRD **UI Element Inventory `function_ref`** allowlist → card AC → orphan. Enforced at three boundaries: PRD mockup-intake (orphans become BLOCKING Discovery items), `ui-expert` implementation-time (BLOCKING pre-work), and `code-reviewer` / `/design-review` per-merge (`UI_ORPHAN_AFFORDANCE` HIGH finding). The `visual-fidelity-verifier` gains a `resolved_orphans` carve-out so a deliberately-dropped orphan is *expected-absent*, not a `component-missing` false positive. **MINOR** (additive discipline across existing UI surfaces; no new agent/skill/command and **no `baldart.config.yml` key** — the gate is registry-independent and reads its allowlist from the PRD inventory, so the schema-change propagation rule does not apply).

package/VERSION

@@ -1 +1 @@
-4.23.0
+4.24.0

package/framework/.claude/agents/prd-card-writer.md

@@ -300,18 +300,36 @@ applies even when N=1.
 
 ### FEAT-XXXX numbering
 
-- Pick the next free `FEAT-XXXX` integer (Grep `^id: FEAT-` in `${paths.backlog_dir}/`, find max,
-  add 1). **Reserve the entire integer for this epic** — do NOT reuse the integer
-  for unrelated cards even if it has fewer than ~99 children.
-- **Scan the canonical backlog, not just the worktree branch.** The worktree
-  branched from the trunk may not contain IDs committed on sibling branches not
-  yet merged. Before computing max, run
-  `git fetch <git.trunk_branch>` and grep `${paths.backlog_dir}/` on the merge-base of the
-  trunk (`git grep '^id: FEAT-' $(git merge-base HEAD <git.trunk_branch>)` plus
-  the local worktree) so concurrent PRD sessions don't both land on the same
-  "next free" integer. If a `git fetch` is not possible (offline), state the
-  reservation is best-effort against the local view and surface a
-  `[ID-RACE-RISK]` note so the caller can re-verify before commit.
+- Pick the next free `FEAT-XXXX` integer. **Reserve the entire integer for this
+  epic** — do NOT reuse the integer for unrelated cards even if it has fewer than
+  ~99 children.
+- **Use the atomic allocator when present (primary path).** Plain `max + 1` is
+  unsafe under parallelism: concurrent PRD sessions on sibling worktrees, all
+  branched from the same trunk, see the same max (the other session's card is in
+  flight on an unmerged branch) and both pick the same integer → merge conflict.
+  The `worktree-manager` allocator reserves the integer atomically across every
+  worktree on this machine (lock + shared high-water mark under `.worktrees/`):
+
+  ```bash
+  # $MAIN is the main repo root: dirname of `git rev-parse --git-common-dir`.
+  ALLOC="$MAIN/.claude/skills/worktree-manager/scripts/allocate-id.sh"
+  if [ -x "$ALLOC" ]; then
+    N="$("$ALLOC" reserve FEAT "<slug>")"   # e.g. prints 0024
+    # → the reserved epic id is FEAT-$N. The integer is now claimed; a parallel
+    #   session calling reserve will get FEAT-$((N+1)).
+  fi
+  ```
+
+  State the reserved integer in your response.
+- **Fallback when the allocator is absent** (older install, no script): degrade to
+  the canonical-backlog scan — `git fetch <git.trunk_branch>`, then
+  `max` over `git grep '^id: FEAT-' $(git merge-base HEAD <git.trunk_branch>)`
+  plus the local worktree backlog. This still misses in-flight sibling-worktree
+  IDs, so surface a `[ID-RACE-RISK]` note so the caller can re-verify before
+  commit. If `git fetch` is impossible (offline), say the reservation is
+  best-effort against the local view.
+- The same procedure applies to any other prefix you mint (`BUG`, `UI`, `DOC`,
+  `PERF`): `reserve <PREFIX> <slug>` — the allocator is prefix-parametric.
 
 ### FORBIDDEN PATTERNS — agent MUST refuse to generate
 
@@ -350,10 +368,12 @@ Mirror their structure when generating new epic+child sets.
 
 Before writing the first YAML file, confirm and report to the caller:
 
-1. **Reserved FEAT-XXXX integer**: Grep `^id: FEAT-` in `${paths.backlog_dir}/`, find max,
-   pick max+1, per the concurrency-safe procedure in § "FEAT-XXXX numbering"
-   (fetch trunk + merge-base scan to avoid duplicate IDs across parallel
-   sessions). State the chosen integer in your response.
+1. **Reserved FEAT-XXXX integer**: reserve it via the atomic allocator
+   (`allocate-id.sh reserve FEAT <slug>`), per § "FEAT-XXXX numbering" — this is
+   the concurrency-safe path that prevents duplicate IDs across parallel sessions
+   on sibling worktrees. If the allocator is absent, fall back to the trunk
+   fetch + merge-base scan with an `[ID-RACE-RISK]` note. State the chosen
+   integer in your response.
 2. **Drafted epic + N children list**: list the planned filenames
    (`FEAT-XXXX-00-<slug>-epic.yml`, `FEAT-XXXX-01-<sub-slug>.yml`, ...) BEFORE
    writing them. This is a contract — the actual files MUST match the list.

package/framework/.claude/agents/prd.md

@@ -498,7 +498,20 @@ Create protocol-compliant backlog cards for every actionable step. Cards MUST fo
 
 #### 4.1 — NAMING CONVENTIONS
 
-Before creating cards, scan `${paths.backlog_dir}/*.yml` to determine the next available number. File naming rules:
+Before creating cards, reserve the next number for the chosen prefix. **Prefer the
+atomic allocator** — a plain `${paths.backlog_dir}/*.yml` scan collides under
+parallelism (concurrent sessions on sibling worktrees both pick the same "next"
+integer and conflict at merge):
+
+```bash
+# $MAIN = dirname of `git rev-parse --git-common-dir` (shared across worktrees).
+ALLOC="$MAIN/.claude/skills/worktree-manager/scripts/allocate-id.sh"
+[ -x "$ALLOC" ] && N="$("$ALLOC" reserve FEAT <slug>")   # also BUG | UI | DOC | PERF
+```
+
+If the allocator is absent (older install), fall back to scanning
+`${paths.backlog_dir}/*.yml` for the max and add 1, noting `[ID-RACE-RISK]`. See
+`worktree-manager` § "ID Allocation" for the mechanism. File naming rules:
 
 | Prefix | When to use | Example |
 |--------|-------------|---------|

package/framework/.claude/skills/worktree-manager/SKILL.md

@@ -292,7 +292,9 @@ git -C "$WORKTREE_PATH" rebase "origin/$TRUNK"
 # 5. Sync local trunk ref — reuse /mw "Common" block: ff-only pull when main
 #    repo HEAD is already $TRUNK; otherwise just fetch.
 
-# 6. Remove the registry entry for this worktree.
+# 6. Remove the registry entry for this worktree, then release its backlog-ID
+#    reservations (best-effort, high-water mark untouched):
+#    .claude/skills/worktree-manager/scripts/allocate-id.sh release "$WORKTREE_PATH" 2>/dev/null || true
 ```
 
 **Forbidden in docs merge**: pre-merge `npm run build`, `npx eslint`, `npx tsc`, `npm run test`, post-merge `npm run build`. The whole point of docs mode is that these gates are inapplicable.
@@ -356,6 +358,57 @@ Create the file if it doesn't exist. Update it on every `/nw`, `/mw`, `/cw` oper
 
 ---
 
+## ID Allocation — atomic backlog-ID reservation across parallel worktrees
+
+When several PRD / card sessions run in parallel on sibling worktrees, each
+branched from the same trunk, a plain `max(^id: PREFIX-) + 1` scan makes them all
+land on the **same next integer**: the other session's card is in flight on an
+unmerged sibling branch, invisible to both the local backlog and the trunk
+merge-base. They collide at rebase/merge time.
+
+`scripts/allocate-id.sh` closes that race **on the same machine**. Every worktree
+shares one main repo root (resolved from `git rev-parse --git-common-dir`), and
+`.worktrees/` lives there and is gitignored — so it is the natural shared
+coordination point, exactly like `registry.json`. The allocator anchors a lock
+and a per-prefix high-water-mark there:
+
+```bash
+# Reserve the next free integer for a prefix (FEAT, BUG, UI, DOC, PERF, …).
+# Prints the integer zero-padded to 4 digits on stdout; diagnostics on stderr.
+.claude/skills/worktree-manager/scripts/allocate-id.sh reserve FEAT <slug>
+
+# Release a finished worktree's reservations (best-effort prune; never blocks).
+.claude/skills/worktree-manager/scripts/allocate-id.sh release <worktree-path>
+```
+
+Shared files, all under `$MAIN/.worktrees/` (already gitignored):
+- `.id-alloc.lock/` — cross-process mutex (atomic `mkdir`, stale-stolen after 30s
+  via the dir's own mtime; it is a directory, NOT a git ref, so it does not touch
+  the shared `refs/stash` that `git stash` in worktrees is forbidden over).
+- `.id-hwm-<PREFIX>` — monotonic high-water mark per prefix. **This is the
+  correctness anchor**: bumped under the lock, never decremented.
+- `id-reservations.jsonl` — append-only `{prefix,id,worktree,slug,ts}` log for
+  observability + `release` pruning. NOT load-bearing for correctness.
+
+Inside the lock, `reserve` takes `NEXT = max(high-water file, local backlog, every
+sibling worktree's backlog from registry.json, reservations log, trunk
+merge-base) + 1`. The `max()` against the real backlog makes it **self-healing**:
+if `.id-hwm-*` is ever lost or a card was created bypassing the allocator, the
+next reservation still skips occupied numbers. Abandoned reservations leave
+**gaps**, which is fine — backlog IDs need not be contiguous, and "reserve the
+whole integer, never reuse" is already the rule.
+
+**Scope: same machine only.** The shared file cannot reach separate cloud agents;
+the trunk merge-base scan inside `reserve` is the best-effort cross-machine guard.
+Callers (`prd-card-writer`, the `prd` agent) invoke `reserve` when the script is
+present and **fall back to their inline merge-base scan + `[ID-RACE-RISK]` note**
+when it is absent (older installs) — the allocator is additive, never required.
+
+`release` is wired into the cleanup path of `/mw`, `mw-docs`, and `/cw` (see those
+steps) so a merged/cleaned worktree's reservations are pruned.
+
+---
+
 ## /nw — New Worktree
 
 Supports three modes:
@@ -1077,6 +1130,13 @@ git worktree prune
 
 Remove the entry from `.worktrees/registry.json`.
 
+Also release this worktree's backlog-ID reservations (best-effort; the high-water
+mark stays untouched so numbering remains monotonic):
+
+```bash
+.claude/skills/worktree-manager/scripts/allocate-id.sh release "$WORKTREE_PATH" 2>/dev/null || true
+```
+
 ### 8. Report
 
 ```
@@ -1184,7 +1244,12 @@ git worktree prune
 
 ### 4. Update registry
 
-Remove cleaned entries from `.worktrees/registry.json`.
+Remove cleaned entries from `.worktrees/registry.json`. For each removed
+worktree, also release its backlog-ID reservations (best-effort):
+
+```bash
+.claude/skills/worktree-manager/scripts/allocate-id.sh release "<removed-worktree-path>" 2>/dev/null || true
+```
 
 ### 5. Report
 

package/framework/.claude/skills/worktree-manager/scripts/allocate-id.sh

@@ -0,0 +1,207 @@
+#!/usr/bin/env bash
+#
+# allocate-id.sh — atomic, cross-worktree backlog-ID allocator (same machine).
+#
+# Problem it solves: several PRD/card sessions running in parallel on sibling
+# worktrees all branch from the same trunk, so each computes the same
+# "max(^id: PREFIX-) + 1" and they collide at rebase/merge time. A plain
+# backlog scan cannot see IDs that are still in flight on an unmerged sibling
+# worktree branch.
+#
+# Mechanism: every worktree shares the same main repo root (resolved from
+# `git rev-parse --git-common-dir`), and `.worktrees/` lives there and is
+# gitignored. We anchor a lock + a per-prefix high-water-mark file there, so a
+# reservation is atomic across every worktree on this machine. The high-water
+# bumped under the lock is the correctness mechanism; the max() against the real
+# backlog makes it self-healing if the counter file is ever lost or bypassed.
+#
+# Scope: SAME MACHINE only (a shared local file). Cross-machine (separate cloud
+# agents) is not covered here — the caller keeps the merge-base scan as a
+# best-effort cross-machine guard and surfaces an [ID-RACE-RISK] note.
+#
+# Usage:
+#   allocate-id.sh reserve <PREFIX> <slug>     # prints the reserved integer, zero-padded to 4
+#   allocate-id.sh release <worktree-path>     # prunes that worktree's reservations (best-effort)
+#
+# Exit non-zero on hard failure (not a git repo, lock unobtainable) so the
+# caller can fall back to its inline scan. All diagnostics go to stderr; stdout
+# carries ONLY the allocated number on success.
+
+set -u
+
+LOCK_STALE_SECONDS=30
+LOCK_MAX_TRIES=150   # ~30s at 0.2s/try
+
+err() { printf '%s\n' "$*" >&2; }
+
+# --- Resolve the shared main repo root from any worktree -------------------
+resolve_main() {
+  local common
+  common="$(git rev-parse --git-common-dir 2>/dev/null)" || return 1
+  case "$common" in
+    /*) ;;                          # already absolute
+    *)  common="$(pwd)/$common" ;;  # relative (we're in the main repo) → absolutise
+  esac
+  (cd "$common/.." 2>/dev/null && pwd) || return 1
+}
+
+# --- Read a paths.* / git.* scalar from baldart.config.yml -----------------
+config_scalar() {
+  # $1 = top-level block (paths|git), $2 = key
+  local block="$1" key="$2" cfg="$MAIN/baldart.config.yml"
+  [ -f "$cfg" ] || return 0
+  grep -A60 "^${block}:" "$cfg" 2>/dev/null \
+    | grep -m1 "[[:space:]]*${key}:" \
+    | sed -E "s/.*${key}:[[:space:]]*\"?([^\"#]*)\"?.*/\1/" \
+    | sed -E 's/[[:space:]]+$//'
+}
+
+# --- Highest integer for PREFIX across one or more directories -------------
+scan_dirs_max() {
+  local prefix="$1"; shift
+  local max="$1"; shift     # starting floor
+  local d line n
+  for d in "$@"; do
+    [ -d "$d" ] || continue
+    while IFS= read -r line; do
+      [ -n "$line" ] || continue
+      n="$(printf '%s' "$line" | sed -E "s/^id:[[:space:]]*${prefix}-0*([0-9]+).*/\1/")"
+      case "$n" in ''|*[!0-9]*) continue ;; esac
+      [ "$n" -gt "$max" ] && max="$n"
+    done <<EOF
+$(grep -rhoE "^id:[[:space:]]*${prefix}-[0-9]+" "$d"/*.yml 2>/dev/null)
+EOF
+  done
+  printf '%s' "$max"
+}
+
+# --- Lock helpers (mkdir is atomic on POSIX; portable, no flock) -----------
+# Staleness uses the lock directory's own mtime (set atomically by mkdir, and
+# refreshed when the holder writes pid) — NOT a ts file that may not be written
+# yet, which would race a just-created lock into an instant false steal. The
+# critical section is local-FS only (the slow `git fetch` runs before the lock),
+# so the stale threshold is never tripped by a legitimate holder.
+file_mtime() { stat -f %m "$1" 2>/dev/null || stat -c %Y "$1" 2>/dev/null || echo 0; }
+acquire_lock() {
+  local tries=0 now m age
+  mkdir -p "$WT_DIR" 2>/dev/null || true
+  while ! mkdir "$LOCKDIR" 2>/dev/null; do
+    if [ -d "$LOCKDIR" ]; then
+      now="$(date +%s)"; m="$(file_mtime "$LOCKDIR")"
+      case "$m" in ''|*[!0-9]*) m=0 ;; esac
+      age=$(( now - m ))
+      if [ "$m" -gt 0 ] && [ "$age" -gt "$LOCK_STALE_SECONDS" ]; then
+        err "WARN: stealing stale id-alloc lock (age ${age}s)"; rm -rf "$LOCKDIR" 2>/dev/null; continue
+      fi
+    fi
+    tries=$(( tries + 1 ))
+    [ "$tries" -gt "$LOCK_MAX_TRIES" ] && { err "ERROR: could not acquire id-alloc lock"; return 1; }
+    sleep 0.2
+  done
+  printf '%s\n' "$$" > "$LOCKDIR/pid" 2>/dev/null || true
+}
+release_lock() { rm -rf "$LOCKDIR" 2>/dev/null || true; }
+
+# ===========================================================================
+CMD="${1:-}"
+MAIN="$(resolve_main)" || { err "ERROR: not inside a git repository"; exit 1; }
+WT_DIR="$MAIN/.worktrees"
+LOCKDIR="$WT_DIR/.id-alloc.lock"
+RESV="$WT_DIR/id-reservations.jsonl"
+REG="$WT_DIR/registry.json"
+
+case "$CMD" in
+  reserve)
+    PREFIX="${2:-}"; SLUG="${3:-}"
+    [ -n "$PREFIX" ] || { err "usage: allocate-id.sh reserve <PREFIX> <slug>"; exit 2; }
+    case "$PREFIX" in *[!A-Z]*|'') err "ERROR: PREFIX must be uppercase letters (e.g. FEAT, BUG)"; exit 2 ;; esac
+
+    BACKLOG_DIR="$(config_scalar paths backlog_dir)"; [ -n "$BACKLOG_DIR" ] || BACKLOG_DIR="backlog"
+    TRUNK="$(config_scalar git trunk_branch)"
+    WT="$(git rev-parse --show-toplevel 2>/dev/null || echo "$MAIN")"
+    HWM="$WT_DIR/.id-hwm-$PREFIX"
+
+    # Refresh the remote trunk ref BEFORE taking the lock — it's the only slow
+    # (network) step; keeping it out of the critical section means a holder can
+    # never be stale-stolen mid-allocation.
+    [ -n "$TRUNK" ] && git fetch origin "$TRUNK" --quiet 2>/dev/null || true
+
+    acquire_lock || exit 1
+    trap release_lock EXIT
+
+    # 1) Floor = stored high-water mark (correctness anchor).
+    max=0
+    if [ -f "$HWM" ]; then
+      max="$(tr -cd '0-9' < "$HWM" 2>/dev/null)"; case "$max" in ''|*[!0-9]*) max=0 ;; esac
+    fi
+
+    # 2) Local worktree backlog + every sibling worktree's backlog (in flight).
+    dirs="$MAIN/$BACKLOG_DIR"
+    [ "$WT" != "$MAIN" ] && dirs="$dirs $WT/$BACKLOG_DIR"
+    if [ -f "$REG" ]; then
+      while IFS= read -r p; do
+        [ -n "$p" ] && dirs="$dirs $p/$BACKLOG_DIR"
+      done <<EOF
+$(grep -oE '"path"[[:space:]]*:[[:space:]]*"[^"]*"' "$REG" 2>/dev/null | sed -E 's/.*"([^"]*)"$/\1/')
+EOF
+    fi
+    # shellcheck disable=SC2086
+    max="$(scan_dirs_max "$PREFIX" "$max" $dirs)"
+
+    # 3) Reservations log (covers a wiped HWM with reservations still in flight).
+    if [ -f "$RESV" ]; then
+      while IFS= read -r n; do
+        n="$(printf '%s' "$n" | sed -E "s/.*\"${PREFIX}-0*([0-9]+).*/\1/")"
+        case "$n" in ''|*[!0-9]*) continue ;; esac
+        [ "$n" -gt "$max" ] && max="$n"
+      done <<EOF
+$(grep -oE "\"id\":\"${PREFIX}-[0-9]+" "$RESV" 2>/dev/null)
+EOF
+    fi
+
+    # 4) Best-effort cross-machine guard: merge-base of trunk (already-merged IDs).
+    #    The fetch already ran before the lock; this is a local object-store read.
+    if [ -n "$TRUNK" ]; then
+      MB="$(git merge-base HEAD "origin/$TRUNK" 2>/dev/null || git merge-base HEAD "$TRUNK" 2>/dev/null || true)"
+      if [ -n "$MB" ]; then
+        while IFS= read -r n; do
+          n="$(printf '%s' "$n" | sed -E "s/^id:[[:space:]]*${PREFIX}-0*([0-9]+).*/\1/")"
+          case "$n" in ''|*[!0-9]*) continue ;; esac
+          [ "$n" -gt "$max" ] && max="$n"
+        done <<EOF
+$(git grep -hoE "^id:[[:space:]]*${PREFIX}-[0-9]+" "$MB" -- "$BACKLOG_DIR/*.yml" 2>/dev/null)
+EOF
+      fi
+    fi
+
+    NEXT=$(( max + 1 ))
+    printf '%s\n' "$NEXT" > "$HWM" 2>/dev/null || true
+    printf '{"prefix":"%s","id":"%s-%04d","worktree":"%s","slug":"%s","ts":"%s"}\n' \
+      "$PREFIX" "$PREFIX" "$NEXT" "$WT" "$SLUG" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$RESV" 2>/dev/null || true
+
+    release_lock; trap - EXIT
+    printf '%04d\n' "$NEXT"
+    ;;
+
+  release)
+    WT="${2:-}"
+    [ -n "$WT" ] || { err "usage: allocate-id.sh release <worktree-path>"; exit 2; }
+    [ -f "$RESV" ] || exit 0
+    acquire_lock || exit 0   # best-effort prune; never block cleanup
+    trap release_lock EXIT
+    # grep -v exit code: 0 = some lines kept, 1 = none kept (all pruned → empty
+    # file is the correct result), >=2 = real error (keep the original).
+    grep -vF "\"worktree\":\"$WT\"" "$RESV" > "$RESV.tmp" 2>/dev/null
+    if [ "$?" -le 1 ]; then
+      mv "$RESV.tmp" "$RESV" 2>/dev/null || rm -f "$RESV.tmp" 2>/dev/null
+    else
+      rm -f "$RESV.tmp" 2>/dev/null
+    fi
+    release_lock; trap - EXIT
+    ;;
+
+  *)
+    err "usage: allocate-id.sh {reserve <PREFIX> <slug> | release <worktree-path>}"
+    exit 2
+    ;;
+esac

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.23.0",
+  "version": "4.24.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"