@jeiemgi/cckit 0.1.6

package/scripts/orchestrate.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+# orchestrate.sh - run N issue flows as live tmux panes, each an agent in its own worktree.
+#
+# For each issue: create an isolated worktree + branch off the configured base branch
+# (cckit.config.json: github.repo + github.baseBranch), then open a tmux session with one tiled
+# pane per flow running the agent command. Branches must be file-disjoint - the flows edit in
+# parallel, so disjointness is the caller's responsibility.
+#
+# Agent-agnostic: the per-pane command defaults to `claude` but is overridable, so cckit drives any
+# CLI agent that takes a prompt as its first argument.
+#   --agent <cmd> / CCKIT_AGENT=<cmd>
+#
+# Hardening:
+#   --dry-run      resolve + print the launch plan; create no worktrees, start no panes
+#   --cap <N>      concurrency cap: launch at most N flows (default 4); the rest are queued + reported
+#   blocked_by     an issue whose native GitHub blocked_by edge points at an OPEN issue is skipped
+#                  (override with --force)
+#   set -euo pipefail + explicit pipe handling throughout
+#
+# Usage:
+#   cckit orchestrate <issueA> <issueB> [<issueC> ...]
+#   cckit orchestrate --dry-run 6 7 8
+#   cckit orchestrate --cap 3 --agent codex 2 3 6 9
+#   cckit orchestrate --no-seed 6 7          # don't auto-prompt each agent
+#   cckit orchestrate --force 7              # launch even if blocked_by an open issue
+#   cckit orchestrate --session=sweep 1 2    # custom tmux session name
+#   cckit orchestrate --detach 6 7           # build the session, don't attach (testing/headless)
+set -euo pipefail
+
+SESSION="orchestrate"
+SEED=1
+DRYRUN=0
+FORCE=0
+DETACH=0
+CAP=4
+AGENT="${CCKIT_AGENT:-claude}"
+ISSUES=()
+
+usage() { sed -n '2,28p' "$0" | sed 's/^# \{0,1\}//'; }
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --no-seed)   SEED=0; shift ;;
+    --dry-run)   DRYRUN=1; shift ;;
+    --force)     FORCE=1; shift ;;
+    --detach)    DETACH=1; shift ;;
+    --cap)       CAP="$2"; shift 2 ;;
+    --cap=*)     CAP="${1#*=}"; shift ;;
+    --agent)     AGENT="$2"; shift 2 ;;
+    --agent=*)   AGENT="${1#*=}"; shift ;;
+    --session=*) SESSION="${1#*=}"; shift ;;
+    -h|--help)   usage; exit 0 ;;
+    [0-9]*)      ISSUES+=("$1"); shift ;;
+    *)           echo "orchestrate: unknown arg '$1'" >&2; exit 2 ;;
+  esac
+done
+
+[ "${#ISSUES[@]}" -ge 1 ] || { echo "orchestrate: pass at least one issue number" >&2; usage; exit 2; }
+case "$CAP" in ''|*[!0-9]*) echo "orchestrate: --cap needs a number (got '$CAP')" >&2; exit 2 ;; esac
+
+# Resolve the main worktree root + load config (repo + base branch drive everything).
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(git -C "$SCRIPT_DIR" worktree list --porcelain | awk '/^worktree /{print $2; exit}')"
+[ -n "$ROOT" ] || { echo "orchestrate: not in a git repo" >&2; exit 1; }
+# shellcheck source=/dev/null
+source "$ROOT/scripts/lib/kit-config.sh" && load_kit_config
+REPO="$KIT_REPO"
+
+# blocked_by gate: echo the OPEN blocker numbers of an issue (native GitHub dependency edge).
+open_blockers() {
+  local n="$1" b st blk
+  blk="$(gh api "repos/$REPO/issues/$n/dependencies/blocked_by" --jq '.[].number' 2>/dev/null || true)"
+  for b in $blk; do
+    st="$(gh issue view "$b" --repo "$REPO" --json state --jq .state 2>/dev/null || echo OPEN)"
+    [ "$st" = "OPEN" ] && printf '%s ' "$b"
+  done
+}
+
+# Partition the requested issues into eligible / blocked / (later) queued.
+ELIGIBLE=()
+echo "orchestrate: repo $REPO (base ${KIT_BASE_BRANCH:-main}), cap $CAP, agent '$AGENT'"
+for num in "${ISSUES[@]}"; do
+  blockers="$(open_blockers "$num")"
+  if [ -n "$blockers" ] && [ "$FORCE" -eq 0 ]; then
+    echo "  #$num  SKIP - blocked_by open: ${blockers% }"
+  else
+    [ -n "$blockers" ] && echo "  #$num  FORCED past open blockers: ${blockers% }"
+    ELIGIBLE+=("$num")
+  fi
+done
+[ "${#ELIGIBLE[@]}" -ge 1 ] || { echo "orchestrate: nothing eligible to launch" >&2; exit 1; }
+
+# Concurrency cap: launch the first CAP eligible flows; queue + report the rest.
+LAUNCH=()
+QUEUE=()
+i=0
+for num in "${ELIGIBLE[@]}"; do
+  if [ "$i" -lt "$CAP" ]; then LAUNCH+=("$num"); else QUEUE+=("$num"); fi
+  i=$((i + 1))
+done
+[ "${#QUEUE[@]}" -eq 0 ] || echo "  queued past cap (run a later wave): ${QUEUE[*]}"
+
+if [ "$DRYRUN" -eq 1 ]; then
+  echo "orchestrate: DRY RUN - would launch ${#LAUNCH[@]} flow(s): ${LAUNCH[*]}"
+  echo "             (no worktrees created, no panes started)"
+  exit 0
+fi
+
+command -v tmux >/dev/null || { echo "orchestrate: tmux not installed (brew install tmux)" >&2; exit 1; }
+command -v "$AGENT" >/dev/null || { echo "orchestrate: agent '$AGENT' not on PATH" >&2; exit 1; }
+
+# shellcheck source=/dev/null
+source "$ROOT/scripts/lib/worktree-start.sh"
+
+# Headless seed: the agent runs with NO human present - it must never ask, decide autonomously,
+# gauge difficulty + apply proportional effort, and close no-op issues itself. cckit verbs only.
+seed_for() {
+  local num="$1" branch="$2"
+  printf '%s' "You are running HEADLESS inside a cckit orchestration: there is NO human to answer \
+questions, so NEVER ask - decide autonomously and proceed. Gauge the task difficulty and apply \
+proportional effort. Worktree + branch $branch for issue #$num are ready. Run: gh issue view $num, \
+implement it, run bash scripts/check.sh until green, then open the PR with: cckit pr $num \"<summary>\". \
+If it is a no-op (nothing to change), comment why and run: cckit close $num \"<reason>\". Do not wait for input."
+}
+
+ENTRIES=()
+for num in "${LAUNCH[@]}"; do
+  entry="$(wt_start "$num")" || { echo "orchestrate: wt_start #$num failed" >&2; exit 1; }
+  ENTRIES+=("$entry")
+done
+
+tmux kill-session -t "$SESSION" 2>/dev/null || true
+first=1
+for entry in "${ENTRIES[@]}"; do
+  wt="${entry%%|*}"; rest="${entry#*|}"; branch="${rest%%|*}"; num="${rest##*|}"
+  if [ "$first" -eq 1 ]; then
+    tmux new-session -d -s "$SESSION" -n flows -c "$wt"
+    pane="$(tmux display -p -t "$SESSION:flows" '#{pane_id}')"
+    first=0
+  else
+    pane="$(tmux split-window -t "$SESSION:flows" -c "$wt" -P -F '#{pane_id}')"
+    tmux select-layout -t "$SESSION:flows" tiled >/dev/null
+  fi
+  if [ "$SEED" -eq 1 ]; then
+    tmux send-keys -t "$pane" "$AGENT \"$(seed_for "$num" "$branch")\"" C-m
+  else
+    tmux send-keys -t "$pane" "$AGENT" C-m
+  fi
+done
+tmux select-layout -t "$SESSION:flows" tiled >/dev/null
+tmux set -t "$SESSION" mouse on
+tmux select-window -t "$SESSION:flows" 2>/dev/null || true
+
+hint="tabs/panes: click to focus, or Ctrl-b <number> - Ctrl-b d detaches"
+if [ "$DETACH" -eq 1 ]; then
+  echo "orchestrate: session '$SESSION' built ($hint). Attach: tmux attach -t $SESSION"
+else
+  echo "orchestrate: attaching to '$SESSION' - $hint"
+  tmux attach -t "$SESSION"
+fi

package/scripts/portable-test.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# portable-test.sh — cckit must operate on the project it is INVOKED in, not its install dir (#41).
+# Regression test for the bug where `cckit sync` in another repo read cckit's own config and so
+# reported an empty board `[]`. Hermetic: stubs `gh` (no network/auth). Run: bash scripts/portable-test.sh
+set -u
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+CCKIT="$ROOT/bin/cckit"
+fail=0
+t() { if [ "$2" = "$3" ]; then echo "ok: $1"; else echo "FAIL: $1 -> got '[$2]' want '[$3]'"; fail=1; fi; }
+
+command -v jq >/dev/null 2>&1 || { echo "portable-test: jq required" >&2; exit 1; }
+
+# Stub gh on PATH: record the --repo it is asked for (to stderr), return an empty JSON array.
+stub="$(mktemp -d)"
+cat > "$stub/gh" <<'SH'
+#!/usr/bin/env bash
+prev=""
+for a in "$@"; do
+  [ "$prev" = "--repo" ] && printf 'REPO=%s\n' "$a" >&2
+  prev="$a"
+done
+echo "[]"
+SH
+chmod +x "$stub/gh"
+
+# A foreign project with its own config pointing at a DISTINCT repo.
+fix="$(mktemp -d)"
+cat > "$fix/cckit.config.json" <<'JSON'
+{ "kitVersion": "9.9.9", "project": {"name":"fixture"}, "github": {"repo":"octo/fixture-repo","owner":"octo","baseBranch":"main"} }
+JSON
+( cd "$fix" && git init -q ) 2>/dev/null
+
+# 1) From the fixture, sync resolves the fixture's config → targets the fixture's repo.
+got_repo="$(cd "$fix" && PATH="$stub:$PATH" "$CCKIT" sync --llm 2>&1 >/dev/null | sed -n 's/^REPO=//p' | tail -1)"
+t "sync targets the invoking project's repo" "$got_repo" "octo/fixture-repo"
+
+# 2) From the fixture, scan reports the fixture as root (no cd to the install dir).
+got_root="$(cd "$fix" && "$CCKIT" scan --llm 2>/dev/null | jq -r .root)"
+t "scan root is the invoking dir" "$got_root" "$(cd "$fix" && pwd -P)"
+
+# 3) Self-hosting: from the cckit repo, sync still targets cckit's own repo.
+own_repo="$(jq -r '.github.repo' "$ROOT/cckit.config.json")"
+got_own="$(cd "$ROOT" && PATH="$stub:$PATH" "$CCKIT" sync --llm 2>&1 >/dev/null | sed -n 's/^REPO=//p' | tail -1)"
+t "self-host sync targets cckit's repo" "$got_own" "$own_repo"
+
+# 4) `version` is the INSTALLED version regardless of where it is invoked.
+inst_ver="$(jq -r '.kitVersion' "$ROOT/cckit.config.json")"
+got_ver="$(cd "$fix" && "$CCKIT" version | awk '{print $2}')"
+t "version is the install version, not the project's" "$got_ver" "$inst_ver"
+
+rm -rf "$stub" "$fix"
+[ "$fail" -eq 0 ] && echo "ALL OK (portable)" || echo "portable: FAILURES"
+exit "$fail"

package/scripts/publish.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# publish.sh - cut a cckit release and (optionally) publish to the Homebrew tap + npm.
+#
+# SAFE BY DEFAULT: a dry run that changes nothing and prints every step. It only acts when you
+# pass --publish. Built so you can hand it a version later and ship in one command.
+#
+# Usage:
+#   scripts/publish.sh 0.1.0                 # DRY RUN - show the plan, change nothing
+#   scripts/publish.sh 0.1.0 --publish       # execute: tag + GitHub release + formula + npm
+#   scripts/publish.sh 0.1.0 --publish --no-npm     # skip npm (brew only)
+#   scripts/publish.sh 0.1.0 --publish --no-brew    # skip brew (npm only)
+# Env: TAP_DIR=~/Dev/jeiemgi/homebrew-cckit (where the tap repo is cloned)
+set -euo pipefail
+
+VERSION="${1:-}"; shift || true
+PUBLISH=0; DO_NPM=1; DO_BREW=1
+for a in "$@"; do case "$a" in
+  --publish) PUBLISH=1 ;; --no-npm) DO_NPM=0 ;; --no-brew) DO_BREW=0 ;;
+  *) echo "unknown flag: $a" >&2; exit 2 ;;
+esac; done
+
+[ -n "$VERSION" ] || { echo "usage: scripts/publish.sh <version> [--publish] [--no-npm] [--no-brew]" >&2; exit 2; }
+echo "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$' || { echo "version must be X.Y.Z" >&2; exit 2; }
+
+root="$(cd "$(dirname "$0")/.." && pwd)"
+repo="jeiemgi/cckit"
+tag="v$VERSION"
+tarball="https://github.com/$repo/archive/refs/tags/$tag.tar.gz"
+tap_dir="${TAP_DIR:-$HOME/Dev/jeiemgi/homebrew-cckit}"
+
+run() { if [ "$PUBLISH" = 1 ]; then echo "+ $*"; "$@"; else echo "DRY: $*"; fi; }
+
+mode="DRY-RUN"; [ "$PUBLISH" = 1 ] && mode="PUBLISH"
+echo "== cckit publish $tag  (mode: $mode) =="
+
+if [ "$PUBLISH" = 1 ]; then
+  [ -z "$(git -C "$root" status --porcelain)" ] || { echo "x working tree not clean" >&2; exit 1; }
+  [ "$(git -C "$root" branch --show-current)" = "main" ] || { echo "x not on main" >&2; exit 1; }
+  ! git -C "$root" rev-parse "$tag" >/dev/null 2>&1 || { echo "x tag $tag already exists" >&2; exit 1; }
+  command -v gh >/dev/null || { echo "x gh required" >&2; exit 1; }
+fi
+
+# 1. Stamp version, tag, and cut the GitHub release (creates the tarball).
+run bash -c "cd '$root' && command -v jq >/dev/null && jq '.kitVersion=\"$VERSION\"' cckit.config.json > .v.tmp && mv .v.tmp cckit.config.json || true"
+run git -C "$root" add -A
+run git -C "$root" commit -m "release: $tag"
+run git -C "$root" tag "$tag"
+run git -C "$root" push origin main --tags
+run gh release create "$tag" --repo "$repo" --title "$tag" --generate-notes
+
+# 2. Compute the tarball sha256 for the stable Homebrew formula.
+if [ "$PUBLISH" = 1 ]; then
+  echo "+ fetching sha256 of $tarball"
+  SHA="$(curl -fsSL "$tarball" | shasum -a 256 | cut -d' ' -f1)"
+  echo "  sha256=$SHA"
+else
+  SHA="<computed-at-publish>"; echo "DRY: curl -fsSL $tarball | shasum -a 256"
+fi
+
+# 3. Inject the stable url+sha256 block into the formula (idempotent).
+formula="$root/Formula/cckit.rb"
+if [ "$PUBLISH" = 1 ]; then
+  if grep -q 'url "https' "$formula"; then
+    perl -0pi -e "s{url \"https[^\"]*\"}{url \"$tarball\"}; s{sha256 \"[^\"]*\"}{sha256 \"$SHA\"}; s{version \"[^\"]*\"}{version \"$VERSION\"}" "$formula"
+  else
+    perl -0pi -e "s{(  homepage[^\n]*\n)}{\$1  url \"$tarball\"\n  sha256 \"$SHA\"\n  version \"$VERSION\"\n}" "$formula"
+  fi
+  echo "+ updated $formula"
+else
+  echo "DRY: inject url=$tarball sha256=$SHA version=$VERSION into Formula/cckit.rb"
+fi
+
+# 4. Homebrew tap: copy the formula into the tap repo and push.
+if [ "$DO_BREW" = 1 ]; then
+  if [ -d "$tap_dir/.git" ]; then
+    run mkdir -p "$tap_dir/Formula"
+    run cp "$formula" "$tap_dir/Formula/cckit.rb"
+    run git -C "$tap_dir" add Formula/cckit.rb
+    run git -C "$tap_dir" commit -m "cckit $VERSION"
+    run git -C "$tap_dir" push
+    echo "   users: brew tap jeiemgi/cckit && brew install cckit"
+  else
+    echo "  ! tap repo not at $tap_dir - create it: gh repo create jeiemgi/homebrew-cckit --public"
+  fi
+fi
+
+# 5. npm publish (scoped, public).
+if [ "$DO_NPM" = 1 ]; then
+  run npm publish --access public
+  echo "   users: npm i -g @jeiemgi/cckit"
+fi
+
+done_msg="dry run - nothing changed"; [ "$PUBLISH" = 1 ] && done_msg="published"
+echo "== done ($done_msg) =="

package/scripts/setup-labels.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Create the kind:/priority:/role: label families on the repo. Idempotent.
+# Reads repo + roles from .claude/kit.config.json. Run from project root.
+set -euo pipefail
+source "$(dirname "$0")/lib/kit-config.sh" && load_kit_config
+
+ensure_label() { # name color description
+  gh label create "$1" --repo "$KIT_REPO" --color "$2" --description "$3" --force >/dev/null 2>&1 \
+    && echo "  ✓ $1" || echo "  • $1 (exists)"
+}
+
+echo "→ Labels on $KIT_REPO"
+echo "kinds:"
+for k in task plan adr scaffold spike; do ensure_label "kind:$k" "5319e7" "Kind: $k"; done
+echo "priorities:"
+ensure_label "priority:p1" "b60205" "Now / blocking"
+ensure_label "priority:p2" "fbca04" "Next"
+ensure_label "priority:p3" "0e8a16" "Later"
+echo "roles:"
+while IFS= read -r role; do
+  [[ -z "$role" ]] && continue
+  slug=$(echo "$role" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+  ensure_label "role:$slug" "1d76db" "Role: $role"
+done <<< "$KIT_ROLES"
+echo "✓ done"

package/scripts/setup-milestones.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Create the project's milestones on the repo. Idempotent.
+# Reads repo + milestones from .claude/kit.config.json. Run from project root.
+set -euo pipefail
+source "$(dirname "$0")/lib/kit-config.sh" && load_kit_config
+
+echo "→ Milestones on $KIT_REPO"
+existing=$(gh api "repos/$KIT_REPO/milestones?state=all" --jq '.[].title' 2>/dev/null || echo "")
+while IFS= read -r m; do
+  [[ -z "$m" ]] && continue
+  if echo "$existing" | grep -qxF "$m"; then
+    echo "  • $m (exists)"
+  else
+    gh api "repos/$KIT_REPO/milestones" -f title="$m" >/dev/null && echo "  ✓ $m"
+  fi
+done <<< "$KIT_MILESTONES"
+echo "✓ done"

package/scripts/showcase.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# showcase.sh — render the showcase dataset to screenshots + a docs gallery.
+#
+# Reads docs-site/showcase/showcase.json (the dataset), runs each (read-only / dry-run) cckit
+# command through charmbracelet/freeze with forced color, writes one PNG per command to
+# docs-site/public/showcase/, and regenerates the gallery page docs-site/src/content/docs/showcase.md.
+# The PNGs + page are committed artifacts, so the site builds without freeze; only regenerating
+# needs `freeze` (brew install charmbracelet/tap/freeze) and `jq`.
+#
+#   scripts/showcase.sh
+set -uo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+MANIFEST="$ROOT/docs-site/showcase/showcase.json"
+IMG_DIR="$ROOT/docs-site/public/showcase"
+GALLERY="$ROOT/docs-site/src/content/docs/showcase.md"
+
+command -v jq >/dev/null     || { echo "showcase: jq required" >&2; exit 1; }
+command -v freeze >/dev/null || { echo "showcase: freeze required (brew install charmbracelet/tap/freeze)" >&2; exit 1; }
+[ -f "$MANIFEST" ]           || { echo "showcase: $MANIFEST not found" >&2; exit 1; }
+
+# Use THIS checkout's cckit (so the captured behavior matches the branch), and force color so the
+# screenshots show cckit's TTY-gated palette even though freeze captures without a real terminal.
+# CCKIT_FORCE_COLOR is cckit-private (see ui.sh) so it never leaks into the gh/jq subprocesses.
+export PATH="$ROOT/bin:$PATH"
+export CCKIT_FORCE_COLOR=1
+mkdir -p "$IMG_DIR"
+
+# Gallery header.
+{
+  echo '---'
+  echo 'title: Showcase'
+  echo 'description: Every cckit capability at a glance — real command output captured as screenshots.'
+  echo '---'
+  echo
+  echo 'A live tour of cckit, generated from a dataset (`docs-site/showcase/showcase.json`) by'
+  echo '`scripts/showcase.sh`: each command is run for real and its output captured as a screenshot.'
+  echo 'Every command here is read-only or a dry-run — safe to run yourself.'
+  echo
+} > "$GALLERY"
+
+prev_group=""
+fail=0
+# Stream the dataset as tab-separated rows (no tabs/newlines inside fields).
+while IFS=$'\t' read -r name group title cmd show; do
+  [ -n "$name" ] || continue
+  out="$IMG_DIR/$name.png"
+  echo "==> $name : $cmd" >&2
+  # </dev/null so freeze never consumes this loop's stdin (the jq dataset stream).
+  if ! freeze --window --padding 20 --execute "$cmd" --output "$out" </dev/null >/dev/null 2>&1; then
+    echo "    FAILED to render $name" >&2; fail=1; continue
+  fi
+  if [ "$group" != "$prev_group" ]; then
+    printf '## %s\n\n' "$group" >> "$GALLERY"
+    prev_group="$group"
+  fi
+  {
+    printf '### %s\n\n' "$title"
+    printf '```bash\n%s\n```\n\n' "$show"
+    printf '![%s](/showcase/%s.png)\n\n' "$title" "$name"
+  } >> "$GALLERY"
+done < <(jq -r '.commands[] | [.name, .group, .title, .cmd, (.show // .cmd)] | @tsv' "$MANIFEST")
+
+echo "==> wrote $GALLERY and PNGs to $IMG_DIR" >&2
+exit "$fail"

package/scripts/status.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# status.sh - a thin, pure-bash status viewer: the board, active worktrees/branches, and the resume
+# handoff on one screen, using native terminal tools (ui.sh: color + TTY gating, glow/fzf when
+# present). This is the lightweight cockpit; the rich opentui TUI is an OPTIONAL separate adapter -
+# the core stays pure bash and dependency-light, so `cckit status` works in any terminal.
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck source=/dev/null
+source "$ROOT/scripts/lib/ui.sh" 2>/dev/null || true
+# shellcheck source=/dev/null
+source "$ROOT/scripts/lib/kit-config.sh" && load_kit_config
+
+hr() { printf '%s\n' "----------------------------------------------------------------"; }
+sec() { if command -v ui_paint >/dev/null 2>&1; then ui_paint '1;36' "$1"; else printf '%s' "$1"; fi; echo; }
+
+sec "cckit status - $KIT_REPO (base ${KIT_BASE_BRANCH:-main})"
+hr
+
+# Board: open issues, blocked count (reuse the read-only board JSON).
+sec "Board"
+board="$(bash "$ROOT/scripts/task-sync.sh" --llm 2>/dev/null || echo '[]')"
+if command -v jq >/dev/null 2>&1; then
+  open="$(printf '%s' "$board" | jq 'length' 2>/dev/null || echo 0)"
+  blocked="$(printf '%s' "$board" | jq '[.[]|select(.blocked)]|length' 2>/dev/null || echo 0)"
+  echo "  open issues: $open   blocked: $blocked"
+  printf '%s' "$board" | jq -r '.[:8][] | "  #\(.number)  \(.title[0:56])"' 2>/dev/null || true
+  [ "$open" -gt 8 ] && echo "  ... and $((open - 8)) more (cckit sync)"
+else
+  echo "  (jq absent - run cckit sync)"
+fi
+hr
+
+# Worktrees + branches: SAFE-to-prune vs active (reuse the gc analysis).
+sec "Worktrees and branches"
+# shellcheck source=/dev/null
+source "$ROOT/scripts/lib/kit-gc.sh"
+kit_gc_analyze 2>/dev/null | grep -E 'SAFE|ACTIVE|PROTECTED|ORPHAN' | head -12 | sed 's/^/  /' || echo "  (clean)"
+hr
+
+# Resume handoff, if one is saved.
+sec "Resume handoff"
+# shellcheck source=/dev/null
+source "$ROOT/scripts/lib/handoff.sh"
+handoff_read | sed 's/^/  /'

package/scripts/task-sync.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Read-only board status, grouped by role. Pure gh + jq. bash 3.2 compatible.
+# Reads repo from .claude/kit.config.json. Run from project root.
+#   ./scripts/task-sync.sh [--role <Name>] [--milestone <label>]
+set -euo pipefail
+source "$(dirname "$0")/lib/kit-config.sh" && load_kit_config
+
+ROLE_FILTER=""; MS_FILTER=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --role) ROLE_FILTER="$2"; shift 2 ;;
+    --milestone) MS_FILTER="$2"; shift 2 ;;
+    --llm|--output=json) CCKIT_OUTPUT=json; shift ;;
+    *) echo "unknown flag: $1" >&2; exit 1 ;;
+  esac
+done
+
+ISSUES=$(gh issue list --repo "$KIT_REPO" --state open --limit 200 \
+  --json number,title,labels,milestone,assignees,updatedAt,body)
+
+# Structured output for agents: emit the open board as a JSON array and stop (--llm / CCKIT_OUTPUT).
+if [ "${CCKIT_OUTPUT:-human}" = "json" ]; then
+  echo "$ISSUES" | jq -c '[.[] | {number, title, labels: [.labels[].name], milestone: (.milestone.title // null), blocked: ((.body // "") | test("Blocked by"))}]'
+  exit 0
+fi
+
+echo "## Board — $KIT_REPO"
+echo ""
+
+# Roles come from config; iterate in declared order, plus an "unlabeled" bucket.
+print_role() {
+  local role="$1" slug rows
+  slug=$(echo "$role" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+  rows=$(echo "$ISSUES" | jq -r --arg slug "role:$slug" --arg ms "$MS_FILTER" '
+    .[] | select(any(.labels[]; .name == $slug))
+        | select($ms == "" or (.milestone.title // "") == $ms)
+        | { n:.number, t:.title,
+            p:([.labels[].name | select(startswith("priority:"))][0] // "—" | sub("priority:";"")),
+            m:(.milestone.title // "—"),
+            blocked:(.body // "" | test("Blocked by")) }
+        | "| #\(.n) | \(.t) | \(.p) | \(.m) | \(if .blocked then "! blocked" else "—" end) |"')
+  [[ -z "$rows" ]] && return
+  echo "### $role"
+  echo "| # | Title | Pri | Milestone | Flag |"
+  echo "| - | ----- | --- | --------- | ---- |"
+  echo "$rows"
+  echo ""
+}
+
+if [[ -n "$ROLE_FILTER" ]]; then
+  print_role "$ROLE_FILTER"
+else
+  while IFS= read -r role; do [[ -n "$role" ]] && print_role "$role"; done <<< "$KIT_ROLES"
+fi
+
+BLOCKED=$(echo "$ISSUES" | jq -r '[.[] | select((.body // "") | test("Blocked by"))] | length')
+echo "**Blocked:** ${BLOCKED} item(s)"
+STALE=$(echo "$ISSUES" | jq -r '[.[] | .updatedAt] | length')
+echo "**Open total:** ${STALE}"

package/scripts/test.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# test.sh — cckit behavioral test runner. Discovers every `*-test.sh` under bin/ and scripts/ and
+# runs each as a self-contained test (a test exits non-zero on failure, prints its own ok/FAIL
+# lines). Exits non-zero if any test fails. bash 3.2 compatible (no mapfile/associative arrays).
+#
+#   scripts/test.sh            run every discovered test
+#   scripts/test.sh <pattern>  run only tests whose path matches <pattern> (grep -E)
+#
+# Folded into scripts/check.sh and run in CI (.github/workflows/test.yml).
+set -uo pipefail
+cd "$(cd "$(dirname "$0")/.." && pwd)"
+
+PATTERN="${1:-}"
+note() { printf '%s\n' "$*" >&2; }
+
+# Discover tests deterministically. Newline-separated, sorted, optionally filtered.
+tests=()
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  [ -z "$PATTERN" ] || printf '%s\n' "$f" | grep -qE "$PATTERN" || continue
+  tests+=("$f")
+done < <(find bin scripts -type f -name '*-test.sh' 2>/dev/null | sort)
+
+if [ "${#tests[@]}" -eq 0 ]; then
+  note "test: no *-test.sh found${PATTERN:+ matching '$PATTERN'}"
+  exit 0
+fi
+
+note "==> cckit tests — ${#tests[@]} file(s)${PATTERN:+ (filter: $PATTERN)}"
+pass=0; failn=0; failed=""
+for t in "${tests[@]}"; do
+  out="$(bash "$t" 2>&1)"; rc=$?
+  if [ "$rc" -eq 0 ]; then
+    pass=$((pass+1)); note "  ok   $t"
+  else
+    failn=$((failn+1)); failed="$failed$t"$'\n'
+    note "  FAIL $t  (rc=$rc)"
+    printf '%s\n' "$out" | sed 's/^/        /' >&2
+  fi
+done
+
+note ""
+note "==> $pass passed, $failn failed"
+if [ "$failn" -ne 0 ]; then
+  note "failed:"; printf '%s' "$failed" | sed 's/^/  - /' >&2
+  exit 1
+fi
+note "PASS all tests"

package/scripts/web-install.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# cckit remote installer — curl -fsSL <url> | bash
+# Clones (or updates) cckit into ~/.cckit and links `cckit` onto your PATH. No build, no npm/brew.
+# Works on macOS, Linux, and Windows via WSL / Git Bash. Honors $CCKIT_HOME.
+set -euo pipefail
+
+repo="https://github.com/jeiemgi/cckit.git"
+dest="${CCKIT_HOME:-$HOME/.cckit}"
+
+command -v git >/dev/null 2>&1 || { echo "cckit: git is required." >&2; exit 1; }
+
+if [ -d "$dest/.git" ]; then
+  echo "cckit: updating $dest"
+  git -C "$dest" pull --ff-only --quiet || echo "cckit: could not fast-forward; using existing checkout" >&2
+else
+  echo "cckit: cloning into $dest"
+  git clone --depth 1 --quiet "$repo" "$dest"
+fi
+
+# Delegate PATH linking to the in-repo installer (single source of truth).
+bash "$dest/scripts/install.sh"
+echo "cckit: done. Run 'cckit help' to get started."