claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/core/hooks/tests/superkit-update_test.sh

@@ -0,0 +1,311 @@
+#!/bin/bash
+# superkit-update_test.sh — acceptance suite for the pristine-preserve auto-updater
+# (packages/core/hooks/superkit-update.sh, the D1 root-defect fix).
+#
+# Everything runs inside a throwaway mktemp workspace: a FAKE kit git repo (three
+# tags v0.0.1/v0.0.2/v0.0.3) and FAKE consumer .claude/ trees. This suite NEVER
+# points at the real clone or at any real consumer — the SUPERKIT_SOURCE the
+# updater sees is always the fixture repo.
+#
+# Assertions (per the D1 acceptance contract):
+#   (a) pristine-at-baseline file  → overwritten with the new version's content
+#   (b) customized file (no tag match) → preserved byte-identical AND reported
+#   (c) stale file matching an OLDER released tag → overwritten (second-chance walk)
+#   (d) internal manifest file → never overwritten AND never newly copied
+#   (e) file absent in consumer → created (incl. NEW coverage: references, hooks/lib, stack-rules)
+#   (f) meta baseline tag missing → fail-safe: no-match files preserved, tag-matches still sync
+#   plus: self-bootstrap replaces a differing installed copy before syncing.
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../../../.." && pwd)"
+NEW_UPDATER="$REPO_ROOT/packages/core/hooks/superkit-update.sh"
+
+PASS=0; FAIL=0
+pass() { echo "PASS: $1"; PASS=$((PASS + 1)); }
+fail() { echo "FAIL: $1"; FAIL=$((FAIL + 1)); }
+# chk <label> <file> <expected-content>
+chk() {
+  if [ -f "$2" ] && [ "$(cat "$2" 2>/dev/null)" = "$3" ]; then
+    pass "$1"
+  else
+    fail "$1 (got: $(cat "$2" 2>/dev/null || echo '<MISSING>'))"
+  fi
+}
+
+WORK=$(mktemp -d 2>/dev/null) || { echo "FAIL: mktemp"; exit 1; }
+trap 'rm -rf "$WORK"' EXIT
+
+SRC="$WORK/kit"                       # fake kit repo → SUPERKIT_SOURCE
+export HOME="$WORK/home"; mkdir -p "$HOME/.claude"   # isolate rate-limit file
+
+wf() { mkdir -p "$(dirname "$1")"; printf '%s\n' "$2" > "$1"; }
+
+# ── Build the fake kit git repo ──────────────────────────────────────
+mkdir -p "$SRC"
+git -C "$SRC" init -q
+git -C "$SRC" config user.email t@example.com
+git -C "$SRC" config user.name test
+git -C "$SRC" config commit.gpgsign false
+
+P="$SRC/packages"
+cp "$NEW_UPDATER" "$P/core/hooks/superkit-update.sh" 2>/dev/null || { mkdir -p "$P/core/hooks"; cp "$NEW_UPDATER" "$P/core/hooks/superkit-update.sh"; }
+chmod +x "$P/core/hooks/superkit-update.sh"
+
+# manifest + the three repo-only internal files it names
+wf "$P/core/INTERNAL-FILES" "$(printf '# fixture manifest\nhooks/superkit-counts-verify.sh\nhooks/verify-hooks.sh\nrules/superkit-integrity.md')"
+wf "$P/core/hooks/superkit-counts-verify.sh" "internal-counts"
+wf "$P/core/hooks/verify-hooks.sh"           "internal-verify"
+wf "$P/core/rules/superkit-integrity.md"     "internal-rule"
+
+# static files (unchanged across tags) — exercise the NEW coverage surfaces
+wf "$P/core/agents/newfile.md"                   "NEWFILE-CONTENT"   # (e) absent → created
+wf "$P/core/hooks/lib/profile.sh"                "LIBPROFILE"        # hooks/lib coverage
+wf "$P/core/skills/demo/SKILL.md"                "SKILL-BODY"
+wf "$P/stack-agents/go/goagent.md"               "GOAGENT"
+wf "$P/stack-agents/go/references/ref.md"        "REF-DOC"           # references coverage
+wf "$P/stack-rules/go/gosafe.md"                 "GOSAFE"            # stack-rules coverage
+wf "$P/stack-hooks/go/gohook.sh"                 "GOHOOK"
+wf "$P/core/docs-templates/adr-template.md"      "ADR-TEMPLATE-BODY" # project-root ADR template (create-if-missing)
+wf "$P/core/helpers/statusline.cjs"              "STATUSLINE-V3"     # (i) synced under the pristine rule
+
+# versioned files: pristine.md, ahook.sh, custom.md change every release
+write_v() {
+  wf "$P/core/agents/pristine.md" "P$1"
+  wf "$P/core/hooks/ahook.sh"     "S$1"
+  wf "$P/core/rules/custom.md"    "R$1"
+}
+commit_tag() { echo "$1" > "$SRC/VERSION"; write_v "$2"; git -C "$SRC" add -A; git -C "$SRC" commit -qm "$1"; git -C "$SRC" tag "v$1"; }
+commit_tag 0.0.1 1
+commit_tag 0.0.2 2
+commit_tag 0.0.3 3   # HEAD / working tree → source VERSION 0.0.3
+
+# ── Build a fresh fake consumer ──────────────────────────────────────
+build_consumer() {  # $1 = consumer root, $2 = meta baseline version
+  local C="$1" ver="$2"
+  rm -rf "$C"
+  mkdir -p "$C/.claude/scripts/hooks/lib" "$C/.claude/agents/references" \
+           "$C/.claude/rules" "$C/.claude/commands" "$C/.claude/skills"
+  cat > "$C/.claude/.superkit-meta" <<EOF
+SUPERKIT_SOURCE="$SRC"
+SUPERKIT_VERSION="$ver"
+SUPERKIT_STACKS="go"
+SUPERKIT_EXTRAS=""
+SUPERKIT_PROFILE="standard"
+EOF
+  # Installed updater = the fixed script PLUS a marker → differs from source →
+  # forces the self-bootstrap path (as a real stale install would).
+  cp "$NEW_UPDATER" "$C/.claude/scripts/hooks/superkit-update.sh"
+  printf '# LOCAL-STUB-MARKER\n' >> "$C/.claude/scripts/hooks/superkit-update.sh"
+  chmod +x "$C/.claude/scripts/hooks/superkit-update.sh"
+  # planted consumer files
+  wf "$C/.claude/agents/pristine.md"                        "P2"          # (a) pristine @ v0.0.2
+  wf "$C/.claude/scripts/hooks/ahook.sh"                    "S1"          # (c) matches older tag v0.0.1
+  wf "$C/.claude/rules/custom.md"                           "LOCAL-EDIT"  # (b) customized
+  wf "$C/.claude/scripts/hooks/superkit-counts-verify.sh"   "PLANTED"     # (d) internal planted
+  # newfile.md / references/ref.md / lib/profile.sh / gosafe.md / gohook.sh / skills → absent (e)
+}
+
+run_updater() {  # $1 = consumer root ; echoes combined stdout+stderr
+  CLAUDE_PROJECT_DIR="$1" bash "$1/.claude/scripts/hooks/superkit-update.sh" 2>&1
+}
+
+# ─────────────────────────────────────────────────────────────────────
+# MAIN RUN — baseline meta 0.0.2 (tag exists), source 0.0.3
+# ─────────────────────────────────────────────────────────────────────
+echo "── main run: meta baseline v0.0.2 → source 0.0.3"
+CONSUMER="$WORK/consumer"
+build_consumer "$CONSUMER" 0.0.2
+OUT="$(run_updater "$CONSUMER")"
+echo "$OUT" | sed 's/^/   [out] /'
+
+chk "(a) pristine@v0.0.2 → overwritten to new (P3)"            "$CONSUMER/.claude/agents/pristine.md" "P3"
+chk "(c) stale matching older tag v0.0.1 → overwritten (S3)"   "$CONSUMER/.claude/scripts/hooks/ahook.sh" "S3"
+chk "(b) customized (no tag match) → preserved byte-identical" "$CONSUMER/.claude/rules/custom.md" "LOCAL-EDIT"
+if echo "$OUT" | grep -qF "$CONSUMER/.claude/rules/custom.md"; then
+  pass "(b) customized file named in the report"
+else
+  fail "(b) customized file NOT named in report"
+fi
+chk "(d) internal file planted in consumer → NOT overwritten"  "$CONSUMER/.claude/scripts/hooks/superkit-counts-verify.sh" "PLANTED"
+if [ ! -e "$CONSUMER/.claude/scripts/hooks/verify-hooks.sh" ]; then
+  pass "(d) internal verify-hooks.sh absent → never newly copied"
+else
+  fail "(d) internal verify-hooks.sh was copied into consumer"
+fi
+if [ ! -e "$CONSUMER/.claude/rules/superkit-integrity.md" ]; then
+  pass "(d) internal superkit-integrity.md absent → never newly copied"
+else
+  fail "(d) internal superkit-integrity.md was copied into consumer"
+fi
+chk "(e) absent core agent → created"          "$CONSUMER/.claude/agents/newfile.md" "NEWFILE-CONTENT"
+chk "(e) absent reference doc → created"       "$CONSUMER/.claude/agents/references/ref.md" "REF-DOC"
+chk "(e) absent hooks/lib file → created"      "$CONSUMER/.claude/scripts/hooks/lib/profile.sh" "LIBPROFILE"
+chk "(e) absent stack-rule → created"          "$CONSUMER/.claude/rules/gosafe.md" "GOSAFE"
+chk "(e) absent stack-hook → created"          "$CONSUMER/.claude/scripts/hooks/gohook.sh" "GOHOOK"
+chk "(e) absent skill file → created"          "$CONSUMER/.claude/skills/demo/SKILL.md" "SKILL-BODY"
+chk "(e) absent ADR template → created at project root" "$CONSUMER/docs-templates/adr-template.md" "ADR-TEMPLATE-BODY"
+chk "(i) absent statusline → created at .claude/scripts/" "$CONSUMER/.claude/scripts/statusline.cjs" "STATUSLINE-V3"
+
+# self-bootstrap: the installed copy must have been replaced by the source copy
+if grep -qF 'LOCAL-STUB-MARKER' "$CONSUMER/.claude/scripts/hooks/superkit-update.sh"; then
+  fail "bootstrap: installed updater still carries the stub marker (not replaced)"
+else
+  pass "bootstrap: installed updater replaced by source copy before sync"
+fi
+# report line shape + K skipped == 3 internal
+if echo "$OUT" | grep -qE '^superkit-update: [0-9]+ synced · [0-9]+ preserved .* · 3 skipped \(internal\)'; then
+  pass "report: compact summary line with 3 internal skipped"
+else
+  fail "report: summary line missing/malformed"
+fi
+# meta version bumped to the new source version
+if grep -q 'SUPERKIT_VERSION="0.0.3"' "$CONSUMER/.claude/.superkit-meta"; then
+  pass "meta version bumped 0.0.2 → 0.0.3"
+else
+  fail "meta version not bumped"
+fi
+
+# ─────────────────────────────────────────────────────────────────────
+# (f) MISSING BASELINE TAG — meta 0.0.9 (no v0.0.9 tag in the fixture)
+# ─────────────────────────────────────────────────────────────────────
+echo ""
+echo "── (f) run: meta baseline v0.0.9 MISSING → source 0.0.3"
+CONSUMER_F="$WORK/consumer_f"
+build_consumer "$CONSUMER_F" 0.0.9
+OUT_F="$(run_updater "$CONSUMER_F")"
+echo "$OUT_F" | sed 's/^/   [out] /'
+
+chk "(f) missing baseline: customized file preserved (fail-safe)" "$CONSUMER_F/.claude/rules/custom.md" "LOCAL-EDIT"
+if echo "$OUT_F" | grep -qF "$CONSUMER_F/.claude/rules/custom.md"; then
+  pass "(f) preserved file reported"
+else
+  fail "(f) preserved file not reported"
+fi
+chk "(f) missing baseline: file matching walked tag v0.0.1 still synced" "$CONSUMER_F/.claude/scripts/hooks/ahook.sh" "S3"
+
+# ─────────────────────────────────────────────────────────────────────
+# (g) ADR TEMPLATE — project-root, create-if-missing, never clobber/report
+# ─────────────────────────────────────────────────────────────────────
+echo ""
+echo "── (g) run: pre-existing ADR template stays untouched & unreported"
+CONSUMER_G="$WORK/consumer_g"
+build_consumer "$CONSUMER_G" 0.0.2
+# Plant a locally-edited ADR template at the PROJECT root (not .claude/)
+wf "$CONSUMER_G/docs-templates/adr-template.md" "MY-CUSTOM-ADR"
+OUT_G="$(run_updater "$CONSUMER_G")"
+echo "$OUT_G" | sed 's/^/   [out] /'
+
+chk "(g) pre-existing ADR template → left untouched" "$CONSUMER_G/docs-templates/adr-template.md" "MY-CUSTOM-ADR"
+if echo "$OUT_G" | grep -qF "$CONSUMER_G/docs-templates/adr-template.md"; then
+  fail "(g) customized ADR template wrongly named in preserved report"
+else
+  pass "(g) ADR template NOT reported (doc template — silence is correct)"
+fi
+
+# ─────────────────────────────────────────────────────────────────────
+# (i-fork) FORKED statusline.cjs → preserved (consumers legitimately fork it)
+# ─────────────────────────────────────────────────────────────────────
+echo ""
+echo "── (i-fork) run: a forked statusline is preserved, not clobbered"
+CONSUMER_I="$WORK/consumer_i"
+build_consumer "$CONSUMER_I" 0.0.2
+wf "$CONSUMER_I/.claude/scripts/statusline.cjs" "MY-FORKED-STATUSLINE"
+OUT_I="$(run_updater "$CONSUMER_I")"
+echo "$OUT_I" | sed 's/^/   [out] /'
+chk "(i-fork) forked statusline → preserved byte-identical" "$CONSUMER_I/.claude/scripts/statusline.cjs" "MY-FORKED-STATUSLINE"
+if echo "$OUT_I" | grep -qF "$CONSUMER_I/.claude/scripts/statusline.cjs"; then
+  pass "(i-fork) forked statusline named in the preserved report"
+else
+  fail "(i-fork) forked statusline NOT reported"
+fi
+
+# ─────────────────────────────────────────────────────────────────────
+# (h) MANIFEST FALLBACK — must be PER CATEGORY (v1.5.2 fix)
+# A manifest that loses just one category's lines must still protect that
+# category via the hard-coded fallback; the healthy category keeps reading
+# from the manifest. Manifest mutations below are working-tree-only.
+# ─────────────────────────────────────────────────────────────────────
+echo ""
+echo "── (h) manifest fallback variants"
+MANIFEST="$P/core/INTERNAL-FILES"
+MANIFEST_BAK="$WORK/manifest.bak"
+cp "$MANIFEST" "$MANIFEST_BAK"
+
+# (h1) hooks-only manifest → rules category empty → rules MUST fall back
+printf 'hooks/superkit-counts-verify.sh\nhooks/verify-hooks.sh\n' > "$MANIFEST"
+C_H1="$WORK/consumer_h1"; build_consumer "$C_H1" 0.0.2
+OUT_H1="$(run_updater "$C_H1")"
+if [ ! -e "$C_H1/.claude/rules/superkit-integrity.md" ]; then
+  pass "(h1) hooks-only manifest: superkit-integrity.md still NOT copied (rules fallback)"
+else
+  fail "(h1) hooks-only manifest: superkit-integrity.md LEAKED into consumer"
+fi
+if [ ! -e "$C_H1/.claude/scripts/hooks/verify-hooks.sh" ]; then
+  pass "(h1) hooks-only manifest: hooks still skipped (from manifest)"
+else
+  fail "(h1) hooks-only manifest: verify-hooks.sh copied"
+fi
+if echo "$OUT_H1" | grep -q "no 'rules/' entries"; then
+  pass "(h1) empty category warned on stderr"
+else
+  fail "(h1) no stderr warning for the empty rules category"
+fi
+
+# (h2) rules-only manifest → hooks category empty → hooks MUST fall back
+printf 'rules/superkit-integrity.md\n' > "$MANIFEST"
+C_H2="$WORK/consumer_h2"; build_consumer "$C_H2" 0.0.2
+OUT_H2="$(run_updater "$C_H2")"
+if [ ! -e "$C_H2/.claude/scripts/hooks/verify-hooks.sh" ]; then
+  pass "(h2) rules-only manifest: verify-hooks.sh still NOT copied (hooks fallback)"
+else
+  fail "(h2) rules-only manifest: verify-hooks.sh LEAKED into consumer"
+fi
+if [ ! -e "$C_H2/.claude/rules/superkit-integrity.md" ]; then
+  pass "(h2) rules-only manifest: rules still skipped (from manifest)"
+else
+  fail "(h2) rules-only manifest: superkit-integrity.md copied"
+fi
+
+# (h3) manifest present but ALL lines commented → both categories fall back
+printf '# nothing here\n# hooks/superkit-counts-verify.sh\n' > "$MANIFEST"
+C_H3="$WORK/consumer_h3"; build_consumer "$C_H3" 0.0.2
+OUT_H3="$(run_updater "$C_H3")"
+if [ ! -e "$C_H3/.claude/rules/superkit-integrity.md" ] && [ ! -e "$C_H3/.claude/scripts/hooks/verify-hooks.sh" ]; then
+  pass "(h3) all-commented manifest: both categories fall back, nothing leaked"
+else
+  fail "(h3) all-commented manifest: an internal file leaked"
+fi
+
+# (h4) manifest MISSING entirely → both fall back, silently (pre-manifest clones)
+rm -f "$MANIFEST"
+C_H4="$WORK/consumer_h4"; build_consumer "$C_H4" 0.0.2
+OUT_H4="$(run_updater "$C_H4")"
+if [ ! -e "$C_H4/.claude/rules/superkit-integrity.md" ] && [ ! -e "$C_H4/.claude/scripts/hooks/verify-hooks.sh" ]; then
+  pass "(h4) missing manifest: both categories fall back, nothing leaked"
+else
+  fail "(h4) missing manifest: an internal file leaked"
+fi
+if echo "$OUT_H4" | grep -q "entries"; then
+  fail "(h4) missing manifest warned (should be silent — benign for pre-manifest clones)"
+else
+  pass "(h4) missing manifest stays silent"
+fi
+
+# (h5) complete manifest restored → all three skipped again (from the manifest)
+cp "$MANIFEST_BAK" "$MANIFEST"
+C_H5="$WORK/consumer_h5"; build_consumer "$C_H5" 0.0.2
+OUT_H5="$(run_updater "$C_H5")"
+if echo "$OUT_H5" | grep -qE '· 3 skipped \(internal\)' && [ ! -e "$C_H5/.claude/rules/superkit-integrity.md" ]; then
+  pass "(h5) complete manifest: 3 internal skipped, no fallback needed"
+else
+  fail "(h5) complete manifest: skip accounting wrong"
+fi
+
+# ── Summary ──────────────────────────────────────────────────────────
+echo ""
+TOTAL=$((PASS + FAIL))
+if [ "$FAIL" -gt 0 ]; then
+  echo "SUPERKIT-UPDATE TESTS FAILED ($FAIL/$TOTAL failed)"
+  exit 1
+fi
+echo "ALL SUPERKIT-UPDATE TESTS PASSED ($PASS/$TOTAL)"

package/packages/core/hooks/tests/warn-visibility_test.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+# warn-visibility_test.sh — regression test for superkit_advise (Task 17)
+#
+# Verifies that warn-only PreToolUse advisories are surfaced as valid JSON
+# `hookSpecificOutput.additionalContext` on stdout (Claude Code can swallow
+# non-blocking PreToolUse stderr). Asserts both validity and correct escaping.
+set -euo pipefail
+
+LIB="$(cd "$(dirname "$0")/.." && pwd)/lib/profile.sh"
+[ -f "$LIB" ] || { echo "FAIL: lib not found at $LIB"; exit 1; }
+# shellcheck source=/dev/null
+source "$LIB"
+
+command -v superkit_advise >/dev/null 2>&1 || { echo "FAIL: superkit_advise not exported by profile.sh"; exit 1; }
+
+# Test 1: valid JSON + correct escaping of embedded double-quotes
+OUT=$(superkit_advise 'hello "world"')
+if ! printf '%s' "$OUT" | jq -e '.hookSpecificOutput.additionalContext == "hello \"world\""' >/dev/null; then
+  echo "FAIL: additionalContext did not round-trip with escaped quotes"
+  echo "  got: $OUT"
+  exit 1
+fi
+echo "PASS: escaped-quote message round-trips as valid JSON"
+
+# Test 2: hookEventName is PreToolUse
+if ! printf '%s' "$OUT" | jq -e '.hookSpecificOutput.hookEventName == "PreToolUse"' >/dev/null; then
+  echo "FAIL: hookEventName should be PreToolUse"
+  exit 1
+fi
+echo "PASS: hookEventName == PreToolUse"
+
+# Test 3: backslashes and plain text survive
+OUT2=$(superkit_advise 'path C:\temp and a plain sentence.')
+if ! printf '%s' "$OUT2" | jq -e '.hookSpecificOutput.additionalContext == "path C:\\temp and a plain sentence."' >/dev/null; then
+  echo "FAIL: backslash message did not round-trip"
+  echo "  got: $OUT2"
+  exit 1
+fi
+echo "PASS: backslash + plain text round-trips"
+
+# Test 4: gateguard-pre-edit advisory path emits additionalContext on stdout.
+# No prior Grep/Read state → advisory branch fires; assert stdout carries
+# valid hookSpecificOutput JSON (stderr is allowed but not relied upon).
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/gateguard-pre-edit.sh"
+[ -x "$HOOK" ] || { echo "FAIL: gateguard hook not executable at $HOOK"; exit 1; }
+GG_STATE="${TMPDIR:-/tmp}/superkit-gateguard-warnvis-$$"
+rm -f "$GG_STATE"
+STDOUT=$(echo '{"hook_event_name":"PreToolUse","tool_name":"Edit","tool_input":{"file_path":"/tmp/fake.txt"}}' \
+  | CLAUDE_GATEGUARD_STATE="$GG_STATE" bash "$HOOK" 2>/dev/null || true)
+rm -f "$GG_STATE"
+if ! printf '%s' "$STDOUT" | jq -e '.hookSpecificOutput.hookEventName == "PreToolUse" and (.hookSpecificOutput.additionalContext | test("GateGuard"))' >/dev/null; then
+  echo "FAIL: gateguard advisory did not surface additionalContext on stdout"
+  echo "  stdout was: $STDOUT"
+  exit 1
+fi
+echo "PASS: gateguard advisory surfaces additionalContext on stdout"
+
+echo ""
+echo "ALL WARN-VISIBILITY TESTS PASSED (4/4)"

package/packages/core/hooks/user-intent-detect.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# user-intent-detect.sh — identify user-initiated quick-work intent
+# Triggers on: UserPromptSubmit
+# Profile: standard, strict
+#
+# When the user explicitly asks for a quick/small change, we mark the
+# session. `dev-required-on-commit.sh` then allows `[quick]` WITHOUT
+# the ≥15 char rationale — the user explicitly took responsibility.
+# When Claude autonomously picks `[quick]` without a matching user
+# signal, the override counts DOUBLE against the Task 12 budget
+# (not implemented here — see Task 15 follow-up in the plan).
+#
+# Marker: ${TMPDIR:-/tmp}/claude-user-said-quick-<session>
+# Opt-out: CLAUDE_DISABLE_INTENT_DETECT=1
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+if [ "$PROFILE" = "fast" ] || [ "${CLAUDE_DISABLE_INTENT_DETECT:-}" = "1" ]; then
+  exit 0
+fi
+
+INPUT=$(cat 2>/dev/null || echo '{}')
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // empty' 2>/dev/null)
+[ "$EVENT" = "UserPromptSubmit" ] || exit 0
+
+PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty' 2>/dev/null)
+[ -z "$PROMPT" ] && exit 0
+
+# Match explicit user signals for quick / small work. Keep these narrow
+# so a user typing "the quick brown fox" doesn't false-trigger.
+if ! printf '%s' "$PROMPT" | grep -qiE '(^|[[:space:]])(quick fix|small tweak|tiny change|just fix|fast fix|hotfix|small fix|quick change|небольшой фикс|быстрый фикс)([[:space:]]|[.,!?:;]|$)'; then
+  exit 0
+fi
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+SESSION_KEY="${SESSION_ID:-${CLAUDE_HOOK_PID:-$PPID}}"
+MARKER="${TMPDIR:-/tmp}/claude-user-said-quick-${SESSION_KEY}"
+touch "$MARKER"
+exit 0

package/packages/core/hooks/verify-hooks.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# verify-hooks.sh — Check that hook scripts are tracked in git and executable
+# Run: bash .claude/scripts/hooks/verify-hooks.sh
+
+# Note: no set -e — hooks must fail-open
+
+HOOKS_DIR=".claude/scripts/hooks"
+ISSUES=0
+
+# Check hooks directory exists
+if [ ! -d "$HOOKS_DIR" ]; then
+  echo "❌ Hooks directory not found: $HOOKS_DIR"
+  echo "   Run the superkit installer to set up hooks."
+  exit 1
+fi
+
+# Check .gitignore doesn't block hooks
+if [ -f ".gitignore" ]; then
+  if grep -qE '^\s*\.claude/scripts/?$|^\s*\.claude/scripts/\*' .gitignore 2>/dev/null; then
+    echo "❌ CRITICAL: .gitignore blocks hook scripts!"
+    echo "   Line found: $(grep -E '\.claude/scripts' .gitignore)"
+    echo "   Remove this line — hooks MUST be tracked in git for enforcement to work."
+    echo "   Other users who clone this repo will get NO hook enforcement."
+    ISSUES=$((ISSUES + 1))
+  fi
+fi
+
+# Check hooks are executable
+for hook in "$HOOKS_DIR"/*.sh; do
+  [ -f "$hook" ] || continue
+  if [ ! -x "$hook" ]; then
+    echo "⚠️  Not executable: $hook"
+    echo "   Fix: chmod +x $hook"
+    ISSUES=$((ISSUES + 1))
+  fi
+done
+
+# Check hooks are tracked in git
+if command -v git >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  for hook in "$HOOKS_DIR"/*.sh; do
+    [ -f "$hook" ] || continue
+    if git check-ignore -q "$hook" 2>/dev/null; then
+      echo "❌ Git-ignored: $hook"
+      echo "   This hook won't be available to anyone who clones the repo."
+      ISSUES=$((ISSUES + 1))
+    fi
+  done
+
+  UNTRACKED=$(git ls-files --others --exclude-standard "$HOOKS_DIR" 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$UNTRACKED" -gt 0 ]; then
+    echo "⚠️  $UNTRACKED hook(s) not committed to git:"
+    git ls-files --others --exclude-standard "$HOOKS_DIR" 2>/dev/null | while read -r f; do
+      echo "   $f"
+    done
+    echo "   Run: git add $HOOKS_DIR/ && git commit"
+    ISSUES=$((ISSUES + 1))
+  fi
+fi
+
+if [ "$ISSUES" -eq 0 ]; then
+  HOOK_COUNT=$(find "$HOOKS_DIR" -name '*.sh' 2>/dev/null | wc -l | tr -d ' ')
+  echo "✅ All $HOOK_COUNT hooks are properly configured and tracked in git."
+else
+  echo ""
+  echo "Found $ISSUES issue(s). Fix them to ensure enforcement works for all team members."
+  exit 1
+fi
+
+exit 0

package/packages/core/rules/auto-commands.md

@@ -0,0 +1,124 @@
+---
+alwaysApply: true
+tokens: 1483
+---
+
+# Auto Command Triggers
+
+Commands Claude MUST invoke automatically when a condition below matches — without the user asking. Complements `dev-workflow.md` (which owns `/dev` auto-triggers).
+
+## Hard Rules
+
+1. **Docs before commit — highest priority, NEVER skip.** Before EVERY `git commit` that includes code changes, verify docs are staged alongside code (see Documentation section below).
+2. **No double-runs.** A command that already ran for this task — via `/dev` or an explicit user call — is not run again.
+3. **Silent execution.** Run auto-triggered commands without announcing or asking permission; report findings in 1–3 lines, not full verbose output.
+4. **Never auto-fix security findings.** `/security-scan` results always go to the user first.
+5. **User override.** If the user says "skip review" / "don't test", skip that command for the current task.
+
+## /review — Auto Code Review
+
+| Trigger | Condition |
+|---------|-----------|
+| Post-implementation | After completing work on **3+ files** in one task |
+| Pre-commit | Before user-requested `git commit` if **5+ files** changed |
+| Security-sensitive | After modifying auth, session, permission, or crypto-related code |
+
+**Behavior:**
+- Run right after finishing implementation — do not ask "should I review?"
+- Use `--comment` only when the user is working on a PR
+- Skip if `/dev` already ran — its Review phase covers this
+
+## /test — Auto Test Run
+
+| Trigger | Condition |
+|---------|-----------|
+| After feature implementation | New endpoint, service, handler, or component created |
+| After bug fix | Any fix that touches logic (not just typos/config) |
+| After refactor | Structural changes to existing code |
+| Test file edited | When test files are directly modified — verify they pass |
+
+**Behavior:**
+- Auto-detect stack and run the matching test command
+- Run the test scope covering the changed files (same package/module/directory); run the full suite only when that mapping is unclear or **10+ files** changed
+- If tests fail — report and suggest fixes, do NOT silently proceed
+- Skip if `/dev` already ran — its Test phase covers this
+
+## /lint — Auto Lint Check
+
+| Trigger | Condition |
+|---------|-----------|
+| Pre-commit | Before any `git commit` with code changes (not docs-only) |
+| Multi-file edit | After editing **5+ code files** in one task |
+
+**Behavior:**
+- Run full lint (single-file hooks catch only basics)
+- Auto-fix safe issues (formatting, import sorting) without asking
+- Report unfixable issues to the user
+- Skip if stack hooks already cover everything (e.g., strict profile with go-vet + typecheck)
+
+## /audit --health — Auto Health Check
+
+| Trigger | Condition |
+|---------|-----------|
+| Session start (long task) | When the user requests a task that will take **10+ file changes** |
+| Post-major-refactor | After refactoring that touches **10+ files** |
+
+**Behavior:**
+- Use `--health` (quick mode, ~30s) — never full `/audit` automatically
+- Report critical findings only, suppress suggestions
+- Launch it in the background and continue the main task; if background execution is unavailable, run it last, after all other auto-triggers
+
+## /security-scan — Auto Security Check
+
+`/security-scan` audits `.claude/` configuration (AgentShield) — its triggers therefore fire on configuration changes, not on application code:
+
+| Trigger | Condition |
+|---------|-----------|
+| Claude config changed | Any file under `.claude/` edited: `settings*.json`, `agents/*`, `hooks/*`, `commands/*`, `rules/*` |
+| MCP wiring changed | `.mcp.json` or `mcpServers` blocks edited |
+| Kit install/update ran | After `npx claude-code-superkit` or `setup.sh` completes |
+
+For application-code security (auth files, new dependencies, CI/CD configs), rely on **security-scanner** — /review and the /dev Review phase auto-dispatch it for exactly those changes.
+
+**Behavior:**
+- Auto-triggered scans use the plain scan — no `--fix`, no `--opus`
+- AgentShield grades on its own `critical / high / medium / low` scale — relay it verbatim, never remap to the kit's CRITICAL / WARNING / SUGGESTION
+- For auto-triggered scans, report only `critical` and `high` findings
+- Do NOT auto-fix security issues — always report to the user first (Hard Rule 4)
+
+## Documentation — Auto Verify Before Commit
+
+Highest-priority auto-trigger (Hard Rule 1).
+
+| Trigger | Condition |
+|---------|-----------|
+| Pre-commit | Before EVERY `git commit` that includes code changes (.go, .ts, .tsx, .sql, .py, .rs) |
+
+**Behavior:**
+- Before committing, verify corresponding docs are staged alongside code:
+  - **Migration staged** → database schema docs updated
+  - **Handler/endpoint changed** → API reference docs updated
+  - **Frontend behavior changed** → frontend state/architecture docs updated
+- Docs missing → update them BEFORE committing, not after
+- The `doc-check-on-commit` hook BLOCKS commits with missing docs — fix the docs, never bypass the hook
+
+## When NOT to auto-trigger
+
+| Situation | Why skip |
+|-----------|----------|
+| Already inside `/dev` workflow | its Verify, Test, and Review phases cover this |
+| User explicitly said "just do X" / "quick fix" | respect user intent for speed |
+| Docs-only or config-only changes | no logic to test/review/scan |
+| User is exploring / asking questions | no code changes to validate |
+| Single file, < 50 lines changed | overhead not justified |
+
+## Priority
+
+When multiple auto-triggers fire, run in this order:
+1. `/lint` (fastest, catches obvious issues)
+2. `/test` (catches logic errors)
+3. `/review` (catches design issues)
+4. `/security-scan` (catches vulnerabilities)
+5. `/audit --health` (overall health, lowest priority)
+
+Early stop: if **fewer than 3 files** changed AND every command already run in this order reported zero issues → skip the remaining lower-priority commands. Exception: a command whose own trigger condition matched still runs (e.g., `/security-scan` after a `.claude/` config edit).