@esoteric-logic/praxis-harness 2.9.0 → 2.10.0

package/base/CLAUDE.md

@@ -56,6 +56,13 @@ Vault path and backend are machine-specific. Read from `~/.claude/praxis.config.
 If config file is missing: tell the user to run `praxis/install.sh`.
 All `{vault_path}` references in rules and skills resolve from this config.
 
+## Model & Context Policy
+- Default model: `claude-opus-4-6` (set `ANTHROPIC_MODEL` in shell profile)
+- Sub-agents spawned by Praxis skills: use `haiku` for polling, search, and lint tasks
+- Compact trigger: when context approaches ceiling, finish the current milestone first
+- Never compact mid-plan — complete the milestone, write phase summary to vault, then compact
+- After compaction: re-bootstrap from § After Compaction below, re-run quality checks fresh
+
 ## Durable Memory
 Context is volatile. Files are permanent. Act accordingly.
 
@@ -164,6 +171,7 @@ Kit manifests live in `~/.claude/kits/<name>/KIT.md`.
 | `~/.claude/rules/powershell.md` | `**/*.ps1`, `**/*.psm1` |
 | `~/.claude/rules/dependency-freshness.md` | `package.json`, `go.mod`, `requirements.txt`, `Cargo.toml`, `pyproject.toml` |
 | `~/.claude/rules/live-docs-required.md` | Dependency manifests, files importing external packages |
+| `~/.claude/rules/desktop-protocol.md` | Claude Desktop ↔ Claude Code handoff sessions |
 
 ### Auto-invocable skills (replace former universal rules)
 | Skill | Triggers when |

package/base/configs/registry.json

@@ -101,7 +101,8 @@
       {"path": "base/hooks/file-guard.sh", "event": "PreToolUse", "matcher": "Write|Edit|MultiEdit"},
       {"path": "base/hooks/identity-check.sh", "event": "PreToolUse", "matcher": "Bash"},
       {"path": "base/hooks/credential-guard.sh", "event": "PreToolUse", "matcher": "Bash"},
-      {"path": "base/hooks/session-data-collect.sh", "event": "Stop", "matcher": ""}
+      {"path": "base/hooks/session-data-collect.sh", "event": "Stop", "matcher": ""},
+      {"path": "base/hooks/on-stop-failure.sh", "event": "StopFailure", "matcher": ""}
     ],
     "optional": [
       {"path": "base/hooks/recursion-guard.sh", "event": "PreToolUse", "matcher": "", "feature": "recursion-detection"},

package/base/hooks/auto-format.sh

@@ -2,6 +2,7 @@
 # PostToolUse hook — auto-formats files after edit.
 # Always exits 0 (advisory, never blocks).
 set -uo pipefail
+trap 'exit 0' ERR
 
 INPUT=$(cat)
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null)

package/base/hooks/dep-audit.sh

@@ -2,7 +2,8 @@
 # dep-audit.sh — PostToolUse:Write|Edit|MultiEdit hook
 # Runs dependency vulnerability checks when manifest files are modified.
 # Always exits 0 (advisory only — PostToolUse cannot hard-block).
-set -euo pipefail
+set -uo pipefail
+trap 'exit 0' ERR
 
 INPUT=$(cat)
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null)
@@ -20,28 +21,40 @@ case "$BASENAME" in
   package.json)
     ECOSYSTEM="npm"
     if command -v npm &>/dev/null && [[ -f "$DIR/package-lock.json" || -f "$DIR/node_modules/.package-lock.json" ]]; then
-      AUDIT_RESULT=$(cd "$DIR" && npm audit --audit-level=high --json 2>/dev/null || true)
+      # npm audit exits non-zero when vulnerabilities exist — capture output regardless
+      AUDIT_RESULT=$(cd "$DIR" && npm audit --audit-level=high --json 2>/dev/null) || {
+        if [[ -n "$AUDIT_RESULT" ]]; then
+          : # non-zero with output = vulnerabilities found (expected)
+        else
+          echo "DEP-AUDIT (npm): audit command failed" >&2
+        fi
+      }
     fi
     ;;
   go.mod)
     ECOSYSTEM="go"
     if command -v govulncheck &>/dev/null; then
-      AUDIT_RESULT=$(cd "$DIR" && govulncheck -json ./... 2>/dev/null || true)
+      AUDIT_RESULT=$(cd "$DIR" && govulncheck -json ./... 2>/dev/null) || {
+        [[ -z "$AUDIT_RESULT" ]] && echo "DEP-AUDIT (go): govulncheck failed" >&2
+      }
     elif command -v go &>/dev/null; then
-      # Fallback: at least check for known issues via go list
-      AUDIT_RESULT=$(cd "$DIR" && go list -m -json all 2>/dev/null | head -c 5000 || true)
+      AUDIT_RESULT=$(cd "$DIR" && go list -m -json all 2>/dev/null | head -c 5000) || AUDIT_RESULT=""
     fi
     ;;
   requirements.txt|pyproject.toml)
     ECOSYSTEM="python"
     if command -v pip-audit &>/dev/null; then
-      AUDIT_RESULT=$(cd "$DIR" && pip-audit --format=json 2>/dev/null || true)
+      AUDIT_RESULT=$(cd "$DIR" && pip-audit --format=json 2>/dev/null) || {
+        [[ -z "$AUDIT_RESULT" ]] && echo "DEP-AUDIT (python): pip-audit failed" >&2
+      }
     fi
     ;;
   Cargo.toml)
     ECOSYSTEM="rust"
     if command -v cargo-audit &>/dev/null; then
-      AUDIT_RESULT=$(cd "$DIR" && cargo audit --json 2>/dev/null || true)
+      AUDIT_RESULT=$(cd "$DIR" && cargo audit --json 2>/dev/null) || {
+        [[ -z "$AUDIT_RESULT" ]] && echo "DEP-AUDIT (rust): cargo-audit failed" >&2
+      }
     fi
     ;;
   *)

package/base/hooks/on-stop-failure.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# on-stop-failure.sh — StopFailure hook (Auto mode failure classifier)
+# Reads Claude's stop context, classifies the failure, and either:
+#   - Auto-repairs (transient: test fail, lint fail, tool error) → exit 0 (continue)
+#   - Escalates to human (boundary/spec/security violation) → exit 1 (halt)
+# Tracks repair attempts per failure fingerprint to prevent infinite loops.
+# Reuses PPID-scoped state pattern from recursion-guard.sh.
+set -euo pipefail
+
+if ! command -v jq &>/dev/null; then
+  echo "on-stop-failure: jq required but not found. Cannot classify failure." >&2
+  exit 1
+fi
+
+# ── Parse input (single jq call) ──
+INPUT=$(cat)
+PARSED=$(echo "$INPUT" | jq -r '[
+  (.exit_code // 1 | tostring),
+  (.stop_reason // ""),
+  (.last_tool_use.name // ""),
+  (.last_tool_use.error // "")
+] | join("\t")' 2>/dev/null || echo "1\t\t\t")
+
+IFS=$'\t' read -r EXIT_CODE STOP_REASON LAST_TOOL TOOL_ERROR <<< "$PARSED"
+
+MAX_REPAIR_ATTEMPTS=3
+MAX_FINGERPRINT_LEN=200
+
+# ── Repair attempt tracker (PPID-scoped, same pattern as recursion-guard.sh) ──
+REPAIR_STATE="/tmp/praxis-repair-${PPID}.json"
+if [[ ! -f "$REPAIR_STATE" ]]; then
+  echo '{"repair_attempts":0,"last_fingerprint":""}' > "$REPAIR_STATE"
+fi
+
+# Compare raw fingerprint strings — no hash needed for equality checks
+FINGERPRINT="${EXIT_CODE}:${LAST_TOOL}:${STOP_REASON:0:$MAX_FINGERPRINT_LEN}"
+
+# Single jq call to read both fields
+STATE_READ=$(jq -r '[(.last_fingerprint // ""), (.repair_attempts // 0 | tostring)] | join("\t")' "$REPAIR_STATE" 2>/dev/null || echo $'\t0')
+IFS=$'\t' read -r LAST_FINGERPRINT CURRENT_ATTEMPTS <<< "$STATE_READ"
+
+# Same fingerprint = looping on the same error
+if [[ "$FINGERPRINT" == "$LAST_FINGERPRINT" ]]; then
+  CURRENT_ATTEMPTS=$((CURRENT_ATTEMPTS + 1))
+else
+  CURRENT_ATTEMPTS=1
+fi
+
+# Atomic state file update (tmp + mv)
+TMP_STATE="${REPAIR_STATE}.tmp"
+jq -n --argjson attempts "$CURRENT_ATTEMPTS" --arg fp "$FINGERPRINT" \
+  '{"repair_attempts": $attempts, "last_fingerprint": $fp}' \
+  > "$TMP_STATE" && mv "$TMP_STATE" "$REPAIR_STATE"
+
+# ── Hard escalation: too many repair attempts on same failure ──
+if [[ $CURRENT_ATTEMPTS -gt $MAX_REPAIR_ATTEMPTS ]]; then
+  echo "AUTO-REPAIR EXHAUSTED: $CURRENT_ATTEMPTS attempts on same failure." >&2
+  echo "Failure: exit=$EXIT_CODE tool=$LAST_TOOL" >&2
+  echo "Halting — human review required." >&2
+
+  CONFIG="$HOME/.claude/praxis.config.json"
+  if [[ -f "$CONFIG" ]]; then
+    VAULT_PATH=$(jq -r '.vault_path // ""' "$CONFIG" 2>/dev/null)
+    if [[ -n "$VAULT_PATH" && -d "$VAULT_PATH" ]]; then
+      TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+      ESCALATION_FILE="$VAULT_PATH/notes/escalations.md"
+
+      if [[ ! -f "$ESCALATION_FILE" ]]; then
+        printf -- "---\ntags: [escalation, auto-repair]\ndate: %s\nsource: agent\n---\n\n# Auto-Repair Escalations\n" \
+          "$(date +%Y-%m-%d)" > "$ESCALATION_FILE"
+      fi
+
+      printf "\n## %s\n- **Failure**: exit=%s tool=%s\n- **Attempts**: %s\n- **Reason**: %s\n- **Status**: HALTED — needs human review\n" \
+        "$TIMESTAMP" "$EXIT_CODE" "$LAST_TOOL" "$CURRENT_ATTEMPTS" "${STOP_REASON:0:$MAX_FINGERPRINT_LEN}" \
+        >> "$ESCALATION_FILE"
+    fi
+  fi
+
+  exit 1
+fi
+
+# ── Hard escalation patterns (single regex, never auto-repair these) ──
+HARD_REGEX="BLOCKED:|secret detected|Protected path|out of scope|permission denied|identity mismatch"
+COMBINED_CONTEXT="$STOP_REASON $TOOL_ERROR"
+
+if echo "$COMBINED_CONTEXT" | grep -qiE "$HARD_REGEX"; then
+  MATCHED=$(echo "$COMBINED_CONTEXT" | grep -oiE "$HARD_REGEX" | head -1)
+  echo "ESCALATING: Hard violation — '$MATCHED' matched." >&2
+  echo "Auto-repair suppressed. Human review required." >&2
+  exit 1
+fi
+
+# Exit code 2 = guard hard-block (recursion-guard.sh, secret-scan.sh, file-guard.sh convention)
+if [[ "$EXIT_CODE" == "2" ]]; then
+  echo "ESCALATING: Exit code 2 = guard hard-block. No auto-repair." >&2
+  exit 1
+fi
+
+# ── Transient failure → emit repair prompt (Auto mode continues) ──
+# Claude Code reads stdout from StopFailure hooks as an injected prompt.
+
+cat <<REPAIR
+Auto-repair attempt $CURRENT_ATTEMPTS of $MAX_REPAIR_ATTEMPTS.
+
+Failure context:
+- Exit code: $EXIT_CODE
+- Last tool: $LAST_TOOL
+- Stop reason: ${STOP_REASON:0:500}
+- Tool error: ${TOOL_ERROR:0:$MAX_FINGERPRINT_LEN}
+
+Instructions:
+1. Read the error above carefully. Identify the root cause from actual output.
+2. Apply the minimum fix required. Do not expand scope.
+3. Re-run validation (tests + lint) after fixing.
+4. If this is attempt $CURRENT_ATTEMPTS of $MAX_REPAIR_ATTEMPTS and the fix is not obvious:
+   report What / So What / Now What and halt.
+
+Do NOT re-attempt the same approach that just failed.
+REPAIR
+
+exit 0

package/base/hooks/session-data-collect.sh

@@ -2,6 +2,7 @@
 # Stop hook — collects structured session data and stages it for the Stop prompt.
 # Always exits 0 (advisory, never blocks session end).
 set -uo pipefail
+trap 'exit 0' ERR
 
 CONFIG_FILE="$HOME/.claude/praxis.config.json"
 

package/base/hooks/settings-hooks.json

@@ -68,6 +68,17 @@
         ]
       }
     ],
+    "StopFailure": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ~/.claude/hooks/on-stop-failure.sh"
+          }
+        ]
+      }
+    ],
     "PreCompact": [
       {
         "matcher": "",

package/base/hooks/vault-checkpoint.sh

@@ -2,6 +2,7 @@
 # PreCompact hook — writes minimal checkpoint to vault before context compaction.
 # Always exits 0 (advisory, never blocks compaction).
 set -uo pipefail
+trap 'exit 0' ERR
 
 CONFIG_FILE="$HOME/.claude/praxis.config.json"
 

package/base/lib/kit-check.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# ════════════════════════════════════════════════════════════════
+#  Praxis — Shared Kit Install Check
+#  Source this file in kit install.sh scripts for consistent
+#  tool-checking output and counters.
+#
+#  Usage:
+#    source "$(dirname "$0")/../../base/lib/kit-check.sh"
+#    check "jq"      "brew install jq"
+#    check "curl"    "pre-installed on macOS/Linux"
+#    kit_check_summary
+# ════════════════════════════════════════════════════════════════
+
+KIT_CHECK_PASS=0
+KIT_CHECK_TOTAL=0
+
+check() {
+  local cmd="$1"
+  local install_hint="$2"
+  local optional="${3:-}"
+
+  KIT_CHECK_TOTAL=$((KIT_CHECK_TOTAL + 1))
+  if command -v "$cmd" &>/dev/null; then
+    echo "  ✓ $cmd found ($(command -v "$cmd"))"
+    KIT_CHECK_PASS=$((KIT_CHECK_PASS + 1))
+  else
+    if [[ "$optional" == "optional" ]]; then
+      echo "  ⚠ $cmd not found (optional)"
+    else
+      echo "  ✗ $cmd not found"
+    fi
+    echo "    Install: $install_hint"
+  fi
+}
+
+kit_check_summary() {
+  echo ""
+  echo "  $KIT_CHECK_PASS/$KIT_CHECK_TOTAL tools found"
+  if [[ $KIT_CHECK_PASS -lt $KIT_CHECK_TOTAL ]]; then
+    echo "  ⚠ Some tools missing. Install them before using kit commands."
+  fi
+}

package/base/lib/output.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# ═══════��════════════════════════════════════════════════════════
+#  Praxis — Shared Output Helpers
+#  Source this file instead of defining colors/helpers inline.
+#
+#  Usage:
+#    source "$(dirname "$0")/../base/lib/output.sh"
+#    # or with absolute path:
+#    source "$HOME/.claude/lib/output.sh"
+#
+#  Safe to source multiple times — guards against redefinition.
+# ════��═══════════════════════════════════════════════════════════
+
+# ─── Colors (skip if already set) ───
+RED="${RED:-\033[0;31m}"
+GREEN="${GREEN:-\033[0;32m}"
+YELLOW="${YELLOW:-\033[0;33m}"
+CYAN="${CYAN:-\033[0;36m}"
+BOLD="${BOLD:-\033[1m}"
+DIM="${DIM:-\033[2m}"
+NC="${NC:-\033[0m}"
+
+# ─── Output helpers (skip if already defined) ───
+if ! declare -f ok &>/dev/null; then
+  ok()   { echo -e "  ${GREEN}✓${NC} $1"; }
+fi
+if ! declare -f warn &>/dev/null; then
+  warn() { echo -e "  ${YELLOW}⚠${NC} $1"; }
+fi
+if ! declare -f fail &>/dev/null; then
+  fail() { echo -e "  ${RED}✗${NC} $1"; }
+fi
+if ! declare -f step &>/dev/null; then
+  step() { echo -e "\n${CYAN}${BOLD}$1${NC}"; }
+fi
+if ! declare -f dim &>/dev/null; then
+  dim()  { echo -e "  ${DIM}$1${NC}"; }
+fi

package/base/rules/desktop-protocol.md

@@ -0,0 +1,64 @@
+# Desktop Protocol — Rules
+# Scope: Sessions involving Claude Desktop ↔ Claude Code handoff
+# Defines role boundaries and structured handoff format
+
+## Role Boundaries
+
+| Surface | Role | Responsible for |
+|---------|------|-----------------|
+| Claude Desktop | Architect / Reviewer | ADR review, security audit, diff validation, prompt engineering |
+| Claude Code | Executor | File writes, git ops, test runs, tool use, vault updates |
+
+Desktop generates structured intent. Code executes it.
+Never use Desktop for file writes. Never use Code for open-ended architecture debate.
+
+## Handoff Format — Desktop → Code
+
+When Desktop completes a review or decision, it emits a structured handoff block.
+Code reads this block as its initial task context.
+
+```
+HANDOFF:
+  TASK: [one-line description]
+  SPEC: [link to vault plan or spec file]
+  CONSTRAINTS: [hard limits — what must NOT change]
+  ACCEPTANCE: [how to know it's done]
+  CONTEXT: [optional — key decisions or rationale from review]
+```
+
+Code MUST NOT start implementation without at least TASK and ACCEPTANCE filled.
+If SPEC is missing, Code asks before proceeding.
+
+## Handoff Format — Code → Desktop
+
+When Code completes implementation and wants architectural review:
+
+```
+REVIEW-REQUEST:
+  TASK: [what was implemented]
+  DIFF: [git diff summary or branch name]
+  SPEC: [link to plan that drove this work]
+  QUESTIONS: [specific things to review — not "does this look good"]
+```
+
+## Vault Write-Back
+
+After Desktop review, append the decision to `{vault_path}/notes/review-decisions.md`:
+
+```
+## YYYY-MM-DD | [task-slug]
+- **Decision**: APPROVED | CHANGES_REQUESTED | DEFERRED
+- **Rationale**: [1-2 sentences]
+- **Action items**: [if CHANGES_REQUESTED — specific items for Code to address]
+```
+
+## Conventions — WARN on violation
+
+- Desktop review decisions that affect architecture go to `{vault_path}/specs/` as ADRs
+- Desktop review decisions that are tactical (naming, style, small refactors) stay in `review-decisions.md`
+- Code must not self-approve architectural changes — route through Desktop review
+- If Desktop is unavailable, Code may proceed but must flag the decision in `status.md` for later review
+
+## Removal Condition
+Remove when a unified Claude surface handles both architecture review and code execution
+natively, eliminating the need for explicit handoff protocols.

package/bin/praxis-preflight.sh

@@ -4,13 +4,10 @@
 # Also implements: set-key subcommand for secret management.
 set -euo pipefail
 
-# ─── Colors ───
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[0;33m'
-CYAN='\033[0;36m'
-BOLD='\033[1m'
-NC='\033[0m'
+# ─── Colors (shared) ───
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_DIR="$(dirname "$SCRIPT_DIR")"
+source "$REPO_DIR/base/lib/output.sh"
 
 PASS=0
 WARN=0
@@ -19,10 +16,10 @@ PRAXIS_DIR="$HOME/.praxis"
 SECRETS_FILE="$PRAXIS_DIR/secrets"
 REPORT_FILE="$PRAXIS_DIR/preflight-report.json"
 
+# Override shared helpers with counter-incrementing versions
 ok()   { echo -e "  ${GREEN}✓${NC} $1"; PASS=$((PASS + 1)); }
 warn() { echo -e "  ${YELLOW}⚠${NC} $1"; WARN=$((WARN + 1)); }
 fail() { echo -e "  ${RED}✗${NC} $1"; BLOCK=$((BLOCK + 1)); }
-step() { echo -e "\n${CYAN}${BOLD}$1${NC}"; }
 
 # ═══════════════════════════════════════════
 # Subcommand: set-key

package/kits/api/install.sh

@@ -4,19 +4,7 @@ set -euo pipefail
 echo "=== Praxis: Installing api kit ==="
 echo ""
 
-PASS=0
-TOTAL=0
-
-check() {
-  TOTAL=$((TOTAL + 1))
-  if command -v "$1" &>/dev/null; then
-    echo "  ✓ $1 found ($(command -v "$1"))"
-    PASS=$((PASS + 1))
-  else
-    echo "  ✗ $1 not found"
-    echo "    Install: $2"
-  fi
-}
+source "$(dirname "$0")/../../base/lib/kit-check.sh"
 
 echo "Checking optional CLI tools..."
 echo ""
@@ -24,10 +12,9 @@ echo ""
 check "jq"      "brew install jq  OR  apt-get install jq"
 check "curl"    "pre-installed on macOS/Linux"
 
-echo ""
-echo "  $PASS/$TOTAL tools found"
-echo ""
+kit_check_summary
 
+echo ""
 echo "Note: This kit uses Claude's built-in analysis capabilities."
 echo "No external API linting tools required."
 echo ""

package/kits/code-quality/hooks/pre-push.sh

@@ -8,6 +8,25 @@ BASELINE="$REPO_ROOT/.quality-baseline.json"
 TMP="/tmp/praxis-quality-$$"
 mkdir -p "$TMP"
 
+# Safe jq wrapper: validates JSON before querying; returns fallback on parse failure
+# and logs a warning so gate operators know a scan produced bad output.
+safe_jq() {
+  local query="$1"
+  local file="$2"
+  local fallback="${3:-0}"
+  if [[ ! -s "$file" ]]; then
+    echo "$fallback"
+    return
+  fi
+  if ! jq empty "$file" 2>/dev/null; then
+    echo "  ⚠ WARNING: $file is not valid JSON — treating as scan failure" >&2
+    GATE_WARNINGS+=("PARSE: $(basename "$file") produced invalid output")
+    echo "$fallback"
+    return
+  fi
+  jq -r "$query" "$file" 2>/dev/null || echo "$fallback"
+}
+
 echo ""
 echo "Praxis Code Quality Gate"
 echo "------------------------"
@@ -32,8 +51,8 @@ if [ -s "$TMP/code-files.txt" ]; then
   FILES=$(cat "$TMP/code-files.txt" | tr '\n' ' ')
   opengrep scan --config auto --json $FILES > "$TMP/sast.json" 2>/dev/null || true
 
-  CRITICAL=$(jq '[.results[] | select(.extra.severity == "ERROR")] | length' "$TMP/sast.json" 2>/dev/null || echo 0)
-  HIGH=$(jq '[.results[] | select(.extra.severity == "WARNING")] | length' "$TMP/sast.json" 2>/dev/null || echo 0)
+  CRITICAL=$(safe_jq '[.results[] | select(.extra.severity == "ERROR")] | length' "$TMP/sast.json")
+  HIGH=$(safe_jq '[.results[] | select(.extra.severity == "WARNING")] | length' "$TMP/sast.json")
 
   [ "$CRITICAL" -gt 0 ] && GATE_FAILURES+=("SAST: $CRITICAL critical findings")
   [ "$HIGH" -gt 0 ]     && GATE_WARNINGS+=("SAST: $HIGH high findings")
@@ -44,7 +63,11 @@ SAST_PID=$!
 # -- SECRETS (TruffleHog) --
 echo "  Secrets scan (TruffleHog)..."
 trufflehog git file://. --since-commit HEAD~1 --only-verified --json > "$TMP/secrets.json" 2>/dev/null || true
-SECRETS=$(jq -s 'length' "$TMP/secrets.json" 2>/dev/null || echo 0)
+if [[ -s "$TMP/secrets.json" ]]; then
+  SECRETS=$(jq -s 'length' "$TMP/secrets.json" 2>/dev/null || echo 0)
+else
+  SECRETS=0
+fi
 [ "$SECRETS" -gt 0 ] && GATE_FAILURES+=("SECRETS: $SECRETS verified secrets found")
 echo "     Verified secrets: $SECRETS" &
 SECRETS_PID=$!
@@ -52,8 +75,8 @@ SECRETS_PID=$!
 # -- SCA (OSV-Scanner) --
 echo "  Dependency scan (OSV-Scanner)..."
 osv-scanner scan --format json "$REPO_ROOT" > "$TMP/sca.json" 2>/dev/null || true
-SCA_CRITICAL=$(jq '[.vulns[]? | select(.database_specific.severity? == "CRITICAL")] | length' "$TMP/sca.json" 2>/dev/null || echo 0)
-SCA_HIGH=$(jq '[.vulns[]? | select(.database_specific.severity? == "HIGH")] | length' "$TMP/sca.json" 2>/dev/null || echo 0)
+SCA_CRITICAL=$(safe_jq '[.vulns[]? | select(.database_specific.severity? == "CRITICAL")] | length' "$TMP/sca.json")
+SCA_HIGH=$(safe_jq '[.vulns[]? | select(.database_specific.severity? == "HIGH")] | length' "$TMP/sca.json")
 [ "$SCA_CRITICAL" -gt 0 ] && GATE_FAILURES+=("SCA: $SCA_CRITICAL critical CVEs in dependencies")
 [ "$SCA_HIGH" -gt 0 ]     && GATE_WARNINGS+=("SCA: $SCA_HIGH high CVEs in dependencies")
 echo "     Critical CVEs: $SCA_CRITICAL  High CVEs: $SCA_HIGH" &
@@ -63,7 +86,7 @@ SCA_PID=$!
 if [ -s "$TMP/iac-files.txt" ]; then
   echo "  IaC scan (Checkov)..."
   checkov -d "$REPO_ROOT" --output json --quiet --compact 2>/dev/null > "$TMP/iac.json" || true
-  IaC_FAIL=$(jq '.results.failed_checks | length' "$TMP/iac.json" 2>/dev/null || echo 0)
+  IaC_FAIL=$(safe_jq '.results.failed_checks | length' "$TMP/iac.json")
   [ "$IaC_FAIL" -gt 0 ] && GATE_WARNINGS+=("IaC: $IaC_FAIL policy violations")
   echo "     Policy violations: $IaC_FAIL"
 fi &
@@ -73,9 +96,9 @@ IaC_PID=$!
 wait $SAST_PID $SECRETS_PID $SCA_PID $IaC_PID 2>/dev/null || true
 
 # -- COVERAGE --
-COVERAGE_THRESHOLD=$(jq -r '.coverage.line_min' "$CONFIG" 2>/dev/null || echo 80)
+COVERAGE_THRESHOLD=$(safe_jq '.coverage.line_min' "$CONFIG" 80)
 if [ -f "$REPO_ROOT/coverage/coverage-summary.json" ]; then
-  COVERAGE=$(jq '.total.lines.pct' "$REPO_ROOT/coverage/coverage-summary.json" 2>/dev/null || echo 100)
+  COVERAGE=$(safe_jq '.total.lines.pct' "$REPO_ROOT/coverage/coverage-summary.json" 100)
   BELOW=$(echo "$COVERAGE < $COVERAGE_THRESHOLD" | bc -l 2>/dev/null || echo 0)
   [ "$BELOW" = "1" ] && GATE_WARNINGS+=("COVERAGE: ${COVERAGE}% below threshold ${COVERAGE_THRESHOLD}%")
   echo "  Coverage: ${COVERAGE}% (threshold: ${COVERAGE_THRESHOLD}%)"

package/kits/data/install.sh

@@ -4,32 +4,19 @@ set -euo pipefail
 echo "=== Praxis: Installing data kit ==="
 echo ""
 
-PASS=0
-TOTAL=0
-
-check() {
-  TOTAL=$((TOTAL + 1))
-  if command -v "$1" &>/dev/null; then
-    echo "  ✓ $1 found ($(command -v "$1"))"
-    PASS=$((PASS + 1))
-  else
-    echo "  ✗ $1 not found (optional)"
-    echo "    Install: $2"
-  fi
-}
+source "$(dirname "$0")/../../base/lib/kit-check.sh"
 
 echo "Checking optional CLI tools..."
 echo ""
 
-check "psql"    "brew install postgresql  OR  apt-get install postgresql-client"
-check "mysql"   "brew install mysql-client  OR  apt-get install mysql-client"
-check "mongosh" "brew install mongosh  OR  https://www.mongodb.com/try/download/shell"
+check "psql"    "brew install postgresql  OR  apt-get install postgresql-client" "optional"
+check "mysql"   "brew install mysql-client  OR  apt-get install mysql-client" "optional"
+check "mongosh" "brew install mongosh  OR  https://www.mongodb.com/try/download/shell" "optional"
 check "jq"      "brew install jq  OR  apt-get install jq"
 
-echo ""
-echo "  $PASS/$TOTAL tools found"
-echo ""
+kit_check_summary
 
+echo ""
 echo "Note: This kit uses Claude's built-in analysis for schema and query review."
 echo "Database CLI tools are needed only for live query testing."
 echo ""

package/kits/infrastructure/install.sh

@@ -4,19 +4,7 @@ set -euo pipefail
 echo "=== Praxis: Installing infrastructure kit ==="
 echo ""
 
-PASS=0
-TOTAL=0
-
-check() {
-  TOTAL=$((TOTAL + 1))
-  if command -v "$1" &>/dev/null; then
-    echo "  ✓ $1 found ($(command -v "$1"))"
-    PASS=$((PASS + 1))
-  else
-    echo "  ✗ $1 not found"
-    echo "    Install: $2"
-  fi
-}
+source "$(dirname "$0")/../../base/lib/kit-check.sh"
 
 echo "Checking required CLI tools..."
 echo ""
@@ -26,13 +14,7 @@ check "terraform"  "https://developer.hashicorp.com/terraform/install"
 check "tflint"     "brew install tflint  OR  https://github.com/terraform-linters/tflint"
 check "jq"         "brew install jq  OR  apt-get install jq"
 
-echo ""
-echo "  $PASS/$TOTAL tools found"
-echo ""
-
-if [[ $PASS -lt $TOTAL ]]; then
-  echo "  ⚠ Some tools missing. Install them before using infrastructure commands."
-fi
+kit_check_summary
 
 echo ""
 echo "Note: Skills chain phases are status: planned."

package/kits/security/install.sh

@@ -4,31 +4,18 @@ set -euo pipefail
 echo "=== Praxis: Installing security kit ==="
 echo ""
 
-PASS=0
-TOTAL=0
-
-check() {
-  TOTAL=$((TOTAL + 1))
-  if command -v "$1" &>/dev/null; then
-    echo "  ✓ $1 found ($(command -v "$1"))"
-    PASS=$((PASS + 1))
-  else
-    echo "  ✗ $1 not found (optional)"
-    echo "    Install: $2"
-  fi
-}
+source "$(dirname "$0")/../../base/lib/kit-check.sh"
 
 echo "Checking optional CLI tools..."
 echo ""
 
-check "trivy"     "brew install trivy  OR  https://aquasecurity.github.io/trivy"
-check "deepsource" "curl -fsSL https://cli.deepsource.com/install | sh"
+check "trivy"     "brew install trivy  OR  https://aquasecurity.github.io/trivy" "optional"
+check "deepsource" "curl -fsSL https://cli.deepsource.com/install | sh" "optional"
 check "rg"        "brew install ripgrep  OR  apt-get install ripgrep"
 
-echo ""
-echo "  $PASS/$TOTAL tools found"
-echo ""
+kit_check_summary
 
+echo ""
 echo "Note: This kit uses Claude's built-in analysis for most checks."
 echo "External tools enhance scanning but are not required."
 echo ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esoteric-logic/praxis-harness",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "description": "Layered Claude Code harness — workflow discipline, AI-Kits, persistent vault integration",
   "bin": {
     "praxis-harness": "./bin/praxis.js"

package/scripts/onboard-mcp.sh

@@ -20,24 +20,9 @@ set -euo pipefail
 CLAUDE_DIR="${CLAUDE_DIR:-$HOME/.claude}"
 CONFIG_FILE="${CONFIG_FILE:-$CLAUDE_DIR/praxis.config.json}"
 
-# ─── Colors (safe defaults if not already set) ───
-RED="${RED:-\033[0;31m}"
-GREEN="${GREEN:-\033[0;32m}"
-YELLOW="${YELLOW:-\033[0;33m}"
-CYAN="${CYAN:-\033[0;36m}"
-BOLD="${BOLD:-\033[1m}"
-NC="${NC:-\033[0m}"
-
-# ─── Output helpers (no-op if already defined by install.sh) ───
-if ! declare -f ok &>/dev/null; then
-  ok()   { echo -e "  $GREEN✓$NC $1"; }
-fi
-if ! declare -f warn &>/dev/null; then
-  warn() { echo -e "  $YELLOW⚠$NC $1"; }
-fi
-if ! declare -f fail &>/dev/null; then
-  fail() { echo -e "  $RED✗$NC $1"; }
-fi
+# ─── Colors & output helpers (safe to source multiple times) ───
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/../base/lib/output.sh"
 
 # ═══════════════════════════════════════════
 # Utilities