@jeiemgi/cckit 0.1.6

package/scripts/lib/secret-guard.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# secret-guard.sh — agnostic secret + privacy guard. Ensures cckit never publishes secrets,
+# key material, env files, or YOUR private project data. NOTHING project-specific is hardcoded:
+# the secret/key patterns are universal, and "what is private to me" is supplied by the user via
+# an optional, gitignored denylist (.cckit/privacy-denylist) — cckit ships only an .example.
+#
+# Applies to EVERYTHING publishable — code, docs, cookbook, examples, templates.
+# Usage:  source secret-guard.sh && secret_guard_scan [file...]   (default: git-tracked files)
+#         exit 0 = clean, 1 = a finding (with a report on stderr).
+
+# Files that must never be committed (by basename). Env files include .env.example/.sample —
+# even an example leaks your variable *names* and structure, so it stays local.
+_sg_forbidden_name() {
+  case "$1" in
+    .env|.env.*|*.env) return 0 ;;
+    *.pem|*.key|*.p12|*.pfx|*.keystore|*.jks|id_rsa|id_rsa.*|id_ed25519|id_ed25519.*) return 0 ;;
+    .netrc|.pgpass|.npmrc|credentials|credentials.*|secrets.json|secrets.yaml|secrets.yml|*.tfvars) return 0 ;;
+    *.project-ids*|.project-ids.env) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# Universal high-signal secret content patterns (provider key prefixes, private-key blocks).
+# Written so the patterns do not match their own literal text.
+_sg_secret_patterns() {
+  cat <<'PAT'
+-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----
+AKIA[0-9A-Z]{16}
+ASIA[0-9A-Z]{16}
+sk-[A-Za-z0-9]{20,}
+sk-proj-[A-Za-z0-9_-]{20,}
+gh[pousr]_[A-Za-z0-9]{36,}
+github_pat_[A-Za-z0-9_]{50,}
+AIza[0-9A-Za-z_-]{35}
+xox[baprs]-[0-9A-Za-z-]{10,}
+sk_live_[0-9A-Za-z]{24,}
+rk_live_[0-9A-Za-z]{24,}
+glpat-[0-9A-Za-z_-]{20,}
+eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}
+PAT
+}
+
+# Generic "assignment of a real-looking secret value" — allows placeholders (<...>, ${...},
+# YOUR_, example, changeme, xxxx, redacted, placeholder).
+_sg_assign_pattern='(api[_-]?key|secret|password|passwd|access[_-]?token|auth[_-]?token|client[_-]?secret|private[_-]?key)["'"'"' ]*[:=]+[ ]*["'"'"'][^"'"'"'$<{ ]{8,}'
+
+secret_guard_scan() {
+  local files findings=0 f line denylist
+  if [ "$#" -gt 0 ]; then files=("$@"); else
+    # default: git-tracked + staged, minus this guard + the example denylist (avoid self-match)
+    mapfile -t files < <(git ls-files 2>/dev/null | grep -vE 'scripts/lib/secret-guard\.sh|privacy-denylist\.example' || true)
+  fi
+
+  # (a) forbidden filenames
+  for f in "${files[@]:-}"; do
+    [ -z "$f" ] && continue
+    if _sg_forbidden_name "$(basename "$f")"; then
+      echo "x secret-guard: forbidden file must not be committed: $f" >&2; findings=$((findings+1))
+    fi
+  done
+
+  # (b) universal secret content patterns
+  local pat
+  while IFS= read -r pat; do
+    [ -z "$pat" ] && continue
+    while IFS= read -r line; do
+      [ -z "$line" ] && continue
+      echo "x secret-guard: secret-like content: $line" >&2; findings=$((findings+1))
+    done < <(printf '%s\n' "${files[@]:-}" | tr '\n' '\0' | xargs -0 grep -nIE "$pat" 2>/dev/null | head -20)
+  done < <(_sg_secret_patterns)
+
+  # (c) generic secret assignment (placeholders allowed)
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    case "$line" in *YOUR_*|*example*|*EXAMPLE*|*placeholder*|*changeme*|*xxxx*|*redacted*|*'<'*|*'${'*) continue ;; esac
+    echo "x secret-guard: secret-like assignment: $line" >&2; findings=$((findings+1))
+  done < <(printf '%s\n' "${files[@]:-}" | tr '\n' '\0' | xargs -0 grep -niIE "$_sg_assign_pattern" 2>/dev/null | head -20)
+
+  # (d) user-supplied privacy denylist (agnostic: YOU declare what is yours; file stays local)
+  denylist=".cckit/privacy-denylist"
+  if [ -f "$denylist" ]; then
+    while IFS= read -r term; do
+      term="$(printf '%s' "$term" | sed 's/#.*//;s/^[[:space:]]*//;s/[[:space:]]*$//')"
+      [ -z "$term" ] && continue
+      while IFS= read -r line; do
+        [ -z "$line" ] && continue
+        echo "x secret-guard: private term '$term' present: $line" >&2; findings=$((findings+1))
+      done < <(printf '%s\n' "${files[@]:-}" | tr '\n' '\0' | xargs -0 grep -nIF "$term" 2>/dev/null | head -10)
+    done < "$denylist"
+  fi
+
+  if [ "$findings" -gt 0 ]; then
+    echo "✗ secret-guard: $findings finding(s) — refusing to proceed" >&2; return 1
+  fi
+  return 0
+}

package/scripts/lib/toon.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# toon.sh - TOON (Token-Oriented Object Notation) encoding for context payloads. A uniform array of
+# flat objects collapses to a compact tabular form - one keys header, then one row per element -
+# which costs far fewer tokens than repeating every key in JSON. Anything that is not a uniform,
+# scalar-only array of objects (or is below the size gate) falls back to compact JSON unchanged.
+#
+#   toon_encode            read JSON on stdin, write TOON (or JSON fallback) on stdout
+#   TOON_MIN_ROWS=N        size gate: arrays shorter than N stay JSON (default 2)
+
+# toon_encode - stdin JSON -> stdout TOON-or-JSON.
+toon_encode() {
+  command -v jq >/dev/null 2>&1 || { cat; return 0; }
+  local json n keys uniform min="${TOON_MIN_ROWS:-2}"
+  json="$(cat)"
+
+  n="$(printf '%s' "$json" | jq 'if type=="array" then length else -1 end' 2>/dev/null || echo -1)"
+  # not an array, or smaller than the gate -> compact JSON (TOON overhead not worth it).
+  if [ "$n" -lt "$min" ]; then printf '%s' "$json" | jq -c . 2>/dev/null || printf '%s\n' "$json"; return 0; fi
+
+  keys="$(printf '%s' "$json" | jq -r '.[0] | (keys_unsorted | join(","))' 2>/dev/null || true)"
+  # uniform = every element has the same key order AND only scalar values (tabular-encodable).
+  uniform="$(printf '%s' "$json" | jq -r --arg k "$keys" '
+    all(.[];
+      (keys_unsorted | join(",")) == $k
+      and ([.[]] | all(type | . == "string" or . == "number" or . == "boolean" or . == "null")))
+  ' 2>/dev/null || echo false)"
+
+  if [ "$uniform" != "true" ] || [ -z "$keys" ]; then
+    printf '%s' "$json" | jq -c .          # non-uniform / nested -> JSON fallback
+    return 0
+  fi
+
+  printf '[%s]{%s}:\n' "$n" "$keys"
+  printf '%s' "$json" | jq -r '.[] | [.[]] | @csv'
+}

package/scripts/lib/ui.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# ui.sh - terminal ergonomics, all detect-or-fallback (never a hard dependency, never required).
+# Color is gated on a real TTY + NO_COLOR; optional tools (glow, fzf, gum) enhance output when
+# present and degrade silently when not. Keeping this in one place gives every verb consistent,
+# pipe-safe behavior: piped or non-tty output is always plain.
+
+# ui_tty - true only when stdout is a real terminal (so pipes/redirects stay plain).
+ui_tty() { [ -t 1 ]; }
+
+# ui_color - true when we should emit ANSI color. NO_COLOR always wins (disables). Otherwise
+# CCKIT_FORCE_COLOR forces color even without a TTY (screenshots, CI, demos); failing that, color
+# needs a real TTY with a non-"dumb" TERM.
+#
+# We deliberately use a cckit-PRIVATE variable rather than the conventional CLICOLOR_FORCE/
+# FORCE_COLOR: those leak into the subprocesses cckit shells out to, and `gh` (mis)honors
+# CLICOLOR_FORCE by coloring even its `--json` output, which corrupts the JSON cckit then pipes to
+# jq. A private flag colors cckit's own output without poisoning child-process machine output.
+ui_color() {
+  [ -z "${NO_COLOR:-}" ] || return 1
+  [ -n "${CCKIT_FORCE_COLOR:-}" ] && return 0
+  ui_tty && [ "${TERM:-}" != "dumb" ]
+}
+
+# ui_paint <ansi-code> <text> - color text when ui_color, else plain.
+ui_paint() {
+  if ui_color; then printf '\033[%sm%s\033[0m' "$1" "$2"; else printf '%s' "$2"; fi
+}
+
+# ui_page - pretty-render markdown on stdin with glow when present + interactive; else cat.
+ui_page() {
+  if ui_tty && command -v glow >/dev/null 2>&1; then glow -; else cat; fi
+}
+
+# ui_pick <prompt> - choose one line from stdin: fzf if present + interactive, else first line.
+# Echoes the chosen line on stdout.
+ui_pick() {
+  if ui_tty && command -v fzf >/dev/null 2>&1; then
+    fzf --prompt="${1:-pick> }" --height=40% --reverse
+  else
+    head -n1
+  fi
+}

package/scripts/lib/version-bump.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# version-bump.sh - SemVer + Conventional Commits. ONE implementation, shared by `cckit release`
+# and the release workflow: compute the next version from the commits since the last tag, or write
+# a version into the project's manifests.
+#
+#   version-bump.sh --next            echo the next version (no side effects)
+#   version-bump.sh --emit            echo `bump=<level>` + `next=<version>` (for $GITHUB_OUTPUT)
+#   version-bump.sh --write <version> set the version in cckit.config.json + plugin.json + package.json
+#
+# Bump rules (Conventional Commits): a `feat!:`/`type!:` or a `BREAKING CHANGE` footer -> major;
+# `feat:` -> minor; `fix|perf|refactor|revert:` -> patch; non-functional types
+# (`docs|chore|style|test|ci|build`) and anything else -> none (no release).
+# no commits -> none (no release).
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+
+vb_current() { git -C "$ROOT" describe --tags --abbrev=0 2>/dev/null | sed 's/^v//'; }
+
+vb_level() {
+  local range="$1" log
+  log="$(git -C "$ROOT" log --format='%s%n%b' $range 2>/dev/null || true)"
+  [ -n "$log" ] || { echo none; return; }
+  if printf '%s\n' "$log" | grep -qE '(^|[[:space:]])BREAKING CHANGE|^[a-z]+(\([^)]*\))?!:'; then echo major; return; fi
+  if printf '%s\n' "$log" | grep -qE '^feat(\([^)]*\))?:'; then echo minor; return; fi
+  if printf '%s\n' "$log" | grep -qE '^(fix|perf|refactor|revert)(\([^)]*\))?:'; then echo patch; return; fi
+  # Only non-functional commits (docs/chore/style/test/ci/build, or untyped) -> no release.
+  echo none
+}
+
+vb_next() {
+  local cur="${1:-0.0.0}" level="$2" M m p rest
+  M="${cur%%.*}"; rest="${cur#*.}"; m="${rest%%.*}"; p="${rest#*.}"
+  case "$level" in
+    major) echo "$((M+1)).0.0" ;;
+    minor) echo "$M.$((m+1)).0" ;;
+    patch) echo "$M.$m.$((p+1))" ;;
+    *)     echo "$cur" ;;
+  esac
+}
+
+vb_write() {
+  local v="$1" f
+  command -v jq >/dev/null || { echo "version-bump: jq required to --write" >&2; return 1; }
+  for f in cckit.config.json .claude-plugin/plugin.json package.json docs-site/package.json; do
+    [ -f "$ROOT/$f" ] || continue
+    if [ "$f" = "cckit.config.json" ]; then jq --arg v "$v" '.kitVersion=$v' "$ROOT/$f" > "$ROOT/$f.tmp"
+    else jq --arg v "$v" '.version=$v' "$ROOT/$f" > "$ROOT/$f.tmp"; fi
+    mv "$ROOT/$f.tmp" "$ROOT/$f" && echo "  set $f -> $v"
+  done
+}
+
+_range() { local cur; cur="$(vb_current)"; if [ -n "$cur" ]; then echo "v$cur..HEAD"; else echo "HEAD"; fi; }
+
+case "${1:-}" in
+  --next)  vb_next "$(vb_current)" "$(vb_level "$(_range)")" ;;
+  --emit)  printf 'bump=%s\n' "$(vb_level "$(_range)")"; printf 'next=%s\n' "$(vb_next "$(vb_current)" "$(vb_level "$(_range)")")" ;;
+  --write) vb_write "${2:?usage: --write <version>}" ;;
+  *) echo "usage: version-bump.sh --next | --emit | --write <version>" >&2; exit 2 ;;
+esac

package/scripts/lib/worktree-issue-test.sh

@@ -0,0 +1,45 @@
+#!/bin/sh
+# worktree-issue-test.sh — self-test for worktree-issue.sh under bash AND zsh (#307).
+# The lib is sourced into whatever shell the session runs (zsh on macOS), so the
+# parsing must behave identically in both. Run:  bash scripts/lib/worktree-issue-test.sh
+#
+# Without args: re-runs itself under every available shell. With WT_TEST_INNER set:
+# runs the assertions in the current interpreter.
+
+dir=$(CDPATH='' cd -- "$(dirname -- "$0")" && pwd)
+
+if [ -n "${WT_TEST_INNER:-}" ]; then
+  . "$dir/worktree-issue.sh"
+  fail=0
+  check() {
+    got=$(wt_issue_number "$1")
+    if [ "$got" != "$2" ]; then
+      echo "FAIL($WT_TEST_INNER): wt_issue_number '$1' -> '[$got]', want '[$2]'"
+      fail=1
+    fi
+  }
+  check "task/293-mobbin"                          "293"   # branch
+  check "feat/46-roadmap-view"                     "46"    # branch
+  check "fix/305-session-registry-phantom"         "305"   # branch
+  check ".claude/worktrees/task+293-mobbin"        "293"   # worktree path
+  check "task+293-mobbin"                          "293"   # worktree dirname
+  check "/abs/path/.claude/worktrees/plan+266-ui"  "266"   # absolute worktree path
+  check "agent/foo"                                ""      # bot branch — no number
+  check "claude/issue-42"                          ""      # bot branch — slug not kind/N-
+  check "develop"                                  ""      # base branch
+  check "main"                                     ""      # base branch
+  check "task/29a3-x"                              ""      # malformed number
+  check "task/293mobbin"                           ""      # missing dash
+  [ "$fail" -eq 0 ] && echo "OK($WT_TEST_INNER): 12 cases"
+  exit "$fail"
+fi
+
+rc=0
+ran=0
+for sh in bash zsh; do
+  command -v "$sh" >/dev/null 2>&1 || continue
+  ran=1
+  WT_TEST_INNER="$sh" "$sh" "$0" || rc=1
+done
+[ "$ran" -eq 1 ] || { echo "no bash/zsh found"; exit 1; }
+exit "$rc"

package/scripts/lib/worktree-issue.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# worktree-issue.sh — associate a branch / worktree with the GitHub issue it belongs to,
+# and report whether that issue is still open. The association is DERIVED from the name —
+# there is no hand-maintained registry.
+#
+# Conventions (see .claude/rules/branch-naming.md):
+#   branch        <kind>/<N>-<slug>     e.g. feat/173-admin-clerk-signin
+#   worktree dir  <kind>+<N>-<slug>     e.g. .claude/worktrees/feat+173-admin-clerk-signin
+#
+# Source it:  source scripts/lib/worktree-issue.sh
+# Requires: git; gh (for state lookups — degrades to "unknown" without it).
+# Portable: POSIX parameter expansion only — sourceable from bash 3.2+ AND zsh (#307;
+# BASH_REMATCH stays silently empty in zsh, which switched the gc protection off).
+# Self-test: bash scripts/lib/worktree-issue-test.sh  (runs the cases under bash + zsh)
+
+# Echo the issue number a branch name / worktree path belongs to (empty if none, e.g. bot branches).
+wt_issue_number() {
+  local ref="$1" base kind rest n
+  # branch form: kind/N-slug  (kind = lowercase letters only, anchored at start)
+  kind="${ref%%/*}"; rest="${ref#*/}"
+  if [ "$kind" != "$ref" ]; then                     # ref contains "/"
+    case "$kind" in
+      ''|*[!a-z]*) : ;;                              # not a pure-lowercase kind
+      *)
+        n="${rest%%-*}"
+        if [ "$n" != "$rest" ]; then                 # a "-" follows the number
+          case "$n" in
+            ''|*[!0-9]*) : ;;
+            *) printf '%s' "$n"; return 0 ;;
+          esac
+        fi
+        ;;
+    esac
+  fi
+  # worktree-dir form: .../kind+N-slug
+  base="${ref##*/}"
+  kind="${base%%+*}"; rest="${base#*+}"
+  if [ "$kind" != "$base" ]; then                    # basename contains "+"
+    case "$kind" in
+      ''|*[!a-z]*) return 0 ;;
+    esac
+    n="${rest%%-*}"
+    [ "$n" = "$rest" ] && return 0                   # no "-" after the number
+    case "$n" in
+      ''|*[!0-9]*) : ;;
+      *) printf '%s' "$n" ;;
+    esac
+  fi
+  return 0
+}
+
+# Echo the issue state ("open" / "closed") for an issue number, lowercased. Empty when unknown
+# (no number, no gh, or lookup failed) — callers must treat empty as "don't assume safe to delete".
+wt_issue_state() {
+  local n="$1" repo="${2:-}"
+  [[ -z "$n" ]] && return 0
+  command -v gh >/dev/null 2>&1 || return 0
+  local args=(issue view "$n" --json state --jq .state)
+  [[ -n "$repo" ]] && args+=(--repo "$repo")
+  gh "${args[@]}" 2>/dev/null | tr '[:upper:]' '[:lower:]'
+}
+
+# Echo a protection reason if a branch/ref must NOT be garbage-collected because its issue
+# is still open; empty string means "no issue-based protection" (other gc rules still apply).
+wt_protected_reason() {
+  local ref="$1" repo="${2:-}" n state
+  n="$(wt_issue_number "$ref")"
+  [[ -z "$n" ]] && return 0
+  state="$(wt_issue_state "$n" "$repo")"
+  if [[ "$state" == "open" ]]; then
+    printf 'issue #%s still OPEN' "$n"
+  fi
+}

package/scripts/lib/worktree-start.sh

@@ -0,0 +1,280 @@
+#!/usr/bin/env bash
+# worktree-start.sh — the canonical "start a worktree for an issue" git-mechanic.
+#
+# Family 1 of kit-engine-boundary.md (rule #1/#2): one bash home for the op, consumed by the
+# kit-task-start skill, scripts/orchestrate.sh, and `kit task start`. No second implementation.
+#
+#   wt_start <issue-number> [slug-override]
+#     stdout: "<worktree-path>|<branch>|<issue-number>"   (one line, machine-readable)
+#     stderr: human progress
+#     returns: 0 on success (created or reused), 1 on failure
+#
+# Requires: gh, jq, git, scripts/lib/gh-project.sh (board update). bash 3.2 compatible.
+
+WT_START_REPO="${WT_START_REPO:-jeiemgi/cckit}"
+
+# _wt_set_port <app-env-file> <port> <issue-num> — append a per-worktree dev PORT to an app's
+# .env.local, but only where one exists (i.e. the app is locally runnable). Idempotent: an existing
+# PORT= line wins. The app dev scripts read ${PORT:-300X} (sub B) so this assignment takes effect.
+_wt_set_port() {
+  local file="$1" port="$2" num="$3"
+  [[ -f "$file" ]] || return 0
+  grep -q '^PORT=' "$file" 2>/dev/null && return 0
+  printf '\n# kit worktree #%s — per-worktree dev port (#773)\nPORT=%s\n' "$num" "$port" >> "$file"
+  echo "[#$num] PORT=$port -> $file" >&2
+}
+
+# wt_assign_ports <worktree> <issue-num> <root> — assign a per-worktree dev PORT to each app whose
+# env file is listed in `.worktree.devPorts` of <root>/.claude/kit.config.json. Each entry is
+# {path, base}; the port = base + (issue % 40) * <count> so lanes stay disjoint within and across
+# worktrees. Config-driven (no hardcoded app paths) so the kit stays portable: a project with no
+# `.worktree.devPorts` (or no kit.config.json) is a silent no-op. bash 3.2.
+wt_assign_ports() {
+  local wt="$1" num="$2" root="$3" cfg ports n offset i path base
+  cfg="$root/.claude/kit.config.json"
+  # jq is a stated requirement of this file (see header) — don't pre-check `command -v jq` here: the
+  # `command -v … || return` idiom mis-fires under zsh, and the jq read below already no-ops on a
+  # missing config / missing jq. Guard only on the config file existing.
+  [[ -f "$cfg" ]] || return 0
+  ports="$(jq -c '.worktree.devPorts // []' "$cfg" 2>/dev/null)" || return 0
+  [[ -n "$ports" && "$ports" != "[]" ]] || return 0
+  n="$(jq 'length' <<<"$ports" 2>/dev/null)"; [[ "$n" =~ ^[0-9]+$ && "$n" -gt 0 ]] || return 0
+  offset=$(( num % 40 )); i=0
+  while [[ "$i" -lt "$n" ]]; do
+    path="$(jq -r ".[$i].path // empty" <<<"$ports")"
+    base="$(jq -r ".[$i].base // empty" <<<"$ports")"
+    [[ -n "$path" && "$base" =~ ^[0-9]+$ ]] && _wt_set_port "$wt/$path" $(( base + offset * n )) "$num"
+    i=$(( i + 1 ))
+  done
+}
+
+# wt_bootstrap <root> <worktree> <issue-num> — make a fresh worktree runnable for local dev.
+# A new worktree inherits no .gitignored local config and no node_modules, and parallel worktrees
+# collide on the hardcoded dev port. This copies the local env, installs deps, and assigns a
+# per-worktree dev port. Every step is best-effort + idempotent — never fail the start (#773).
+wt_bootstrap() {
+  local root="$1" wt="$2" num="$3" rel src dst offset
+  [[ -d "$wt" ]] || return 0
+
+  # 1. Copy gitignored local config the worktree can't inherit: every .env.local* + project ids.
+  while IFS= read -r rel; do
+    [[ -n "$rel" ]] || continue
+    src="$root/$rel"; dst="$wt/$rel"
+    [[ -f "$src" ]] || continue
+    [[ -f "$dst" ]] && continue   # idempotent: never clobber edits already made in the worktree
+    mkdir -p "$(dirname "$dst")"
+    cp "$src" "$dst" && echo "[#$num] copied $rel" >&2
+  done < <(cd "$root" && {
+    find . -name '.env.local*' \
+      -not -path './node_modules/*' -not -path './.git/*' -not -path './.claude/worktrees/*' 2>/dev/null
+    [[ -f scripts/.project-ids.env ]] && echo './scripts/.project-ids.env'
+  } | sed 's|^\./||' | sort -u)
+
+  # 2. Assign a per-worktree dev PORT per app (base + offset*lanes from the issue number) so two
+  #    worktrees never fight for the same port. The app→base map is config-driven
+  #    (`.worktree.devPorts` in kit.config.json) so the kit carries no hardcoded app paths.
+  wt_assign_ports "$wt" "$num" "$root"
+
+  # 3. Install deps — node_modules is per-worktree, not shared. Opt out with KIT_WT_INSTALL=0.
+  if [[ "${KIT_WT_INSTALL:-1}" != "0" ]] && command -v pnpm >/dev/null 2>&1; then
+    echo "[#$num] pnpm install (set KIT_WT_INSTALL=0 to skip)..." >&2
+    ( cd "$wt" && pnpm install --prefer-offline >/dev/null 2>&1 ) \
+      && echo "[#$num] deps installed" >&2 \
+      || echo "[#$num] pnpm install failed — run 'pnpm install' in the worktree manually" >&2
+  fi
+}
+
+# ── Idle-worktree pool (OPT-IN, KIT_WT_POOL=1) ──────────────────────────────────────────────
+# Treehouse-style reuse: instead of always creating a fresh worktree, recycle an IDLE one whose
+# work already landed — saving the `git worktree add` + env copy + dependency install. OFF by
+# default: with KIT_WT_POOL unset/0, wt_start takes the exact same create path as before and none
+# of these helpers run. A worktree is REUSABLE only when ALL of these hold (conservative — if
+# unsure, don't reuse; fall through to create):
+#   • it lives under .claude/worktrees/ (a pooled tree — never the main checkout or the target)
+#   • it is not locked
+#   • its branch is already merged into origin/${KIT_BASE_BRANCH:-main} (the committed work landed — recycling it
+#     destroys nothing; the old branch ref survives in the object store regardless)
+#   • its working tree is clean (no staged/unstaged/untracked changes — recover-before-prune)
+#   • no LIVE session owns it (kit-sessions registry: no live pid sitting in that dir)
+
+# _wt_mtime <path> — file mtime as epoch seconds (BSD stat, then GNU stat). Picks the oldest tree.
+_wt_mtime() { stat -f %m "$1" 2>/dev/null || stat -c %Y "$1" 2>/dev/null; }
+
+# _wt_list <root> — emit one "<path>\t<branch-or-->\t<locked:0|1>" line per worktree (porcelain).
+_wt_list() {
+  local root="$1" line wt_path="" branch="" locked="0"
+  while IFS= read -r line; do
+    case "$line" in
+      "worktree "*) wt_path="${line#worktree }" ;;
+      "branch refs/heads/"*) branch="${line#branch refs/heads/}" ;;
+      "detached") branch="-" ;;
+      "locked"*) locked="1" ;;
+      "") [[ -n "$wt_path" ]] && printf '%s\t%s\t%s\n' "$wt_path" "${branch:--}" "$locked"
+          wt_path=""; branch=""; locked="0" ;;
+    esac
+  done < <(git -C "$root" worktree list --porcelain 2>/dev/null)
+  [[ -n "$wt_path" ]] && printf '%s\t%s\t%s\n' "$wt_path" "${branch:--}" "$locked"
+}
+
+# _wt_branch_merged <root> <branch> — true when <branch> is an ancestor of origin/${KIT_BASE_BRANCH:-main} (landed).
+_wt_branch_merged() {
+  local root="$1" branch="$2"
+  [[ -n "$branch" && "$branch" != "-" ]] || return 1
+  git -C "$root" merge-base --is-ancestor "refs/heads/$branch" origin/${KIT_BASE_BRANCH:-main} 2>/dev/null
+}
+
+# _wt_is_clean <path> — true only when the worktree exists AND has no staged/unstaged/untracked
+# changes. A missing/zombie dir (git -C fails) is reported NOT clean, so it can never be recycled.
+_wt_is_clean() {
+  local out
+  out="$(git -C "$1" status --porcelain 2>/dev/null)" || return 1
+  [[ -z "$out" ]]
+}
+
+# _wt_session_owns <root> <path> — true when a LIVE Claude session sits in <path> (or a subdir),
+# per the kit-sessions registry (.git/kit-sessions/*.json, written by session-registry.sh). A dead
+# pid is not an owner. No registry → no known live owner (returns false).
+_wt_session_owns() {
+  local root="$1" wt_path="$2" common reg f opid ocwd
+  common="$(git -C "$root" rev-parse --path-format=absolute --git-common-dir 2>/dev/null)" || return 1
+  reg="$common/kit-sessions"
+  [[ -d "$reg" ]] || return 1
+  for f in "$reg"/*.json; do
+    [[ -e "$f" ]] || continue
+    case "$f" in "$reg"/cache-*) continue ;; esac
+    opid="$(jq -r '.pid // 0' "$f" 2>/dev/null)"
+    [[ "$opid" =~ ^[1-9][0-9]*$ ]] || continue
+    kill -0 "$opid" 2>/dev/null || continue
+    ocwd="$(jq -r '.cwd // empty' "$f" 2>/dev/null)"
+    case "$ocwd" in "$wt_path"|"$wt_path"/*) return 0 ;; esac
+  done
+  return 1
+}
+
+# _wt_pool_find <root> <target> — path of the OLDEST reusable pooled worktree, or nothing. Applies
+# the full eligibility gate above; <target> (the path wt_start is about to use) is always excluded.
+_wt_pool_find() {
+  local root="$1" target="$2" wtdir best="" best_mt="" wt_path branch locked mt
+  wtdir="$root/.claude/worktrees/"
+  while IFS=$'\t' read -r wt_path branch locked; do
+    [[ -n "$wt_path" ]] || continue
+    case "$wt_path" in "$wtdir"*) : ;; *) continue ;; esac
+    [[ "$wt_path" == "$target" ]] && continue
+    [[ -d "$wt_path" ]] || continue
+    [[ "$locked" == "1" ]] && continue
+    _wt_branch_merged "$root" "$branch" || continue
+    _wt_is_clean "$wt_path" || continue
+    _wt_session_owns "$root" "$wt_path" && continue
+    mt="$(_wt_mtime "$wt_path")"; [[ "$mt" =~ ^[0-9]+$ ]] || mt=0
+    if [[ -z "$best" || "$mt" -lt "$best_mt" ]]; then best="$wt_path"; best_mt="$mt"; fi
+  done < <(_wt_list "$root")
+  [[ -n "$best" ]] && printf '%s\n' "$best"
+}
+
+# wt_pool_status — diagnostic listing of pooled worktrees + their reuse signals (read-only; never
+# mutates). Shows branch / merged-into-develop? / clean? / live-session? / overall reusable?.
+wt_pool_status() {
+  local root wtdir wt_path branch locked merged clean owned reusable any=0
+  root="$(git worktree list --porcelain | awk '/^worktree /{print $2; exit}')"
+  [[ -n "$root" ]] || { echo "wt_pool_status: not in a git repo" >&2; return 1; }
+  wtdir="$root/.claude/worktrees/"
+  git -C "$root" fetch origin "${KIT_BASE_BRANCH:-main}" --quiet 2>/dev/null || true
+  printf '%-44s %-26s %-7s %-6s %-8s %s\n' "WORKTREE" "BRANCH" "MERGED" "CLEAN" "SESSION" "REUSABLE"
+  while IFS=$'\t' read -r wt_path branch locked; do
+    [[ -n "$wt_path" ]] || continue
+    case "$wt_path" in "$wtdir"*) : ;; *) continue ;; esac
+    any=1
+    _wt_branch_merged "$root" "$branch" && merged="yes" || merged="no"
+    _wt_is_clean "$wt_path" && clean="yes" || clean="no"
+    _wt_session_owns "$root" "$wt_path" && owned="live" || owned="-"
+    if [[ "$locked" != "1" && "$merged" == "yes" && "$clean" == "yes" && "$owned" == "-" ]]; then
+      reusable="yes"
+    else
+      reusable="no"
+    fi
+    printf '%-44s %-26s %-7s %-6s %-8s %s\n' "${wt_path#"$wtdir"}" "$branch" "$merged" "$clean" "$owned" "$reusable"
+  done < <(_wt_list "$root")
+  [[ "$any" == "1" ]] || echo "(no pooled worktrees under $wtdir)"
+}
+
+wt_start() {
+  local num="${1:-}" slug_override="${2:-}" root meta title kind slug branch wt reused cand
+  [[ -n "$num" ]] || { echo "wt_start: issue number required" >&2; return 1; }
+
+  root="$(git worktree list --porcelain | awk '/^worktree /{print $2; exit}')"
+  [[ -n "$root" ]] || { echo "wt_start: not in a git repo" >&2; return 1; }
+
+  # The board's Status is set server-side by built-in automations (Item closed→Done, PR
+  # merged→Done) — wt_start no longer writes In Progress, so no board helpers are loaded here.
+
+  meta="$(gh issue view "$num" --repo "$WT_START_REPO" --json title,labels 2>/dev/null)" \
+    || { echo "[#$num] issue not found" >&2; return 1; }
+  title="$(echo "$meta" | jq -r '.title')"
+  kind="$(echo "$meta" | jq -r '([.labels[].name | select(startswith("kind:"))][0] // "kind:task") | sub("^kind:";"")')"
+  if [[ -n "$slug_override" ]]; then
+    slug="$slug_override"
+  else
+    slug="$(echo "$title" \
+      | sed -E 's/^\[[^]]+\][[:space:]]*//' \
+      | tr '[:upper:]' '[:lower:]' \
+      | sed -E 's/[^a-z0-9]+/-/g; s/^-+|-+$//g' \
+      | cut -c1-40)"
+  fi
+  branch="$kind/$num-$slug"
+  wt="$root/.claude/worktrees/${kind}+${num}-${slug}"
+
+  git -C "$root" fetch origin "${KIT_BASE_BRANCH:-main}" --quiet
+  if git -C "$root" worktree list --porcelain | grep -q "/${kind}+${num}-${slug}$"; then
+    echo "[#$num] reusing worktree $wt" >&2
+  else
+    reused=""
+    # OPT-IN (KIT_WT_POOL=1): recycle an idle, already-landed worktree instead of creating one.
+    # Safe by construction: _wt_pool_find only returns a clean, merged, session-free tree, and we
+    # only attempt it when the new branch does not yet exist — so re-pointing can't collide with a
+    # branch checked out elsewhere. Any hiccup leaves `reused` empty and falls through to the
+    # unchanged create path below; with the flag off this whole block is skipped.
+    if [[ "${KIT_WT_POOL:-0}" == "1" ]] && ! git -C "$root" show-ref --verify --quiet "refs/heads/$branch"; then
+      cand="$(_wt_pool_find "$root" "$wt")"
+      if [[ -n "$cand" ]] && git -C "$root" worktree move "$cand" "$wt" >/dev/null 2>&1; then
+        # The recycled tree is now at the conventional path with its env + dependencies intact
+        # (they moved with the dir — the pool's whole payoff). Re-point it to a fresh branch off
+        # the latest develop; the clean+merged+branch-absent preconditions make -B reliable.
+        git -C "$wt" checkout -B "$branch" origin/${KIT_BASE_BRANCH:-main} >/dev/null 2>&1 || true
+        reused="1"
+        echo "[#$num] reused idle worktree $wt" >&2
+      fi
+    fi
+    if [[ -z "$reused" ]]; then
+      git -C "$root" worktree add -B "$branch" "$wt" origin/${KIT_BASE_BRANCH:-main} >/dev/null 2>&1 \
+        || { echo "[#$num] worktree add failed (branch $branch may exist elsewhere)" >&2; return 1; }
+      echo "[#$num] created worktree $wt (branch $branch)" >&2
+    fi
+  fi
+
+  # Bootstrap the worktree for local dev: copy local env, install deps, assign a dev port (#773).
+  # Best-effort — a bootstrap hiccup never fails the start.
+  wt_bootstrap "$root" "$wt" "$num" || true
+
+  # Register with zoxide so `kit cd <issue|slug>` can jump here (no-op when zoxide is absent).
+  command -v zoxide >/dev/null && zoxide add "$wt" >/dev/null 2>&1 || true
+
+  # Mark the issue In Progress on the board. The board's built-in automations own the other
+  # transitions server-side (Item added→Todo, PR linked→In Review, closed/merged→Done) — but GitHub
+  # has no "branch started" trigger, so the kit owns In Progress. Cheap now: an O(1) issue.projectItems
+  # lookup on the org board, not a full-board scan. Best-effort — a board hiccup never fails the start.
+  if source "$root/scripts/lib/gh-project.sh" 2>/dev/null; then
+    [[ -n "${STATUS_FIELD_ID:-}" ]] || load_project_ids >/dev/null 2>&1 || true
+    item="$(project_find_item_by_issue "$num" 2>/dev/null)"
+    if [[ -z "$item" ]]; then
+      local content_id
+      content_id="$(gh api graphql -f query='query($o:String!,$r:String!,$n:Int!){repository(owner:$o,name:$r){issue(number:$n){id}}}' \
+        -F o="${WT_START_REPO%/*}" -F r="${WT_START_REPO#*/}" -F n="$num" --jq '.data.repository.issue.id' 2>/dev/null)"
+      [[ -n "$content_id" ]] && item="$(project_add_item "$content_id" 2>/dev/null)"
+    fi
+    [[ -n "$item" && -n "${STATUS_FIELD_ID:-}" && -n "${STATUS_OPT_IN_PROGRESS:-}" ]] \
+      && project_set_single_select "$item" "$STATUS_FIELD_ID" "$STATUS_OPT_IN_PROGRESS" >/dev/null 2>&1 \
+      && echo "[#$num] board → In Progress" >&2 || true
+  fi
+
+  echo "$wt|$branch|$num"
+}