@esoteric-logic/praxis-harness 2.5.1 → 2.6.0

package/base/CLAUDE.md

@@ -134,7 +134,7 @@ Kit manifests live in `~/.claude/kits/<name>/KIT.md`.
 
 ## Rules Registry — Load on Demand Only
 
-### Universal — always active (7 rules)
+### Universal — always active (8 rules)
 | File | Purpose |
 |------|---------|
 | `~/.claude/rules/profile.md` | Who the user is, identities, working style |
@@ -144,6 +144,7 @@ Kit manifests live in `~/.claude/kits/<name>/KIT.md`.
 | `~/.claude/rules/vault.md` | Second brain integration — vault backend, file purposes |
 | `~/.claude/rules/context-management.md` | Context anti-rot, phase scoping, context reset protocol |
 | `~/.claude/rules/memory-boundary.md` | Auto-memory boundary, MEMORY.md cap, dream integration |
+| `~/.claude/rules/security-posture.md` | Sandbox model, credential protection, protected paths |
 
 ### Scoped — load only when paths match
 | File | Loads when |
@@ -152,9 +153,24 @@ Kit manifests live in `~/.claude/kits/<name>/KIT.md`.
 | `~/.claude/rules/terraform.md` | `**/*.tf`, `**/*.tfvars` |
 | `~/.claude/rules/github-actions.md` | `.github/workflows/**` |
 | `~/.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 |
 
 ### Auto-invocable skills (replace former universal rules)
 | Skill | Triggers when |
 |-------|--------------|
 | `communication-standards` | Writing client-facing docs, proposals, status reports, commits, PRs |
 | `architecture-patterns` | Writing ADRs, specs, system design, risk docs, blocker reports |
+
+## Judgment & Research Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/duel` | Parallel Alpha/Beta implementation → blind scoring → synthesis |
+| `/deliberate` | Multi-perspective decision analysis with scored option matrix |
+| `/freshness` | Full dependency audit — CVEs, outdated packages, maintenance status |
+| `/research <pkg>` | Live docs (Context7) + CVE/version/maintenance check (Perplexity Sonar) |
+
+MCP server templates: `base/configs/mcp-servers.json` — declarative config for context7, github, perplexity-sonar.
+Dependency registry: `base/configs/registry.json` — single source of truth for all tools, auth, hooks.
+Preflight gate: `bin/praxis-preflight.sh` (alias: `praxis doctor`) — verifies auth, tools, MCP, keys.

package/base/configs/mcp-servers.json

@@ -0,0 +1,26 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"],
+      "description": "Real-time library documentation — always use before generating code that touches any npm/PyPI/crate dependency"
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      },
+      "description": "GitHub MCP — issues, PRs, repos. Token auto-set from gh auth."
+    },
+    "perplexity-sonar": {
+      "command": "npx",
+      "args": ["-y", "mcp-perplexity-server"],
+      "env": {
+        "PERPLEXITY_API_KEY": "${PERPLEXITY_API_KEY}",
+        "PERPLEXITY_MODEL": "sonar-pro"
+      },
+      "description": "Web search for CVEs, changelogs, security advisories. Default sonar-pro. Override per-call: sonar (fast), sonar-reasoning (/deliberate only)."
+    }
+  }
+}

package/base/configs/registry.json

@@ -0,0 +1,113 @@
+{
+  "version": "2.0",
+  "auth": {
+    "claude": {
+      "check": "claude auth status",
+      "fix": "claude auth login",
+      "blocking": true,
+      "description": "Claude Code OAuth — browser login, no API key needed"
+    },
+    "github": {
+      "check": "gh auth status",
+      "fix": "gh auth login",
+      "fallback_env": "GITHUB_TOKEN",
+      "auto_populate": "gh auth token",
+      "blocking": false,
+      "feature": "github-mcp"
+    }
+  },
+  "binaries": {
+    "required": [
+      {"name": "claude", "minVersion": "1.0.0", "install": "npm install -g @anthropic-ai/claude-code"},
+      {"name": "node", "minVersion": "18.0.0", "install": "brew install node"},
+      {"name": "npm", "minVersion": "9.0.0", "install": "npm install -g npm@latest"},
+      {"name": "git", "minVersion": "2.30.0", "install": "brew install git"},
+      {"name": "jq", "minVersion": "1.6", "install": "brew install jq"},
+      {"name": "gh", "minVersion": "2.0.0", "install": "brew install gh"}
+    ],
+    "optional": [
+      {"name": "trufflehog", "feature": "secret-scanning", "install": "brew install trufflehog"},
+      {"name": "gitleaks", "feature": "secret-scanning", "install": "brew install gitleaks"},
+      {"name": "osv-scanner", "feature": "dep-audit", "install": "go install github.com/google/osv-scanner/cmd/osv-scanner@latest"},
+      {"name": "pip-audit", "feature": "dep-audit-python", "install": "pip install pip-audit"},
+      {"name": "docker", "feature": "docker-sandbox", "install": "brew install --cask docker"}
+    ]
+  },
+  "env_vars": {
+    "optional": [
+      {
+        "name": "PERPLEXITY_API_KEY",
+        "description": "Perplexity Sonar — live CVE lookups, dep research",
+        "validation": "starts_with:pplx-",
+        "secure_store": true,
+        "masked_preview": 8,
+        "feature": "live-research",
+        "get_key_url": "https://www.perplexity.ai/settings/api"
+      },
+      {
+        "name": "GITHUB_TOKEN",
+        "description": "Auto-populated from gh auth token — for GitHub MCP",
+        "validation": "starts_with:gh",
+        "secure_store": true,
+        "masked_preview": 8,
+        "feature": "github-mcp",
+        "auto_populate": "gh auth token"
+      },
+      {
+        "name": "OBSIDIAN_VAULT",
+        "description": "Absolute path to Obsidian vault for long-term memory",
+        "validation": "is_directory",
+        "secure_store": false,
+        "feature": "obsidian-memory"
+      }
+    ]
+  },
+  "git_config": {
+    "required": [
+      {"key": "user.name", "description": "git commit author name"},
+      {"key": "user.email", "description": "git commit author email"}
+    ]
+  },
+  "mcp_servers": [
+    {
+      "name": "context7",
+      "package": "@upstash/context7-mcp@latest",
+      "requires_env": [],
+      "zero_config": true,
+      "feature": "live-docs"
+    },
+    {
+      "name": "github",
+      "package": "@modelcontextprotocol/server-github",
+      "requires_env": ["GITHUB_TOKEN"],
+      "feature": "github-mcp"
+    },
+    {
+      "name": "perplexity-sonar",
+      "package": "mcp-perplexity-server",
+      "requires_env": ["PERPLEXITY_API_KEY"],
+      "env_config": {"PERPLEXITY_MODEL": "sonar-pro"},
+      "feature": "live-research"
+    }
+  ],
+  "hooks": {
+    "required": [
+      {"path": "base/hooks/secret-scan.sh", "event": "PreToolUse", "matcher": "Write|Edit|MultiEdit"},
+      {"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/quality-check.sh", "event": "PostToolUse", "matcher": "Write|Edit|MultiEdit"},
+      {"path": "base/hooks/session-data-collect.sh", "event": "Stop", "matcher": ""}
+    ],
+    "optional": [
+      {"path": "base/hooks/recursion-guard.sh", "event": "PreToolUse", "matcher": "", "feature": "recursion-detection"},
+      {"path": "base/hooks/dep-audit.sh", "event": "PostToolUse", "matcher": "Write|Edit|MultiEdit", "feature": "dep-audit"}
+    ]
+  },
+  "claude_settings": {
+    "required": [
+      {"path": "sandbox.failIfUnavailable", "expected": true},
+      {"path": "sandbox.allowUnsandboxedCommands", "expected": false}
+    ]
+  }
+}

package/base/hooks/credential-guard.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# credential-guard.sh — PreToolUse:Bash hook
+# Blocks Bash commands that access credential files or sensitive directories.
+# Exit 0 = allow, Exit 2 = block with message.
+set -euo pipefail
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+if [[ -z "$COMMAND" ]]; then
+  exit 0
+fi
+
+# ── Allowlist: verification commands that reference credential paths safely ──
+SAFE_PATTERNS=(
+  "ssh-keygen -l"
+  "ssh-keygen -lf"
+  "gh auth status"
+  "gh auth token"
+  "gh auth switch"
+  "aws sts get-caller-identity"
+  "az account show"
+  "gcloud auth list"
+  "kubectl config current-context"
+  "docker login --help"
+  "gpg --list-keys"
+  "security find-identity"
+)
+
+for safe in "${SAFE_PATTERNS[@]}"; do
+  if echo "$COMMAND" | grep -qF "$safe"; then
+    exit 0
+  fi
+done
+
+# ── Blocked paths: credential stores and private key locations ──
+BLOCKED_PATHS=(
+  "$HOME/.ssh"
+  "$HOME/.aws"
+  "$HOME/.azure"
+  "$HOME/.kube"
+  "$HOME/.gnupg"
+  "$HOME/.docker/config.json"
+  "$HOME/Library/Keychains"
+  "$HOME/.config/gcloud"
+  "$HOME/.praxis/secrets"
+)
+
+# Expand ~ in commands for matching
+EXPANDED_CMD=$(echo "$COMMAND" | sed "s|~|$HOME|g")
+
+for blocked in "${BLOCKED_PATHS[@]}"; do
+  if echo "$EXPANDED_CMD" | grep -qF "$blocked"; then
+    echo "BLOCKED: Command references protected credential path: $blocked" >&2
+    echo "Praxis credential-guard prevents access to sensitive directories." >&2
+    echo "If this is a legitimate operation, use the allowlisted verification commands." >&2
+
+    # Log to audit trail
+    AUDIT_FILE="$HOME/.claude/praxis-audit.jsonl"
+    if command -v jq &>/dev/null; then
+      jq -nc \
+        --arg ts "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
+        --arg tool "Bash" \
+        --arg event "credential-guard-block" \
+        --arg path "$blocked" \
+        --arg cmd "${COMMAND:0:200}" \
+        --arg session "$PPID" \
+        '{ts: $ts, tool: $tool, event: $event, blocked_path: $path, command_prefix: $cmd, session_id: $session}' \
+        >> "$AUDIT_FILE" 2>/dev/null || true
+    fi
+
+    exit 2
+  fi
+done
+
+# ── Blocked file patterns: private keys and env files ──
+BLOCKED_FILE_PATTERNS=(
+  "_rsa[[:space:]]"
+  "_rsa$"
+  "_ed25519[[:space:]]"
+  "_ed25519$"
+  "\.pem[[:space:]]"
+  "\.pem$"
+  "\.p12[[:space:]]"
+  "\.p12$"
+  "\.pfx[[:space:]]"
+  "\.pfx$"
+)
+
+for pattern in "${BLOCKED_FILE_PATTERNS[@]}"; do
+  if echo "$EXPANDED_CMD" | grep -qE "$pattern"; then
+    echo "BLOCKED: Command references private key or certificate file pattern." >&2
+    echo "Praxis credential-guard prevents access to private key files." >&2
+    exit 2
+  fi
+done
+
+exit 0

package/base/hooks/dep-audit.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# 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
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null)
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+BASENAME=$(basename "$FILE_PATH")
+DIR=$(dirname "$FILE_PATH")
+AUDIT_RESULT=""
+ECOSYSTEM=""
+
+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)
+    fi
+    ;;
+  go.mod)
+    ECOSYSTEM="go"
+    if command -v govulncheck &>/dev/null; then
+      AUDIT_RESULT=$(cd "$DIR" && govulncheck -json ./... 2>/dev/null || true)
+    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)
+    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)
+    fi
+    ;;
+  Cargo.toml)
+    ECOSYSTEM="rust"
+    if command -v cargo-audit &>/dev/null; then
+      AUDIT_RESULT=$(cd "$DIR" && cargo audit --json 2>/dev/null || true)
+    fi
+    ;;
+  *)
+    # Not a dependency manifest — skip silently
+    exit 0
+    ;;
+esac
+
+if [[ -z "$ECOSYSTEM" ]]; then
+  exit 0
+fi
+
+# ── Parse results and warn on critical findings ──
+CRITICAL_COUNT=0
+HIGH_COUNT=0
+
+if [[ -n "$AUDIT_RESULT" ]]; then
+  case "$ECOSYSTEM" in
+    npm)
+      CRITICAL_COUNT=$(echo "$AUDIT_RESULT" | jq -r '.metadata.vulnerabilities.critical // 0' 2>/dev/null || echo "0")
+      HIGH_COUNT=$(echo "$AUDIT_RESULT" | jq -r '.metadata.vulnerabilities.high // 0' 2>/dev/null || echo "0")
+      ;;
+    python)
+      VULN_COUNT=$(echo "$AUDIT_RESULT" | jq -r 'length // 0' 2>/dev/null || echo "0")
+      if [[ "$VULN_COUNT" -gt 0 ]]; then
+        CRITICAL_COUNT="$VULN_COUNT"
+      fi
+      ;;
+    rust|go)
+      # For cargo-audit and govulncheck, count any findings as high
+      if echo "$AUDIT_RESULT" | jq -e '.vulnerabilities // .findings // empty' &>/dev/null 2>&1; then
+        HIGH_COUNT=1
+      fi
+      ;;
+  esac
+fi
+
+# ── Report findings ──
+if [[ "$CRITICAL_COUNT" -gt 0 ]]; then
+  echo "DEP-AUDIT ($ECOSYSTEM): $CRITICAL_COUNT CRITICAL vulnerabilities found in $BASENAME" >&2
+  echo "Run '/freshness' for a full audit report." >&2
+fi
+
+if [[ "$HIGH_COUNT" -gt 0 ]]; then
+  echo "DEP-AUDIT ($ECOSYSTEM): $HIGH_COUNT HIGH vulnerabilities found in $BASENAME" >&2
+fi
+
+# ── Write audit result to ~/.praxis/ ──
+PRAXIS_DIR="$HOME/.praxis"
+if [[ -d "$PRAXIS_DIR" ]] && command -v jq &>/dev/null; then
+  jq -nc \
+    --arg ts "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
+    --arg ecosystem "$ECOSYSTEM" \
+    --arg file "$FILE_PATH" \
+    --argjson critical "${CRITICAL_COUNT:-0}" \
+    --argjson high "${HIGH_COUNT:-0}" \
+    '{timestamp: $ts, ecosystem: $ecosystem, file: $file, critical: $critical, high: $high}' \
+    > "$PRAXIS_DIR/dep-audit-latest.json" 2>/dev/null || true
+fi
+
+exit 0

package/base/hooks/quality-check.sh

@@ -103,10 +103,11 @@ case "$EXT" in
     fi
     ;;
   md)
-    if command -v vale &>/dev/null; then
-      LINT_OUT=$(vale --output=line "$FILE_PATH" 2>&1) || true
+    # Markdown linting handled by markdownlint if available
+    if command -v markdownlint &>/dev/null; then
+      LINT_OUT=$(markdownlint "$FILE_PATH" 2>&1) || true
       if [ -n "$LINT_OUT" ]; then
-        ISSUES+=("vale: $LINT_OUT")
+        ISSUES+=("markdownlint: $LINT_OUT")
       fi
     fi
     ;;

package/base/hooks/recursion-guard.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# recursion-guard.sh — PreToolUse hook (all matchers)
+# Detects repetitive tool invocations and blocks infinite loops.
+# Tracks per-session state in /tmp. Lightweight — sub-millisecond.
+# Exit 0 = allow (with optional warning), Exit 2 = block.
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"' 2>/dev/null)
+
+# ── Configuration ──
+WARN_SAME_CMD=5
+BLOCK_SAME_CMD=8
+WARN_SAME_FILE=15
+BLOCK_SAME_FILE=25
+
+# ── State file scoped to session ──
+STATE_FILE="/tmp/praxis-recursion-${PPID}.json"
+
+# Initialize state if missing
+if [[ ! -f "$STATE_FILE" ]]; then
+  echo '{"commands":{},"files":{}}' > "$STATE_FILE"
+fi
+
+# ── Extract key based on tool type ──
+case "$TOOL_NAME" in
+  Bash)
+    KEY=$(echo "$INPUT" | jq -r '.tool_input.command // "unknown"' 2>/dev/null)
+    CATEGORY="commands"
+    WARN_THRESHOLD=$WARN_SAME_CMD
+    BLOCK_THRESHOLD=$BLOCK_SAME_CMD
+    ;;
+  Write|Edit|MultiEdit)
+    KEY=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // "unknown"' 2>/dev/null)
+    CATEGORY="files"
+    WARN_THRESHOLD=$WARN_SAME_FILE
+    BLOCK_THRESHOLD=$BLOCK_SAME_FILE
+    ;;
+  *)
+    # Other tools: track but with higher thresholds
+    KEY=$(echo "$INPUT" | jq -r '.tool_input | tostring' 2>/dev/null | head -c 200)
+    CATEGORY="commands"
+    WARN_THRESHOLD=$WARN_SAME_CMD
+    BLOCK_THRESHOLD=$BLOCK_SAME_CMD
+    ;;
+esac
+
+# Truncate key to prevent state file bloat
+KEY="${KEY:0:300}"
+
+# ── Increment counter ──
+# Use a hash of the key for safe JSON field names
+KEY_HASH=$(echo -n "$KEY" | md5 2>/dev/null || echo -n "$KEY" | md5sum 2>/dev/null | cut -d' ' -f1 || echo "fallback")
+
+COUNT=$(jq -r --arg cat "$CATEGORY" --arg key "$KEY_HASH" \
+  '.[$cat][$key] // 0' "$STATE_FILE" 2>/dev/null || echo "0")
+COUNT=$((COUNT + 1))
+
+jq --arg cat "$CATEGORY" --arg key "$KEY_HASH" --argjson count "$COUNT" \
+  '.[$cat][$key] = $count' "$STATE_FILE" > "${STATE_FILE}.tmp" 2>/dev/null \
+  && mv "${STATE_FILE}.tmp" "$STATE_FILE" 2>/dev/null || true
+
+# ── Check thresholds ──
+if [[ $COUNT -ge $BLOCK_THRESHOLD ]]; then
+  echo "BLOCKED: Repetition detected — $TOOL_NAME invoked $COUNT times with same input." >&2
+  echo "This looks like an infinite loop. Stop and reassess your approach." >&2
+  echo "Threshold: $BLOCK_THRESHOLD for $CATEGORY." >&2
+  exit 2
+fi
+
+if [[ $COUNT -ge $WARN_THRESHOLD ]]; then
+  echo "WARNING: $TOOL_NAME invoked $COUNT times with same input (block at $BLOCK_THRESHOLD)." >&2
+  echo "Consider whether you are in a loop." >&2
+fi
+
+exit 0

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

@@ -102,4 +102,7 @@ if command -v jq &>/dev/null && [[ -f "$PROGRESS_FILE" ]]; then
   fi
 fi
 
+# Clean up recursion guard state files from this session
+rm -f /tmp/praxis-recursion-*.json 2>/dev/null || true
+
 exit 0

package/base/hooks/settings-hooks.json

@@ -27,6 +27,15 @@
             "command": "bash ~/.claude/hooks/identity-check.sh"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ~/.claude/hooks/credential-guard.sh"
+          }
+        ]
       }
     ],
     "PostToolUse": [
@@ -38,6 +47,15 @@
             "command": "bash ~/.claude/hooks/quality-check.sh"
           }
         ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ~/.claude/hooks/dep-audit.sh"
+          }
+        ]
       }
     ],
     "Stop": [

package/base/rules/coding.md

@@ -117,7 +117,7 @@ Before adding any new package:
 
 Style, formatting, import ordering, complexity thresholds, and security patterns
 are enforced by automated tooling (golangci-lint, shellcheck, hadolint, tflint,
-semgrep, vale). Rules files cover ONLY:
+semgrep). Rules files cover ONLY:
 - Architecture decisions tooling cannot express
 - Permission boundaries and file-group scoping
 - Error learning from real session failures
@@ -130,7 +130,7 @@ Do NOT duplicate in CLAUDE.md what hooks already enforce.
 ## Verification Commands
 
 Single-file (matches PostToolUse hooks):
-- `go vet <file>` / `shellcheck <file>` / `hadolint Dockerfile` / `vale <file>.md`
+- `go vet <file>` / `shellcheck <file>` / `hadolint Dockerfile` / `markdownlint <file>.md`
 
 Project-level (matches pre-commit + /verify):
 - `golangci-lint run`

package/base/rules/dependency-freshness.md

@@ -0,0 +1,50 @@
+# Dependency Freshness — Rules
+# Scope: Projects with dependency manifests (package.json, go.mod, requirements.txt, Cargo.toml, pyproject.toml)
+# Enforces live version verification and freshness SLAs
+
+## Invariants — BLOCK on violation
+
+### Never hardcode versions from memory
+All package versions in dependency manifests must be verified live against the registry
+at the time of generation. Never use a version number from training data.
+
+Verification commands by ecosystem:
+- npm: `npm view <package> version`
+- PyPI: `pip index versions <package>`
+- Go: `go list -m -versions <module>`
+- Cargo: `cargo search <crate>`
+
+State in output: "Verified: <package>@<version> as of [date]"
+
+### Freshness SLAs
+When a vulnerability or outdated dependency is identified:
+- **CRITICAL CVE**: Fix same day. No exceptions.
+- **HIGH CVE**: Fix within 1 week. Log in vault `tasks.md` if deferred.
+- **Major version drift > 2**: Flag for review. Do not silently leave 3+ major versions behind.
+- **Unmaintained (no release in 12+ months)**: Flag as risk. Recommend alternative if available.
+
+Enforcement: `dep-audit.sh` hook (PostToolUse:Write) runs ecosystem auditors when manifests change.
+On-demand: `/freshness` skill runs a full audit with structured report.
+
+## Conventions — WARN on violation
+
+### Production vs Development pinning
+- Development deps: `^major.minor.0` ranges acceptable
+- Production and security-sensitive deps: pin exact verified version
+- Always commit lockfiles (`package-lock.json`, `uv.lock`, `Cargo.lock`, `go.sum`)
+
+### Pre-recommend checklist
+Before suggesting any new dependency:
+- [ ] Verified current version via registry (not training data)
+- [ ] < 5 open CVEs in last 12 months
+- [ ] Active maintenance (commit in last 90 days)
+- [ ] > 1000 weekly downloads OR explicitly justified
+- [ ] Not in archived/unmaintained state
+
+See `base/rules/live-docs-required.md` for the full Context7 + Perplexity verification protocol.
+
+---
+
+## Removal Condition
+Permanent. Dependency freshness is a supply chain security concern
+that applies to any project with external dependencies.

package/base/rules/live-docs-required.md

@@ -0,0 +1,81 @@
+# Live Documentation Requirement — Rules
+# Scope: All code touching external libraries, frameworks, or APIs
+# Enforces Context7-first + Perplexity Sonar fallback for documentation freshness
+
+## Invariants — BLOCK on violation
+
+### Context7 is ALWAYS required before generating dependency code
+Before writing any code that uses an external library, framework, or API:
+1. Call `resolve-library-id` with the package name to get the Context7 ID
+2. Call `get-library-docs` with that ID and the specific topic
+3. Use ONLY the returned documentation — not training-data memory
+4. Cite the doc version in a comment: `// Docs: <library>@<version> via Context7`
+
+**This is non-negotiable.** Training data has a cutoff. Official docs do not.
+
+### Perplexity Sonar fallback sequence
+If `resolve-library-id` returns no results for a library:
+1. Query Sonar: `"<library> official documentation site:docs.<domain> OR site:github.com"`
+2. Use the returned URL as the documentation source
+3. State in output: "Context7 had no index for <library> — sourced from [URL] via Sonar"
+
+Never silently fall back to training data. Always disclose the documentation source.
+
+### Mandatory version verification before install suggestions
+Before suggesting `npm install <package>`, `pip install <package>`, or any dependency addition:
+1. Context7: resolve the library, confirm current major version
+2. Sonar (`sonar` model): search `"<package> latest version site:npmjs.com"` to confirm with date
+3. State in output: "Verified: <package>@<version> as of [date]"
+4. Never suggest a version from memory alone
+
+## Conventions — WARN on violation
+
+### Auto-trigger conditions
+The research pipeline fires AUTOMATICALLY (do not wait to be asked) when:
+- Any `npm install <package>` or `pip install <package>` suggestion is generated
+- Any new dependency is added to a manifest file
+- Any framework or library recommendation appears in a plan
+- Any code imports an external package not previously verified in this session
+
+### Sonar model selection
+Use the appropriate Perplexity model for each query type:
+
+| Query type | Model | Why |
+|------------|-------|-----|
+| Version lookup, changelog | `sonar` | Fast, cheap, factual |
+| CVE research, security analysis | `sonar-pro` | Better citations, less hallucination on security claims |
+| "Should I use X vs Y?" decisions | `sonar-reasoning` | Extended thinking for tradeoff analysis |
+| Breach/incident research | `sonar-pro` + `search_recency_filter: "month"` | Restricts to recent results only |
+
+### Query templates (use verbatim)
+- Latest version: `"[package] npm latest version site:npmjs.com OR site:github.com"`
+- CVE check: `"[package] CVE vulnerability 2025 2026 site:nvd.nist.gov OR site:github.com/advisories"`
+- Breaking changes: `"[package] breaking changes migration [version]"`
+- Maintenance: `"[package] last commit release 2025 2026 archived"`
+
+### When to use Perplexity Sonar alongside Context7
+- **Always**: Version verification (Context7 confirms API surface, Sonar confirms release date)
+- **On new deps**: CVE check before adding to any manifest
+- **On major upgrades**: Breaking changes search before recommending migration
+- **On unfamiliar packages**: Maintenance and activity check
+
+### Session caching rules
+- Context7 docs: valid for the entire session — do NOT re-fetch same library
+- Sonar version checks: valid for the session (versions don't change mid-session)
+- Sonar CVE checks: re-fetch if > 24 hours elapsed (use session timestamp)
+- On new session: all caches reset, re-fetch everything fresh
+
+### When Context7 is unavailable
+If the MCP server is not running or returns errors:
+1. State that docs could not be verified via Context7
+2. Fall back to Perplexity Sonar for documentation lookup
+3. If both are unavailable: flag the specific method/API as "unverified against current version"
+4. Proceed with best-knowledge implementation but mark for review
+
+For comprehensive research (CVEs + maintenance + version), use `/research <package>`.
+
+---
+
+## Removal Condition
+Remove when training data freshness is guaranteed to match live documentation,
+or when a built-in documentation verification mechanism replaces MCP-based lookups.