claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/core/hooks/tests/internal-manifest_test.sh

@@ -0,0 +1,130 @@
+#!/bin/bash
+# internal-manifest_test.sh — guards the single-source-of-truth for repo-only
+# files (packages/core/INTERNAL-FILES) and its two consumers.
+#
+# Three internal files must NEVER ship into a consumer's .claude/:
+#   hooks/superkit-counts-verify.sh, hooks/verify-hooks.sh, rules/superkit-integrity.md
+# The skip-list used to be hand-duplicated in lib/installer.js and
+# superkit-counts-verify.sh (and missing from superkit-update.sh). This suite
+# fails the moment either consumer re-hard-codes a name instead of reading the
+# manifest, or the manifest itself drifts from the three expected entries.
+#
+# Pure read-only: `grep`/file tests only. No writes, no network.
+set -uo pipefail
+
+# Resolve the repo root exactly like sibling suites (counts-verify_test.sh):
+# tests → hooks → core → packages → repo root.
+REPO_ROOT="$(cd "$(dirname "$0")/../../../.." && pwd)"
+
+MANIFEST_REL="packages/core/INTERNAL-FILES"
+MANIFEST="$REPO_ROOT/$MANIFEST_REL"
+INSTALLER="lib/installer.js"
+HOOK="packages/core/hooks/superkit-counts-verify.sh"
+
+# Exactly these three, no more, no fewer (see PROMPT D2: "Do not expand").
+EXPECTED_ENTRIES=(
+  "hooks/superkit-counts-verify.sh"
+  "hooks/verify-hooks.sh"
+  "rules/superkit-integrity.md"
+)
+
+PASS_COUNT=0
+FAIL_COUNT=0
+pass() { echo "PASS: $1"; PASS_COUNT=$((PASS_COUNT + 1)); }
+fail() { echo "FAIL: $1"; FAIL_COUNT=$((FAIL_COUNT + 1)); }
+
+# ── Parse the manifest the same way its consumers do ────────────────────────
+# Drop '#' comment lines and blanks; trim surrounding whitespace.
+ENTRIES=()
+if [ -f "$MANIFEST" ]; then
+  while IFS= read -r line || [ -n "$line" ]; do
+    line="${line#"${line%%[![:space:]]*}"}"   # ltrim
+    line="${line%"${line##*[![:space:]]}"}"   # rtrim
+    [ -z "$line" ] && continue
+    case "$line" in \#*) continue ;; esac
+    ENTRIES+=("$line")
+  done < "$MANIFEST"
+fi
+
+# ── (a) manifest exists with exactly the 3 expected entries ─────────────────
+echo "── (a): manifest exists with exactly the 3 expected entries"
+if [ ! -f "$MANIFEST" ]; then
+  fail "(a) manifest not found: $MANIFEST_REL"
+else
+  if [ "${#ENTRIES[@]}" -eq "${#EXPECTED_ENTRIES[@]}" ]; then
+    pass "(a) manifest has exactly ${#EXPECTED_ENTRIES[@]} entries"
+  else
+    fail "(a) manifest has ${#ENTRIES[@]} entries, expected ${#EXPECTED_ENTRIES[@]} (${ENTRIES[*]:-<none>})"
+  fi
+  # Every expected entry must be present.
+  for want in "${EXPECTED_ENTRIES[@]}"; do
+    found=0
+    for got in "${ENTRIES[@]:-}"; do [ "$got" = "$want" ] && found=1; done
+    if [ "$found" -eq 1 ]; then pass "(a) manifest lists '$want'"; else fail "(a) manifest MISSING '$want'"; fi
+  done
+  # No unexpected entry may sneak in.
+  for got in "${ENTRIES[@]:-}"; do
+    [ -z "$got" ] && continue
+    ok=0
+    for want in "${EXPECTED_ENTRIES[@]}"; do [ "$got" = "$want" ] && ok=1; done
+    [ "$ok" -eq 1 ] || fail "(a) manifest has UNEXPECTED entry '$got' (do not expand without evidence)"
+  done
+fi
+
+# ── (b) each entry resolves to an existing file under packages/core/ ────────
+echo ""
+echo "── (b): each entry resolves to an existing file under packages/core/"
+for entry in "${ENTRIES[@]:-}"; do
+  [ -z "$entry" ] && continue
+  if [ -f "$REPO_ROOT/packages/core/$entry" ]; then
+    pass "(b) packages/core/$entry exists"
+  else
+    fail "(b) packages/core/$entry does NOT exist"
+  fi
+done
+
+# ── (c) both consumers reference the manifest by name ───────────────────────
+echo ""
+echo "── (c): installer.js and superkit-counts-verify.sh reference INTERNAL-FILES"
+for f in "$INSTALLER" "$HOOK"; do
+  if grep -qF -- "INTERNAL-FILES" "$REPO_ROOT/$f"; then
+    pass "(c) $f references INTERNAL-FILES"
+  else
+    fail "(c) $f does NOT reference INTERNAL-FILES (must read the manifest)"
+  fi
+done
+
+# ── (d) no internal file NAME hard-coded outside a FALLBACK-marked line ─────
+# The only legitimate literal occurrences are the fallback constants that guard
+# against a missing manifest — those lines are tagged FALLBACK. Any occurrence
+# on a non-FALLBACK line means a consumer re-hard-coded the skip-list.
+echo ""
+echo "── (d): 'verify-hooks.sh' / 'superkit-integrity.md' appear only on FALLBACK lines"
+assert_only_in_fallback() {
+  local file="$1" literal="$2" path="$REPO_ROOT/$1" offenders
+  # Lines that contain the literal but are NOT marked FALLBACK are offenders.
+  offenders="$(grep -nF -- "$literal" "$path" 2>/dev/null | grep -v 'FALLBACK' || true)"
+  if [ -n "$offenders" ]; then
+    fail "(d) $file hard-codes '$literal' outside a FALLBACK line:"
+    echo "$offenders" | sed 's/^/         /'
+  elif grep -qF -- "$literal" "$path"; then
+    pass "(d) $file: '$literal' only on FALLBACK line(s)"
+  else
+    # Absent entirely is also fine — nothing to hard-code — but flag it so a
+    # silently-deleted fallback is noticed.
+    fail "(d) $file: '$literal' not found at all (fallback removed?)"
+  fi
+}
+assert_only_in_fallback "$INSTALLER" "verify-hooks.sh"
+assert_only_in_fallback "$INSTALLER" "superkit-integrity.md"
+assert_only_in_fallback "$HOOK"      "verify-hooks.sh"
+assert_only_in_fallback "$HOOK"      "superkit-integrity.md"
+
+# ── Summary ─────────────────────────────────────────────────────────────────
+echo ""
+TOTAL=$((PASS_COUNT + FAIL_COUNT))
+if [ "$FAIL_COUNT" -gt 0 ]; then
+  echo "INTERNAL-MANIFEST TESTS FAILED ($FAIL_COUNT/$TOTAL failed)"
+  exit 1
+fi
+echo "ALL INTERNAL-MANIFEST TESTS PASSED ($PASS_COUNT/$TOTAL)"

package/packages/core/hooks/tests/json-path_test.sh

@@ -0,0 +1,108 @@
+#!/bin/bash
+# json-path_test.sh — sanity tests that the 5 hooks read `.tool_input.*`
+# correctly after the 2026-04-14 fix. Before the fix, these hooks read
+# `.command` / `.file_path` at the top level and silently exited 0.
+# Each case here asserts that the hook actually exercises its main
+# branch when given a well-formed Claude Code payload.
+#
+# Usage: bash packages/core/hooks/tests/json-path_test.sh
+# Exit codes: 0 if all cases pass, 1 on first failure.
+
+set -u
+
+HOOKS=$(cd "$(dirname "$0")/.." && pwd)
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+
+PASS=0
+FAIL=0
+FAIL_DETAILS=""
+
+# Prepare a repo with staged changes so doc-check + dev-required have something
+# to diff against.
+REPO="$TMP/repo"
+mkdir -p "$REPO/backend/migrations"
+(cd "$REPO" && git init -q && \
+  echo "init" > README.md && git add README.md && \
+  git -c user.email=t@t -c user.name=t commit -qm init && \
+  echo "CREATE TABLE foo();" > backend/migrations/001_foo.up.sql && \
+  git add backend/migrations/001_foo.up.sql)
+
+assert_exit() {
+  local name="$1"
+  local expected="$2"
+  local actual="$3"
+  local allow_any="${4:-false}"
+  if [ "$allow_any" = "true" ] || [ "$actual" = "$expected" ]; then
+    echo "  ✓ $name (exit=$actual)"
+    PASS=$((PASS + 1))
+  else
+    echo "  ✗ $name — expected $expected, got $actual"
+    FAIL=$((FAIL + 1))
+    FAIL_DETAILS="${FAIL_DETAILS}\n  - $name (expected=$expected actual=$actual)"
+  fi
+}
+
+echo "json-path_test.sh — verify all 5 hooks read .tool_input.* correctly"
+echo ""
+
+# 1) doc-check-on-commit — must BLOCK (code staged, no docs)
+PAYLOAD=$(printf '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"git -C %s commit -m test"}}' "$REPO")
+ACTUAL=$(echo "$PAYLOAD" | bash "$HOOKS/doc-check-on-commit.sh" >/dev/null 2>&1; echo $?)
+assert_exit "doc-check-on-commit blocks missing docs" 2 "$ACTUAL"
+
+# 2) superkit-counts-verify — exit 0 outside superkit repo (no packages/ layout)
+PAYLOAD=$(printf '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"git -C %s commit -m test"}}' "$REPO")
+ACTUAL=$(cd "$TMP" && echo "$PAYLOAD" | bash "$HOOKS/superkit-counts-verify.sh" >/dev/null 2>&1; echo $?)
+assert_exit "superkit-counts-verify exits 0 outside superkit repo" 0 "$ACTUAL"
+
+# 3) config-protection — warn on .eslintrc (exit 0 always, but must fire)
+PAYLOAD='{"hook_event_name":"PostToolUse","tool_name":"Edit","tool_input":{"file_path":"/tmp/.eslintrc.json"}}'
+OUTPUT=$(echo "$PAYLOAD" | bash "$HOOKS/config-protection.sh" 2>&1)
+ACTUAL=$?
+if echo "$OUTPUT" | grep -q "WARNING: Config file modified"; then
+  echo "  ✓ config-protection warns on .eslintrc (exit=$ACTUAL)"
+  PASS=$((PASS + 1))
+else
+  echo "  ✗ config-protection did NOT warn on .eslintrc — output: $OUTPUT"
+  FAIL=$((FAIL + 1))
+  FAIL_DETAILS="${FAIL_DETAILS}\n  - config-protection missed .eslintrc.json"
+fi
+
+# 4) security-patterns — warn on eval() in a .js file (exit 0 always)
+echo 'foo(eval(x));' > "$TMP/bad.js"
+PAYLOAD=$(printf '{"hook_event_name":"PostToolUse","tool_name":"Edit","tool_input":{"file_path":"%s"}}' "$TMP/bad.js")
+OUTPUT=$(echo "$PAYLOAD" | bash "$HOOKS/security-patterns.sh" 2>&1)
+if echo "$OUTPUT" | grep -q "eval()"; then
+  echo "  ✓ security-patterns flags eval()"
+  PASS=$((PASS + 1))
+else
+  echo "  ✗ security-patterns missed eval() — output: $OUTPUT"
+  FAIL=$((FAIL + 1))
+  FAIL_DETAILS="${FAIL_DETAILS}\n  - security-patterns missed eval() in .js"
+fi
+
+# 5) loop-guard — first call just records (exit 0, no block)
+export TMPDIR="$TMP"
+rm -f "$TMP/claude-loop-guard-"*
+PAYLOAD='{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"ls -la"}}'
+ACTUAL=$(echo "$PAYLOAD" | bash "$HOOKS/loop-guard.sh" >/dev/null 2>&1; echo $?)
+assert_exit "loop-guard first call → allow" 0 "$ACTUAL"
+# Verify a fingerprint file was actually written (proves COMMAND was read)
+LOG=$(ls "$TMP/claude-loop-guard-"* 2>/dev/null | head -1)
+if [ -n "$LOG" ] && [ -s "$LOG" ]; then
+  echo "  ✓ loop-guard wrote fingerprint ($(wc -l < "$LOG") entries)"
+  PASS=$((PASS + 1))
+else
+  echo "  ✗ loop-guard did not write a fingerprint — command was not parsed"
+  FAIL=$((FAIL + 1))
+  FAIL_DETAILS="${FAIL_DETAILS}\n  - loop-guard skipped (empty .tool_input.command parse)"
+fi
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+if [ "$FAIL" -gt 0 ]; then
+  echo -e "Failures:${FAIL_DETAILS}"
+  exit 1
+fi
+exit 0

package/packages/core/hooks/tests/mirror-invariants_test.sh

@@ -0,0 +1,139 @@
+#!/bin/bash
+# mirror-invariants_test.sh — mirror-drift regression suite.
+#
+# Claude components and their Codex mirrors are hand-maintained copies. When a
+# clause is edited on one side and not the other, the pair silently drifts.
+# This suite pins invariant substrings on BOTH sides of each mirror pair, the
+# same way ponytail's scripts/check-rule-copies.js pins its 9 substrings:
+# drift on either side fails the suite.
+#
+# Pure read-only: `grep`/`find`/`ls` only. No writes, no network.
+#
+# ─────────────────────────────────────────────────────────────────────────────
+#  MAINTENANCE CONTRACT
+#  Every string pinned in the tables below is expected to appear VERBATIM on
+#  BOTH sides of its mirror pair. If you edit a mirrored clause:
+#    • edit BOTH files (the Claude agent AND its Codex SKILL/AGENTS mirror), and
+#    • if the clause's wording legitimately changed, update the pin here too.
+#  Never "fix" a failure by touching only one side — that IS the drift this
+#  suite exists to catch.
+# ─────────────────────────────────────────────────────────────────────────────
+set -uo pipefail
+
+# Resolve the repo root exactly like sibling suites (counts-verify_test.sh):
+# tests → hooks → core → packages → repo root.
+REPO_ROOT="$(cd "$(dirname "$0")/../../../.." && pwd)"
+
+PASS_COUNT=0
+FAIL_COUNT=0
+
+# assert_contains <label> <repo-relative-file> <fixed-substring>
+# PASS when the file exists AND contains the literal substring; FAIL otherwise.
+assert_contains() {
+  local label="$1" file="$2" substr="$3"
+  local path="$REPO_ROOT/$file"
+  if [ ! -f "$path" ]; then
+    echo "FAIL: $label — file not found: $file"
+    FAIL_COUNT=$((FAIL_COUNT + 1))
+    return
+  fi
+  if grep -qF -- "$substr" "$path"; then
+    echo "PASS: $label — [$substr] present in $file"
+    PASS_COUNT=$((PASS_COUNT + 1))
+  else
+    echo "FAIL: $label — [$substr] MISSING from $file"
+    FAIL_COUNT=$((FAIL_COUNT + 1))
+  fi
+}
+
+# ─── INVARIANT TABLE (GROUP 1 + GROUP 2 share these 6 pairs) ─────────────────
+# Row format: <claude_file>::<codex_mirror>::<sub1>|<sub2>|<sub3>
+# The three subs per row are the external-symbol Evidence-Gate clause: the
+# reviewer must consult real symbols (go doc / node_modules / inspect.signature
+# / cargo) rather than reason "from memory", and label anything unverified
+# "ASSUMED". Both sides of every pair must carry all three.
+MIRROR_PAIRS=(
+  "packages/stack-agents/go/go-reviewer.md::packages/codex/skills/go-reviewer/SKILL.md::go doc|from memory|ASSUMED"
+  "packages/stack-agents/go/go-error-reviewer.md::packages/codex/skills/go-error-reviewer/SKILL.md::go doc|from memory|ASSUMED"
+  "packages/stack-agents/go/go-concurrency-reviewer.md::packages/codex/skills/go-concurrency-reviewer/SKILL.md::go doc|from memory|ASSUMED"
+  "packages/stack-agents/typescript/ts-reviewer.md::packages/codex/skills/ts-reviewer/SKILL.md::node_modules|from memory|ASSUMED"
+  "packages/stack-agents/python/py-reviewer.md::packages/codex/skills/py-reviewer/SKILL.md::inspect.signature|from memory|ASSUMED"
+  "packages/stack-agents/rust/rs-reviewer.md::packages/codex/skills/rs-reviewer/SKILL.md::cargo|from memory|ASSUMED"
+)
+
+# GROUP 2: severity enum — every reviewer (Claude + Codex) must offer all three.
+SEVERITY_TOKENS=("CRITICAL" "WARNING" "SUGGESTION")
+
+# GROUP 3: the Solution Ladder coding-style clause, mirrored Claude → Codex.
+SOLUTION_LADDER_FILES=(
+  "packages/core/rules/coding-style.md"
+  "packages/codex/AGENTS.md"
+)
+SOLUTION_LADDER_SUBS="Solution Ladder|Minimal never means fragile|YAGNI"
+
+# GROUP 4: Go reference-doc count reconciliation.
+GO_REF_DIR="packages/stack-agents/go/references"
+GO_COUNT_FILE="CLAUDE.md"
+
+# ── GROUP 1 — external-symbol Evidence Gate pins on both sides of each pair ──
+echo "── GROUP 1: Evidence-Gate mirror pairs (both sides carry all 3 pins)"
+for row in "${MIRROR_PAIRS[@]}"; do
+  claude_file="${row%%::*}"
+  rest="${row#*::}"
+  codex_file="${rest%%::*}"
+  subs="${rest##*::}"
+  IFS='|' read -r -a sub_arr <<< "$subs"
+  for s in "${sub_arr[@]}"; do
+    assert_contains "G1 claude" "$claude_file" "$s"
+    assert_contains "G1 codex " "$codex_file" "$s"
+  done
+done
+
+# ── GROUP 2 — severity enum present in all 12 reviewers (6 Claude + 6 Codex) ─
+echo ""
+echo "── GROUP 2: severity enum (CRITICAL/WARNING/SUGGESTION) in all 12 reviewers"
+for row in "${MIRROR_PAIRS[@]}"; do
+  claude_file="${row%%::*}"
+  rest="${row#*::}"
+  codex_file="${rest%%::*}"
+  for f in "$claude_file" "$codex_file"; do
+    for tok in "${SEVERITY_TOKENS[@]}"; do
+      assert_contains "G2" "$f" "$tok"
+    done
+  done
+done
+
+# ── GROUP 3 — Solution Ladder mirror ────────────────────────────────────────
+echo ""
+echo "── GROUP 3: Solution Ladder clause mirrored Claude ↔ Codex"
+IFS='|' read -r -a sl_arr <<< "$SOLUTION_LADDER_SUBS"
+for f in "${SOLUTION_LADDER_FILES[@]}"; do
+  for s in "${sl_arr[@]}"; do
+    assert_contains "G3" "$f" "$s"
+  done
+done
+
+# ── GROUP 4 — Go reference count reconciliation ─────────────────────────────
+echo ""
+echo "── GROUP 4: Go reference count reconciles with CLAUDE.md structure note"
+N=$(find "$REPO_ROOT/$GO_REF_DIR" -maxdepth 1 -name '*.md' | wc -l | tr -d ' ')
+LITERAL="# ${N} Go knowledge documents"
+if grep -qF -- "$LITERAL" "$REPO_ROOT/$GO_COUNT_FILE"; then
+  echo "PASS: G4 — $GO_COUNT_FILE reconciles: '$LITERAL' (=$N *.md in $GO_REF_DIR)"
+  PASS_COUNT=$((PASS_COUNT + 1))
+else
+  # Surface what CLAUDE.md actually claims, for a clear expected-vs-found error.
+  FOUND=$(grep -E 'Go knowledge documents' "$REPO_ROOT/$GO_COUNT_FILE" \
+            | head -1 | sed -nE 's/.*# *([0-9]+) Go knowledge documents.*/\1/p')
+  echo "FAIL: G4 — $GO_REF_DIR has $N *.md files, but $GO_COUNT_FILE says '${FOUND:-<none>} Go knowledge documents' (expected literal '$LITERAL')"
+  FAIL_COUNT=$((FAIL_COUNT + 1))
+fi
+
+# ── Summary ──────────────────────────────────────────────────────────────────
+echo ""
+TOTAL=$((PASS_COUNT + FAIL_COUNT))
+if [ "$FAIL_COUNT" -gt 0 ]; then
+  echo "MIRROR-INVARIANTS TESTS FAILED ($FAIL_COUNT/$TOTAL failed)"
+  exit 1
+fi
+echo "ALL MIRROR-INVARIANTS TESTS PASSED ($PASS_COUNT/$TOTAL)"

package/packages/core/hooks/tests/nudge-throttle_test.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+# nudge-throttle_test.sh — regression test for advisory throttling (Task 18)
+#
+# Opus 4.8 self-flags, so repeated identical advisories are noise. The
+# superkit_should_emit_advisory helper suppresses an identical advisory that
+# recurs within CLAUDE_NUDGE_WINDOW_MIN (default 10). This test proves:
+#   1. first identical advisory is emitted, second within the window is suppressed
+#   2. CLAUDE_NUDGE_WINDOW_MIN=0 disables throttling
+#   3. a different message is NOT suppressed by an unrelated one
+#   4. edit-streak-check.sh suppresses its repeated streak nudge under one session
+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_should_emit_advisory >/dev/null 2>&1 \
+  || { echo "FAIL: superkit_should_emit_advisory not exported by profile.sh"; exit 1; }
+
+TMPDIR="${TMPDIR:-/tmp}"
+
+# ── Test 1: first emits, second within window suppressed ──────────────
+export SUPERKIT_NUDGE_STATE="$TMPDIR/superkit-nudge-helper-test-$$"
+rm -f "$SUPERKIT_NUDGE_STATE"
+if superkit_should_emit_advisory "same nudge"; then
+  echo "PASS: first identical advisory emitted"
+else
+  echo "FAIL: first advisory should be emitted"
+  rm -f "$SUPERKIT_NUDGE_STATE"; exit 1
+fi
+if superkit_should_emit_advisory "same nudge"; then
+  echo "FAIL: second identical advisory within window should be suppressed"
+  rm -f "$SUPERKIT_NUDGE_STATE"; exit 1
+else
+  echo "PASS: second identical advisory suppressed within window"
+fi
+
+# ── Test 2: a different message is not suppressed ─────────────────────
+if superkit_should_emit_advisory "a different nudge"; then
+  echo "PASS: distinct advisory not suppressed by unrelated one"
+else
+  echo "FAIL: distinct advisory should still emit"
+  rm -f "$SUPERKIT_NUDGE_STATE"; exit 1
+fi
+rm -f "$SUPERKIT_NUDGE_STATE"
+
+# ── Test 3: CLAUDE_NUDGE_WINDOW_MIN=0 disables throttling ─────────────
+export SUPERKIT_NUDGE_STATE="$TMPDIR/superkit-nudge-helper-test2-$$"
+rm -f "$SUPERKIT_NUDGE_STATE"
+CLAUDE_NUDGE_WINDOW_MIN=0 superkit_should_emit_advisory "x" || { echo "FAIL: window=0 should always emit (1st)"; rm -f "$SUPERKIT_NUDGE_STATE"; exit 1; }
+CLAUDE_NUDGE_WINDOW_MIN=0 superkit_should_emit_advisory "x" || { echo "FAIL: window=0 should always emit (2nd)"; rm -f "$SUPERKIT_NUDGE_STATE"; exit 1; }
+echo "PASS: CLAUDE_NUDGE_WINDOW_MIN=0 disables throttling"
+rm -f "$SUPERKIT_NUDGE_STATE"
+
+# ── Test 4: edit-streak-check.sh end-to-end throttling ────────────────
+# Under a fixed SESSION_ID, drive the streak past the threshold so the
+# advisory fires, then drive it again — the second nudge must be suppressed.
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/edit-streak-check.sh"
+[ -x "$HOOK" ] || { echo "FAIL: edit-streak hook not executable at $HOOK"; exit 1; }
+
+export SESSION_ID="nudge-throttle-sess-$$"
+export SUPERKIT_NUDGE_STATE="$TMPDIR/superkit-nudge-${SESSION_ID}"
+STREAK_FILE="$TMPDIR/claude-edit-streak-${SESSION_ID}"
+rm -f "$SUPERKIT_NUDGE_STATE" "$STREAK_FILE"
+unset CLAUDE_EDIT_STREAK_FILE 2>/dev/null || true
+
+fire_edit() {
+  echo '{"tool_name":"Edit","tool_input":{"file_path":"/tmp/fake.txt"}}' | bash "$HOOK" 2>&1 >/dev/null
+}
+
+# Edits 1-4 silent, 5th fires the advisory.
+for i in 1 2 3 4; do fire_edit >/dev/null || true; done
+OUT5=$(fire_edit || true)
+if ! echo "$OUT5" | grep -q "edit streak — 5"; then
+  echo "FAIL: 5th edit should warn (first advisory)"
+  echo "  stderr: $OUT5"
+  rm -f "$SUPERKIT_NUDGE_STATE" "$STREAK_FILE"; unset SESSION_ID SUPERKIT_NUDGE_STATE; exit 1
+fi
+echo "PASS: edit-streak first advisory emitted (edit 5)"
+
+# 6th edit: streak >= 5 again, but identical advisory must be throttled.
+OUT6=$(fire_edit || true)
+if echo "$OUT6" | grep -q "edit streak"; then
+  echo "FAIL: 6th edit advisory should be suppressed within window"
+  echo "  stderr: $OUT6"
+  rm -f "$SUPERKIT_NUDGE_STATE" "$STREAK_FILE"; unset SESSION_ID SUPERKIT_NUDGE_STATE; exit 1
+fi
+echo "PASS: edit-streak repeat advisory suppressed within window"
+
+rm -f "$SUPERKIT_NUDGE_STATE" "$STREAK_FILE"
+unset SESSION_ID SUPERKIT_NUDGE_STATE
+
+echo ""
+echo "ALL NUDGE-THROTTLE TESTS PASSED (6/6)"

package/packages/core/hooks/tests/profile-helper_test.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+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"
+
+# Test 1: CLAUDE_DISABLED_HOOKS matches
+CLAUDE_DISABLED_HOOKS="loop-guard,security-patterns" should_skip_hook "loop-guard" && echo "PASS: loop-guard disabled" || { echo "FAIL"; exit 1; }
+CLAUDE_DISABLED_HOOKS="loop-guard,security-patterns" should_skip_hook "audit-trail" && { echo "FAIL: should not skip"; exit 1; } || echo "PASS: audit-trail not disabled"
+
+# Test 2: CLAUDE_HOOK_PROFILE=fast skips non-critical
+CLAUDE_HOOK_PROFILE=fast should_skip_hook "loop-guard" && echo "PASS: fast skips loop-guard" || { echo "FAIL"; exit 1; }
+CLAUDE_HOOK_PROFILE=fast should_skip_hook "block-dangerous-git" && { echo "FAIL: fast should not skip critical"; exit 1; } || echo "PASS: fast keeps block-dangerous-git"
+
+# Test 3: Default profile keeps all hooks
+unset CLAUDE_HOOK_PROFILE CLAUDE_DISABLED_HOOKS
+should_skip_hook "loop-guard" && { echo "FAIL: default should not skip"; exit 1; } || echo "PASS: default keeps loop-guard"
+
+echo "ALL PROFILE-HELPER TESTS PASSED"

package/packages/core/hooks/tests/run-all.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+# run-all.sh — invoke every regression-test suite and report a summary.
+# Usage: bash packages/core/hooks/tests/run-all.sh
+
+DIR=$(cd "$(dirname "$0")" && pwd)
+SUITES=(
+  "doc-check-on-commit_test.sh"
+  "dev-required-on-commit_test.sh"
+  "dev-required-wip-on-main_test.sh"
+  "json-path_test.sh"
+  "profile-helper_test.sh"
+  "session-key-helper_test.sh"
+  "edit-streak-check_test.sh"
+  "audit-trail-chain_test.sh"
+  "warn-visibility_test.sh"
+  "nudge-throttle_test.sh"
+  "counts-verify_test.sh"
+  "block-dangerous-git_test.sh"
+  "mirror-invariants_test.sh"
+  "internal-manifest_test.sh"
+  "superkit-update_test.sh"
+)
+
+TOTAL_PASS=0
+TOTAL_FAIL=0
+FAILED_SUITES=""
+
+for suite in "${SUITES[@]}"; do
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "▶ $suite"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  if bash "$DIR/$suite"; then
+    TOTAL_PASS=$((TOTAL_PASS + 1))
+  else
+    TOTAL_FAIL=$((TOTAL_FAIL + 1))
+    FAILED_SUITES="${FAILED_SUITES}\n  - $suite"
+  fi
+  echo ""
+done
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Summary: $TOTAL_PASS suites passed, $TOTAL_FAIL failed"
+if [ "$TOTAL_FAIL" -gt 0 ]; then
+  echo -e "Failed suites:${FAILED_SUITES}"
+  exit 1
+fi
+exit 0

package/packages/core/hooks/tests/session-key-helper_test.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -u
+LIB="$(cd "$(dirname "$0")/.." && pwd)/lib/profile.sh"
+. "$LIB"
+
+fail=0
+# SESSION_ID wins
+SESSION_ID="sid123" CLAUDE_HOOK_PID="" ; k=$(superkit_session_key)
+[ "$k" = "sid123" ] || { echo "FAIL: SESSION_ID precedence got '$k'"; fail=1; }
+# falls back to CLAUDE_HOOK_PID
+unset SESSION_ID; CLAUDE_HOOK_PID="pid456"; k=$(superkit_session_key)
+[ "$k" = "pid456" ] || { echo "FAIL: CLAUDE_HOOK_PID fallback got '$k'"; fail=1; }
+# falls back to PPID (non-empty)
+unset SESSION_ID CLAUDE_HOOK_PID; k=$(superkit_session_key)
+[ -n "$k" ] || { echo "FAIL: PPID fallback empty"; fail=1; }
+
+[ "$fail" -eq 0 ] && echo "PASS: session-key helper" && exit 0 || exit 1