@jeiemgi/cckit 0.1.6

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

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# kit-engine-test.sh — self-test for the kit engine core (manifest + resolver + operate), #368.
+# Libs are sourced into whatever shell the session runs (zsh on macOS), so they must behave
+# identically under bash AND zsh. Run:  bash scripts/lib/kit-engine-test.sh
+# Re-runs itself under every available shell; set KIT_ENGINE_TEST_INNER to run assertions in-process.
+
+set -u
+dir=$(CDPATH='' cd -- "$(dirname -- "$0")" && pwd)
+
+if [ -n "${KIT_ENGINE_TEST_INNER:-}" ]; then
+  . "$dir/kit-manifest.sh"
+  . "$dir/kit-config-resolve.sh"
+  . "$dir/kit-operate.sh"
+  fail=0
+  t() { # t <label> <got> <want>
+    if [ "$2" != "$3" ]; then echo "FAIL($KIT_ENGINE_TEST_INNER): $1 -> got '[$2]' want '[$3]'"; fail=1
+    else echo "ok($KIT_ENGINE_TEST_INNER): $1"; fi
+  }
+
+  work="$(mktemp -d)"; trap 'rm -rf "$work"' EXIT
+
+  # --- cascade fixture: workspace -> project -> island ---------------------
+  mkdir -p "$work/ws/proj/island/.claude" "$work/ws/proj/.claude" "$work/ws"
+  printf '{"project":{"language":"en"},"mode":"guided","roles":["pm","tech-lead"]}\n' > "$work/ws/kit.workspace.json"
+  printf '{"project":{"language":"es","name":"proj"},"mode":"enforced"}\n' > "$work/ws/proj/kit.config.json"
+  printf '{"mode":"enforced","roles":["backend"]}\n' > "$work/ws/proj/island/kit.config.json"
+
+  # layers far->near from island: workspace, project, island
+  layers="$(kit_resolve_layers "$work/ws/proj/island" | sed "s#$work/##g" | tr '\n' '|')"
+  t "layers order" "$layers" "ws/kit.workspace.json|ws/proj/kit.config.json|ws/proj/island/kit.config.json|"
+
+  # scalar override: language es (project) beats en (workspace)
+  t "scalar override (language)" "$(kit_resolve_get '.project.language' "$work/ws/proj/island")" "es"
+  # deep-merge keeps project name even though island doesn't mention project
+  t "deep-merge keeps name"      "$(kit_resolve_get '.project.name' "$work/ws/proj/island")" "proj"
+  # array replace: island roles replace workspace roles (replace mode)
+  t "array replace (roles)"      "$(kit_resolve_get '.roles | join(",")' "$work/ws/proj/island")" "backend"
+  # at project level (no island), roles come from workspace
+  t "array inherit at project"   "$(kit_resolve_get '.roles | join(",")' "$work/ws/proj")" "pm,tech-lead"
+  # mode: enforced at island
+  t "mode at island"             "$(kit_resolve_get '.mode' "$work/ws/proj/island")" "enforced"
+
+  # --explain origin: language is set by the project config (nearest definer)
+  origin="$(kit_resolve_explain '.project.language' "$work/ws/proj/island" | awk -F': ' '/^set by/{print $2}' | sed "s#$work/##")"
+  t "explain origin (language)"  "$origin" "ws/proj/kit.config.json"
+
+  # concat mode: arrays concatenate
+  cm="$(KIT_MERGE_MODE=concat kit_resolve_get '.roles | join(",")' "$work/ws/proj/island")"
+  t "concat mode (roles)"        "$cm" "pm,tech-lead,backend"
+
+  # --- manifest ------------------------------------------------------------
+  proj="$work/p"; mkdir -p "$proj/.claude"; cd "$proj"
+  export KIT_MANIFEST=".claude/kit.manifest.json"
+  printf 'hello\n' > tracked.txt
+  kit_manifest_record "tracked.txt" "A" "init" "1.0.0" "2026-01-01T00:00:00Z"
+  t "verify intact"     "$(kit_manifest_verify tracked.txt)" "intact"
+  printf 'changed\n' > tracked.txt
+  t "verify modified"   "$(kit_manifest_verify tracked.txt)" "modified"
+  rm -f tracked.txt
+  t "verify missing"    "$(kit_manifest_verify tracked.txt)" "missing"
+  t "verify untracked"  "$(kit_manifest_verify other.txt)"   "untracked"
+  printf 'x\n' > b.txt; kit_manifest_record "b.txt" "B" "wire" "1.0.0" "2026-01-01T00:00:00Z"
+  t "list tier B"       "$(kit_manifest_list B | tr '\n' ',')" "b.txt,"
+  kit_manifest_remove_entry "b.txt"
+  t "remove entry"      "$(kit_manifest_verify b.txt)" "untracked"
+
+  # --- operate -------------------------------------------------------------
+  printf 'SRC v1\n' > src.txt
+  # dry-run writes nothing
+  KIT_DRY_RUN=1 kit_op_write src.txt dst.txt A wire >/dev/null 2>&1
+  t "dry-run no write"  "$([ -f dst.txt ] && echo yes || echo no)" "no"
+  # real write with assume-yes
+  KIT_ASSUME_YES=1 kit_op_write src.txt dst.txt A wire >/dev/null 2>&1
+  t "op write created"  "$([ -f dst.txt ] && echo yes || echo no)" "yes"
+  t "op write tracked"  "$(kit_manifest_verify dst.txt)" "intact"
+  # idempotent: same content, no error, still intact
+  KIT_ASSUME_YES=1 kit_op_write src.txt dst.txt A wire >/dev/null 2>&1
+  t "op write idempotent" "$(kit_manifest_verify dst.txt)" "intact"
+  # conffiles: user edits dst, then op WITHOUT assume-yes must not clobber (declined => exit 10)
+  printf 'USER EDIT\n' > dst.txt
+  KIT_ASSUME_YES= kit_op_write src.txt dst.txt A wire </dev/null >/dev/null 2>&1
+  t "conffiles keeps edit" "$(cat dst.txt)" "USER EDIT"
+  # remove untracked refuses
+  printf 'z\n' > untracked2.txt
+  KIT_ASSUME_YES=1 kit_op_remove untracked2.txt >/dev/null 2>&1
+  t "remove refuses untracked" "$([ -f untracked2.txt ] && echo yes || echo no)" "yes"
+  # remove tracked-intact deletes (record fresh first to match current content)
+  printf 'SRC v1\n' > dst.txt; kit_manifest_record dst.txt A wire 1.0.0 2026-01-01T00:00:00Z
+  KIT_ASSUME_YES=1 kit_op_remove dst.txt >/dev/null 2>&1
+  t "remove intact deletes" "$([ -f dst.txt ] && echo yes || echo no)" "no"
+
+  [ "$fail" -eq 0 ] && echo "ALL OK($KIT_ENGINE_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 ---"
+  # -f / --no-rcs: skip user startup files (they can reset PATH); pass PATH explicitly so the
+  # subshell finds jq + coreutils regardless of the invoked shell's default environment.
+  rcflag=""; [ "$sh" = "zsh" ] && rcflag="--no-rcs"
+  KIT_ENGINE_TEST_INNER="$sh" PATH="$PATH" "$sh" $rcflag "$0" || rc=1
+done
+[ "$ran" -eq 0 ] && { echo "no shell found"; exit 1; }
+exit "$rc"

package/scripts/lib/kit-events.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# scripts/lib/kit-events.sh — the kit event bus (append-only JSONL).
+#
+# A durable, single-writer-safe event stream that kit ops emit to and the kit-ui
+# (packages/kit-ui) tails. Lives under $(git rev-parse --git-common-dir) so it is
+# WORKTREE-DURABLE and survives ephemeral session mounts (same home as kit-sessions
+# / kit-usage.jsonl). No second implementation: every kit op that wants to surface
+# progress to the TUI sources this file and calls emit_event.
+#
+# Event shape (one JSON object per line):
+#   { "ts": "<ISO-8601 UTC>", "type": "<type>", "op": "<op-name>", "payload": {…} }
+#
+# Types (the contract — packages/kit-ui/CONTRACT.md is the source of truth):
+#   op.start | op.progress | op.done     — lifecycle of a kit operation
+#   notice                               — a SessionStart-style notice (consolidated in the notice feed)
+#   collision                            — a worktree/file collision between two flows
+#   update-available                     — a kit version update is available
+#   flow.status                          — an orchestrate flow changed state
+#
+# Public API (source this file, then call):
+#   emit_event <type> <op> [payload-json]   -> appends one event line; payload defaults to {}
+#   kit_events_path                         -> prints the absolute path to kit-events.jsonl
+#
+# Always non-fatal: a failure to emit (no jq, unwritable dir) never breaks the caller.
+
+# Resolve the durable, absolute path to the event log.
+# git-common-dir may be relative (".git") — resolve it against the repo root.
+kit_events_path() {
+  local gcd
+  gcd="$(git rev-parse --git-common-dir 2>/dev/null)" || return 1
+  case "$gcd" in
+    /*) : ;;                                   # already absolute
+    *)  gcd="$(cd "$gcd" 2>/dev/null && pwd)" || return 1 ;;
+  esac
+  printf '%s/kit-events.jsonl\n' "$gcd"
+}
+
+# emit_event <type> <op> [payload-json]
+# payload-json must be a valid JSON object string; defaults to {}.
+emit_event() {
+  local type="${1:-}" op="${2:-}" payload="${3:-}"
+  [[ -n "$type" && -n "$op" ]] || return 0
+  [[ -n "$payload" ]] || payload='{}'
+  command -v jq >/dev/null 2>&1 || return 0
+
+  local path ts line
+  path="$(kit_events_path)" || return 0
+  ts="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+
+  # Build the line with jq so payload is validated + the record is well-formed.
+  # If payload isn't valid JSON, fall back to wrapping it as a string note.
+  line="$(jq -cn \
+            --arg ts "$ts" --arg type "$type" --arg op "$op" \
+            --argjson payload "$payload" \
+            '{ts:$ts, type:$type, op:$op, payload:$payload}' 2>/dev/null)" || \
+  line="$(jq -cn \
+            --arg ts "$ts" --arg type "$type" --arg op "$op" --arg raw "$payload" \
+            '{ts:$ts, type:$type, op:$op, payload:{note:$raw}}' 2>/dev/null)" || return 0
+
+  # Single-writer append; >> is atomic for short lines on local fs.
+  printf '%s\n' "$line" >> "$path" 2>/dev/null || return 0
+}

package/scripts/lib/kit-gc.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# kit-gc.sh — the canonical "garbage-collect the repo" git-mechanic (#373 / #419 extraction).
+#
+# Plugin mirror of the canonical scripts/lib/kit-gc.sh (#370 self-contained). Same op, one home.
+# Family 1 of kit-engine-boundary.md (rule #1/#2): ONE bash home for the gc op, consumed by the
+# kit-gc skill, `kit gc`, and the kit-ui Run cockpit (#816 — it shells `scripts/kit gc`). No second
+# implementation. This extracts the read-only ANALYSIS — branch/worktree/stash classification with
+# the issue-open protection — out of the skill so a UI can run a REAL verb (not just preview text).
+#
+# The DESTRUCTIVE prune stays interactive (the skill / a human drives the confirmed deletes); a
+# headless surface only ever runs the analysis. That split is deliberate: `kit_gc_analyze` is safe
+# to run anywhere, anytime (it writes nothing), so the cockpit can flip its `gc` verb to runnable.
+#
+#   kit_gc_analyze            print the classification table (read-only). rc 0 always.
+#   kit_gc_has_prunable       rc 0 if anything is safe to delete (for a UI badge / nudge).
+#
+# Requires: git; gh (degrades to "unknown" issue/PR state without it); scripts/lib/worktree-issue.sh.
+# Portable: bash 3.2+ AND zsh.
+
+KIT_GC_REPO="${KIT_GC_REPO:-${KIT_REPO:-}}"
+
+_kit_gc_root() { git worktree list --porcelain 2>/dev/null | awk '/^worktree /{print $2; exit}'; }
+
+# Source worktree-issue.sh (wt_issue_number / wt_protected_reason) from whatever lib dir we live in.
+_kit_gc_load_deps() {
+  command -v wt_protected_reason >/dev/null 2>&1 && return 0
+  local d; d="$(CDPATH='' cd -- "$(dirname -- "${BASH_SOURCE[0]:-$0}")" && pwd)"
+  # shellcheck source=/dev/null
+  [ -f "$d/worktree-issue.sh" ] && . "$d/worktree-issue.sh"
+}
+
+# kit_gc_analyze — read-only classification of worktrees, branches, and stashes. Writes NOTHING.
+# Each row is tagged PROTECTED / SAFE / ACTIVE / ORPHAN so a human or UI can decide what to prune.
+kit_gc_analyze() {
+  _kit_gc_load_deps
+  local repo="$KIT_GC_REPO" b ref path reason pr prot
+  git fetch origin --prune --quiet 2>/dev/null || true
+
+  echo "# worktrees"
+  git worktree list --porcelain 2>/dev/null \
+    | awk '/^worktree /{w=$2} /^branch /{print w" "$2}' \
+    | while read -r path ref; do
+        b="${ref#refs/heads/}"
+        reason="$(wt_protected_reason "$b" "$repo" 2>/dev/null || true)"
+        if [ -n "$reason" ]; then echo "  $path [$b] -> PROTECTED: $reason"
+        else echo "  $path [$b] -> prunable if PR merged"; fi
+      done
+
+  echo "# branches"
+  for b in $(git branch --format='%(refname:short)' 2>/dev/null); do
+    case "$b" in develop|main) echo "  $b -> ACTIVE (base branch)"; continue;; esac
+    pr="$(gh pr list --repo "$repo" --head "$b" --state all --json number,state --jq '.[0]|"PR#\(.number) \(.state)"' 2>/dev/null || true)"
+    prot="$(wt_protected_reason "$b" "$repo" 2>/dev/null || true)"
+    if [ -n "$prot" ]; then
+      echo "  $b -> PROTECTED: $prot"
+    elif printf '%s' "$pr" | grep -q 'MERGED'; then
+      echo "  $b -> SAFE (${pr}, issue closed/absent — verify level with remote before delete)"
+    elif printf '%s' "$pr" | grep -q 'OPEN'; then
+      echo "  $b -> ACTIVE (${pr})"
+    else
+      echo "  $b -> ${pr:-ORPHAN (no PR — surface, never auto-delete)}"
+    fi
+  done
+
+  echo "# stashes"
+  git stash list 2>/dev/null | sed 's/^/  /' || true
+}
+
+# kit_gc_has_prunable — rc 0 if at least one branch is SAFE to delete (a merged, unprotected branch).
+kit_gc_has_prunable() {
+  kit_gc_analyze 2>/dev/null | grep -q '> SAFE '
+}
+
+# kit_gc_prune [--yes] - remove worktrees + local branches whose PR is MERGED (the SAFE rows).
+# DRY-RUN by default (lists what it WOULD remove); --yes performs the deletions. Never touches a
+# PROTECTED/ACTIVE/ORPHAN branch, and never a DIRTY worktree (recover-before-prune): a worktree with
+# staged/unstaged/untracked changes is skipped with a warning, not destroyed. The remote branch is
+# already deleted at merge time (gh pr merge --delete-branch); this cleans up the local side.
+kit_gc_prune() {
+  _kit_gc_load_deps
+  local repo="$KIT_GC_REPO" yes=0 a path ref b pr
+  for a in "$@"; do case "$a" in --yes|-y) yes=1 ;; esac; done
+
+  # Worktrees first - a branch's worktree must be removed before the branch can be deleted.
+  git worktree list --porcelain 2>/dev/null \
+    | awk '/^worktree /{w=$2} /^branch /{print w" "$2}' \
+    | while read -r path ref; do
+        b="${ref#refs/heads/}"
+        case "$b" in develop|main|"") continue ;; esac
+        [ -n "$(wt_protected_reason "$b" "$repo" 2>/dev/null || true)" ] && continue
+        pr="$(gh pr list --repo "$repo" --head "$b" --state all --json state --jq '.[0].state' 2>/dev/null || true)"
+        [ "$pr" = "MERGED" ] || continue
+        if [ -n "$(git -C "$path" status --porcelain 2>/dev/null)" ]; then
+          echo "  SKIP dirty worktree $path [$b] - commit/recover before pruning" >&2; continue
+        fi
+        if [ "$yes" -eq 1 ]; then
+          git worktree remove --force "$path" 2>/dev/null && echo "  removed worktree $path [$b]"
+        else
+          echo "  would remove worktree $path [$b] (PR MERGED)"
+        fi
+      done
+  git worktree prune 2>/dev/null || true
+
+  # Then local branches whose PR merged (worktree now gone).
+  for b in $(git branch --format='%(refname:short)' 2>/dev/null); do
+    case "$b" in develop|main) continue ;; esac
+    [ -n "$(wt_protected_reason "$b" "$repo" 2>/dev/null || true)" ] && continue
+    pr="$(gh pr list --repo "$repo" --head "$b" --state all --json state --jq '.[0].state' 2>/dev/null || true)"
+    [ "$pr" = "MERGED" ] || continue
+    if [ "$yes" -eq 1 ]; then
+      git branch -D "$b" >/dev/null 2>&1 && echo "  deleted local branch $b (PR MERGED)"
+    else
+      echo "  would delete local branch $b (PR MERGED)"
+    fi
+  done
+  [ "$yes" -eq 1 ] && echo "gc prune: done" || echo "gc prune: DRY RUN - pass --yes to delete"
+}

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

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# kit-interview-test.sh — self-test for kit-interview (#372). Runs under bash AND zsh.
+# Run:  bash scripts/lib/kit-interview-test.sh
+dir=$(CDPATH='' cd -- "$(dirname -- "$0")" && pwd)
+
+if [ -n "${KIT_IV_TEST_INNER:-}" ]; then
+  set -u
+  . "$dir/kit-interview.sh"
+  fail=0
+  t() { if [ "$2" != "$3" ]; then echo "FAIL($KIT_IV_TEST_INNER): $1 -> got '[$2]' want '[$3]'"; fail=1; else echo "ok($KIT_IV_TEST_INNER): $1"; fi; }
+
+  export KIT_PROFILE_HOME="$(mktemp -d)"
+  work="$(mktemp -d)"; trap 'rm -rf "$KIT_PROFILE_HOME" "$work"' EXIT
+
+  # --- catalogs load + tier matches + module routing ---
+  t "catalog global tier"   "$(kit_interview_catalog global   | jq -r .tier)" "global"
+  t "catalog project tier"  "$(kit_interview_catalog project  | jq -r .tier)" "project"
+  t "catalog software tier" "$(kit_interview_catalog software | jq -r .tier)" "software"
+  case "$(kit_interview_catalog_file software)" in
+    */modules/software.json) t "software routes to modules/" yes yes;;
+    *) t "software routes to modules/" "$(kit_interview_catalog_file software)" "*/modules/software.json";;
+  esac
+  kit_interview_catalog nope >/dev/null 2>&1; t "unknown tier rc" "$?" "1"
+
+  # --- context: repo detection ---
+  mkdir -p "$work/proj"; printf '{}' > "$work/proj/package.json"
+  ctx="$(kit_interview_context "$work/proj")"
+  t "ctx repo.dir"      "$(printf '%s' "$ctx" | jq -r .repo.dir)"      "proj"
+  t "ctx repo.language" "$(printf '%s' "$ctx" | jq -r .repo.language)" "javascript"
+  t "ctx repo.hasGit"   "$(printf '%s' "$ctx" | jq -r .repo.hasGit)"   "false"
+
+  # --- render: per-project pre-fill from profile + repo ---
+  . "$dir/kit-profile.sh"
+  kit_profile_set name "Ada" string tester
+  kit_profile_set language "es" string tester
+  rp="$(KIT_PROFILE_USER=tester kit_interview_render project "$work/proj")"
+  t "render name<-repo.dir"   "$(printf '%s' "$rp" | jq -r '.questions[]|select(.key=="name").default')"    "proj"
+  t "render owner<-profile"   "$(printf '%s' "$rp" | jq -r '.questions[]|select(.key=="owner").default')"   "Ada"
+  t "render lang<-profile"    "$(printf '%s' "$rp" | jq -r '.questions[]|select(.key=="language").default')" "es"
+
+  # --- apply project: text + select targets ---
+  printf '%s\n' '{"name":"My App","owner":"Ada","language":"es","mode":"enforced","software":"no"}' > "$work/ans-proj.json"
+  ap="$(kit_interview_apply project "$work/ans-proj.json")"
+  t "apply project.name" "$(printf '%s' "$ap" | jq -r .project.name)" "My App"
+  t "apply mode"         "$(printf '%s' "$ap" | jq -r .mode)"         "enforced"
+  t "control no key"     "$(printf '%s' "$ap" | jq -r 'has("software")')" "false"
+
+  # --- apply software wizard: sets + idempotent modules union ---
+  printf '%s\n' '{"versioning":"github","deploy":"vercel","ci":"github-actions"}' > "$work/ans-sw.json"
+  printf '%s\n' "$ap" > "$work/base.json"
+  sw1="$(kit_interview_apply software "$work/ans-sw.json" "$work/base.json")"
+  t "sw modules"        "$(printf '%s' "$sw1" | jq -c .modules)"            '["software"]'
+  t "sw github"         "$(printf '%s' "$sw1" | jq -r .github.projectsV2)"  "true"
+  t "sw deploy"         "$(printf '%s' "$sw1" | jq -r .deploy.target)"      "vercel"
+  t "sw ci"             "$(printf '%s' "$sw1" | jq -r .ci.provider)"        "github-actions"
+  printf '%s\n' "$sw1" > "$work/base2.json"
+  sw2="$(kit_interview_apply software "$work/ans-sw.json" "$work/base2.json")"
+  t "sw modules idempotent" "$(printf '%s' "$sw2" | jq -c .modules)" '["software"]'
+
+  # --- apply with missing answer falls back to default ---
+  printf '%s\n' '{}' > "$work/ans-empty.json"
+  swd="$(kit_interview_apply software "$work/ans-empty.json")"
+  t "apply default deploy" "$(printf '%s' "$swd" | jq -r .deploy.target)" "none"
+
+  [ "$fail" -eq 0 ] && echo "ALL OK($KIT_IV_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_IV_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-interview.sh

@@ -0,0 +1,203 @@
+#!/usr/bin/env bash
+# kit-interview.sh — the deterministic brain of the two-tier onboarding interview (D11, #372).
+#
+# THE SPLIT: the ASKING is interactive (the kit-onboard skill drives AskUserQuestion — Tier A,
+# portable to Cowork/claude.ai). The DERIVING is pure data and lives here, so it is unit-testable
+# under bash AND zsh with zero interactivity:
+#   - catalog : the question set per tier (global | project | software), loaded from interview/*.json
+#               and modules/*.json — data, reviewable, not buried in bash.
+#   - context : profile + repo detection, used to PRE-FILL per-project / wizard defaults.
+#   - render  : the catalog with every `default` resolved from context (what the skill renders).
+#   - apply   : answers {key:value} + a base config  ->  merged config JSON (no side effects).
+# The caller (kit-onboard skill / kit-add.sh) persists the merged JSON — to the global profile
+# directly, or to a project's .claude/kit.config.json through kit-operate (so it is manifest-tracked).
+#
+# Source it:  source scripts/lib/kit-interview.sh
+# CLI:        kit-interview.sh --catalog TIER
+#             kit-interview.sh --context [--dir DIR]
+#             kit-interview.sh --render  TIER [--dir DIR]
+#             kit-interview.sh --apply   TIER --answers FILE [--base FILE]
+# Requires: jq.
+
+_kit_iv_dir="$(CDPATH='' cd -- "$(dirname -- "${BASH_SOURCE[0]:-$0}")" && pwd)"
+# shellcheck source=/dev/null
+. "$_kit_iv_dir/kit-cli.sh"      # kit_is_main, kit_say/warn/die
+# shellcheck source=/dev/null
+. "$_kit_iv_dir/kit-profile.sh"  # kit_profile_read
+
+# Plugin root = two levels up from scripts/lib/. Override with KIT_PLUGIN_ROOT (tests).
+kit_iv_plugin_root() {
+  if [ -n "${KIT_PLUGIN_ROOT:-}" ]; then printf '%s\n' "$KIT_PLUGIN_ROOT"; return 0; fi
+  if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then printf '%s\n' "$CLAUDE_PLUGIN_ROOT"; return 0; fi
+  ( CDPATH='' cd -- "$_kit_iv_dir/../.." && pwd )
+}
+
+_kit_iv_require() { command -v jq >/dev/null 2>&1 || { kit_warn "kit-interview: jq is required"; return 1; }; }
+
+# kit_interview_catalog_file <tier> -> path of the catalog JSON for a tier.
+#   global|project -> interview/<tier>.json ;  anything else -> modules/<tier>.json (software, ...)
+kit_interview_catalog_file() {
+  local tier="$1" root; root="$(kit_iv_plugin_root)"
+  case "$tier" in
+    global|project) printf '%s/interview/%s.json\n' "$root" "$tier";;
+    *)              printf '%s/modules/%s.json\n'    "$root" "$tier";;
+  esac
+}
+
+# kit_interview_catalog <tier> -> the catalog JSON (verbatim)
+kit_interview_catalog() {
+  _kit_iv_require || return 1
+  local f; f="$(kit_interview_catalog_file "$1")"
+  [ -f "$f" ] || { kit_warn "kit-interview: no catalog for tier '$1' ($f)"; return 1; }
+  jq -e . "$f" >/dev/null 2>&1 || { kit_warn "kit-interview: invalid JSON in $f"; return 1; }
+  cat "$f"
+}
+
+# --- repo detection (per-project pre-fill) --------------------------------
+# kit_interview_context [dir] -> { profile:{...}, repo:{dir,language,hasGit,remote,hasGitHub} }
+kit_interview_context() {
+  _kit_iv_require || return 1
+  local dir; dir="$(cd "${1:-$PWD}" 2>/dev/null && pwd)" || dir="${1:-$PWD}"
+  local base; base="$(basename "$dir")"
+  local lang="" hasgit=false remote="" hasgh=false
+  [ -f "$dir/package.json" ]   && lang="javascript"
+  [ -f "$dir/pyproject.toml" ] && lang="python"
+  [ -f "$dir/Cargo.toml" ]     && lang="rust"
+  [ -f "$dir/go.mod" ]         && lang="go"
+  if git -C "$dir" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    hasgit=true
+    local url; url="$(git -C "$dir" remote get-url origin 2>/dev/null || true)"
+    if [ -n "$url" ]; then
+      hasgh=true
+      remote="$(printf '%s' "$url" | sed -E 's#^git@github.com:##; s#^https://github.com/##; s#\.git$##')"
+    fi
+  fi
+  local profile; profile="$(kit_profile_read)"
+  jq -n --argjson p "$profile" --arg d "$base" --arg l "$lang" \
+        --argjson g "$hasgit" --arg r "$remote" --argjson gh "$hasgh" \
+    '{profile:$p, repo:{dir:$d, language:$l, hasGit:$g, remote:$r, hasGitHub:$gh}}'
+}
+
+# kit_interview_render <tier> [dir] -> the catalog with each question.default resolved from context.
+# For a question with "prefillFrom":"profile.language", if context.<prefillFrom> is non-empty it
+# becomes the default. This is what the skill renders into AskUserQuestion.
+kit_interview_render() {
+  _kit_iv_require || return 1
+  local tier="$1" dir="${2:-$PWD}" cat ctx
+  cat="$(kit_interview_catalog "$tier")" || return 1
+  ctx="$(kit_interview_context "$dir")"  || return 1
+  jq --argjson ctx "$ctx" '
+    def deref($path): ($path | split(".")) as $p | reduce $p[] as $k ($ctx; if type=="object" then .[$k] else null end);
+    .questions |= map(
+      if (.prefillFrom // "") != ""
+      then (deref(.prefillFrom)) as $v | if ($v != null and $v != "") then .default = ($v|tostring) else . end
+      else . end
+    )
+  ' <<EOF
+$cat
+EOF
+}
+
+# --- apply: answers + base config -> merged config (pure) -----------------
+# _kit_iv_setpath <dotpath> <value> <valtype>  : jq filter snippet applied to stdin JSON.
+# valtype: string | bool | number | json. For valtype json on an existing array, unions uniquely
+# (so adding a module twice is a no-op — idempotent modules:[]).
+_kit_iv_apply_set() {
+  local dotpath="$1" value="$2" valtype="${3:-string}"   # `path` is $PATH-tied in zsh — never use it
+  local setexpr
+  setexpr="$(printf '%s' "$dotpath" | awk -F. '{out="["; for(i=1;i<=NF;i++){ if(i>1)out=out","; out=out"\""$i"\""}; out=out"]"; print out}')"
+  case "$valtype" in
+    bool|boolean|number|int)
+      jq --argjson v "$value" "setpath($setexpr; \$v)";;
+    json)
+      jq --argjson v "$value" "
+        getpath($setexpr) as \$cur
+        | if (\$cur|type)==\"array\" and (\$v|type)==\"array\"
+          then setpath($setexpr; (\$cur + \$v | unique))
+          else setpath($setexpr; \$v) end";;
+    *)
+      jq --arg v "$value" "setpath($setexpr; \$v)";;
+  esac
+}
+
+# kit_interview_apply <tier> <answersfile> [basefile] -> merged config JSON on stdout.
+# answersfile: {"<key>":"<chosen value>", ...}. Unanswered questions fall back to their default.
+# Control questions (e.g. project.software) carry no `set` — they steer the caller, not the config.
+kit_interview_apply() {
+  _kit_iv_require || return 1
+  # ALL locals declared ONCE up front. A BARE `local x` re-run inside a loop PRINTS the var under
+  # zsh (treated like `typeset x`), polluting stdout — so never re-declare locals in the loops below.
+  local tier="$1" ans="$2" base="${3:-}"
+  local catalog merged nsets nq i p v vt tmp q key qtype def answer target nset j
+  [ -f "$ans" ] || { kit_warn "kit-interview apply: answers file missing: $ans"; return 1; }
+  catalog="$(kit_interview_catalog "$tier")" || return 1
+  merged="$(mktemp)" || return 1
+  if [ -n "$base" ] && [ -f "$base" ]; then cp "$base" "$merged"; else printf '{}\n' > "$merged"; fi
+
+  # 1. unconditional catalog-level sets (e.g. modules:["software"])
+  nsets="$(printf '%s' "$catalog" | jq '(.sets // []) | length')"
+  i=0
+  while [ "$i" -lt "$nsets" ]; do
+    p="$(printf '%s' "$catalog"  | jq -r ".sets[$i].path")"
+    v="$(printf '%s' "$catalog"  | jq -r ".sets[$i].value")"
+    vt="$(printf '%s' "$catalog" | jq -r ".sets[$i].valtype // \"string\"")"
+    tmp="$(mktemp)"; _kit_iv_apply_set "$p" "$v" "$vt" < "$merged" > "$tmp" && mv "$tmp" "$merged" || { rm -f "$tmp" "$merged"; return 1; }
+    i=$((i+1))
+  done
+
+  # 2. per-question answers
+  nq="$(printf '%s' "$catalog" | jq '.questions | length')"
+  i=0
+  while [ "$i" -lt "$nq" ]; do
+    q="$(printf '%s' "$catalog" | jq ".questions[$i]")"
+    key="$(printf '%s' "$q" | jq -r '.key')"
+    qtype="$(printf '%s' "$q" | jq -r '.type // "text"')"
+    def="$(printf '%s' "$q" | jq -r '.default // ""')"
+    answer="$(jq -r --arg k "$key" '.[$k] // empty' "$ans")"
+    [ -z "$answer" ] && answer="$def"
+
+    if [ "$qtype" = "text" ]; then
+      target="$(printf '%s' "$q" | jq -r '.target // empty')"
+      if [ -n "$target" ] && [ -n "$answer" ]; then
+        tmp="$(mktemp)"; _kit_iv_apply_set "$target" "$answer" string < "$merged" > "$tmp" && mv "$tmp" "$merged" || { rm -f "$tmp" "$merged"; return 1; }
+      fi
+    else
+      # select: apply the chosen option's set[] (control-only options have none)
+      nset="$(printf '%s' "$q" | jq --arg a "$answer" '[.options[] | select(.value==$a)] | .[0].set // [] | length')"
+      j=0
+      while [ "$j" -lt "$nset" ]; do
+        p="$(printf '%s' "$q"  | jq -r --arg a "$answer" "[.options[] | select(.value==\$a)][0].set[$j].path")"
+        v="$(printf '%s' "$q"  | jq -r --arg a "$answer" "[.options[] | select(.value==\$a)][0].set[$j].value")"
+        vt="$(printf '%s' "$q" | jq -r --arg a "$answer" "[.options[] | select(.value==\$a)][0].set[$j].valtype // \"string\"")"
+        tmp="$(mktemp)"; _kit_iv_apply_set "$p" "$v" "$vt" < "$merged" > "$tmp" && mv "$tmp" "$merged" || { rm -f "$tmp" "$merged"; return 1; }
+        j=$((j+1))
+      done
+    fi
+    i=$((i+1))
+  done
+
+  cat "$merged"; rm -f "$merged"
+}
+
+# CLI — direct execution only.
+if kit_is_main; then
+  _mode=""; _tier=""; _dir="$PWD"; _ans=""; _base=""
+  while [ $# -gt 0 ]; do case "$1" in
+    --catalog) _mode=catalog; _tier="$2"; shift 2;;
+    --context) _mode=context; shift;;
+    --render)  _mode=render; _tier="$2"; shift 2;;
+    --apply)   _mode=apply; _tier="$2"; shift 2;;
+    --dir)     _dir="$2"; shift 2;;
+    --answers) _ans="$2"; shift 2;;
+    --base)    _base="$2"; shift 2;;
+    -h|--help) echo "usage: kit-interview.sh --catalog|--render TIER [--dir D] | --context [--dir D] | --apply TIER --answers F [--base F]"; exit 0;;
+    *) kit_warn "unknown arg: $1"; exit 2;;
+  esac; done
+  case "$_mode" in
+    catalog) kit_interview_catalog "$_tier";;
+    context) kit_interview_context "$_dir";;
+    render)  kit_interview_render "$_tier" "$_dir";;
+    apply)   kit_interview_apply "$_tier" "$_ans" "$_base";;
+    *) kit_warn "nothing to do (see --help)"; exit 2;;
+  esac
+fi

package/scripts/lib/kit-local.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# kit-local.sh — local model client for claude-kit NL chores (digest, summarize, classify, draft).
+# Backed by mlx_lm.server (Apple MLX), an OpenAI-compatible HTTP server on localhost.
+#
+# Setup (one-time — /kit-doctor does both automatically, #313):
+#   uv tool install mlx-lm        # isolated venv, PEP 668-safe (fallback: pipx install mlx-lm)
+#   mlx_lm.server --model mlx-community/Qwen3-8B-4bit --port 8080
+#
+# Source this from hooks/skills:  source scripts/lib/kit-local.sh
+#   kit_local_alive                      -> 0 if the server responds (fast: 1s timeout)
+#   kit_local_chat "<system>" "<prompt>" -> prints the model reply; non-zero on any failure
+#   kit_local_dismissed                  -> 0 if the "layer down" notice was dismissed
+#
+# HARD RULE — fallback always: every caller must treat a non-zero exit as "use the current
+# (non-local) path". This lib never blocks a hook: alive-check 1s, chat bounded by
+# KIT_LOCAL_TIMEOUT (default 90s; hooks should pass lower via env when latency matters).
+# Config: .claude/kit.config.json -> .local {enabled, port, model} (KIT_LOCAL_* env wins).
+
+KIT_LOCAL_CONFIG="${KIT_CONFIG:-.claude/kit.config.json}"
+
+_kit_local_cfg() {  # _kit_local_cfg <jq-path> <default>
+  local v=""
+  if command -v jq >/dev/null 2>&1 && [[ -f "$KIT_LOCAL_CONFIG" ]]; then
+    v="$(jq -r "$1 // empty" "$KIT_LOCAL_CONFIG" 2>/dev/null)"
+  fi
+  printf '%s' "${v:-$2}"
+}
+
+KIT_LOCAL_ENABLED="${KIT_LOCAL_ENABLED:-$(_kit_local_cfg '.local.enabled' 'false')}"
+KIT_LOCAL_PORT="${KIT_LOCAL_PORT:-$(_kit_local_cfg '.local.port' '8080')}"
+KIT_LOCAL_MODEL="${KIT_LOCAL_MODEL:-$(_kit_local_cfg '.local.model' 'mlx-community/Qwen3-8B-4bit')}"
+KIT_LOCAL_URL="http://127.0.0.1:${KIT_LOCAL_PORT}"
+KIT_LOCAL_TIMEOUT="${KIT_LOCAL_TIMEOUT:-90}"
+
+# 0 if enabled in config AND the server answers /v1/models within 1s.
+kit_local_alive() {
+  [[ "$KIT_LOCAL_ENABLED" == "true" ]] || return 1
+  command -v curl >/dev/null 2>&1 || return 1
+  curl -sf -m 1 "$KIT_LOCAL_URL/v1/models" >/dev/null 2>&1
+}
+
+# kit_local_chat "<system>" "<user prompt>" [max_tokens]
+# Prints the assistant reply (reasoning <think> blocks stripped). Non-zero on any failure.
+kit_local_chat() {
+  local system="$1" prompt="$2" max_tokens="${3:-1024}"
+  kit_local_alive || return 1
+  command -v jq >/dev/null 2>&1 || return 1
+
+  local payload reply
+  payload="$(jq -n --arg m "$KIT_LOCAL_MODEL" --arg s "$system" --arg p "$prompt" --argjson t "$max_tokens" \
+    '{model:$m, messages:[{role:"system",content:$s},{role:"user",content:$p}], max_tokens:$t, temperature:0.2}')" || return 1
+
+  reply="$(curl -sf -m "$KIT_LOCAL_TIMEOUT" "$KIT_LOCAL_URL/v1/chat/completions" \
+    -H 'Content-Type: application/json' \
+    -d "$payload" 2>/dev/null | jq -r '.choices[0].message.content // empty')" || return 1
+  [[ -n "$reply" ]] || return 1
+
+  # Qwen3 reasoning models may prefix a <think>...</think> block — strip it.
+  printf '%s' "$reply" | perl -0pe 's/<think>.*?<\/think>\s*//gs' 2>/dev/null || printf '%s' "$reply"
+}
+
+# Short model tag for banners: "Qwen3-8B-4bit" from "mlx-community/Qwen3-8B-4bit".
+kit_local_model_tag() {
+  printf '%s' "${KIT_LOCAL_MODEL##*/}"
+}
+
+# 0 if the "local layer down" session notice is dismissed (#313). Dismiss channels:
+#   - env KIT_LOCAL_DISMISS=1 (this session/shell only)
+#   - config .local.dismissed = "<kitVersion at dismissal>" (written by kit-doctor
+#     --dismiss-local) — sticks until the kit's x.y core moves past it; "true" = forever
+kit_local_dismissed() {
+  [[ "${KIT_LOCAL_DISMISS:-}" == "1" ]] && return 0
+  local d cur
+  d="$(_kit_local_cfg '.local.dismissed' '')"
+  [[ -n "$d" ]] || return 1
+  [[ "$d" == "true" ]] && return 0
+  cur="$(_kit_local_cfg '.kitVersion' '0.0.0')"
+  [[ "$(printf '%s' "$d" | cut -d. -f1-2)" == "$(printf '%s' "$cur" | cut -d. -f1-2)" ]]
+}