@esoteric-logic/praxis-harness 2.13.0 → 2.14.0

package/base/CLAUDE.md

@@ -101,8 +101,14 @@ Registered via `claude mcp add`. Persist globally across sessions.
 Check: `claude mcp list` | Manage: `bash scripts/onboard-mcp.sh [server|all]`
 Missing servers are non-blocking — features degrade gracefully.
 
+**CLI companions** — invoked via npx, not MCP:
+
+| Tool | Purpose | Invoke | Degrades without |
+|------|---------|--------|-----------------|
+| opensrc | Fetch library source for deep inspection | `npx opensrc <package>` | No source-level investigation; Context7 docs only |
+
 ## After Compaction — Bootstrap
-1. Read project CLAUDE.md (always first)
+1. Read project CLAUDE.md (always first). If `AGENTS.md` exists in project root, read it too — it contains opensrc source manifests.
 2. Active task? → read active plan current milestone only
    No active task? → read `status.md`
 4. Load rules only for what the current task touches:

package/base/configs/registry.json

@@ -35,7 +35,8 @@
       {"name": "markdownlint", "feature": "lint-markdown", "install": "npm install -g markdownlint-cli"},
       {"name": "golangci-lint", "feature": "lint-go", "install": "brew install golangci-lint"},
       {"name": "rustfmt", "feature": "format-rust", "install": "rustup component add rustfmt"},
-      {"name": "clippy", "feature": "lint-rust", "install": "rustup component add clippy"}
+      {"name": "clippy", "feature": "lint-rust", "install": "rustup component add clippy"},
+      {"name": "opensrc", "feature": "source-inspection", "install": "npx opensrc@latest --help"}
     ]
   },
   "env_vars": {
@@ -106,7 +107,8 @@
     ],
     "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"}
+      {"path": "base/hooks/dep-audit.sh", "event": "PostToolUse", "matcher": "Write|Edit|MultiEdit", "feature": "dep-audit"},
+      {"path": "base/hooks/context7-remind.sh", "event": "PostToolUse", "matcher": "Write|Edit|MultiEdit", "feature": "context7-enforcement"}
     ]
   },
   "claude_settings": {

package/base/hooks/context7-remind.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# context7-remind.sh — PostToolUse hook
+# Scans written/edited files for external import statements.
+# Reminds Claude to verify via Context7 if new imports are detected.
+# PostToolUse hooks always exit 0 — this is a reminder, not a gate.
+set -euo pipefail
+
+trap 'exit 0' ERR
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null)
+
+if [[ -z "$FILE_PATH" || ! -f "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+# Only scan code files where imports are meaningful
+case "$FILE_PATH" in
+  *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs) LANG="js" ;;
+  *.py)                               LANG="py" ;;
+  *.go)                               LANG="go" ;;
+  *.rs)                               LANG="rs" ;;
+  *.java)                             LANG="java" ;;
+  *.cs)                               LANG="cs" ;;
+  *)                                  exit 0 ;;
+esac
+
+# Build import pattern per language
+case "$LANG" in
+  js)   PATTERN="^import .+ from ['\"]|require\(['\"]" ;;
+  py)   PATTERN="^import |^from .+ import " ;;
+  go)   PATTERN="^import |^\t\"" ;;
+  rs)   PATTERN="^use [a-z]" ;;
+  java) PATTERN="^import " ;;
+  cs)   PATTERN="^using " ;;
+esac
+
+# Extract external imports (skip relative/internal)
+IMPORTS=$(grep -E "$PATTERN" "$FILE_PATH" 2>/dev/null || true)
+
+if [[ -z "$IMPORTS" ]]; then
+  exit 0
+fi
+
+# Filter out internal/relative imports
+EXTERNAL=""
+while IFS= read -r line; do
+  case "$LANG" in
+    js)
+      # Skip relative imports (./  ../)
+      if echo "$line" | grep -qE "from ['\"]\."; then continue; fi
+      ;;
+    py)
+      # Skip relative imports (from . import, from .. import)
+      if echo "$line" | grep -qE "^from \."; then continue; fi
+      ;;
+    go)
+      # Skip stdlib (no dots in path) — external modules have dots (github.com, etc.)
+      if ! echo "$line" | grep -qE '\"[a-z]+\.[a-z]'; then continue; fi
+      ;;
+    rs)
+      # Skip std/crate/self/super
+      if echo "$line" | grep -qE "^use (std|crate|self|super)::"; then continue; fi
+      ;;
+    java|cs)
+      # Skip java.*/javax.*/System.*
+      if echo "$line" | grep -qE "^(import|using) (java\.|javax\.|System\.)"; then continue; fi
+      ;;
+  esac
+  EXTERNAL="${EXTERNAL}${line}\n"
+done <<< "$IMPORTS"
+
+if [[ -z "$EXTERNAL" ]]; then
+  exit 0
+fi
+
+# Count unique external packages
+PKG_COUNT=$(echo -e "$EXTERNAL" | grep -c '.' 2>/dev/null || echo "0")
+
+echo "CONTEXT7-REMIND: $FILE_PATH contains $PKG_COUNT external import(s). Verify each was looked up via Context7 (resolve-library-id → get-library-docs) this session. If not: do it now before proceeding." >&2
+exit 0

package/base/hooks/settings-hooks.json

@@ -47,6 +47,15 @@
             "command": "bash ~/.claude/hooks/dep-audit.sh"
           }
         ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ~/.claude/hooks/context7-remind.sh"
+          }
+        ]
       }
     ],
     "Stop": [

package/base/rules/coding.md

@@ -29,6 +29,13 @@ Language-specific patterns matched:
 Every new external import requires a Context7 verification before the gate clears.
 Internal packages (same repo, same module) are excluded.
 
+### Source-level investigation (opensrc)
+- When Context7 docs are insufficient to understand library behavior (bugs, edge cases,
+  undocumented internals), run `npx opensrc <package>` to fetch source into `opensrc/<pkg>/`.
+- Before fetching: check `opensrc/sources.json` for already-fetched packages.
+- After fetching: read `AGENTS.md` in project root for the source manifest.
+- This is an escalation path, not a default — Context7 docs are the first stop.
+
 ### Tool preferences
 - Use Read/Edit/Write tools instead of cat/sed/echo.
 - Use `rg` (ripgrep) for searching code, not grep.

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

@@ -62,6 +62,16 @@ Use `perplexity_search` (model: `sonar` for speed):
 - Query: `"[package] last commit release 2025 2026 archived"`
 - Extract: last commit date, last release date, repository status, contributor count
 
+## Step 5.5 — Source Fetch (optional, on `--deep` flag or when investigating internals)
+
+If the research is for understanding implementation behavior (not just API surface):
+1. Check `opensrc/sources.json` — skip if package already fetched
+2. Run `npx opensrc <package>` to fetch source into `opensrc/<pkg>/`
+3. Read `AGENTS.md` for the source manifest
+4. Note key implementation details in the report under a new "### Implementation Notes" section
+
+Skip this step for standard dependency evaluation (version/CVE/maintenance checks).
+
 ## Step 6 — Produce Report
 
 Output in this exact format:
@@ -81,6 +91,9 @@ Output in this exact format:
 ### API Notes (from live docs)
 [Relevant API surface, configuration, or usage patterns from Context7/Sonar docs]
 
+### Implementation Notes (when source was fetched)
+[Key internals, edge cases, or undocumented behavior discovered from source]
+
 ### Sources
 - [Citation URL 1]
 - [Citation URL 2]

package/kits/web-designer/rules/web-design.md

@@ -9,25 +9,30 @@ paths:
   - "design-system/**"
   - "styles/**"
 ---
+
 # Web Design — Rules
-# Scope: Frontend component and design system files
-# Part of: web-designer AI-Kit
+
+Scope: Frontend component and design system files.
+Part of: web-designer AI-Kit.
 
 ## Invariants (BLOCK on violation)
 
 ### Design Tokens
+
 - No inline styles in component files — use design tokens or Tailwind utilities.
 - No hardcoded color values (`#fff`, `rgb(...)`) — must reference token variables
   (`var(--color-primary)`, Tailwind classes, or theme values).
 - Check: `grep -rn "color:" src/components/ | grep -v "var(--" | grep -v "tailwind"`
 
 ### Semantic HTML
+
 - No `<div>` click handlers — use `<button>` for actions, `<a>` for navigation.
 - Check: `grep -rn 'onClick.*<div' src/components/`
 - Every interactive element must have explicit keyboard handling (`onKeyDown` or
   native keyboard support via semantic elements).
 
 ### Accessibility
+
 - Every `<img>` must have an `alt` attribute (empty `alt=""` for decorative images).
 - Form inputs must have associated `<label>` elements or `aria-label`.
 - Color contrast must meet WCAG AA minimum (4.5:1 for text, 3:1 for large text).
@@ -35,6 +40,7 @@ paths:
 ## Conventions (WARN on violation)
 
 ### Component Structure
+
 - Component files follow `ComponentName/index.tsx` + `ComponentName.module.css`
   (or `ComponentName.tsx` with Tailwind — pick one pattern per project, don't mix).
 - Design tokens live in `design-system/tokens/` or equivalent.
@@ -42,21 +48,25 @@ paths:
   live in `src/components/[page-name]/`.
 
 ### Animation and Motion
+
 - Animation durations use token values, not magic numbers.
 - Respect `prefers-reduced-motion` — wrap animations in media query.
 - CSS transitions preferred over JS animation libraries for simple effects.
 
 ### Performance
+
 - Images have explicit `width` and `height` to prevent CLS (Cumulative Layout Shift).
 - Lazy-load images below the fold (`loading="lazy"`).
 - No layout-triggering CSS in animation loops (`top`, `left`, `width`, `height` — use `transform` and `opacity`).
 
 ### Design System Hygiene
+
 - New components must use existing tokens before creating new ones.
 - If a new token is needed: add to the token file, not inline.
 - Component variants use a consistent API pattern (props, not className overrides).
 
 ## Verification Commands
+
 ```bash
 # Token compliance — find hardcoded colors
 grep -rn "color:" src/components/ | grep -v "var(--" | grep -v "token" | grep -v "tailwind"
@@ -75,5 +85,6 @@ npx axe-core src/ --exit
 ```
 
 ## Removal Condition
+
 Remove when the project's design system is mature with >90% component coverage
 and design review is handled by a dedicated design tool or CI pipeline.

package/package.json

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