@esoteric-logic/praxis-harness 2.13.0 → 2.15.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-prompt/SKILL.md

@@ -0,0 +1,373 @@
+---
+name: px-prompt
+disable-model-invocation: true
+description: "Unified prompt engine. Creates, generates, condenses, and syncs system prompts for Claude Projects, Perplexity Spaces, and Claude Code. Auto-detects what to do based on project state."
+---
+
+# px-prompt Skill
+
+## Overview
+Single entry point for the prompt engine. Detects what needs to happen based on project state and user intent.
+
+## Invocation
+- `/px-prompt <project-name>` — create, generate, or regenerate a project's prompts
+- `/px-prompt --sync` — recompile all projects, report diffs and budgets
+- `/px-prompt --list` — list all projects and their status
+
+---
+
+## Routing Logic
+
+When invoked with a project name, detect the right action:
+
+```
+/px-prompt <project-name>
+  │
+  ├─ Project doesn't exist?
+  │   → ACTION: CREATE (Step 1)
+  │
+  ├─ Project exists, mode: standalone, system-prompt.md missing?
+  │   → ACTION: GENERATE FROM SCRATCH (Step 2)
+  │
+  ├─ Project exists, mode: standalone, system-prompt.md exists, platform outputs missing?
+  │   → ACTION: CONDENSE (Step 3)
+  │
+  ├─ Project exists, mode: standalone, all files present?
+  │   → ACTION: VALIDATE + offer to regenerate (Step 4)
+  │
+  ├─ Project exists, mode: compiled?
+  │   → ACTION: COMPILE (Step 4)
+  │
+  └─ --sync flag?
+      → ACTION: SYNC ALL (Step 5)
+```
+
+---
+
+## Step 1 — CREATE: New project scaffold
+
+**Triggered when:** project folder doesn't exist.
+
+### 1a. Core intake (always ask)
+
+1. **Description** — "Describe this project in one sentence."
+
+2. **Role** — "Who is the AI in this project?"
+   - Show available identity blocks: `node bin/prompt-blocks.js --category identity`
+   - User can pick one OR describe a custom role
+
+3. **Target platforms** — "Which platforms will you deploy to?"
+   - Multi-select: Claude Projects, Perplexity Spaces, Claude Code
+   - Default: Claude Projects + Perplexity Spaces
+
+4. **Complexity** — Based on the description, recommend a mode:
+   - Simple/standard project → **compiled** (block-based, continue to 1b)
+   - Complex multi-role agent → **standalone** with AI generation (continue to 1c)
+   - User already has a prompt → **standalone** paste-in (scaffold folder, skip to Step 3)
+
+### 1b. Compiled project setup
+
+5. **Domain expertise** — Show available domain blocks:
+   ```bash
+   node bin/prompt-blocks.js --category domains
+   ```
+   User picks from list or describes custom domains.
+   For custom domains: create a new block file at `prompts/blocks/domains/<id>.md`.
+
+6. **Research domains** (if Perplexity selected) — "What topics should Perplexity prioritize?"
+   Suggest based on selected domains. User accepts or customizes.
+
+7. **Knowledge files** — "Reference documents to upload alongside? (compliance matrices, standards, playbooks)"
+
+8. **Claude Code extras** (only if Claude Code selected) — tech stack, commands, git identity
+
+9. **Build project folder:**
+   ```bash
+   mkdir -p prompts/projects/<project-name>/references
+   ```
+
+   Write `prompt-config.yaml`:
+   ```yaml
+   project: <project-name>
+   description: <from intake>
+   mode: compiled
+   version: "1.0"
+   platforms: [claude-project, perplexity-space]
+   profile: null
+   blocks:
+     identity: [<matched-block>]
+     domains: [<selected-blocks>]
+     behaviors: []
+     formats: []
+     context: [<auto-selected by platform>]
+   research_domains: [<from intake>]
+   knowledge_files: [<from intake>]
+   ```
+
+   **Auto-add context blocks by platform:**
+   - Perplexity → `official-docs-first`, `flag-confidence`
+   - Claude Code → `vault-integration`, `mcp-servers`, `praxis-workflow`
+
+10. **Compile:** `node bin/prompt-compile.js <project-name>`
+
+11. → Go to **Step 4** (results + deployment)
+
+### 1c. Standalone project with AI generation
+
+→ Go to **Step 2** (generate from scratch)
+
+---
+
+## Step 2 — GENERATE: AI-powered system prompt creation
+
+**Triggered when:** standalone project exists but `system-prompt.md` is empty/missing, OR user explicitly requests generation.
+
+### 2a. Intake (if not already gathered in Step 1)
+
+1. **Description** — 2-3 sentences about the project
+2. **Role** — primary AI responsibility
+3. **Domains** — expertise areas (free-form, not limited to existing blocks)
+4. **Key behaviors** — rules beyond defaults
+5. **Target audience** — who reads the output
+6. **Knowledge files** — reference documents
+7. **Target platforms** — deployment targets
+
+### 2b. Domain research via Perplexity
+
+**Mandatory before generating.** For each domain, run Perplexity queries:
+
+**Query 1 — Best practices:**
+```
+perplexity_ask: "What are the current best practices for [domain]
+AI assistants in 2025-2026? Key terminology, active standards,
+common workflows, expert expectations."
+```
+
+**Query 2 — Standards:**
+```
+perplexity_search: "[domain] key frameworks standards certifications 2025"
+```
+
+**Query 3 — Use cases:**
+```
+perplexity_ask: "What are the most common tasks [target audience]
+asks AI assistants to help with in [domain]? Top 10 use cases."
+```
+
+If Perplexity unavailable: state "Domain research could not be completed — prompt uses training data only. Review for currency." and proceed.
+
+### 2c. Generate system-prompt.md
+
+Using intake + Perplexity research, generate following the 5-layer skeleton:
+
+```markdown
+---
+version: "1.0"
+date: [today]
+platform: claude-project
+generated_by: px-prompt
+---
+
+## Role
+[One-sentence role from intake, using current terminology from research]
+
+## Behavioral Constraints
+[_base defaults: no-flattery, verify-before-reporting, recommend-with-reasons, handle-uncertainty]
+[Custom behaviors from intake]
+[Domain-specific constraints from research]
+
+## Domain Expertise
+[Structured areas from research — current framework names, standard versions]
+
+## Output Format
+[Format rules for target audience]
+[What/So What/Now What for analytical outputs]
+
+## Common Tasks
+[Top 5-10 use cases from Perplexity research]
+
+## Knowledge Interaction Rules
+[How to use reference files, when to cite, quote-before-answer]
+
+## Accuracy Standards
+- Flag confidence levels when synthesizing across sources
+- Distinguish verified facts from analytical inferences
+- If sources disagree, cite both and explain the discrepancy
+- Never fabricate version numbers, citations, or references
+- When information may be outdated, note this explicitly
+
+## When Uncertain
+State uncertainty explicitly. Ask one clarifying question rather than guessing.
+```
+
+**Generation rules:**
+- Use terminology from Perplexity research, not training-data assumptions
+- Positive framing: "Do X" over "Don't do Y"
+- No few-shot examples (breaks Perplexity)
+- Under 5,000 characters
+- Include Accuracy Standards + When Uncertain (mandatory)
+
+Write to `prompts/projects/<project-name>/system-prompt.md`.
+
+### 2d. Auto-condense
+
+→ Go to **Step 3** (condense to platform outputs)
+
+---
+
+## Step 3 — CONDENSE: Generate platform outputs from system-prompt.md
+
+**Triggered when:** standalone project has `system-prompt.md` but missing `space-instructions.md` or `CLAUDE.md`.
+
+Read the full `system-prompt.md` as source.
+
+### 3a. Generate Perplexity Space instructions
+
+**Target:** `space-instructions.md` | **Budget:** under 4,000 chars
+
+**Include:** identity, domain expertise, research domains, source priority, answer format, key frameworks (by name only)
+**Exclude:** internal templates, scoring matrices, reference file content, deployment details, full tables
+
+**Output format:**
+```markdown
+## Purpose
+## Domain Expertise
+## Research Domains
+## Source Priority
+## How to Answer
+## Accuracy Standards
+```
+
+**Perplexity guardrails:**
+- No few-shot examples
+- No URLs in instructions
+- Replace absolute language with conditional ("if available", "when sources confirm")
+- Search-friendly domain terms
+
+### 3b. Generate Claude Code CLAUDE.md (if Claude Code is a target platform)
+
+**Target:** `CLAUDE.md` | **Budget:** under 250 lines
+
+**Include:** identity, behaviors, domain expertise, frameworks (one-line each), operating modes, quality controls
+**Exclude:** full scoring matrices, templates, reference file content, corporate data tables
+
+**Output format:**
+```markdown
+# [Project Name]
+## Identity
+## Behaviors
+## Domain Expertise
+## Frameworks
+## Operating Modes
+## Quality Controls
+## References
+```
+
+**Claude Code guardrails:**
+- Positive framing: "Do X" over "Don't do Y"
+- No "CRITICAL: YOU MUST" language (Claude 4.6 overtriggers)
+- Self-check block for quality-critical outputs
+- Reference knowledge files by filename only
+
+### 3c. Validate budgets
+
+After generating, check:
+- `space-instructions.md` under 4,000 chars
+- `CLAUDE.md` under 250 lines
+
+If over budget: flag and suggest sections to trim.
+
+→ Go to **Step 4** (results)
+
+---
+
+## Step 4 — RESULTS: Validate + show deployment instructions
+
+**Triggered when:** project has outputs to display (compiled or standalone).
+
+### 4a. Run validator
+```bash
+node bin/prompt-compile.js <project-name>
+```
+
+### 4b. Show results table
+
+```
+| Output               | Chars  | Budget | Status |
+|----------------------|--------|--------|--------|
+| system-prompt.md     | X      | —      | Source |
+| project-instructions | X      | 2,500  | OK     |
+| space-instructions   | X      | 4,000  | OK     |
+| CLAUDE.md            | X lines| 250 ln | OK     |
+| references/          | N files| —      | Upload |
+```
+
+### 4c. Deployment instructions
+
+**Claude Projects (claude.ai):**
+1. Open project at claude.ai/projects → "Set project instructions"
+2. Standalone: paste `system-prompt.md` | Compiled: paste `project-instructions.md`
+3. If `references/` exists: upload each `.md` file as project knowledge
+4. Save
+
+**Perplexity Spaces:**
+1. Open Space → Settings → Answer Instructions
+2. Paste `space-instructions.md`
+3. Save
+
+**Claude Code:**
+1. Copy `CLAUDE.md` to project repo root
+
+### 4d. Offer next actions
+- "Edit the prompt? I'll regenerate platform outputs after."
+- "Want to regenerate? Run `/px-prompt <project-name>` again."
+
+---
+
+## Step 5 — SYNC: Recompile all projects
+
+**Triggered when:** `/px-prompt --sync`
+
+```bash
+node bin/prompt-compile.js --all --diff
+```
+
+Show summary table:
+```
+| Project | CLAUDE.md | Project Instr. | Space Instr. | Changes |
+|---------|-----------|----------------|--------------|---------|
+| praxis  | 3,534     | 1,316 ✓        | 1,529 ✓      | none    |
+| maximus | —         | —              | 3,977 ✓      | standalone |
+```
+
+For standalone projects, report validation status instead of compilation status.
+
+Print deployment reminders for any project with changes.
+
+---
+
+## Rules
+
+### Always
+- `_base` behaviors (no-flattery, verify, recommend, handle-uncertainty) are included in every project — non-negotiable
+- Accuracy Standards section is mandatory in all Perplexity outputs
+- When Uncertain section is mandatory in all Claude Project outputs
+- Never ask for repo URL, vault path, or git email unless Claude Code is a target platform
+
+### Platform-specific
+- **Perplexity**: no few-shot examples, no URLs, conditional language, search-friendly terms
+- **Claude Code**: positive framing, no "CRITICAL YOU MUST", self-check blocks
+- **Claude Projects**: 5-layer skeleton (Role, Constraints, Format, Knowledge Rules, Failure Handling)
+
+### Generation
+- ALWAYS run Perplexity research before generating system prompts (Step 2)
+- Use current terminology from research, not training-data assumptions
+- Generated prompts are starting points — tell user to review and refine
+- If Perplexity unavailable: proceed with training data, flag for review
+
+### Block matching (compiled mode)
+- Role → identity block: "architect" → `solutions-architect`, "engineer" → `senior-engineer`, "researcher" → `research-partner`
+- Domain keywords → domain blocks: "cloud/azure/aws" → `cloud-infrastructure`, "federal/govcon" → `govcon`, "web/react" → `web-development`
+- If no match: create custom block on the fly
+- Auto-add `official-docs-first` + `flag-confidence` for Perplexity targets
+- Auto-add `vault-integration` + `mcp-servers` + `praxis-workflow` for Claude Code targets

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/bin/praxis.js

@@ -141,6 +141,13 @@ async function install() {
     ok('kits installed');
   }
 
+  // Copy prompts/ → ~/.claude/prompts/
+  const promptsDir = path.join(PKG_DIR, 'prompts');
+  if (fs.existsSync(promptsDir)) {
+    copyDir(promptsDir, path.join(CLAUDE_DIR, 'prompts'));
+    ok('prompt library installed');
+  }
+
   // Orphan cleanup: deleted rules and legacy files
   const orphans = [
     'obsidian.md', 'security.md',