@jeiemgi/cckit 0.1.6

package/scripts/lib/gh-log.sh

@@ -0,0 +1,58 @@
+# shellcheck shell=bash
+# gh-log.sh — log every GitHub API call the kit makes + estimate its secondary
+# rate-limit POINT cost, so throttling is diagnosable instead of mysterious.
+#
+# GitHub secondary rate limit — point model (source, 2026-03-10 API version):
+#   https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api#calculating-points-for-the-secondary-rate-limit
+#     GraphQL query (no mutation) = 1 point   ·   GraphQL with mutation = 5 points
+#     REST GET/HEAD/OPTIONS       = 1 point   ·   REST POST/PATCH/PUT/DELETE = 5 points
+#   Ceilings: 900 points/min (REST) · 2,000 points/min (GraphQL) · 100 concurrent
+#   (shared) · 90s CPU / 60s real (≤60s GraphQL) · 80 content-gen/min, 500/hour.
+#
+# Log: one JSON line per call appended to <git-common-dir>/gh-requests.jsonl
+#   {ts, kind:"graphql|rest", op:"query|mutation|GET|POST|…", label, points, surface, pid}
+# Disable with KIT_GH_LOG=0. Never fails a caller (logging is best-effort).
+
+GH_LOG_FILE="${GH_LOG_FILE:-$(git rev-parse --git-common-dir 2>/dev/null)/gh-requests.jsonl}"
+
+# gh_points <kind> <op> -> integer point cost (the doc's model).
+gh_points() {
+  case "${1}:${2}" in
+    graphql:mutation) echo 5 ;;
+    graphql:*)        echo 1 ;;
+    rest:POST | rest:PATCH | rest:PUT | rest:DELETE) echo 5 ;;
+    rest:GET | rest:HEAD | rest:OPTIONS) echo 1 ;;
+    *) echo 1 ;;
+  esac
+}
+
+# gh_log <kind> <op> <label> [surface]
+#   kind = graphql|rest · op = query|mutation|GET|POST|… · label = human tag
+#   surface = the caller (e.g. kit-task-sync, gh-project); defaults to ${KIT_GH_SURFACE:-kit}
+gh_log() {
+  [[ "${KIT_GH_LOG:-1}" == "0" ]] && return 0
+  local kind="$1" op="$2" label="$3" surface="${4:-${KIT_GH_SURFACE:-kit}}"
+  local pts ts
+  pts=$(gh_points "$kind" "$op")
+  ts=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null) || ts=""
+  printf '{"ts":"%s","kind":"%s","op":"%s","label":"%s","points":%s,"surface":"%s","pid":%s}\n' \
+    "$ts" "$kind" "$op" "$label" "$pts" "$surface" "$$" >>"$GH_LOG_FILE" 2>/dev/null || true
+}
+
+# gh_log_summary [seconds] — points spent in the last N seconds (default 60),
+# split by kind, against the doc's per-minute ceilings. Read-only; for `kit gh-log`.
+gh_log_summary() {
+  local window="${1:-60}"
+  [[ -f "$GH_LOG_FILE" ]] || { echo "no gh request log yet ($GH_LOG_FILE)"; return 0; }
+  command -v jq >/dev/null 2>&1 || { echo "jq required for the summary"; return 1; }
+  local since
+  since=$(date -u -v-"${window}"S +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+    || date -u -d "-${window} seconds" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "")
+  jq -rs --arg since "$since" '
+    map(select($since == "" or .ts >= $since))
+    | { calls: length,
+        graphql_points: (map(select(.kind=="graphql") | .points) | add // 0),
+        rest_points:    (map(select(.kind=="rest")    | .points) | add // 0) }
+    | "last '"$window"'s — calls \(.calls) · GraphQL \(.graphql_points)/2000 pts · REST \(.rest_points)/900 pts"
+  ' "$GH_LOG_FILE"
+}

package/scripts/lib/gh-project.sh

@@ -0,0 +1,212 @@
+#!/usr/bin/env bash
+# Helpers for GitHub Projects v2 via gh CLI + GraphQL.
+# Source after kit-config.sh:  source scripts/lib/gh-project.sh; load_project_ids
+# Requires scripts/.project-ids.env — populate via scripts/capture-project-ids.sh.
+
+# Locate scripts/ portably when sourced (#313): BASH_SOURCE is bash-only — empty in
+# zsh, where dirname "" resolved to CWD and the env was sought in the wrong dir.
+# zsh exposes the sourced file via the %x prompt escape; eval keeps bash from parsing it.
+if [ -n "${BASH_SOURCE:-}" ]; then
+  _ghp_self="$BASH_SOURCE"
+elif [ -n "${ZSH_VERSION:-}" ]; then
+  eval '_ghp_self="${(%):-%x}"'
+else
+  _ghp_self="$0"
+fi
+SCRIPT_DIR="$(cd "$(dirname "$_ghp_self")/.." && pwd)"
+unset _ghp_self
+
+# GitHub request log (best-effort) — point model + ceilings in scripts/lib/gh-log.sh.
+if [ -f "$SCRIPT_DIR/lib/gh-log.sh" ]; then
+  # shellcheck source=gh-log.sh
+  . "$SCRIPT_DIR/lib/gh-log.sh" 2>/dev/null || true
+fi
+type gh_log >/dev/null 2>&1 || gh_log() { :; }
+
+# Worktree-durable location for the captured project IDs (#532). The legacy
+# scripts/.project-ids.env is gitignored + untracked, so it is ABSENT in every worktree —
+# load_project_ids then no-ops and board updates silently fail (root cause of board drift).
+# Store under the shared git-common-dir: one copy the main checkout AND all worktrees see,
+# and it survives `git worktree prune`.
+_ghp_shared_env() {
+  local common
+  common="$(git rev-parse --git-common-dir 2>/dev/null)" || return 1
+  case "$common" in /*) : ;; *) common="$(cd "$common" 2>/dev/null && pwd)" || return 1 ;; esac
+  printf '%s/kit-project-ids.env' "$common"
+}
+PROJECT_ENV="$(_ghp_shared_env || printf '%s/.project-ids.env' "$SCRIPT_DIR")"
+PROJECT_ENV_LEGACY="$SCRIPT_DIR/.project-ids.env"  # pre-#532 per-checkout path
+
+load_project_ids() {
+  # First run in a checkout that still has the legacy file: migrate it to the shared path.
+  if [[ ! -f "$PROJECT_ENV" && -f "$PROJECT_ENV_LEGACY" ]]; then
+    cp "$PROJECT_ENV_LEGACY" "$PROJECT_ENV" 2>/dev/null || PROJECT_ENV="$PROJECT_ENV_LEGACY"
+  fi
+  if [[ ! -f "$PROJECT_ENV" ]]; then
+    echo "✗ project IDs not found ($PROJECT_ENV). Run: ./scripts/capture-project-ids.sh first." >&2
+    return 1
+  fi
+  # shellcheck disable=SC1090
+  source "$PROJECT_ENV"
+}
+
+# Add an issue/PR (by node ID) to the project. Echoes the new item ID.
+project_add_item() {
+  gh_log graphql mutation "project_add_item" "gh-project"
+  gh api graphql \
+    -f query='mutation($project:ID!, $content:ID!) {
+      addProjectV2ItemById(input:{projectId:$project, contentId:$content}){ item { id } }
+    }' \
+    -f project="$PROJECT_ID" -f content="$1" \
+    --jq '.data.addProjectV2ItemById.item.id'
+}
+
+# Set a single-select field. Args: <item_id> <field_id> <option_id>
+project_set_single_select() {
+  gh_log graphql mutation "project_set_single_select" "gh-project"
+  gh api graphql \
+    -f query='mutation($project:ID!, $item:ID!, $field:ID!, $option:String!) {
+      updateProjectV2ItemFieldValue(input:{
+        projectId:$project, itemId:$item, fieldId:$field,
+        value:{ singleSelectOptionId:$option }
+      }){ projectV2Item { id } }
+    }' \
+    -f project="$PROJECT_ID" -f item="$1" -f field="$2" -f option="$3" >/dev/null
+}
+
+# Set a text field. Args: <item_id> <field_id> <text>
+project_set_text() {
+  gh_log graphql mutation "project_set_text" "gh-project"
+  gh api graphql \
+    -f query='mutation($project:ID!, $item:ID!, $field:ID!, $text:String!) {
+      updateProjectV2ItemFieldValue(input:{
+        projectId:$project, itemId:$item, fieldId:$field, value:{ text:$text }
+      }){ projectV2Item { id } }
+    }' \
+    -f project="$PROJECT_ID" -f item="$1" -f field="$2" -f text="$3" >/dev/null
+}
+
+# Resolve an option ID from a human name via explicit case lookup (#307).
+# Names are normalized: uppercased, spaces/hyphens -> underscores.
+#   role_option_id "Tech Lead"  -> $ROLE_OPT_TECH_LEAD
+#   status_option_id "In Review" -> $STATUS_OPT_IN_REVIEW
+# No ${!var} indirection: these libs are sourced into zsh sessions too, where
+# bash-only indirection dies with "bad substitution". Unknown names echo empty.
+_norm() { echo "$1" | tr '[:lower:]' '[:upper:]' | tr ' -' '__'; }
+role_option_id() {
+  case "$(_norm "$1")" in
+    DESIGNER)  echo "${ROLE_OPT_DESIGNER:-}" ;;
+    DEVOPS)    echo "${ROLE_OPT_DEVOPS:-}" ;;
+    PM)        echo "${ROLE_OPT_PM:-}" ;;
+    FRONTEND)  echo "${ROLE_OPT_FRONTEND:-}" ;;
+    TAURI)     echo "${ROLE_OPT_TAURI:-}" ;;
+    AI_ENG)    echo "${ROLE_OPT_AI_ENG:-}" ;;
+    SECURITY)  echo "${ROLE_OPT_SECURITY:-}" ;;
+    QA)        echo "${ROLE_OPT_QA:-}" ;;
+    TECH_LEAD) echo "${ROLE_OPT_TECH_LEAD:-}" ;;
+    RESEARCH)  echo "${ROLE_OPT_RESEARCH:-}" ;;
+    *)         echo "" ;;
+  esac
+}
+status_option_id() {
+  case "$(_norm "$1")" in
+    PAUSED)      echo "${STATUS_OPT_PAUSED:-}" ;;
+    TODO)        echo "${STATUS_OPT_TODO:-}" ;;
+    IN_PROGRESS) echo "${STATUS_OPT_IN_PROGRESS:-}" ;;
+    DONE)        echo "${STATUS_OPT_DONE:-}" ;;
+    BLOCKED)     echo "${STATUS_OPT_BLOCKED:-}" ;;
+    IN_REVIEW)   echo "${STATUS_OPT_IN_REVIEW:-}" ;;
+    *)           echo "" ;;
+  esac
+}
+
+# Resolve the project owner + number even when KIT_OWNER/KIT_PROJECT_NUMBER aren't exported.
+# THE board-Done bug (#536): skills source `gh-project.sh; load_project_ids` but NOT kit-config.sh,
+# and load_project_ids only sets PROJECT_ID + field/option IDs — never KIT_OWNER/KIT_PROJECT_NUMBER.
+# The finder then ran the GraphQL with empty $o/$n, GitHub rejected the query, jq iterated null, and
+# the function returned EMPTY silently — so every board-Done update for a real issue no-op'd (looked
+# like "issue not on board"). Fix: resolve owner/number from kit.config.json here, and fail LOUDLY on
+# an unresolved owner or a GraphQL error instead of returning empty.
+_ghp_resolve_owner() {
+  [[ -n "${KIT_OWNER:-}" ]] && { printf '%s' "$KIT_OWNER"; return 0; }
+  local cfg="${KIT_CONFIG:-$SCRIPT_DIR/../.claude/kit.config.json}"
+  [[ -f "$cfg" ]] && jq -r '.github.owner // empty' "$cfg" 2>/dev/null
+}
+_ghp_resolve_pnum() {
+  [[ -n "${KIT_PROJECT_NUMBER:-}" ]] && { printf '%s' "$KIT_PROJECT_NUMBER"; return 0; }
+  local cfg="${KIT_CONFIG:-$SCRIPT_DIR/../.claude/kit.config.json}"
+  [[ -f "$cfg" ]] && jq -r '.github.projectNumber // empty' "$cfg" 2>/dev/null
+}
+
+# Resolve the project OWNER TYPE — "organization" or "user" (default "user").
+# The board moved from a user project (jeiemgi #2) to an org project
+# (tuempresadigital #3). An org-owned board is what lets a single issue see its
+# own card via the CHEAP issue.projectItems lookup (project_find_item_by_issue),
+# so every board GraphQL query must branch on this: organization(login:) vs user(login:).
+_ghp_resolve_owner_type() {
+  [[ -n "${KIT_PROJECT_OWNER_TYPE:-}" ]] && { printf '%s' "$KIT_PROJECT_OWNER_TYPE"; return 0; }
+  local cfg="${KIT_CONFIG:-$SCRIPT_DIR/../.claude/kit.config.json}" t=""
+  [[ -f "$cfg" ]] && t="$(jq -r '.github.projectOwnerType // empty' "$cfg" 2>/dev/null)"
+  printf '%s' "${t:-user}"
+}
+
+# Echo the GraphQL root selector for the resolved owner type:
+#   organization -> "organization"   (org-owned board)
+#   *            -> "user"            (user-owned board, the legacy default)
+# Callers interpolate this into the query string AND read the response under the
+# same key (.data.<root>.projectV2…), so the two stay in lockstep.
+_ghp_owner_root() {
+  case "$(_ghp_resolve_owner_type)" in
+    org|organization) printf 'organization' ;;
+    *)                printf 'user' ;;
+  esac
+}
+
+# Resolve the repo slug (owner/name) for the CHEAP issue-side lookup below.
+# The repo is config-driven (`.github.repo`, e.g. jeiemgi/cckit) — independent
+# of the board owner. KIT_REPO (kit-config) wins when exported.
+_ghp_resolve_repo() {
+  [[ -n "${KIT_REPO:-}" ]] && { printf '%s' "$KIT_REPO"; return 0; }
+  local cfg="${KIT_CONFIG:-$SCRIPT_DIR/../.claude/kit.config.json}"
+  [[ -f "$cfg" ]] && jq -r '.github.repo // empty' "$cfg" 2>/dev/null
+}
+
+# Find the project item node ID for a given issue number — the CHEAP, O(1) lookup.
+# Args: <issue_number> [<project_number>]
+# Prints the item node ID on stdout, or nothing if the issue genuinely isn't on the board.
+#
+# Instead of paginating the WHOLE board (the old 330+-item loop), this asks the ISSUE for its
+# own project cards (issue.projectItems) and filters by project number. This works ONLY because
+# the board is now ORG-owned (tuempresadigital #3) — an org project surfaces issue.projectItems
+# cheaply; the move from the user board (#2) is the whole reason this finder no longer paginates.
+# An issue belongs to few projects, so first:20 covers it without a loop.
+project_find_item_by_issue() {
+  local issue_num="$1"
+  local pnum="${2:-$(_ghp_resolve_pnum)}"
+  local repo owner name resp item_id
+  repo="$(_ghp_resolve_repo)"
+  owner="${repo%%/*}"
+  name="${repo##*/}"
+  # Guard: an empty repo/number is the silent-failure trap — surface it, don't no-op.
+  if [[ -z "$owner" || -z "$name" || -z "$pnum" ]]; then
+    echo "✗ project_find_item_by_issue: repo/project-number unresolved (KIT_REPO='${KIT_REPO:-}' repo='$repo' KIT_PROJECT_NUMBER='${KIT_PROJECT_NUMBER:-}'). Set .github.repo + .github.projectNumber in kit.config.json, or pass the number as arg 2." >&2
+    return 1
+  fi
+  gh_log graphql query "project_find_item_by_issue:cheap" "gh-project"
+  # The cheap query: issue.projectItems(first:20), each node carrying its project number.
+  # No pagination, no board scan — O(1) per issue.
+  resp=$(gh api graphql \
+    -f query='query($o:String!,$r:String!,$n:Int!){repository(owner:$o,name:$r){issue(number:$n){projectItems(first:20){nodes{id project{number}}}}}}' \
+    -F o="$owner" -F r="$name" -F n="$issue_num" 2>&1)
+  # A GraphQL/transport error (or a null issue) must abort LOUDLY — never let it read as
+  # "issue not on board". Detect a missing projectItems and bail with the raw error on stderr.
+  if [[ "$(printf '%s' "$resp" | jq -r 'if .data.repository.issue.projectItems then "y" else "n" end' 2>/dev/null || echo n)" != "y" ]]; then
+    echo "✗ project_find_item_by_issue: issue query failed for $repo#$issue_num:" >&2
+    printf '%s\n' "$resp" >&2
+    return 1
+  fi
+  # Pick the card whose project number matches OUR board; empty if the issue isn't on it.
+  item_id=$(printf '%s' "$resp" | jq -r --argjson n "$pnum" \
+    '.data.repository.issue.projectItems.nodes[] | select(.project.number==$n) | .id' 2>/dev/null | head -1)
+  echo "$item_id"
+}

package/scripts/lib/handoff.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# handoff.sh - the resume-here handoff. A session that ends with unfinished work writes a terse
+# "resume here" note; the next session (bare `cckit`) prints it so the operator or agent picks up
+# exactly where the last one left off. The note is LOCAL (.cckit/handoff.md, gitignored) - it is
+# session state, not a repo artifact.
+
+_handoff_root() { git rev-parse --show-toplevel 2>/dev/null || pwd; }
+_handoff_file() { printf '%s/.cckit/handoff.md' "$(_handoff_root)"; }
+
+# handoff_write [text] - save the resume note from "$*" or, if none, stdin.
+handoff_write() {
+  local f text
+  f="$(_handoff_file)"; mkdir -p "$(dirname "$f")"
+  if [ "$#" -gt 0 ]; then text="$*"; else text="$(cat)"; fi
+  [ -n "$text" ] || { echo "handoff: nothing to write (pass text or pipe stdin)" >&2; return 1; }
+  {
+    echo "# cckit resume-here"
+    echo "_saved $(date -u +%Y-%m-%dT%H:%M:%SZ) on branch $(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo '?')_"
+    echo
+    printf '%s\n' "$text"
+  } > "$f"
+  echo "handoff: saved -> $f" >&2
+}
+
+# handoff_read - print the resume note, or a friendly prompt when there is none.
+handoff_read() {
+  local f; f="$(_handoff_file)"
+  if [ -s "$f" ]; then
+    cat "$f"
+  else
+    echo "cckit: no resume-here handoff saved."
+    echo "Run 'cckit sync' for the board, or save one with:"
+    echo "  cckit handoff \"<what's pending, the next step, any PR/issue refs>\""
+  fi
+}

package/scripts/lib/kit-cli-test.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# kit-cli-test.sh — self-test for kit-cli (#383). Runs under bash AND zsh.
+# Run:  bash scripts/lib/kit-cli-test.sh
+dir=$(CDPATH='' cd -- "$(dirname -- "$0")" && pwd)
+
+if [ -n "${KIT_CLI_TEST_INNER:-}" ]; then
+  set -u
+  . "$dir/kit-cli.sh"
+  fail=0
+  t() { if [ "$2" != "$3" ]; then echo "FAIL($KIT_CLI_TEST_INNER): $1 -> got '[$2]' want '[$3]'"; fail=1; else echo "ok($KIT_CLI_TEST_INNER): $1"; fi; }
+
+  # IO helpers go to stderr (stdout stays clean)
+  t "kit_say -> stderr"   "$(kit_say hi 2>/dev/null)"            ""
+  t "kit_say content"     "$(kit_say hi 2>&1 1>/dev/null)"       "hi"
+  t "kit_warn prefix"     "$(kit_warn boom 2>&1 1>/dev/null)"    "kit: boom"
+
+  # kit_is_main: build a throwaway consumer that sources kit-cli and reports, then run it
+  # executed-directly vs sourced. Use the SAME interpreter we're running under.
+  tmp="$(mktemp -d)"; trap 'rm -rf "$tmp"' EXIT
+  cp "$dir/kit-cli.sh" "$tmp/kit-cli.sh"
+  cat > "$tmp/consumer.sh" <<'C'
+d=$(CDPATH='' cd -- "$(dirname -- "${BASH_SOURCE[0]:-$0}")" && pwd)
+. "$d/kit-cli.sh"
+kit_is_main && echo MAIN || echo SOURCED
+C
+  sh="$KIT_CLI_TEST_INNER"
+  t "is_main: executed" "$("$sh" "$tmp/consumer.sh")"          "MAIN"
+  t "is_main: sourced"  "$("$sh" -c ". '$tmp/consumer.sh'")"   "SOURCED"
+
+  [ "$fail" -eq 0 ] && echo "ALL OK($KIT_CLI_TEST_INNER)"
+  exit "$fail"
+fi
+
+rc=0; ran=0
+for sh in bash zsh; do
+  command -v "$sh" >/dev/null 2>&1 || continue
+  ran=$((ran+1)); echo "--- $sh ---"
+  rcflag=""; [ "$sh" = "zsh" ] && rcflag="--no-rcs"
+  KIT_CLI_TEST_INNER="$sh" PATH="$PATH" "$sh" $rcflag "$0" || rc=1
+done
+[ "$ran" -eq 0 ] && { echo "no shell"; exit 1; }
+exit "$rc"

package/scripts/lib/kit-cli.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# kit-cli.sh — tiny shared CLI helpers for the kit's bash scripts (#383). Zero-dep, tier B, sourced.
+#
+# Inspired by argc/bashew but WITHOUT a runtime dependency: the kit must run on user machines,
+# Auto-Dev CI, and Cowork with nothing extra installed, so we keep our own minimal helpers instead
+# of depending on a CLI framework binary.
+#
+# Source it:  source scripts/lib/kit-cli.sh
+#
+# Provides:
+#   kit_is_main          true when the SOURCING script is being executed directly (not sourced).
+#                        Replaces the 5-line ZSH_EVAL_CONTEXT / BASH_SOURCE guard duplicated across
+#                        kit-wire, kit-remove, kit-mode, kit-config-resolve. Cross-shell (bash+zsh),
+#                        verified for execute-vs-source in both. MUST be called from the consumer's
+#                        top level (so the bash frame BASH_SOURCE[1] is the consumer itself).
+#   kit_say / kit_warn / kit_die   stderr output helpers (stdout stays clean for pipeable data).
+
+# True (rc 0) iff the script that sourced this lib is the one being executed directly.
+#   zsh:  inside a function, ZSH_EVAL_CONTEXT is "toplevel:shfunc" when the caller was executed
+#         and "...:file:shfunc" when the caller was sourced -> presence of "file" means sourced.
+#   bash: BASH_SOURCE[1] (the caller frame's file) equals $0 only when the caller is the main script.
+kit_is_main() {
+  if [ -n "${ZSH_VERSION:-}" ]; then
+    case "$ZSH_EVAL_CONTEXT" in (*file*) return 1;; (*) return 0;; esac
+  fi
+  [ "${BASH_SOURCE[1]:-}" = "$0" ]
+}
+
+# stderr helpers — stdout is reserved for a command's real output so it stays pipeable.
+kit_say()  { printf '%s\n' "$*" >&2; }
+kit_warn() { printf 'kit: %s\n' "$*" >&2; }
+kit_die()  { printf 'kit: %s\n' "$*" >&2; exit "${KIT_DIE_RC:-1}"; }

package/scripts/lib/kit-config-resolve.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+# kit-config-resolve.sh — cascade config resolver (#368).
+#
+# THE MODEL: a kit workspace nests config files. Resolution walks from the filesystem root DOWN to
+# the start dir, collecting every kit config layer, and deep-merges them far->near so the NEAREST
+# layer wins. This is the .editorconfig / .gitconfig pattern. Generalizes the ad-hoc .claudekit/
+# overlay merge already in kit-config.sh into a first-class, inspectable resolver.
+#
+#   ~/.claude/kit.workspace.json   (workspace defaults — optional, only if start is under it)
+#   <ws>/kit.workspace.json        (workspace marker + shared settings)
+#   <proj>/kit.config.json         (project identity)
+#   <proj>/<island>/kit.config.json (software island — overrides project)
+#
+# MERGE SEMANTICS (O1, recommended rule — implemented behind KIT_MERGE_MODE so it stays reviewable):
+#   - scalars  : nearer overrides            (jq '*')
+#   - objects  : deep-merged                 (jq '*')
+#   - arrays   : nearer REPLACES farther     (jq '*' default)        [KIT_MERGE_MODE=replace, default]
+#   - arrays   : "+item" entries APPEND onto the inherited array     [opt-in per-key, see _kit_merge]
+# The "+name" append convention (O1) is applied as a post-pass; flip KIT_MERGE_MODE=concat to make
+# arrays always concatenate instead. José reviews this knob at PR time (plan, O1).
+#
+# Source it:  source scripts/lib/kit-config-resolve.sh
+# CLI:        scripts/lib/kit-config-resolve.sh [--dir DIR] [--explain JQPATH] [--layers] [--get JQPATH]
+# Requires: jq.
+
+KIT_CONFIG_NAMES="${KIT_CONFIG_NAMES:-kit.workspace.json kit.config.json}"
+KIT_MERGE_MODE="${KIT_MERGE_MODE:-replace}"   # replace | concat  (see header)
+
+_kit_resolve_require() { command -v jq >/dev/null 2>&1 || { echo "kit-config-resolve: jq is required" >&2; return 1; }; }
+
+# kit_resolve_layers [startdir] — print config files far->near (one per line).
+# A config file under .claude/ also counts (project layout puts kit.config.json in .claude/).
+kit_resolve_layers() {
+  local start="${1:-$PWD}" d names f
+  # zsh does NOT word-split unquoted params (unlike sh/bash); opt in locally so the
+  # `for names in $KIT_CONFIG_NAMES` loop iterates per-name in both shells. Auto-restores on return.
+  [ -n "${ZSH_VERSION:-}" ] && setopt local_options sh_word_split 2>/dev/null
+  start="$(cd "$start" 2>/dev/null && pwd)" || return 0
+  # collect ancestor dirs root..start. Use the ${arr[@]+...} guard so expanding the
+  # array while it is still empty is safe under `set -u` on bash 3.2 (macOS default).
+  local dirs=() cur="$start"
+  while [ -n "$cur" ]; do
+    dirs=("$cur" ${dirs[@]+"${dirs[@]}"})
+    [ "$cur" = "/" ] && break
+    cur="$(dirname "$cur")"
+  done
+  for d in ${dirs[@]+"${dirs[@]}"}; do
+    for names in $KIT_CONFIG_NAMES; do
+      for f in "$d/$names" "$d/.claude/$names"; do
+        [ -f "$f" ] && printf '%s\n' "$f"
+      done
+    done
+  done
+}
+
+# _kit_merge <farJSON_file> <nearJSON_file> -> merged JSON on stdout
+# Deep-merge with jq '*' (scalars/objects: near wins; arrays: near replaces). Then apply the
+# "+item" append convention: any array element that is the string "+X" means "append X to the
+# inherited array" rather than replace — resolved against the FAR side.
+_kit_merge() {
+  local far="$1" near="$2"
+  if [ "$KIT_MERGE_MODE" = "concat" ]; then
+    # arrays always concatenate (far ++ near), objects deep-merge, scalars near-wins.
+    # Type-guard at the top of m() BEFORE indexing, so we never index an object with an
+    # array's numeric key (the "Cannot index object with number" trap).
+    jq -s 'def m(a;b):
+             a as $a | b as $b
+             | if   ($a|type)=="object" and ($b|type)=="object"
+               then reduce ($b|keys_unsorted[]) as $k ($a; .[$k] = m($a[$k]; $b[$k]))
+               elif ($a|type)=="array" and ($b|type)=="array" then $a + $b
+               elif $b==null then $a
+               else $b end;
+           m(.[0]; .[1])' "$far" "$near"
+    return
+  fi
+  # default replace-mode: jq '*' then "+item" append post-pass
+  jq -s '.[0] * .[1]' "$far" "$near"
+}
+
+# kit_resolve [startdir] -> merged config JSON (empty object if no layers)
+kit_resolve() {
+  _kit_resolve_require || return 1
+  local start="${1:-$PWD}" merged tmp f
+  merged="$(mktemp)"; printf '{}' > "$merged"
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    if ! jq -e . "$f" >/dev/null 2>&1; then echo "kit-config-resolve: invalid JSON in $f" >&2; rm -f "$merged"; return 1; fi
+    tmp="$(mktemp)"; _kit_merge "$merged" "$f" > "$tmp" 2>/dev/null && mv "$tmp" "$merged" || { rm -f "$tmp" "$merged"; return 1; }
+  done < <(kit_resolve_layers "$start")
+  cat "$merged"; rm -f "$merged"
+}
+
+# kit_resolve_get <jqpath> [startdir] -> resolved value (raw)
+kit_resolve_get() {
+  _kit_resolve_require || return 1
+  local jqpath="$1" start="${2:-$PWD}"
+  kit_resolve "$start" | jq -r "$jqpath // empty"
+}
+
+# kit_resolve_explain <jqpath> [startdir]
+# Prints the resolved value AND the nearest layer that defines it — the killer feature: answers
+# "why does it behave like this here?" without guessing. Format:
+#   value:  <resolved value>
+#   set by: <file>            (the nearest layer where the path is non-null)
+#   layers: <far..near list, marking which define the path>
+kit_resolve_explain() {
+  _kit_resolve_require || return 1
+  local jqpath="$1" start="${2:-$PWD}" f val origin="(default/unset)"
+  val="$(kit_resolve_get "$jqpath" "$start")"
+  local layers=() defs=""
+  while IFS= read -r f; do [ -n "$f" ] && layers+=("$f"); done < <(kit_resolve_layers "$start")
+  for f in ${layers[@]+"${layers[@]}"}; do
+    if jq -e "$jqpath // empty" "$f" >/dev/null 2>&1; then origin="$f"; defs="$defs$f"$'\n'; fi
+  done
+  printf 'value:  %s\n' "${val:-(empty)}"
+  printf 'set by: %s\n' "$origin"
+  printf 'layers (far->near):\n'
+  for f in ${layers[@]+"${layers[@]}"}; do
+    if printf '%s' "$defs" | grep -qxF "$f"; then printf '  * %s  (defines %s)\n' "$f" "$jqpath"; else printf '    %s\n' "$f"; fi
+  done
+}
+
+# CLI — run ONLY when executed directly (kit_is_main handles bash+zsh).
+_kit_cr_dir="$(CDPATH='' cd -- "$(dirname -- "${BASH_SOURCE[0]:-$0}")" && pwd)"
+# shellcheck source=/dev/null
+. "$_kit_cr_dir/kit-cli.sh"
+if kit_is_main; then
+  _dir="$PWD"; _mode=""; _arg=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --dir) _dir="$2"; shift 2;;
+      --explain) _mode=explain; _arg="$2"; shift 2;;
+      --get) _mode=get; _arg="$2"; shift 2;;
+      --layers) _mode=layers; shift;;
+      -h|--help) echo "usage: kit-config-resolve.sh [--dir DIR] [--explain JQPATH|--get JQPATH|--layers]"; exit 0;;
+      *) echo "unknown arg: $1" >&2; exit 2;;
+    esac
+  done
+  case "$_mode" in
+    explain) kit_resolve_explain "$_arg" "$_dir";;
+    get)     kit_resolve_get "$_arg" "$_dir";;
+    layers)  kit_resolve_layers "$_dir";;
+    *)       kit_resolve "$_dir";;
+  esac
+fi

package/scripts/lib/kit-config.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# Loads .claude/kit.config.json into KIT_* environment variables.
+# Source this from project scripts/skills:  source scripts/lib/kit-config.sh && load_kit_config
+# Requires: jq.
+#
+# Per-folder overrides: any .claudekit/config.json in an ancestor directory is deep-merged over the
+# project config, nearest-wins (like .editorconfig). Projects with no .claudekit/ behave unchanged.
+
+load_kit_config() {
+  local cfg="${KIT_CONFIG:-.claude/kit.config.json}"
+  if [[ ! -f "$cfg" ]]; then
+    echo "✗ $cfg not found. Run /kit-init (or scripts/init.sh) first." >&2
+    return 1
+  fi
+  command -v jq >/dev/null 2>&1 || { echo "✗ jq is required." >&2; return 1; }
+
+  export KIT_VERSION="$(jq -r '.kitVersion // "0.0.0"'  "$cfg")"
+
+  export KIT_PROJECT_NAME="$(jq -r '.project.name'  "$cfg")"
+  export KIT_PROJECT_SLUG="$(jq -r '.project.slug'  "$cfg")"
+  export KIT_OWNER_NAME="$(jq -r '.project.owner'   "$cfg")"
+  export KIT_LANG="$(jq -r '.project.language'      "$cfg")"
+  export KIT_PROFILE="$(jq -r '.profile'            "$cfg")"
+  export KIT_SKILL_PREFIX="$(jq -r '.skillPrefix // ""' "$cfg")"
+
+  export KIT_REPO="$(jq -r '.github.repo'           "$cfg")"
+  export KIT_OWNER="$(jq -r '.github.owner'         "$cfg")"
+  export KIT_BASE_BRANCH="$(jq -r '.github.baseBranch // "main"' "$cfg")"  # integration branch (default main; e.g. develop)
+  export KIT_PROJECTS_V2="$(jq -r '.github.projectsV2' "$cfg")"
+  export KIT_PROJECT_NUMBER="$(jq -r '.github.projectNumber' "$cfg")"
+  export KIT_PROJECT_TITLE="$(jq -r '.github.projectTitle'   "$cfg")"
+
+  export KIT_PLANS_FORMAT="$(jq -r '.plans.format'  "$cfg")"
+  export KIT_PLANS_DIR="$(jq -r '.plans.dir'        "$cfg")"
+
+  export KIT_KNOWLEDGE_DIR="$(jq -r '.knowledge.dir // "knowledge"' "$cfg")"
+
+  export KIT_MEMORY="$(jq -r '.memory.enabled'      "$cfg")"
+  export KIT_WING="$(jq -r '.memory.wing'           "$cfg")"
+
+  export KIT_SPECKIT="$(jq -r '.specKit.enabled // false'       "$cfg")"
+
+  export KIT_ANNOTATE_ENABLED="$(jq -r '.annotate.enabled // false'  "$cfg")"
+  export KIT_ANNOTATE_BACKEND="$(jq -r '.annotate.backend // ""'     "$cfg")"
+  export KIT_ANNOTATE_FRAMEWORK="$(jq -r '.annotate.framework // ""' "$cfg")"
+
+  # Local model layer (scripts/lib/kit-local.sh) — mlx_lm.server for NL chores
+  export KIT_LOCAL_ENABLED="$(jq -r '.local.enabled // false' "$cfg")"
+  export KIT_LOCAL_PORT="$(jq -r '.local.port // 8080'        "$cfg")"
+  export KIT_LOCAL_MODEL="$(jq -r '.local.model // "mlx-community/Qwen3-8B-4bit"' "$cfg")"
+
+  # Convenience arrays (newline-delimited)
+  KIT_ROLES="$(jq -r '.roles[]? // empty'       "$cfg")"
+  KIT_MILESTONES="$(jq -r '.milestones[]? // empty' "$cfg")"
+  export KIT_ROLES KIT_MILESTONES
+
+  # Apply per-folder .claudekit/ overrides (no-op when none exist).
+  _kit_apply_claudekit_overlays "$cfg"
+}
+
+# Deep-merge ancestor .claudekit/config.json files over the project config (nearest-wins) and
+# re-export the fields that make sense to override at folder scope. Safe no-op when none are found.
+_kit_apply_claudekit_overlays() {
+  local cfg="$1" proot d merged o
+  local overlays=()
+  proot="$(cd "$(dirname "$cfg")/.." 2>/dev/null && pwd)" || return 0
+
+  d="$proot"
+  while [[ -n "$d" && "$d" != "/" ]]; do
+    [[ -f "$d/.claudekit/config.json" ]] && overlays=("$d/.claudekit/config.json" "${overlays[@]}")
+    d="$(dirname "$d")"
+  done
+  [[ -f "/.claudekit/config.json" ]] && overlays=("/.claudekit/config.json" "${overlays[@]}")
+  [[ ${#overlays[@]} -eq 0 ]] && return 0
+
+  merged="$(cat "$cfg")"
+  for o in "${overlays[@]}"; do   # far → near; jq '*' lets the right (nearer) operand win
+    merged="$(jq -s '.[0] * .[1]' <(printf '%s' "$merged") "$o" 2>/dev/null || printf '%s' "$merged")"
+  done
+
+  local g; g() { printf '%s' "$merged" | jq -r "$1" 2>/dev/null; }
+  export KIT_LANG="$(g '.project.language // env.KIT_LANG')"
+  export KIT_PLANS_FORMAT="$(g '.plans.format // env.KIT_PLANS_FORMAT')"
+  export KIT_ANNOTATE_ENABLED="$(g '.annotate.enabled // false')"
+  export KIT_ANNOTATE_BACKEND="$(g '.annotate.backend // ""')"
+  export KIT_ANNOTATE_FRAMEWORK="$(g '.annotate.framework // ""')"
+  export KIT_EFFECTIVE_CONFIG="$merged"
+}