@jeiemgi/cckit 0.1.6

package/scripts/lib/kit-manifest.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# kit-manifest.sh — ownership manifest for everything the kit writes into a project (#368).
+#
+# THE PROBLEM IT SOLVES: kit-wire / kit-init / kit-promote write files into a project. To update
+# or UNINSTALL them safely we must distinguish "the kit wrote this and the user hasn't touched it"
+# (safe to overwrite/remove) from "the user edited it" (ask first) from "not ours" (never touch).
+# Guessing by filename is how you delete a user's work. The manifest records path + content hash +
+# kit version + portability tier for each managed file, so every later op consults facts, not
+# heuristics. This is the prerequisite for kit-remove (D12), kit-wire, kit-migrate, kit-promote.
+#
+# Source it:  source scripts/lib/kit-manifest.sh
+# Requires: jq + a sha256 tool (shasum -a 256 | sha256sum).
+#
+# Manifest shape (.claude/kit.manifest.json):
+#   {
+#     "schema": 1,
+#     "entries": {
+#       "<relpath>": { "hash": "<sha256>", "kitVersion": "<v>", "tier": "A|B", "op": "<who>", "ts": "<iso>" }
+#     }
+#   }
+# tier A = portable (Cowork/claude.ai), tier B = CLI-only — see kit-v2 plan §5.
+
+# --- location -------------------------------------------------------------
+# Manifest lives at the project root's .claude/kit.manifest.json. Override with KIT_MANIFEST.
+kit_manifest_path() {
+  if [ -n "${KIT_MANIFEST:-}" ]; then printf '%s\n' "$KIT_MANIFEST"; return 0; fi
+  printf '%s\n' ".claude/kit.manifest.json"
+}
+
+# --- portable sha256 ------------------------------------------------------
+kit_manifest_hash() {
+  # hash of file "$1"; empty string if missing
+  [ -f "$1" ] || { printf ''; return 0; }
+  if command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 -- "$1" | awk '{print $1}'
+  elif command -v sha256sum >/dev/null 2>&1; then
+    sha256sum -- "$1" | awk '{print $1}'
+  else
+    echo "kit-manifest: no sha256 tool (shasum/sha256sum)" >&2; return 1
+  fi
+}
+
+_kit_manifest_require() {
+  command -v jq >/dev/null 2>&1 || { echo "kit-manifest: jq is required" >&2; return 1; }
+}
+
+# --- lifecycle ------------------------------------------------------------
+# Create an empty manifest if none exists. Idempotent.
+kit_manifest_init() {
+  _kit_manifest_require || return 1
+  local mf; mf="$(kit_manifest_path)"
+  [ -f "$mf" ] && return 0
+  mkdir -p "$(dirname "$mf")"
+  printf '{\n  "schema": 1,\n  "entries": {}\n}\n' > "$mf"
+}
+
+# kit_manifest_record <relpath> <tier> [op] [kitVersion] [ts]
+# Records (or updates) the entry, hashing the CURRENT content of <relpath>.
+# ts/kitVersion are injectable so callers in deterministic contexts (tests, resumable workflows)
+# can pass stable values instead of reading the clock.
+kit_manifest_record() {
+  _kit_manifest_require || return 1
+  local relpath="$1" tier="${2:-A}" op="${3:-wire}" ver="${4:-${KIT_VERSION:-0.0.0}}" ts="${5:-}"
+  [ -n "$relpath" ] || { echo "kit-manifest record: path required" >&2; return 1; }
+  case "$tier" in A|B) ;; *) echo "kit-manifest: tier must be A or B (got '$tier')" >&2; return 1;; esac
+  local mf hash; mf="$(kit_manifest_path)"; kit_manifest_init || return 1
+  hash="$(kit_manifest_hash "$relpath")" || return 1
+  if [ -z "$ts" ]; then ts="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo unknown)"; fi
+  local tmp; tmp="$(mktemp)" || return 1
+  jq --arg p "$relpath" --arg h "$hash" --arg t "$tier" --arg o "$op" --arg v "$ver" --arg ts "$ts" \
+     '.entries[$p] = {hash:$h, kitVersion:$v, tier:$t, op:$o, ts:$ts}' "$mf" > "$tmp" \
+     && mv "$tmp" "$mf" || { rm -f "$tmp"; return 1; }
+}
+
+# kit_manifest_get <relpath> -> the entry JSON (or empty + rc 1 if untracked)
+kit_manifest_get() {
+  _kit_manifest_require || return 1
+  local mf; mf="$(kit_manifest_path)"; [ -f "$mf" ] || return 1
+  local out; out="$(jq -e --arg p "$1" '.entries[$p] // empty' "$mf" 2>/dev/null)" || return 1
+  [ -n "$out" ] || return 1
+  printf '%s\n' "$out"
+}
+
+# kit_manifest_verify <relpath> -> prints one of: intact | modified | missing | untracked
+#   intact    = tracked and current content matches recorded hash (safe to overwrite/remove)
+#   modified  = tracked but content changed since the kit wrote it (ASK before touching)
+#   missing   = tracked but the file is gone
+#   untracked = not in the manifest (NEVER touch on the kit's behalf)
+# rc: 0 intact, 1 modified, 2 missing, 3 untracked — so callers can branch on $?.
+kit_manifest_verify() {
+  _kit_manifest_require || return 1
+  local relpath="$1" mf stored cur; mf="$(kit_manifest_path)"
+  if [ ! -f "$mf" ] || ! stored="$(jq -er --arg p "$relpath" '.entries[$p].hash // empty' "$mf" 2>/dev/null)" || [ -z "$stored" ]; then
+    echo untracked; return 3
+  fi
+  if [ ! -f "$relpath" ]; then echo missing; return 2; fi
+  cur="$(kit_manifest_hash "$relpath")" || return 1
+  if [ "$cur" = "$stored" ]; then echo intact; return 0; else echo modified; return 1; fi
+}
+
+# kit_manifest_remove_entry <relpath> — drop the entry (does NOT delete the file)
+kit_manifest_remove_entry() {
+  _kit_manifest_require || return 1
+  local mf tmp; mf="$(kit_manifest_path)"; [ -f "$mf" ] || return 0
+  tmp="$(mktemp)" || return 1
+  jq --arg p "$1" 'del(.entries[$p])' "$mf" > "$tmp" && mv "$tmp" "$mf" || { rm -f "$tmp"; return 1; }
+}
+
+# kit_manifest_list [tier] — newline-list of tracked paths, optionally filtered by tier (A|B)
+kit_manifest_list() {
+  _kit_manifest_require || return 1
+  local mf; mf="$(kit_manifest_path)"; [ -f "$mf" ] || return 0
+  if [ -n "${1:-}" ]; then
+    jq -r --arg t "$1" '.entries | to_entries[] | select(.value.tier==$t) | .key' "$mf"
+  else
+    jq -r '.entries | keys[]' "$mf"
+  fi
+}
+
+# kit_manifest_diff — print "<status>\t<path>" for every tracked path (intact/modified/missing)
+kit_manifest_diff() {
+  _kit_manifest_require || return 1
+  local p; while IFS= read -r p; do
+    [ -n "$p" ] || continue
+    printf '%s\t%s\n' "$(kit_manifest_verify "$p")" "$p"
+  done < <(kit_manifest_list)
+}

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

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# kit-mode-test.sh — self-test for kit-mode (#371). Runs under bash AND zsh.
+# Run:  bash scripts/lib/kit-mode-test.sh
+dir=$(CDPATH='' cd -- "$(dirname -- "$0")" && pwd)
+
+if [ -n "${KIT_MODE_TEST_INNER:-}" ]; then
+  set -u
+  . "$dir/kit-mode.sh"
+  fail=0
+  t() { if [ "$2" != "$3" ]; then echo "FAIL($KIT_MODE_TEST_INNER): $1 -> got '[$2]' want '[$3]'"; fail=1; else echo "ok($KIT_MODE_TEST_INNER): $1"; fi; }
+
+  work="$(mktemp -d)"; trap 'rm -rf "$work"' EXIT
+  mkdir -p "$work/ws/proj/island"
+  printf '{"mode":"guided"}\n'   > "$work/ws/kit.workspace.json"
+  printf '{"mode":"enforced"}\n' > "$work/ws/proj/kit.config.json"
+  printf '{"mode":"draft"}\n'    > "$work/ws/proj/island/kit.config.json"
+  mkdir -p "$work/bare"   # no config anywhere
+
+  unset KIT_MODE 2>/dev/null || true
+  t "mode workspace"   "$(kit_mode "$work/ws")"             "guided"
+  t "mode project"     "$(kit_mode "$work/ws/proj")"        "enforced"
+  t "mode island"      "$(kit_mode "$work/ws/proj/island")" "draft"
+  t "mode default"     "$(kit_mode "$work/bare")"           "guided"
+
+  t "gate enforced"    "$(kit_gate "$work/ws/proj")"        "block"
+  t "gate guided"      "$(kit_gate "$work/ws")"             "warn"
+  t "gate draft"       "$(kit_gate "$work/ws/proj/island")" "off"
+
+  # KIT_MODE env overrides the cascade
+  t "env override"     "$(KIT_MODE=enforced kit_mode "$work/bare")" "enforced"
+
+  # kit_gate_apply exit codes: enforced -> rc 2 (blocks), guided -> rc 0, draft -> rc 0
+  kit_gate_apply "x" "$work/ws/proj"        >/dev/null 2>&1; t "apply enforced rc" "$?" "2"
+  kit_gate_apply "x" "$work/ws"             >/dev/null 2>&1; t "apply guided rc"   "$?" "0"
+  kit_gate_apply "x" "$work/ws/proj/island" >/dev/null 2>&1; t "apply draft rc"    "$?" "0"
+
+  [ "$fail" -eq 0 ] && echo "ALL OK($KIT_MODE_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_MODE_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-mode.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# kit-mode.sh — resolve the effective enforcement MODE for a location, and map it to a gate (#371).
+#
+# `mode` (draft | guided | enforced) is a cascade key (workspace -> project -> island), so it is
+# resolved by kit-config-resolve.sh like any other field. This lib gives hooks and skills a single
+# place to ask "how strict am I HERE?" and "should I block, warn, or stay silent?".
+#
+#   draft     guardrails OFF      — explore freely; hooks no-op
+#   guided    guardrails WARN     — hooks print a notice, never block (default)
+#   enforced  guardrails BLOCK    — hooks exit non-zero (worktree-only, PR-per-issue)
+#
+# Source it:  source scripts/lib/kit-mode.sh   (auto-sources kit-config-resolve.sh alongside)
+# CLI:        scripts/lib/kit-mode.sh [--dir DIR]            -> prints the mode
+#             scripts/lib/kit-mode.sh --gate [--dir DIR]     -> prints block|warn|off
+
+_kit_mode_dir="$(CDPATH='' cd -- "$(dirname -- "${BASH_SOURCE[0]:-$0}")" && pwd)"
+# shellcheck source=/dev/null
+. "$_kit_mode_dir/kit-config-resolve.sh"
+# shellcheck source=/dev/null
+. "$_kit_mode_dir/kit-cli.sh"   # kit_is_main
+
+KIT_MODE_DEFAULT="${KIT_MODE_DEFAULT:-guided}"
+
+# kit_mode [dir] -> draft|guided|enforced  (default guided; KIT_MODE env overrides everything)
+kit_mode() {
+  if [ -n "${KIT_MODE:-}" ]; then printf '%s\n' "$KIT_MODE"; return 0; fi
+  local m; m="$(kit_resolve_get '.mode' "${1:-$PWD}" 2>/dev/null)"
+  case "$m" in
+    draft|guided|enforced) printf '%s\n' "$m";;
+    *) printf '%s\n' "$KIT_MODE_DEFAULT";;
+  esac
+}
+
+# kit_gate [dir] -> block|warn|off  (what a guardrail hook should do at this mode)
+kit_gate() {
+  case "$(kit_mode "${1:-$PWD}")" in
+    enforced) printf 'block\n';;
+    draft)    printf 'off\n';;
+    *)        printf 'warn\n';;   # guided
+  esac
+}
+
+# kit_gate_apply <message> [dir]
+# The hook helper: emit + exit per the resolved gate. enforced -> stderr + exit 2 (blocks the
+# tool call in Claude Code); guided -> stderr notice + exit 0; draft -> silent exit 0.
+# Hooks call:  kit_gate_apply "branch-naming: use <kind>/<N>-slug"   (and let it set the exit code)
+kit_gate_apply() {
+  local msg="$1" dir="${2:-$PWD}"
+  case "$(kit_gate "$dir")" in
+    block) printf 'kit[enforced]: %s\n' "$msg" >&2; return 2;;
+    warn)  printf 'kit[guided]: %s\n'   "$msg" >&2; return 0;;
+    off)   return 0;;
+  esac
+}
+
+# CLI (direct execution only; zsh-safe guard)
+# CLI (direct execution only)
+if kit_is_main; then
+  _d="$PWD"; _gate=0
+  while [ $# -gt 0 ]; do case "$1" in
+    --dir) _d="$2"; shift 2;;
+    --gate) _gate=1; shift;;
+    -h|--help) echo "usage: kit-mode.sh [--dir DIR] [--gate]"; exit 0;;
+    *) echo "unknown arg: $1" >&2; exit 2;;
+  esac; done
+  [ "$_gate" = 1 ] && kit_gate "$_d" || kit_mode "$_d"
+fi

package/scripts/lib/kit-operate.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# kit-operate.sh — the single operation machine (D10, #368).
+#
+# Every kit mutation (init, wire, promote, migrate, remove) is the SAME four-beat machine:
+#   propose diff  ->  ask permission  ->  apply  ->  record in manifest
+# Building it once means those five commands are configurations of one audited, idempotent,
+# dry-runnable primitive — not five hand-rolled file-stompers. Honors KIT_DRY_RUN (preview only)
+# and the conffiles rule from the manifest (never clobber user-modified files silently).
+#
+# Source it:  source scripts/lib/kit-operate.sh   (auto-sources kit-manifest.sh alongside)
+# Env:
+#   KIT_DRY_RUN=1     show what would happen, write nothing
+#   KIT_ASSUME_YES=1  apply without the interactive confirm (CI / batch / Cowork)
+#   KIT_NO_COLOR / NO_COLOR  plain output
+
+_kit_op_dir="$(CDPATH='' cd -- "$(dirname -- "${BASH_SOURCE[0]:-$0}")" && pwd)"
+# shellcheck source=/dev/null
+. "$_kit_op_dir/kit-manifest.sh"
+
+_kit_op_say()  { printf '%s\n' "$*" >&2; }
+_kit_op_dry()  { [ -n "${KIT_DRY_RUN:-}" ]; }
+
+# _kit_op_confirm <prompt> -> rc 0 yes / 1 no
+_kit_op_confirm() {
+  [ -n "${KIT_ASSUME_YES:-}" ] && return 0
+  [ -n "${KIT_DRY_RUN:-}" ] && return 1
+  local reply; printf '%s [y/N] ' "$1" >&2
+  IFS= read -r reply || return 1
+  case "$reply" in y|Y|yes|YES) return 0;; *) return 1;; esac
+}
+
+# _kit_op_diff <src> <dest> — print a unified diff src->dest (best-effort, never fails the op)
+_kit_op_diff() {
+  local src="$1" dest="$2"
+  if [ ! -f "$dest" ]; then _kit_op_say "  + create $dest"; return 0; fi
+  if cmp -s "$src" "$dest"; then _kit_op_say "  = unchanged $dest"; return 0; fi
+  _kit_op_say "  ~ update $dest"
+  if command -v diff >/dev/null 2>&1; then diff -u "$dest" "$src" 2>/dev/null | sed 's/^/    /' >&2 || true; fi
+}
+
+# kit_op_write <src> <destrelpath> <tier> [op]
+# Copy src -> dest with the four-beat machine. Respects conffiles: if dest is tracked and the user
+# MODIFIED it, ask before overwriting even with KIT_ASSUME_YES.
+# rc: 0 applied/created, 10 skipped (declined or dry-run), 1 error.
+kit_op_write() {
+  local src="$1" dest="$2" tier="${3:-A}" op="${4:-wire}"
+  [ -f "$src" ] || { _kit_op_say "kit-operate: source missing: $src"; return 1; }
+
+  # conffiles guard: tracked + user-modified => never silent overwrite
+  local verdict; verdict="$(kit_manifest_verify "$dest" 2>/dev/null || true)"
+  _kit_op_say "propose: $dest  (tier $tier, $op, current=$verdict)"
+  _kit_op_diff "$src" "$dest"
+
+  if cmp -s "$src" "$dest" 2>/dev/null; then
+    # content already identical — just (re)record, no write needed (idempotent)
+    _kit_op_dry || kit_manifest_record "$dest" "$tier" "$op" || return 1
+    return 0
+  fi
+
+  if [ "$verdict" = "modified" ]; then
+    if ! _kit_op_confirm "  $dest was edited by you — overwrite?"; then
+      _kit_op_say "  skip (kept your version): $dest"; return 10
+    fi
+  elif ! _kit_op_confirm "  apply?"; then
+    _kit_op_say "  skip: $dest"; return 10
+  fi
+
+  if _kit_op_dry; then _kit_op_say "  [dry-run] would write $dest"; return 10; fi
+  mkdir -p "$(dirname "$dest")" || return 1
+  cp -- "$src" "$dest" || return 1
+  kit_manifest_record "$dest" "$tier" "$op" || return 1
+  _kit_op_say "  applied: $dest"
+}
+
+# kit_op_write_content <destrelpath> <tier> <op>  (content on stdin)
+# Same machine but the source is piped — for generated files (KIT.md, shims).
+kit_op_write_content() {
+  local dest="$1" tier="${2:-A}" op="${3:-wire}" tmp
+  tmp="$(mktemp)" || return 1
+  cat > "$tmp"
+  kit_op_write "$tmp" "$dest" "$tier" "$op"; local rc=$?
+  rm -f "$tmp"; return $rc
+}
+
+# kit_op_remove <destrelpath>
+# Manifest-driven uninstall (D12 conffiles): intact->delete, modified->ask, missing->drop entry,
+# untracked->refuse. rc: 0 removed/cleaned, 10 kept (declined/untracked), 1 error.
+kit_op_remove() {
+  local dest="$1" verdict; verdict="$(kit_manifest_verify "$dest")"
+  case "$verdict" in
+    untracked) _kit_op_say "refuse: $dest is not kit-managed — not touching it"; return 10;;
+    missing)   _kit_op_say "clean: $dest already gone, dropping manifest entry"
+               _kit_op_dry || kit_manifest_remove_entry "$dest"; return 0;;
+    modified)  # Deleting a USER-EDITED file is NEVER silent — even under KIT_ASSUME_YES. Losing
+               # the user's work to an automated run is exactly what conffiles (D12) prevents.
+               if _kit_op_dry; then _kit_op_say "  [dry-run] would ASK before deleting edited $dest"; return 10; fi
+               local _r=""; printf '  %s was edited by you — delete anyway? [y/N] ' "$dest" >&2
+               IFS= read -r _r </dev/tty 2>/dev/null || IFS= read -r _r 2>/dev/null || _r=""
+               case "$_r" in y|Y|yes|YES) ;; *) _kit_op_say "  kept (your edits): $dest"; return 10;; esac;;
+    intact)    : ;;  # safe to remove
+  esac
+  if _kit_op_dry; then _kit_op_say "  [dry-run] would remove $dest"; return 10; fi
+  rm -f -- "$dest" && kit_manifest_remove_entry "$dest" || return 1
+  _kit_op_say "  removed: $dest"
+}

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

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# kit-profile-test.sh — self-test for kit-profile (#372). Runs under bash AND zsh.
+# Run:  bash scripts/lib/kit-profile-test.sh
+dir=$(CDPATH='' cd -- "$(dirname -- "$0")" && pwd)
+
+if [ -n "${KIT_PROFILE_TEST_INNER:-}" ]; then
+  set -u
+  . "$dir/kit-profile.sh"
+  fail=0
+  t() { if [ "$2" != "$3" ]; then echo "FAIL($KIT_PROFILE_TEST_INNER): $1 -> got '[$2]' want '[$3]'"; fail=1; else echo "ok($KIT_PROFILE_TEST_INNER): $1"; fi; }
+  tt() { if [ "$2" = "$3" ]; then echo "FAIL($KIT_PROFILE_TEST_INNER): $1 -> '[$2]' should differ from '[$3]'"; fail=1; else echo "ok($KIT_PROFILE_TEST_INNER): $1"; fi; }
+
+  export KIT_PROFILE_HOME="$(mktemp -d)"; trap 'rm -rf "$KIT_PROFILE_HOME"' EXIT
+
+  # slug normalization (O8)
+  t "slug spaces+case"  "$(KIT_PROFILE_USER='Jose Gutierrez' kit_profile_user_slug)" "jose-gutierrez"
+  t "slug explicit arg" "$(kit_profile_user_slug 'Ada Lovelace')"                    "ada-lovelace"
+  t "slug all-symbols -> user" "$(kit_profile_user_slug '!!!')" "user"
+
+  # path encodes the slug
+  case "$(kit_profile_path tester)" in
+    *"/kit.profile.tester.json") t "path encodes slug" yes yes;;
+    *) t "path encodes slug" "$(kit_profile_path tester)" "*/kit.profile.tester.json";;
+  esac
+
+  # exists is false before, true after init; init idempotent
+  kit_profile_exists tester; t "exists before" "$?" "1"
+  kit_profile_init tester;   t "init rc" "$?" "0"
+  kit_profile_exists tester; t "exists after" "$?" "0"
+  h1="$(cat "$(kit_profile_path tester)")"; kit_profile_init tester; h2="$(cat "$(kit_profile_path tester)")"
+  t "init idempotent" "$h1" "$h2"
+
+  # set / get scalar + nested
+  kit_profile_set name "Jose" string tester
+  t "get name"        "$(kit_profile_get .name tester)"          "Jose"
+  kit_profile_set defaults.mode guided string tester
+  t "get nested mode" "$(kit_profile_get .defaults.mode tester)" "guided"
+  kit_profile_set defaults.memory_on true bool tester
+  t "get bool"        "$(kit_profile_get .defaults.memory_on tester)" "true"
+
+  # read returns {} for an unknown user; get empty for unset path
+  t "read unknown"    "$(kit_profile_read nobody)" "{}"
+  t "get unset empty" "$(kit_profile_get .nope tester)" ""
+
+  # the $PATH-tied 'path' var regression: a set must NOT break later jq calls (zsh)
+  kit_profile_set a.b.c "deep" string tester
+  t "deep set survives PATH" "$(kit_profile_get .a.b.c tester)" "deep"
+  t "jq still found after set" "$(command -v jq >/dev/null 2>&1 && echo ok)" "ok"
+
+  [ "$fail" -eq 0 ] && echo "ALL OK($KIT_PROFILE_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_PROFILE_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-profile.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# kit-profile.sh — the global, per-USER profile (D7, O8, #372).
+#
+# THE MODEL: the wide-range interview runs ONCE in a user's life and writes a global profile at
+#   ~/.claude/kit.profile.<user>.json
+# Multi-user by file (D7): the <user> slug names the file, so two humans on one machine never clash.
+# This profile is the FAR end of the cascade — kit-config-resolve reads project layers on top of it,
+# and the per-project interview (tier 2) pre-fills its answers FROM this profile. It lives in the
+# user's home, OUTSIDE any project, so it is NOT manifest-tracked (the manifest is project-scoped).
+#
+# Source it:  source scripts/lib/kit-profile.sh
+# CLI:        scripts/lib/kit-profile.sh [--user U] [--path | --user-slug | --show | --get JQPATH]
+# Requires: jq.
+
+_kit_profile_dir="$(CDPATH='' cd -- "$(dirname -- "${BASH_SOURCE[0]:-$0}")" && pwd)"
+# shellcheck source=/dev/null
+. "$_kit_profile_dir/kit-cli.sh"   # kit_is_main, kit_say/warn/die
+
+KIT_PROFILE_SCHEMA=1
+
+_kit_profile_require() { command -v jq >/dev/null 2>&1 || { kit_warn "kit-profile: jq is required"; return 1; }; }
+
+# kit_profile_slugify <text> -> lower-kebab slug (ASCII; drops non-alnum). Matches kit-task-start.
+kit_profile_slugify() {
+  printf '%s' "$1" \
+    | tr '[:upper:]' '[:lower:]' \
+    | sed -E 's/[^a-z0-9]+/-/g; s/^-+|-+$//g'
+}
+
+# kit_profile_user_slug [explicit] -> the <user> slug for the profile filename (O8).
+# Source cascade: explicit arg > $KIT_PROFILE_USER > git config user.name > $USER/$LOGNAME > "user".
+# Always normalized to a slug. The tier-1 interview can confirm/override before first write.
+kit_profile_user_slug() {
+  local raw="${1:-${KIT_PROFILE_USER:-}}"
+  if [ -z "$raw" ]; then raw="$(git config user.name 2>/dev/null || true)"; fi
+  if [ -z "$raw" ]; then raw="${USER:-${LOGNAME:-}}"; fi
+  [ -z "$raw" ] && raw="user"
+  local slug; slug="$(kit_profile_slugify "$raw")"
+  [ -z "$slug" ] && slug="user"
+  printf '%s\n' "$slug"
+}
+
+# kit_profile_home -> the dir that holds profiles. Override with KIT_PROFILE_HOME (tests use this).
+kit_profile_home() { printf '%s\n' "${KIT_PROFILE_HOME:-$HOME/.claude}"; }
+
+# kit_profile_path [user] -> absolute path of the user's global profile JSON.
+kit_profile_path() {
+  local u; u="$(kit_profile_user_slug "${1:-}")"
+  printf '%s/kit.profile.%s.json\n' "$(kit_profile_home)" "$u"
+}
+
+# kit_profile_exists [user] -> rc 0 if the profile file is present (drives "once in a lifetime").
+kit_profile_exists() { [ -f "$(kit_profile_path "${1:-}")" ]; }
+
+# kit_profile_init [user] -> create an empty, schema'd profile if none exists. Idempotent.
+kit_profile_init() {
+  _kit_profile_require || return 1
+  local p; p="$(kit_profile_path "${1:-}")"
+  [ -f "$p" ] && return 0
+  mkdir -p "$(dirname "$p")" || return 1
+  local u; u="$(kit_profile_user_slug "${1:-}")"
+  jq -n --argjson s "$KIT_PROFILE_SCHEMA" --arg u "$u" --arg v "${KIT_VERSION:-0.0.0}" \
+    '{schema:$s, user:$u, defaults:{}, createdWith:$v}' > "$p"
+}
+
+# kit_profile_read [user] -> the profile JSON ({} if absent)
+kit_profile_read() {
+  _kit_profile_require || return 1
+  local p; p="$(kit_profile_path "${1:-}")"
+  if [ -f "$p" ]; then cat "$p"; else printf '{}\n'; fi
+}
+
+# kit_profile_get <jqpath> [user] -> a resolved value (raw, empty if unset)
+kit_profile_get() {
+  _kit_profile_require || return 1
+  kit_profile_read "${2:-}" | jq -r "$1 // empty"
+}
+
+# kit_profile_set <dotpath> <value> [valtype string|bool|number] [user]
+# Merge a single value into the profile (deep, by path). Creates the profile if missing.
+kit_profile_set() {
+  _kit_profile_require || return 1
+  local dotpath="$1" value="$2" valtype="${3:-string}" user="${4:-}"
+  [ -n "$dotpath" ] || { kit_warn "kit-profile set: path required"; return 1; }
+  kit_profile_init "$user" || return 1
+  local p tmp; p="$(kit_profile_path "$user")"; tmp="$(mktemp)" || return 1
+  # "a.b.c" -> a jq setpath array  ["a","b","c"]   (var named dotpath: `path` is $PATH-tied in zsh)
+  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)" "$p" > "$tmp" || { rm -f "$tmp"; return 1; };;
+    *)                       jq --arg     v "$value" "setpath($setexpr; \$v)" "$p" > "$tmp" || { rm -f "$tmp"; return 1; };;
+  esac
+  mv "$tmp" "$p"
+}
+
+# CLI — direct execution only.
+if kit_is_main; then
+  _u=""; _mode="path"; _arg=""
+  while [ $# -gt 0 ]; do case "$1" in
+    --user) _u="$2"; shift 2;;
+    --path) _mode="path"; shift;;
+    --user-slug) _mode="slug"; shift;;
+    --show) _mode="show"; shift;;
+    --get) _mode="get"; _arg="$2"; shift 2;;
+    -h|--help) echo "usage: kit-profile.sh [--user U] [--path|--user-slug|--show|--get JQPATH]"; exit 0;;
+    *) kit_warn "unknown arg: $1"; exit 2;;
+  esac; done
+  case "$_mode" in
+    path) kit_profile_path "$_u";;
+    slug) kit_profile_user_slug "$_u";;
+    show) kit_profile_read "$_u";;
+    get)  kit_profile_get "$_arg" "$_u";;
+  esac
+fi

package/scripts/lib/kit-task-ops-test.sh

@@ -0,0 +1,63 @@
+#!/bin/sh
+# kit-task-ops-test.sh — self-test for kit-task-ops.sh pure helpers under bash AND zsh.
+# Network-free: covers the parsers + body composers only (the gh-calling ops are not exercised).
+# Run:  bash scripts/lib/kit-task-ops-test.sh
+
+dir=$(CDPATH='' cd -- "$(dirname -- "$0")" && pwd)
+
+if [ -n "${KTO_TEST_INNER:-}" ]; then
+  # role_signature is a no-op stub so body composers run without sourcing role-identity.
+  role_signature() { :; }
+  role_display() { :; }
+  . "$dir/kit-task-ops.sh"
+  fail=0
+
+  eq() { # <label> <got> <want>
+    if [ "$2" != "$3" ]; then
+      echo "FAIL($KTO_TEST_INNER): $1 -> '[$2]', want '[$3]'"
+      fail=1
+    fi
+  }
+
+  # kto_branch_issue_number
+  eq "branch feat/173-x"   "$(kto_branch_issue_number 'feat/173-admin-clerk')" "173"
+  eq "branch fix/46-y"     "$(kto_branch_issue_number 'fix/46-roadmap')"       "46"
+  eq "branch develop"      "$(kto_branch_issue_number 'develop')"              ""
+  eq "branch effort/851-z" "$(kto_branch_issue_number 'effort/851-tail')"      "851"
+
+  # kto_base_branch / kto_board_enabled (portability toggles)
+  eq "base default"        "$(kto_base_branch)"                             "develop"
+  eq "base override"       "$(KIT_BASE_BRANCH=main; kto_base_branch)"       "main"
+  if kto_board_enabled; then eq "board default on" "on" "on"; else eq "board default on" "off" "on"; fi
+  ( KIT_PROJECTS_V2=false; if kto_board_enabled; then exit 0; else exit 1; fi ) \
+    && eq "board off" "on" "off" || eq "board off" "off" "off"
+
+  # kto_labels_role / kto_labels_kind
+  eq "role from labels"  "$(kto_labels_role 'kind:feat,priority:p2,role:tech-lead')" "tech-lead"
+  eq "kind from labels"  "$(kto_labels_kind 'kind:feat,priority:p2,role:tech-lead')" "feat"
+  eq "role absent"       "$(kto_labels_role 'kind:chore,priority:p3')"               ""
+
+  # kto_compose_pr_body must carry Closes #N and the Summary
+  body="$(kto_compose_pr_body 42 'Did the thing.' 'tech-lead')"
+  case "$body" in *"Closes #42"*) ;; *) echo "FAIL($KTO_TEST_INNER): pr body missing Closes #42"; fail=1 ;; esac
+  case "$body" in *"Did the thing."*) ;; *) echo "FAIL($KTO_TEST_INNER): pr body missing summary"; fail=1 ;; esac
+
+  # kto_compose_issue_body must include the user body, and the Plan + Blocked lines when given
+  ib="$(kto_compose_issue_body 'Context here' 'apps/admin/p.mdx' '#9' 'frontend')"
+  case "$ib" in *"Context here"*) ;; *) echo "FAIL($KTO_TEST_INNER): issue body missing user body"; fail=1 ;; esac
+  case "$ib" in *"**Plan:**"*) ;; *) echo "FAIL($KTO_TEST_INNER): issue body missing Plan line"; fail=1 ;; esac
+  case "$ib" in *"**Blocked by:** #9"*) ;; *) echo "FAIL($KTO_TEST_INNER): issue body missing Blocked line"; fail=1 ;; esac
+  ib2="$(kto_compose_issue_body 'Only body' '' '' 'frontend')"
+  case "$ib2" in *"**Plan:**"*) echo "FAIL($KTO_TEST_INNER): issue body has Plan line when none given"; fail=1 ;; *) ;; esac
+
+  if [ "$fail" -eq 0 ]; then echo "PASS($KTO_TEST_INNER): kit-task-ops helpers"; fi
+  exit "$fail"
+fi
+
+# Outer: re-run under each available shell.
+rc=0
+for sh in bash zsh; do
+  command -v "$sh" >/dev/null 2>&1 || continue
+  KTO_TEST_INNER="$sh" "$sh" "$0" || rc=1
+done
+exit "$rc"