@jeiemgi/cckit 0.1.6

package/scripts/autopilot.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# autopilot.sh - unattended multi-flow driver. A THIN wrapper over orchestrate.sh: pick the issues
+# to run (explicit args, or auto-select the unblocked open issues from the board), then orchestrate
+# them under a concurrency cap, detached, with no human present.
+#
+# This is the SCRIPT half of autopilot - it launches the flows. The "captain" half (decide, review,
+# merge each PR, continue to the next wave) is the driving agent's job, not this script's.
+#
+# Usage:
+#   cckit autopilot                 # auto-select unblocked open issues from the board
+#   cckit autopilot 6 7 8           # drive exactly these issues
+#   cckit autopilot --cap 3         # cap concurrent flows (passed through to orchestrate)
+#   cckit autopilot --agent codex   # drive a different agent CLI
+#   cckit autopilot --dry-run       # print the plan, launch nothing
+set -euo pipefail
+
+PASS=()        # flags forwarded to orchestrate
+ISSUES=()
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --cap|--agent) PASS+=("$1" "$2"); shift 2 ;;
+    --cap=*|--agent=*|--dry-run|--no-seed|--force|--session=*) PASS+=("$1"); shift ;;
+    -h|--help) sed -n '2,17p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    [0-9]*) ISSUES+=("$1"); shift ;;
+    *) echo "autopilot: unknown arg '$1'" >&2; exit 2 ;;
+  esac
+done
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(git -C "$SCRIPT_DIR" worktree list --porcelain | awk '/^worktree /{print $2; exit}')"
+[ -n "$ROOT" ] || { echo "autopilot: not in a git repo" >&2; exit 1; }
+
+# No explicit issues -> auto-select from the board: open issues, minus effort PARENTS (the
+# "[Effort] N ..." umbrella issues that decompose into subs, identified by label:effort OR the
+# title convention) and minus anything blocked_by an open issue. orchestrate re-checks the
+# blocked_by gate at launch; this is the coarse pre-filter so the board drives the wave.
+if [ "${#ISSUES[@]}" -eq 0 ]; then
+  echo "autopilot: no issues passed - auto-selecting unblocked open issues from the board"
+  board="$(bash "$ROOT/scripts/task-sync.sh" --llm)"
+  while IFS= read -r n; do
+    [ -n "$n" ] && ISSUES+=("$n")
+  done < <(printf '%s' "$board" | jq -r '
+    .[]
+    | select((any(.labels[]; . == "effort")) or (.title | test("^\\[Effort\\] ")) | not)
+    | .number')
+  [ "${#ISSUES[@]}" -ge 1 ] || { echo "autopilot: nothing open to drive" >&2; exit 0; }
+fi
+
+echo "autopilot: driving ${#ISSUES[@]} issue(s) -> orchestrate (detached): ${ISSUES[*]}"
+exec bash "$ROOT/scripts/orchestrate.sh" --detach "${PASS[@]+"${PASS[@]}"}" "${ISSUES[@]}"

package/scripts/capture-project-ids.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Capture Projects v2 field + option IDs into scripts/.project-ids.env.
+# Reads owner + project number from .claude/kit.config.json. Run from project root.
+# Handles "Status", "Role", and "Plan Link" fields by name (case-insensitive).
+set -euo pipefail
+source "$(dirname "$0")/lib/kit-config.sh" && load_kit_config
+
+[[ "$KIT_PROJECTS_V2" != "true" ]] && { echo "Projects v2 not enabled for this project — nothing to capture."; exit 0; }
+
+OUT="$(dirname "$0")/.project-ids.env"
+
+DATA=$(gh api graphql -f query='
+  query($login:String!, $number:Int!){
+    user(login:$login){
+      projectV2(number:$number){
+        id
+        fields(first:50){ nodes{
+          __typename
+          ... on ProjectV2FieldCommon { id name }
+          ... on ProjectV2SingleSelectField { id name options { id name } }
+        }}
+      }
+    }
+  }' -f login="$KIT_OWNER" -F number="$KIT_PROJECT_NUMBER")
+
+PROJECT_ID=$(echo "$DATA" | jq -r '.data.user.projectV2.id')
+[[ -z "$PROJECT_ID" || "$PROJECT_ID" == "null" ]] && { echo "✗ Could not resolve project #$KIT_PROJECT_NUMBER for $KIT_OWNER"; exit 1; }
+
+# jq filter: normalize an option/field label -> UPPER_SNAKE
+norm='def n: ascii_upcase | gsub("[ -]";"_");'
+
+{
+  echo "# Generated by capture-project-ids.sh — do not edit by hand."
+  echo "PROJECT_ID=$PROJECT_ID"
+
+  # Single-select fields -> <FIELD>_FIELD_ID + <FIELD>_OPT_<OPTION>
+  echo "$DATA" | jq -r "$norm"'
+    .data.user.projectV2.fields.nodes[]
+    | select(.options != null)
+    | (.name | n) as $f
+    | ([ "\($f)_FIELD_ID=\(.id)" ]
+       + (.options[] | "\($f)_OPT_\(.name | n)=\(.id)" | [.])) []'
+
+  # Text/other fields -> <FIELD>_FIELD_ID
+  echo "$DATA" | jq -r "$norm"'
+    .data.user.projectV2.fields.nodes[]
+    | select(.options == null) | select(.name != null)
+    | "\(.name | n)_FIELD_ID=\(.id)"'
+} > "$OUT"
+
+echo "✓ Wrote $OUT"
+echo "  Fields captured:"
+grep -E '_FIELD_ID=' "$OUT" | sed 's/^/    /'

package/scripts/check.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# check.sh - cckit local gate. Runs the fast, dependency-light checks that must pass before a PR.
+# No CI required; this is the bar. Exit non-zero on the first failure.
+set -uo pipefail
+cd "$(cd "$(dirname "$0")/.." && pwd)"
+
+fail=0
+note() { printf '%s\n' "$*" >&2; }
+
+# 1. Every shell script parses (bash -n).
+note "==> shell syntax (bash -n)"
+while IFS= read -r f; do
+  bash -n "$f" || { note "x syntax: $f"; fail=1; }
+done < <(find bin scripts -type f \( -name '*.sh' -o -perm -u+x \) 2>/dev/null | sort -u)
+
+# 1b. shellcheck at error severity — static analysis when available, skipped if not installed
+# (like jq below) so the gate stays dependency-light. CI installs shellcheck so this always runs there.
+note "==> shellcheck (errors)"
+if command -v shellcheck >/dev/null 2>&1; then
+  find bin scripts -type f \( -name '*.sh' -o -name 'cckit' \) -print0 \
+    | xargs -0 shellcheck --severity=error || fail=1
+else
+  note "  (shellcheck absent - skipping)"
+fi
+
+# 2. The plugin manifest is valid JSON.
+note "==> plugin manifest JSON"
+if command -v jq >/dev/null 2>&1; then
+  jq -e . .claude-plugin/plugin.json >/dev/null || { note "x invalid plugin.json"; fail=1; }
+  jq -e . cckit.config.json >/dev/null || { note "x invalid cckit.config.json"; fail=1; }
+else
+  note "  (jq absent - skipping JSON validation)"
+fi
+
+# 3. No tedos branding leaked into what SHIPS (the de-tedos-ification gate). Scans TRACKED files
+# only (git grep) so gitignored runtime state (.cckit/), build output (dist/), and deps never trip
+# a false positive - only committed content must be tedos-free. Falls back to a filtered recursive
+# grep outside a git work tree.
+note "==> no tedos branding (tracked files)"
+_tedos_scan() {
+  if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    git grep -inI tedos -- . ':!scripts/check.sh'
+  else
+    grep -rniI --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=.cckit \
+      --exclude-dir=dist --exclude=check.sh tedos .
+  fi
+}
+if _tedos_scan >/dev/null 2>&1; then
+  note "x found 'tedos' references - cckit must be tedos-free:"
+  _tedos_scan | head -20 >&2
+  fail=1
+fi
+
+# 4. Secret + privacy guard - no secrets, keys, env, or private data in anything publishable.
+note "==> secret + privacy guard"
+if [ -f scripts/lib/secret-guard.sh ]; then
+  . scripts/lib/secret-guard.sh
+  secret_guard_scan || fail=1
+fi
+
+# 5. Behavioral tests - run every *-test.sh through the test runner.
+note "==> behavioral tests"
+bash scripts/test.sh || fail=1
+
+[ "$fail" -eq 0 ] && note "PASS cckit check passed" || note "FAIL cckit check FAILED"
+exit "$fail"

package/scripts/contribute.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# contribute.sh - open a contribution PR to cckit, GATED on the local checks. The checks gate
+# (scripts/check.sh: shell syntax, valid manifests, no stray branding, secret/privacy guard) MUST
+# pass before anything is pushed - a red gate stops here. This is the agent-agnostic CLI half of
+# the kit-contribute skill.
+#
+# Usage:
+#   cckit contribute "<one-line summary>"   # gate -> push branch -> open PR to the upstream base
+#   cckit contribute --dry-run "<summary>"  # run the gate + preconditions, push/PR nothing
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck source=/dev/null
+source "$ROOT/scripts/lib/kit-config.sh" && load_kit_config
+repo="$KIT_REPO"; base="${KIT_BASE_BRANCH:-main}"
+
+dry=0; summary=""
+for a in "$@"; do
+  case "$a" in --dry-run) dry=1 ;; *) summary="${summary:+$summary }$a" ;; esac
+done
+
+branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+case "$branch" in
+  ""|main|develop|"$base") echo "contribute: start a feature branch first (cckit start <issue>)." >&2; exit 2 ;;
+esac
+
+echo "==> contribute: checks gate (scripts/check.sh)"
+if ! bash "$ROOT/scripts/check.sh"; then
+  echo "contribute: checks gate FAILED - fix it before contributing (a green gate is the bar)." >&2
+  exit 1
+fi
+
+git fetch origin "$base" --quiet 2>/dev/null || true
+if [ -z "$(git log --oneline "origin/$base..$branch" 2>/dev/null)" ]; then
+  echo "contribute: no commits ahead of $base on '$branch' - commit your change first." >&2; exit 2
+fi
+
+[ -n "$summary" ] || { echo "contribute: pass a one-line summary: cckit contribute \"<what + why>\"" >&2; exit 2; }
+
+if [ "$dry" -eq 1 ]; then
+  echo "contribute: DRY RUN - gate green, '$branch' has commits ahead of $base."
+  echo "            would: push '$branch' + open a PR to $repo ($base) titled: $summary"
+  exit 0
+fi
+
+git push -u origin "$branch" 2>&1 | tail -1
+gh pr create --repo "$repo" --base "$base" --head "$branch" \
+  --title "$summary" \
+  --body "$(printf '## Contribution\n\n%s\n\nChecks gate (scripts/check.sh): green.\nDual-licensed MIT OR Apache-2.0 per CONTRIBUTING.md.\n' "$summary")"

package/scripts/debug.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# debug.sh - OPTIONAL, auto-detected browser-debug capability via chrome-devtools-axi (Kun Chen,
+# https://github.com/kunchenguid/chrome-devtools-axi). Token-efficient (TOON output), self-contained
+# Chrome bridge. NOT a hard dependency: cckit is pure bash; axi needs Node + Chrome. When present,
+# this drives axi; when absent, it prints how to enable it and exits 0 (degrade, never hard-fail an
+# unattended run).
+#
+# Usage:
+#   cckit debug <axi-args...>   drive axi (screenshot / a11y / console / network / lighthouse)
+#   cckit debug --check         report whether the capability is available, then exit
+#
+# Resolution order for the axi command:
+#   1. $CCKIT_AXI                       explicit command/path override
+#   2. chrome-devtools-axi on PATH      (npm i -g chrome-devtools-axi)
+#   3. npx -y chrome-devtools-axi       when node + npx are present
+set -euo pipefail
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+chrome_present() {
+  have google-chrome || have chromium || have chromium-browser \
+    || [ -x "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" ] \
+    || [ -x "/Applications/Chromium.app/Contents/MacOS/Chromium" ]
+}
+
+# Echo how to invoke axi, or return non-zero if unavailable.
+axi_cmd() {
+  if [ -n "${CCKIT_AXI:-}" ]; then printf '%s' "$CCKIT_AXI"; return 0; fi
+  if have chrome-devtools-axi; then printf 'chrome-devtools-axi'; return 0; fi
+  if have npx && have node; then printf 'npx -y chrome-devtools-axi'; return 0; fi
+  return 1
+}
+
+cmd="$(axi_cmd || true)"
+
+if [ "${1:-}" = "--check" ]; then
+  if [ -n "$cmd" ] && chrome_present; then
+    echo "cckit debug: AVAILABLE via '$cmd' (Chrome detected)"
+  else
+    echo "cckit debug: optional capability NOT available."
+    [ -n "$cmd" ] || echo "  - axi: install with 'npm i -g chrome-devtools-axi' (or have node+npx)"
+    chrome_present || echo "  - Chrome: not detected (install Google Chrome or Chromium)"
+  fi
+  exit 0
+fi
+
+if [ -z "$cmd" ] || ! chrome_present; then
+  echo "cckit debug: browser-debug capability unavailable - skipping (optional)." >&2
+  [ -n "$cmd" ] || echo "  enable: npm i -g chrome-devtools-axi  (needs Node + Chrome)" >&2
+  exit 0   # degrade, do not hard-fail an unattended run
+fi
+
+# shellcheck disable=SC2086
+exec $cmd "$@"

package/scripts/init-upgrade-test.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# init-upgrade-test.sh — self-test for the `init.sh --upgrade` clobber contract (#334).
+#
+# Reproduces the 2026-06-11 incident in a throwaway project and asserts the fix:
+#   1. existing kit-owned files (scripts/) are PRESERVED, never downgraded to older templates;
+#   2. paths the project removed/renamed (kit.config.json `upgrade.removed/renamed`) are
+#      NEVER re-added by "add missing files";
+#   3. the net effect of an upgrade on a converged project is ONLY the kitVersion bump.
+#
+# Network-free: drives init.sh through the --upgrade path only (skips kit-doctor + gh).
+# Run:  bash scripts/init-upgrade-test.sh
+
+set -uo pipefail
+PLUGIN_DIR=$(CDPATH='' cd -- "$(dirname -- "$0")/.." && pwd)
+INIT="$PLUGIN_DIR/scripts/init.sh"
+
+fail=0
+t() {  # t <label> <got> <want>
+  if [ "$2" != "$3" ]; then echo "FAIL: $1 -> got '[$2]' want '[$3]'"; fail=1; else echo "ok: $1"; fi
+}
+
+command -v jq  >/dev/null 2>&1 || { echo "SKIP: jq not available";  exit 0; }
+command -v git >/dev/null 2>&1 || { echo "SKIP: git not available"; exit 0; }
+
+PLUGIN_VERSION="$(jq -r '.version // "0.0.0"' "$PLUGIN_DIR/.claude-plugin/plugin.json" 2>/dev/null || echo 0.0.0)"
+
+proj="$(mktemp -d)"; trap 'rm -rf "$proj"' EXIT
+cd "$proj"
+git init -q
+git config user.email kit-test@example.com
+git config user.name  kit-test
+
+# --- seed a minimal initialized project so the --upgrade path engages (no doctor/gh) ----
+mkdir -p .claude
+cat > .claude/kit.config.json <<JSON
+{
+  "kitVersion": "0.0.1",
+  "profile": "software",
+  "project": { "name": "UpgradeTest", "slug": "upgrade-test" },
+  "github": { "repo": "example/upgrade-test", "owner": "example", "projectsV2": false }
+}
+JSON
+
+# First upgrade = full scaffold via the upgrade path. --force skips the dirty-tree guard
+# (the seed config is still untracked at this point).
+CLAUDE_PLUGIN_ROOT="$PLUGIN_DIR" bash "$INIT" --upgrade --target "$proj" --force >/dev/null 2>&1 \
+  || { echo "FAIL: initial scaffold (--upgrade) exited non-zero"; exit 1; }
+
+t "scaffold added morning-briefing skill" "$([ -f .claude/skills/morning-briefing/SKILL.md ] && echo yes || echo no)" "yes"
+t "scaffold added speckit skill"         "$([ -d .claude/skills/speckit ] && echo yes || echo no)"           "yes"
+t "scaffold added task-management rule"  "$([ -f .claude/rules/task-management.md ] && echo yes || echo no)" "yes"
+t "scaffold copied task-sync.sh"         "$([ -f scripts/task-sync.sh ] && echo yes || echo no)"             "yes"
+
+git add -A && git commit -q -m "scaffold"
+
+# --- simulate the project's deliberate divergence (the cckit state) --------------------
+# rename a scaffolded skill, delete two scaffolded paths, register them in the upgrade block,
+# and mark a kit-owned script so a downgrade would be detectable.
+git mv .claude/skills/morning-briefing .claude/skills/kit-morning-briefing
+git rm -q -r .claude/skills/speckit
+git rm -q    .claude/rules/task-management.md
+MARKER="# LOCAL-FIX-MARKER-#334 (must survive upgrade)"
+printf '\n%s\n' "$MARKER" >> scripts/task-sync.sh
+
+jq --arg k "0.0.1" '
+  .kitVersion = $k
+  | .upgrade = {
+      removed: [ ".claude/skills/speckit", ".claude/rules/task-management.md" ],
+      renamed: { ".claude/skills/morning-briefing": ".claude/skills/kit-morning-briefing" }
+    }' .claude/kit.config.json > .claude/kit.config.json.tmp && mv .claude/kit.config.json.tmp .claude/kit.config.json
+
+git add -A && git commit -q -m "diverge: rename + delete + register exclusions"
+
+# --- the upgrade under test (clean tree, real un-forced path) --------------------------
+CLAUDE_PLUGIN_ROOT="$PLUGIN_DIR" bash "$INIT" --upgrade --target "$proj" >/dev/null 2>&1 \
+  || { echo "FAIL: upgrade under test exited non-zero"; exit 1; }
+
+# 1. removed/renamed are NOT resurrected
+t "renamed morning-briefing NOT re-added" "$([ -e .claude/skills/morning-briefing ] && echo present || echo absent)" "absent"
+t "removed speckit NOT re-added"         "$([ -e .claude/skills/speckit ] && echo present || echo absent)"         "absent"
+t "removed rule NOT re-added"            "$([ -e .claude/rules/task-management.md ] && echo present || echo absent)" "absent"
+t "renamed target still present"         "$([ -d .claude/skills/kit-morning-briefing ] && echo yes || echo no)"   "yes"
+
+# 2. kit-owned script PRESERVED (not downgraded — marker survives)
+t "script not downgraded (marker kept)"  "$(grep -cF "$MARKER" scripts/task-sync.sh)" "1"
+
+# 3. net effect = ONLY the kitVersion bump
+changed="$(git status --porcelain | awk '{print $2}' | sort | tr '\n' ' ' | sed 's/ $//')"
+t "only kit.config.json changed"         "$changed" ".claude/kit.config.json"
+
+diff_body="$(git diff -- .claude/kit.config.json | grep -E '^[+-]' | grep -vE '^(\+\+\+|---)')"
+only_kitver="$(printf '%s\n' "$diff_body" | grep -vqE '"kitVersion"' && echo no || echo yes)"
+t "diff is only the kitVersion line"     "$only_kitver" "yes"
+t "kitVersion bumped to plugin version"  "$(jq -r '.kitVersion' .claude/kit.config.json)" "$PLUGIN_VERSION"
+t "upgrade block preserved through merge" "$(jq -r '.upgrade.removed | length' .claude/kit.config.json)" "2"
+
+echo ""
+[ "$fail" -eq 0 ] && echo "PASS: init.sh --upgrade honors the preserve/exclude contract (#334)" || echo "FAILED"
+exit "$fail"