@esoteric-logic/praxis-harness 2.11.0 → 2.13.0

package/base/skills/px-scaffold-new/SKILL.md

@@ -46,10 +46,10 @@ Read identity table from `~/.claude/rules/git-workflow.md`.
 
 ## Phase 1 — Gather Info
 
-Before asking, run vault duplicate check:
-```bash
-obsidian search query="{slug}" path="01_Projects" limit=3
-```
+Before asking, run vault duplicate check using configured backend:
+- If `obsidian`: `obsidian search query="{slug}" path="01_Projects" limit=3`
+- If `ripgrep`: `rg --files-with-matches "{slug}" {vault_path}/`
+- If vault search fails: warn and proceed without blocking.
 
 Ask in one message:
 - **Project name** — display name
@@ -71,7 +71,7 @@ today_date   = current date YYYY-MM-DD
 
 ## Phase 2 — Scaffold repo CLAUDE.md
 
-1. Read `references/repo-CLAUDE-md-template.md`
+1. Read `templates/project-index.md` (the repo CLAUDE.md template)
 2. Apply full substitution map. All placeholders must resolve.
 3. Scan output for remaining `{placeholder}` patterns. Resolve before writing.
 4. Write to `{repo_root}/CLAUDE.md`
@@ -85,19 +85,19 @@ Create directories:
 mkdir -p {vault_path}/plans {vault_path}/notes {vault_path}/specs {vault_path}/research
 ```
 
-Create files from templates in `references/`:
-- `_index.md` from `vault-index-template.md`
-- `status.md` from `vault-status-template.md` (`current_plan:` empty)
-- `tasks.md` from `vault-tasks-template.md`
-- `notes/learnings.md` from `vault-learnings-template.md`
-- `notes/decision-log.md` from `decision-log` template (append-only decision log)
-- `.gitignore` from `gitignore-template.txt` (new repos only)
+Create files from templates in `templates/`:
+- `_index.md` from `templates/_index.md`
+- `status.md` from `templates/status.md` (`current_plan:` empty)
+- `tasks.md` from `templates/tasks.md`
+- `notes/learnings.md` — scaffold minimal learnings file (no template exists; create with YAML frontmatter + empty `## Learnings` section)
+- `notes/decision-log.md` from `templates/decision-log.md` (append-only decision log)
+- `.gitignore` — scaffold standard gitignore for detected stack (new repos only)
 
 ---
 
 ## Phase 3.5 — Scaffold claude-progress.json
 
-From `references/claude-progress-template.json`. Apply substitution map.
+From `templates/claude-progress.json`. Apply substitution map.
 Write to `{vault_path}/claude-progress.json`.
 
 ---
@@ -105,7 +105,9 @@ Write to `{vault_path}/claude-progress.json`.
 ## Phase 4 — Vault Search Check
 
 Vault indexing is automatic for `obsidian` backend. No manual re-index needed.
-Verify the new project is searchable: `obsidian search query="{slug}" limit=1`
+Verify the new project is searchable using configured backend:
+- If `obsidian`: `obsidian search query="{slug}" limit=1`
+- If `ripgrep`: `rg --files-with-matches "{slug}" {vault_path}/`
 On failure: warn, do not block.
 
 ---

package/base/skills/px-session-retro/SKILL.md

@@ -48,7 +48,7 @@ Classify each: type, tag (`bugfix|convention|perf|security|tooling|arch|process`
 For each finding with clear root cause:
 - Project-specific → `{vault_path}/notes/learnings.md`
 - Global/harness pattern → harness project learnings.md
-- Check for duplicates via `obsidian search` before writing
+- Check for duplicates via vault search (using configured backend) before writing. If vault search unavailable: skip duplicate check and proceed.
 
 Format:
 ```markdown

package/base/skills/px-spec/SKILL.md

@@ -21,11 +21,15 @@ You are creating a spec for the current project.
 Ask the following in a single message:
 - What is this spec for? (one sentence)
 - Type: ADR (architecture decision) / RISK (risk register entry) / SPEC (technical spec)
-- Is there an existing related spec in `specs/`? (run `obsidian search query="{topic}" limit=3` first)
+- Is there an existing related spec in `specs/`?
+  - Read `vault_backend` from `~/.claude/praxis.config.json`
+  - If `obsidian`: run `obsidian search query="{topic}" limit=3`
+  - If `ripgrep`: run `rg --files-with-matches "{topic}" {vault_path}/specs/`
+  - If vault search fails (e.g., Obsidian not running): warn "Vault search unavailable — skipping conflict check" and proceed without blocking
 
 **Step 2b — Cross-spec conflict check**
 After the vault search from Step 2, check for conflicts with accepted ADRs:
-- Run: `obsidian search query="{topic}" limit=10`
+- Run vault search for topic (using backend detected above) with limit=10
 - For each result with `status: accepted` or `status: proposed`:
   - Compare the decision direction. Does the new spec contradict an accepted decision?
 - If conflict detected, present:

package/base/skills/px-verify/SKILL.md

@@ -17,7 +17,8 @@ Execute in order, showing actual output (never assertions):
    - **DeepSource**: `deepsource issues list <file>` for files in diff (if deepsource CLI available)
    - If either tool finds HIGH/CRITICAL: treat as blocking — must fix before proceeding.
    - If tools not installed: skip with advisory note, do not block. DeepSource cloud validates on push.
-6. **Functional check** — ask: "Is there a smoke test, `terraform plan` output, or browser check needed for this milestone?" If yes: block until user confirms it passed. If no: proceed.
+6. **Quality gate** → run `/px-quality-gate` on changed files → BLOCK on naming/prose/structure violations. See `px-quality-gate` skill for full check list.
+7. **Functional check** — ask: "Is there a smoke test, `terraform plan` output, or browser check needed for this milestone?" If yes: block until user confirms it passed. If no: proceed.
 
 Read test/lint/build commands from the project CLAUDE.md `## Commands` section.
 If no commands are defined: warn and ask user for the correct commands.

package/bin/praxis.js

@@ -19,7 +19,7 @@ function fail(msg)   { console.error('  \x1b[31m\u2717\x1b[0m ' + msg); }
 function dim(msg)    { console.log('  \x1b[2m' + msg + '\x1b[0m'); }
 
 function toolExists(name) {
-  const r = spawnSync('which', [name], { stdio: 'pipe' });
+  const r = spawnSync('command', ['-v', name], { stdio: 'pipe', shell: true });
   return r.status === 0;
 }
 
@@ -94,12 +94,33 @@ async function install() {
     const hooksConfig = path.join(hooksDir, 'settings-hooks.json');
     const settingsFile = path.join(CLAUDE_DIR, 'settings.json');
     if (fs.existsSync(hooksConfig)) {
-      const hooksCfg = JSON.parse(fs.readFileSync(hooksConfig, 'utf8'));
+      let hooksCfg;
+      try {
+        hooksCfg = JSON.parse(fs.readFileSync(hooksConfig, 'utf8'));
+      } catch (hookParseErr) {
+        fail('settings-hooks.json has invalid JSON: ' + hookParseErr.message);
+        hooksCfg = {};
+      }
       let settings = {};
       if (fs.existsSync(settingsFile)) {
-        try { settings = JSON.parse(fs.readFileSync(settingsFile, 'utf8')); } catch { /* invalid JSON — use empty defaults */ }
+        const raw = fs.readFileSync(settingsFile, 'utf8');
+        try {
+          settings = JSON.parse(raw);
+        } catch (parseErr) {
+          // Preserve corrupt file as backup before overwriting
+          const backupPath = settingsFile + '.backup';
+          fs.writeFileSync(backupPath, raw);
+          fail('settings.json has invalid JSON — backed up to ' + backupPath);
+        }
+      }
+      // Deep merge: preserve existing keys, overlay hooks
+      for (const [key, value] of Object.entries(hooksCfg)) {
+        if (typeof value === 'object' && !Array.isArray(value) && settings[key] && typeof settings[key] === 'object') {
+          settings[key] = { ...settings[key], ...value };
+        } else {
+          settings[key] = value;
+        }
       }
-      Object.assign(settings, hooksCfg);
       fs.writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
       ok('hooks configuration merged into settings.json');
     }
@@ -261,7 +282,7 @@ function health() {
       } else {
         total++; fail('vault_path not set in config');
       }
-    } catch { total++; fail('praxis.config.json is invalid JSON'); }
+    } catch (configErr) { total++; fail('praxis.config.json is invalid JSON: ' + configErr.message); }
   }
 
   // Tools
@@ -386,7 +407,7 @@ else if (arg === '--version' || arg === '-v') { console.log(VERSION); }
 else if (commands[arg]) {
   const result = commands[arg]();
   if (result && typeof result.catch === 'function') {
-    result.catch(err => { fail(err.message); process.exit(1); });
+    result.catch(err => { fail(err?.message || String(err)); process.exit(1); });
   }
 }
 else { fail('Unknown command: ' + arg); printHelp(); process.exit(1); }

package/kits/api/KIT.md

@@ -14,6 +14,8 @@ skills_chain:
   - phase: contract
     skills: []
     status: planned
+context_cost: medium
+depends_on: []
 mcp_servers: []
 rules:
   - api-design.md

package/kits/api/install.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
 echo "=== Praxis: Installing api kit ==="

package/kits/api/teardown.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
 echo "=== Praxis: Removing api kit ==="

package/kits/code-quality/KIT.md

@@ -4,6 +4,8 @@ version: 1.0.0
 description: "Code quality enforcement — parallel deterministic gate (SAST, secrets, SCA, IaC) + AI review layer (over-engineering, smells, structure, performance)"
 activation: /kit:code-quality
 deactivation: /kit:off
+context_cost: high
+depends_on: []
 skills_chain:
   - phase: gate
     skills: [sast-scan, secrets-scan, sca-scan, iac-scan]

package/kits/code-quality/hooks/generate-baseline.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Run once on kit install to snapshot existing violations
 # Pre-push hook only blocks on NET NEW violations above this baseline
 

package/kits/code-quality/hooks/post-commit.sh

@@ -1,4 +1,5 @@
-#!/bin/bash
+#!/usr/bin/env bash
+set -euo pipefail
 # Triggers Claude AI self-review after commit
 # This is advisory — does not block, surfaces findings for next commit
 
@@ -11,7 +12,7 @@ if ! command -v claude &>/dev/null; then
 fi
 
 CHANGED=$(git diff --name-only HEAD~1...HEAD 2>/dev/null | head -20)
-if [ -z "$CHANGED" ]; then
+if [[ -z "$CHANGED" ]]; then
   exit 0
 fi
 

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

@@ -1,5 +1,5 @@
-#!/bin/bash
-set -uo pipefail
+#!/usr/bin/env bash
+set -euo pipefail
 
 REPO_ROOT=$(git rev-parse --show-toplevel)
 KIT_DIR="$REPO_ROOT/.claude/kits/code-quality"
@@ -33,7 +33,7 @@ echo "------------------------"
 
 # Get changed files only (diff-scoped scanning)
 CHANGED=$(git diff --name-only origin/HEAD...HEAD 2>/dev/null || git diff --name-only HEAD~1...HEAD 2>/dev/null || echo "")
-if [ -z "$CHANGED" ]; then
+if [[ -z "$CHANGED" ]]; then
   echo "  No changed files detected — skipping gate"
   exit 0
 fi
@@ -46,7 +46,7 @@ GATE_FAILURES=()
 GATE_WARNINGS=()
 
 # -- SAST (OpenGrep) --
-if [ -s "$TMP/code-files.txt" ]; then
+if [[ -s "$TMP/code-files.txt" ]]; then
   echo "  SAST scan (OpenGrep)..."
   FILES=$(cat "$TMP/code-files.txt" | tr '\n' ' ')
   opengrep scan --config auto --json $FILES > "$TMP/sast.json" 2>/dev/null || true
@@ -54,8 +54,8 @@ if [ -s "$TMP/code-files.txt" ]; then
   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")
+  [[ "$CRITICAL" -gt 0 ]] && GATE_FAILURES+=("SAST: $CRITICAL critical findings")
+  [[ "$HIGH" -gt 0 ]]     && GATE_WARNINGS+=("SAST: $HIGH high findings")
   echo "     Critical: $CRITICAL  High: $HIGH"
 fi &
 SAST_PID=$!
@@ -68,7 +68,7 @@ if [[ -s "$TMP/secrets.json" ]]; then
 else
   SECRETS=0
 fi
-[ "$SECRETS" -gt 0 ] && GATE_FAILURES+=("SECRETS: $SECRETS verified secrets found")
+[[ "$SECRETS" -gt 0 ]] && GATE_FAILURES+=("SECRETS: $SECRETS verified secrets found")
 echo "     Verified secrets: $SECRETS" &
 SECRETS_PID=$!
 
@@ -77,17 +77,17 @@ echo "  Dependency scan (OSV-Scanner)..."
 osv-scanner scan --format json "$REPO_ROOT" > "$TMP/sca.json" 2>/dev/null || true
 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")
+[[ "$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" &
 SCA_PID=$!
 
 # -- IaC (Checkov) --
-if [ -s "$TMP/iac-files.txt" ]; then
+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=$(safe_jq '.results.failed_checks | length' "$TMP/iac.json")
-  [ "$IaC_FAIL" -gt 0 ] && GATE_WARNINGS+=("IaC: $IaC_FAIL policy violations")
+  [[ "$IaC_FAIL" -gt 0 ]] && GATE_WARNINGS+=("IaC: $IaC_FAIL policy violations")
   echo "     Policy violations: $IaC_FAIL"
 fi &
 IaC_PID=$!
@@ -97,10 +97,10 @@ wait $SAST_PID $SECRETS_PID $SCA_PID $IaC_PID 2>/dev/null || true
 
 # -- COVERAGE --
 COVERAGE_THRESHOLD=$(safe_jq '.coverage.line_min' "$CONFIG" 80)
-if [ -f "$REPO_ROOT/coverage/coverage-summary.json" ]; then
+if [[ -f "$REPO_ROOT/coverage/coverage-summary.json" ]]; then
   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}%")
+  [[ "$BELOW" == "1" ]] && GATE_WARNINGS+=("COVERAGE: ${COVERAGE}% below threshold ${COVERAGE_THRESHOLD}%")
   echo "  Coverage: ${COVERAGE}% (threshold: ${COVERAGE_THRESHOLD}%)"
 fi
 
@@ -108,12 +108,12 @@ fi
 echo ""
 echo "------------------------"
 
-if [ ${#GATE_WARNINGS[@]} -gt 0 ]; then
+if [[ ${#GATE_WARNINGS[@]} -gt 0 ]]; then
   echo "Warnings:"
   for w in "${GATE_WARNINGS[@]}"; do echo "   $w"; done
 fi
 
-if [ ${#GATE_FAILURES[@]} -gt 0 ]; then
+if [[ ${#GATE_FAILURES[@]} -gt 0 ]]; then
   echo "Gate BLOCKED:"
   for f in "${GATE_FAILURES[@]}"; do echo "   $f"; done
   echo ""

package/kits/code-quality/install.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
 echo "Installing code-quality kit dependencies..."

package/kits/code-quality/teardown.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
 echo "Removing code-quality kit hooks..."
@@ -6,8 +6,8 @@ echo "Removing code-quality kit hooks..."
 REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".")
 HOOKS_DIR="$REPO_ROOT/.git/hooks"
 
-[ -f "$HOOKS_DIR/pre-push" ] && rm "$HOOKS_DIR/pre-push" && echo "  pre-push hook removed"
-[ -f "$HOOKS_DIR/post-commit" ] && rm "$HOOKS_DIR/post-commit" && echo "  post-commit hook removed"
+[[ -f "$HOOKS_DIR/pre-push" ]] && rm "$HOOKS_DIR/pre-push" && echo "  pre-push hook removed"
+[[ -f "$HOOKS_DIR/post-commit" ]] && rm "$HOOKS_DIR/post-commit" && echo "  post-commit hook removed"
 
 echo ""
 echo "Note: CLI tools (opengrep, trufflehog, osv-scanner, checkov) are system-level"

package/kits/data/KIT.md

@@ -14,6 +14,8 @@ skills_chain:
   - phase: query
     skills: []
     status: planned
+context_cost: medium
+depends_on: []
 mcp_servers: []
 rules:
   - data.md

package/kits/data/install.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
 echo "=== Praxis: Installing data kit ==="

package/kits/data/teardown.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
 echo "=== Praxis: Removing data kit ==="

package/kits/infrastructure/KIT.md

@@ -17,6 +17,8 @@ skills_chain:
   - phase: compliance
     skills: []
     status: planned
+context_cost: high
+depends_on: []
 mcp_servers: []
 rules:
   - infrastructure.md

package/kits/infrastructure/install.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
 echo "=== Praxis: Installing infrastructure kit ==="

package/kits/infrastructure/teardown.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
 echo "=== Praxis: Removing infrastructure kit ==="

package/kits/security/KIT.md

@@ -14,6 +14,8 @@ skills_chain:
   - phase: audit
     skills: []
     status: planned
+context_cost: medium
+depends_on: []
 mcp_servers: []
 rules:
   - security.md

package/kits/security/install.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
 echo "=== Praxis: Installing security kit ==="

package/kits/security/teardown.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
 echo "=== Praxis: Removing security kit ==="

package/kits/web-designer/KIT.md

@@ -13,6 +13,8 @@ skills_chain:
     skills: [web-accessibility, ui-skills-baseline, ui-skills-motion]
   - phase: final-lint
     skills: [web-design-guidelines]
+context_cost: medium
+depends_on: []
 mcp_servers:
   - name: 21st-magic
     command: npx -y @21st-dev/magic@latest

package/kits/web-designer/install.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
 echo "=== Praxis: Installing web-designer kit ==="

package/kits/web-designer/teardown.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
 echo "=== Praxis: Removing web-designer kit dependencies ==="

package/package.json

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

package/scripts/health-check.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
 # ════════════════════════════════════════════════════════════════
@@ -16,23 +16,29 @@ FAIL=0
 TOTAL=0
 
 check() {
+  local label="$2"
   TOTAL=$((TOTAL + 1))
-  if eval "$1" 2>/dev/null; then
-    echo "  ✓ $2"
+  if "$@" 2>/dev/null; then
+    echo "  ✓ $label"
     PASS=$((PASS + 1))
   else
-    echo "  ✗ $2"
+    echo "  ✗ $label"
     FAIL=$((FAIL + 1))
   fi
 }
 
+check_exists() { [[ -e "$1" ]]; }
+check_file()   { [[ -f "$1" ]]; }
+check_dir()    { [[ -d "$1" ]]; }
+check_cmd()    { command -v "$1" &>/dev/null; }
+
 echo "Praxis Health Check"
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 
 # ─── CLAUDE.md symlink ───
 echo ""
 echo "Core:"
-check "[[ -e '$CLAUDE_DIR/CLAUDE.md' ]]" "CLAUDE.md installed"
+check check_exists "$CLAUDE_DIR/CLAUDE.md" "CLAUDE.md installed"
 
 # ─── Rules symlinks ───
 echo ""
@@ -41,7 +47,7 @@ if [[ -d "$PRAXIS_DIR/base/rules" ]]; then
   for rule in "$PRAXIS_DIR"/base/rules/*.md; do
     [[ -f "$rule" ]] || continue
     fname=$(basename "$rule")
-    check "[[ -e '$CLAUDE_DIR/rules/$fname' ]]" "rules/$fname installed"
+    check check_exists "$CLAUDE_DIR/rules/$fname" "rules/$fname installed"
   done
 fi
 
@@ -52,7 +58,7 @@ if [[ -d "$PRAXIS_DIR/base/commands" ]]; then
   for cmd in "$PRAXIS_DIR"/base/commands/*.md; do
     [[ -f "$cmd" ]] || continue
     fname=$(basename "$cmd")
-    check "[[ -e '$CLAUDE_DIR/commands/$fname' ]]" "commands/$fname installed"
+    check check_exists "$CLAUDE_DIR/commands/$fname" "commands/$fname installed"
   done
 fi
 
@@ -63,24 +69,24 @@ if [[ -d "$PRAXIS_DIR/base/skills" ]]; then
   for skill_dir in "$PRAXIS_DIR"/base/skills/*/; do
     [[ -d "$skill_dir" ]] || continue
     skill_name=$(basename "$skill_dir")
-    check "[[ -e '$CLAUDE_DIR/skills/$skill_name' ]]" "skills/$skill_name installed"
+    check check_exists "$CLAUDE_DIR/skills/$skill_name" "skills/$skill_name installed"
   done
 fi
 
 # ─── Kits symlink ───
 echo ""
 echo "Kits:"
-check "[[ -e '$CLAUDE_DIR/kits' ]]" "kits directory installed"
+check check_exists "$CLAUDE_DIR/kits" "kits directory installed"
 
 # ─── Config ───
 echo ""
 echo "Config:"
-check "[[ -f '$CONFIG_FILE' ]]" "praxis.config.json exists"
+check check_file "$CONFIG_FILE" "praxis.config.json exists"
 
 if [[ -f "$CONFIG_FILE" ]]; then
   VAULT_PATH=$(jq -r '.vault_path // empty' "$CONFIG_FILE" 2>/dev/null)
   if [[ -n "$VAULT_PATH" ]]; then
-    check "[[ -d '$VAULT_PATH' ]]" "vault_path ($VAULT_PATH) is a real directory"
+    check check_dir "$VAULT_PATH" "vault_path ($VAULT_PATH) is a real directory"
   else
     TOTAL=$((TOTAL + 1))
     echo "  ✗ vault_path not set in config"
@@ -91,10 +97,10 @@ fi
 # ─── Required tools ───
 echo ""
 echo "Tools:"
-check "command -v obsidian" "Obsidian CLI available"
-check "command -v node" "node available"
-check "command -v claude" "claude available"
-check "command -v jq" "jq available"
+check check_cmd obsidian "Obsidian CLI available"
+check check_cmd node "node available"
+check check_cmd claude "claude available"
+check check_cmd jq "jq available"
 
 # ─── MCP Servers (warn only) ───
 echo ""

package/scripts/install-tools.sh

@@ -17,7 +17,7 @@ for arg in "$@"; do
 done
 
 # Auto-detect if no flags
-if [ $# -eq 0 ]; then
+if [[ $# -eq 0 ]]; then
   command -v go &>/dev/null && INSTALL_GO=true
   command -v terraform &>/dev/null && INSTALL_TF=true
 fi
@@ -43,7 +43,7 @@ install_go()   { go install "$@" 2>/dev/null || true; }
 
 # ── Core (always) ──
 echo "── Installing core tools ──"
-if [ "$PKG" = "brew" ]; then
+if [[ "$PKG" == "brew" ]]; then
   install_brew shellcheck shfmt jq gitleaks
 else
   sudo apt-get update -qq
@@ -60,7 +60,7 @@ if $INSTALL_GO; then
   echo "── Installing Go quality tools ──"
   install_go golang.org/x/tools/cmd/goimports@latest
   install_go golang.org/x/vuln/cmd/govulncheck@latest
-  if [ "$PKG" = "brew" ]; then
+  if [[ "$PKG" == "brew" ]]; then
     install_brew golangci-lint
   else
     curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b "$(go env GOPATH)/bin" 2>/dev/null || true
@@ -71,7 +71,7 @@ fi
 if $INSTALL_TF; then
   echo ""
   echo "── Installing Terraform quality tools ──"
-  if [ "$PKG" = "brew" ]; then
+  if [[ "$PKG" == "brew" ]]; then
     install_brew tflint trivy infracost
   else
     echo "NOTE: Install tflint, trivy, infracost manually for Linux"
@@ -82,7 +82,7 @@ fi
 if command -v docker &>/dev/null; then
   echo ""
   echo "── Installing container tools ──"
-  if [ "$PKG" = "brew" ]; then
+  if [[ "$PKG" == "brew" ]]; then
     install_brew hadolint
   fi
 fi

package/scripts/lint-harness.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
 # ════════════════════════════════════════════════════════════════

package/scripts/onboard-mcp.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
 # ════════════════════════════════════════════════════════════════

package/scripts/test-harness.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
 # ════════════════════════════════════════════════════════════════

package/scripts/update.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
 # ════════════════════════════════════════════════════════════════