@esoteric-logic/praxis-harness 2.1.0 → 2.2.0

package/README.md

@@ -17,16 +17,18 @@ Praxis gives Claude Code a three-layer operating system:
 ## Quick start
 
 ```bash
-npx praxis-harness
+npx @esoteric-logic/praxis-harness@latest
 ```
 
 One command. Copies rules, commands, skills, and kits directly into `~/.claude/`. Node.js 18+ must be installed first.
 
+> **Always use `@latest`** — `npx` caches packages locally. Without `@latest`, you may get a stale version on machines that installed previously.
+
 **Subsequent commands:**
 ```bash
-npx praxis-harness update      # re-copy from latest npm version
-npx praxis-harness health      # verify install integrity
-npx praxis-harness uninstall   # remove Praxis-owned files from ~/.claude/
+npx @esoteric-logic/praxis-harness@latest update      # re-copy from latest npm version
+npx @esoteric-logic/praxis-harness@latest health      # verify install integrity
+npx @esoteric-logic/praxis-harness@latest uninstall   # remove Praxis-owned files from ~/.claude/
 ```
 
 ## After install
@@ -167,18 +169,20 @@ Praxis auto-documents your work in the vault with zero manual effort. Two indepe
 ### Updating the harness
 
 ```bash
-npx praxis-harness update
+npx @esoteric-logic/praxis-harness@latest update
 ```
 
 Re-copies all hooks, skills, rules, and kits from the latest npm package version. Config file is preserved.
 
+> **Always use `@latest`** to avoid `npx` serving a cached older version.
+
 ### Updating existing projects
 
 After a harness update that adds new vault files (like `decision-log.md`), run `/scaffold-exist` in a Claude Code session to audit your vault and add any missing files. This is non-destructive — it never overwrites existing content.
 
 ```
-Step 1: npx praxis-harness update     → deploys new hooks, skills, rules to ~/.claude/
-Step 2: /scaffold-exist                → audits vault, adds missing files
+Step 1: npx @esoteric-logic/praxis-harness@latest update   → deploys new hooks, skills, rules
+Step 2: /scaffold-exist                                      → audits vault, adds missing files
 ```
 
 New projects get everything automatically via `/scaffold-new`.
@@ -186,7 +190,7 @@ New projects get everything automatically via `/scaffold-new`.
 ## Uninstalling
 
 ```bash
-npx praxis-harness uninstall
+npx @esoteric-logic/praxis-harness@latest uninstall
 ```
 
 Removes all Praxis-owned files from `~/.claude/`. Does not delete config, vault templates, or installed plugins.

package/base/CLAUDE.md

@@ -81,7 +81,13 @@ Registered via `claude mcp add`. Persist globally across sessions.
 | context7 | Live library/API docs | None |
 | github | Repo operations, PRs, issues | `GITHUB_PERSONAL_ACCESS_TOKEN` |
 
-Optional: `perplexity` (AI web search). Run `bash scripts/onboard-mcp.sh perplexity` to add.
+**Optional servers** — enhance but don't require Praxis:
+
+| Server | Purpose | Install | Degrades without |
+|--------|---------|---------|-----------------|
+| perplexity | AI web search | `bash scripts/onboard-mcp.sh perplexity` | No web research in `/discover` |
+| filesystem | Direct vault file access | `claude mcp add filesystem` | Uses shell for vault reads |
+| sequential-thinking | Multi-step reasoning | `claude mcp add sequential-thinking` | Standard reasoning only |
 
 Check: `claude mcp list` | Manage: `bash scripts/onboard-mcp.sh [server|all]`
 Missing servers are non-blocking — features degrade gracefully.
@@ -116,6 +122,9 @@ Kits activate via `/kit:<n>` slash command. Kits are idempotent — double-activ
 |-----|----------|--------|
 | web-designer | `/kit:web-designer` | Design system → components → accessibility → production lint |
 | infrastructure | `/kit:infrastructure` | Terraform → Azure → GitHub Actions → compliance |
+| api | `/kit:api` | RESTful conventions → OpenAPI specs → contract testing |
+| security | `/kit:security` | Threat modeling → IAM review → OWASP audit |
+| data | `/kit:data` | Schema design → migration planning → query optimization |
 
 Kit manifests live in `~/.claude/kits/<name>/KIT.md`.
 

package/base/skills/context-probe/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: context-probe
+disable-model-invocation: true
+description: "Assess current context health and recommend action. Reads session data and conversation signals to estimate context bracket (FRESH/MODERATE/DEPLETED/CRITICAL)."
+---
+
+# context-probe Skill
+
+You are assessing the current session's context health.
+
+## Vault Path Resolution
+Read vault_path from `~/.claude/praxis.config.json`.
+
+---
+
+**Step 1 — Gather signals**
+
+Assess these indicators (do NOT read external files just for this — use what you already know):
+
+| Signal | How to assess |
+|--------|--------------|
+| Conversation length | Estimate from your sense of how much has been discussed |
+| Tool calls made | Rough count of reads, writes, bash calls this session |
+| Files touched | How many files have been read or edited |
+| Corrections received | How many times the user corrected your output |
+| Compaction occurred | Did you receive a compaction bootstrap? |
+| Active task complexity | Simple (1-2 files) vs complex (5+ files, multi-milestone) |
+
+**Step 2 — Estimate bracket**
+
+| Bracket | Signals | Action |
+|---------|---------|--------|
+| **FRESH** | <10 tool calls, <5 files, no corrections, no compaction | Full speed. Batch aggressively. Load full context. |
+| **MODERATE** | 10-30 tool calls, 5-15 files, 0-1 corrections | Re-read key requirements before decisions. Prefer concise output. |
+| **DEPLETED** | 30+ tool calls, 15+ files, 2+ corrections, OR scope drift detected | Checkpoint to vault NOW. Write milestone summaries. Suggest `/session-retro` + `/clear`. |
+| **CRITICAL** | Post-compaction, OR repeated corrections, OR instruction drift | STOP new work. Complete current milestone only. Write all state to vault. Start new session. |
+
+**Step 3 — Report**
+
+```
+CONTEXT PROBE
+━━━━━━━━━━━━━━━━━━━━━
+Bracket:  {FRESH | MODERATE | DEPLETED | CRITICAL}
+Signals:  {key indicators}
+Action:   {recommendation}
+━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Step 4 — Act on DEPLETED/CRITICAL**
+
+If DEPLETED or CRITICAL:
+1. Update `{vault_path}/status.md` with current state
+2. Write any in-progress decisions to the active plan file
+3. Suggest: "Context is [bracket name]. Recommend `/session-retro` then `/clear` for a fresh start."
+
+## Removal Condition
+Remove when Claude Code exposes token count or context utilization metrics natively.

package/base/skills/repair/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: repair
+disable-model-invocation: true
+description: "Structured repair phase for failed milestones. 3-attempt fix-and-verify loop with root cause analysis. Triggered by /verify failure or manually."
+---
+
+# repair Skill
+
+You are running a structured repair cycle for a failed milestone.
+
+## Vault Path Resolution
+Read vault_path from `~/.claude/praxis.config.json`.
+
+## Acceptance
+- [ ] Failure captured with exact error, file, line
+- [ ] Root cause classified (flawed implementation vs flawed spec)
+- [ ] Fix applied with minimal diff
+- [ ] Validation passes after fix
+- [ ] Repair trace written to vault
+
+## Boundaries
+- No refactoring — fix the failure, nothing else
+- No scope expansion — do not add features or change behavior beyond the fix
+- No new files unless the fix requires them
+- Maximum 3 attempts before STOP
+
+---
+
+**Step 1 — Capture failure**
+- Read the failure output from `/verify` (or ask user for the error)
+- Extract: exact error message, file(s), line number(s), test name (if applicable)
+- State the failure in one sentence:
+  `Failure: {what failed} in {file}:{line} because {symptom}.`
+
+**Step 2 — Classify root cause**
+Determine whether this is:
+- **Flawed implementation** → the code doesn't match the spec. Fix forward.
+- **Flawed spec** → the spec itself is wrong or incomplete. STOP.
+  Report to user: "Spec issue detected: [describe the issue]. Run `/discuss` to re-spec before continuing."
+  Do not attempt to fix spec issues — that's a different phase.
+
+**Step 3 — Fix attempt (attempt {n}/3)**
+- State what you're changing and why in one sentence
+- Apply the minimal fix — smallest diff that addresses the root cause
+- Do not refactor surrounding code
+- Do not fix unrelated issues discovered during repair
+
+**Step 4 — Re-validate**
+Run the full validation sequence from `/verify` Step 1:
+1. Test suite
+2. Linter
+3. Typecheck (if applicable)
+4. Build (if applicable)
+
+**Step 5 — Evaluate result**
+- **PASS** → Milestone repaired. Commit the fix. Return to workflow.
+  Output: `Repaired: {what was fixed} in {file}. Next: continue with /execute or /verify.`
+- **FAIL (same error)** → Root cause was misidentified. Re-analyze in Step 2.
+- **FAIL (different error)** → Fix introduced a regression. Revert the fix, re-analyze.
+- Track attempt count. If attempt 3 fails → Step 6.
+
+**Step 6 — STOP after 3 failures**
+Do not attempt a 4th fix. Report:
+
+```
+REPAIR FAILED — 3 attempts exhausted
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+What:    {original failure + all 3 attempt descriptions}
+So What: {root cause analysis — why 3 fixes didn't work}
+Now What: {recommended next step: re-spec, different approach, escalate}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Step 7 — Write repair trace to vault**
+Whether the repair succeeded or failed, write to `{vault_path}/notes/{YYYY-MM-DD}_repair-trace.md`:
+
+```markdown
+---
+tags: [repair, {project-slug}]
+date: {YYYY-MM-DD}
+source: agent
+---
+# Repair Trace — {short title}
+
+## Original Failure
+{error message, file, line}
+
+## Root Cause
+{classification: flawed implementation | flawed spec}
+{root cause statement}
+
+## Attempts
+### Attempt 1
+- Fix: {what was changed}
+- Result: {PASS | FAIL — error}
+
+### Attempt 2 (if applicable)
+- Fix: {what was changed}
+- Result: {PASS | FAIL — error}
+
+### Attempt 3 (if applicable)
+- Fix: {what was changed}
+- Result: {PASS | FAIL — error}
+
+## Resolution
+{Fixed in attempt N | FAILED — escalated}
+```
+
+**Step 8 — Write learning (if applicable)**
+If the repair reveals a recurring pattern, write a `[LEARN:bugfix]` entry to `{vault_path}/notes/learnings.md`.
+
+## Error Handling
+
+| Condition | Action |
+|-----------|--------|
+| No failure output provided | Ask user for error details |
+| Spec issue detected | STOP, redirect to `/discuss` |
+| Fix causes new failure | Revert fix, count as failed attempt |
+| Cannot identify root cause | Count as failed attempt, try different angle |
+
+## Callers
+
+| Caller | When |
+|--------|------|
+| `/verify` Step 4 | On FAIL — delegates to `/repair` |
+| Manual `/repair` | Any time a fix is needed |
+
+## Removal Condition
+Remove when an automated repair agent (e.g., SWE-agent) handles fix-and-verify loops with equivalent quality.

package/base/skills/review/SKILL.md

@@ -28,6 +28,7 @@ Ask: "Review staged changes, last commit, or specific SHA?"
   - Any file → `~/.claude/rules/coding.md`
 
 **Step 4 — Launch subagent review**
+Follow the subagent dispatch protocol (see `/subagent` skill for reference).
 Launch a subagent with ONLY these inputs (zero conversation history):
 - The diff
 - The SPEC (if available from Step 3)

package/base/skills/simplify/SKILL.md

@@ -35,6 +35,7 @@ Determine what to simplify:
 
 ## Phase 2 — Launch Subagent
 
+Follow the subagent dispatch protocol (see `/subagent` skill for reference).
 Launch a subagent with ONLY these inputs (zero conversation history):
 
 ```

package/base/skills/subagent/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: subagent
+disable-model-invocation: true
+description: "Reference protocol for subagent dispatch. Defines how to package context, spawn, interpret results, and escalate findings. Not invoked directly — referenced by review, simplify, verify-app, and verify skills."
+---
+
+# Subagent Dispatch Protocol
+
+This is a reference protocol, not a directly invocable skill. Skills that spawn subagents
+(review, simplify, verify-app, verify) follow this protocol for consistency.
+
+---
+
+## Step 1 — Package Context
+
+Subagents receive ONLY these inputs. Zero conversation history.
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Diff | `git diff` output scoped to the task | Yes |
+| SPEC | `## SPEC` section from the active plan file | If available |
+| Rules | Relevant `~/.claude/rules/*.md` based on file types in diff | Yes |
+| Project config | Project CLAUDE.md `## Commands` and `## Code Style` | If available |
+
+**Never include:**
+- Conversation history
+- User preferences or profile
+- Vault state or session notes
+- Full plan file (only SPEC section)
+
+## Step 2 — Define Role
+
+One sentence. The role constrains the subagent's perspective.
+
+Examples:
+- "You are a critical code reviewer."
+- "You are a code simplification expert."
+- "You are a regression analyst."
+- "You are a security auditor."
+
+## Step 3 — Define Task
+
+Specific questions or analysis to perform. Include:
+- What to look for (bugs, complexity, regressions, etc.)
+- What NOT to do (don't suggest features, don't change behavior)
+- Scope boundaries (only these files, only this diff)
+
+## Step 4 — Define Output Format
+
+All subagent findings use this structure:
+
+```
+{file}:{line} — {severity} — {category} — {description} — {fix}
+```
+
+**Severity levels** (consistent across all subagent types):
+- **Critical** — Must fix before proceeding. Blocks merge/ship.
+- **Major** — Should fix before merge. Recommend addressing.
+- **Minor** — Note for future cleanup. Does not block.
+
+**If the subagent finds nothing:** Output "No findings." (not an empty list)
+
+## Step 5 — Spawn
+
+Launch an Agent with:
+- `subagent_type`: use `general-purpose` for review/analysis tasks
+- `prompt`: role + task + inputs + output format
+- Description: short (3-5 words) summary of what the subagent does
+
+```
+Agent(
+  description: "Review diff for bugs",
+  prompt: "{role}\n\n{task}\n\n## Diff\n{diff}\n\n## SPEC\n{spec}\n\n## Rules\n{rules}\n\n{output format}"
+)
+```
+
+## Step 6 — Interpret Results
+
+Parse the subagent output:
+1. Group findings by severity (Critical → Major → Minor)
+2. Count findings per severity
+3. If output is unparseable: treat entire output as a single Minor finding
+
+## Step 7 — Escalate
+
+| Severity | Action |
+|----------|--------|
+| Critical (any) | Block. Address immediately before proceeding. |
+| Major (any) | Recommend fixing before merge. |
+| Minor only | Note for future cleanup. Proceed. |
+| No findings | "Clean." Proceed. |
+
+**Re-review threshold:** If >3 findings were addressed, re-run the subagent (max 3 rounds).
+
+---
+
+## Callers
+
+| Skill | Subagent Role | Spawned At |
+|-------|---------------|------------|
+| `/review` | Critical code reviewer | Step 4 |
+| `/simplify` | Code simplification expert | Phase 2 |
+| `/verify-app` | Regression analyst | Phase 3 |
+| `/verify` | Critical code reviewer (self-review) | Step 5 |
+| `/repair` | (uses /verify internally, which spawns subagent) | — |
+
+## Removal Condition
+Remove when Claude Code provides a native subagent dispatch API with
+structured input/output handling.

package/base/skills/verify/SKILL.md

@@ -69,12 +69,11 @@ After self-review passes, write phase summary:
 - `/simplify` runs after UNIFY, before shipping. It is the quality gate between "it works" and "it's clean".
 
 **Step 4 — On FAIL (Stop-and-Fix)**
-1. Identify the failure: exact error, file, line
-2. Fix NOW. Do not proceed to the next milestone.
-3. Re-run the full validation sequence (Step 1)
-4. If still failing after 3 attempts: STOP.
-   Report: **What** (full error + 3 attempts) → **So What** (root cause) → **Now What** (next steps)
-5. Write failure details to the active plan file if >1 attempt was needed
+Run `/repair` — it handles the structured fix-and-verify loop:
+- Captures the failure, classifies root cause, attempts up to 3 fixes
+- Re-runs validation after each attempt
+- STOPs with What/So What/Now What after 3 failures
+- Writes repair trace and learnings to vault
 
 **Rules:**
 - Never say "tests pass" without showing output.

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

@@ -76,6 +76,7 @@ For each item in the plan's `## Done When`:
 
 ## Phase 3 — Regression Check
 
+Follow the subagent dispatch protocol (see `/subagent` skill for reference).
 Launch a subagent with zero conversation history:
 
 ```

package/kits/api/KIT.md

@@ -0,0 +1,48 @@
+---
+name: api
+version: 1.0.0
+description: "API design — RESTful conventions, OpenAPI specs, contract testing, endpoint review"
+activation: /kit:api
+deactivation: /kit:off
+skills_chain:
+  - phase: spec
+    skills: []
+    status: planned
+  - phase: review
+    skills: []
+    status: planned
+  - phase: contract
+    skills: []
+    status: planned
+mcp_servers: []
+rules:
+  - api-design.md
+removal_condition: >
+  Remove when API design is fully handled by a dedicated API gateway or design tool
+  with no manual Claude-driven operations remaining.
+---
+
+# API Kit
+
+## Purpose
+Enforce API design best practices across RESTful and GraphQL endpoints.
+Covers spec generation, endpoint review, and contract test scaffolding.
+
+## Skills Chain
+
+| # | Phase | Command | What It Provides |
+|---|-------|---------|-----------------|
+| 1 | Spec | `/api:spec` | Generate or validate OpenAPI spec from code |
+| 2 | Review | `/api:review` | Endpoint naming, versioning, error codes, auth patterns |
+| 3 | Contract | `/api:contract` | Generate contract tests from OpenAPI spec |
+
+## Workflow Integration
+
+This kit operates WITHIN the Praxis workflow:
+- **Praxis** structures the work (discuss → plan → execute → verify → simplify → ship)
+- **This kit** adds API-specific rules and commands
+
+## Prerequisites
+
+Run `install.sh` in this directory to check for required CLI tools.
+Verify with `/kit:api` after install.

package/kits/api/commands/api-contract.md

@@ -0,0 +1,18 @@
+---
+description: "Generate contract tests from an OpenAPI spec or route definitions"
+---
+
+# api:contract
+
+## Steps
+
+1. **Locate spec** — read `docs/openapi.yaml` or detect routes from code
+2. **For each endpoint**, generate a contract test that verifies:
+   - Response status code matches expected
+   - Response body matches schema
+   - Required fields are present
+   - Error responses follow the standard format
+3. **Detect test framework** — Jest, pytest, Go testing, etc.
+4. **Write tests** to project test directory
+5. **Run tests** — execute and report results
+6. **Report** — tests generated, pass/fail counts

package/kits/api/commands/api-review.md

@@ -0,0 +1,19 @@
+---
+description: "Review API endpoints for naming, versioning, error handling, and auth patterns"
+---
+
+# api:review
+
+## Steps
+
+1. **Identify scope** — review all endpoints, or specific routes if user specifies
+2. **Launch subagent** (follow `/subagent` protocol) with role: "API design reviewer"
+3. **Check against api-design rules:**
+   - RESTful naming conventions
+   - HTTP status code usage
+   - Error response format consistency
+   - Authentication/authorization patterns
+   - Pagination implementation
+   - Versioning strategy
+4. **Present findings** by severity (Critical/Major/Minor)
+5. **Write review** to vault `specs/api-review-{date}.md`

package/kits/api/commands/api-spec.md

@@ -0,0 +1,19 @@
+---
+description: "Generate or validate an OpenAPI spec from the current codebase"
+---
+
+# api:spec
+
+## Steps
+
+1. **Detect API framework** — scan for route definitions (Express, FastAPI, Gin, etc.)
+2. **Extract endpoints** — list all routes with methods, paths, handlers
+3. **Generate OpenAPI 3.x spec** — for each endpoint:
+   - Path and method
+   - Request parameters (path, query, header)
+   - Request body schema (from types/models)
+   - Response schemas (success + error)
+   - Authentication requirements
+4. **Validate against api-design rules** — flag violations
+5. **Write spec** to `docs/openapi.yaml` (or project-configured location)
+6. **Report** — endpoints found, violations flagged, spec location

package/kits/api/install.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+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
+}
+
+echo "Checking optional CLI tools..."
+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 ""
+
+echo "Note: This kit uses Claude's built-in analysis capabilities."
+echo "No external API linting tools required."
+echo ""
+echo "Commands available: /api:spec, /api:review, /api:contract"
+echo ""
+echo "=== api kit check complete ==="
+echo "Activate with: /kit:api"
+echo ""

package/kits/api/rules/api-design.md

@@ -0,0 +1,63 @@
+# API Design — Rules
+# Scope: Loads when api kit is active
+# Paths: **/*.ts, **/*.js, **/*.py, **/*.go (API route files)
+
+## Invariants — BLOCK on violation
+
+### RESTful naming
+- Resources are nouns, plural: `/users`, `/orders`, not `/getUser`, `/createOrder`
+- Nested resources for relationships: `/users/{id}/orders`
+- No verbs in URLs — HTTP methods convey the action
+- Query parameters for filtering, sorting, pagination: `?status=active&sort=created_at&page=2`
+
+### HTTP status codes
+- 200: success with body. 201: created. 204: success no body.
+- 400: client error (validation). 401: not authenticated. 403: not authorized. 404: not found.
+- 409: conflict. 422: unprocessable entity.
+- 500: server error (never leak internals).
+- Never return 200 with an error body — use the appropriate 4xx/5xx code.
+
+### Error response format
+All error responses use a consistent structure:
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Human-readable description",
+    "details": [{"field": "email", "issue": "required"}]
+  }
+}
+```
+Never return raw stack traces or internal error messages.
+
+### Versioning
+- URL path versioning preferred: `/v1/users`, `/v2/users`
+- Header versioning acceptable: `Accept: application/vnd.api.v2+json`
+- Never break existing versions without a migration path
+- Deprecation: announce in response headers before removal
+
+### Authentication
+- Bearer tokens in Authorization header, not query parameters
+- API keys in headers, never in URLs (URLs are logged)
+- Short-lived tokens with refresh mechanism for user-facing APIs
+
+## Conventions — WARN on violation
+
+### Pagination
+- Cursor-based for large/real-time datasets
+- Offset-based acceptable for small, static datasets
+- Always return: `total`, `page`/`cursor`, `per_page`, `next`/`prev` links
+
+### Request/Response
+- Use camelCase for JSON fields (or snake_case — be consistent per project)
+- Dates in ISO 8601: `2024-01-15T10:30:00Z`
+- IDs as strings (UUIDs preferred over sequential integers for external APIs)
+- Envelope responses only when metadata is needed — prefer flat responses
+
+### Rate limiting
+- Return `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers
+- 429 status code with `Retry-After` header when exceeded
+
+### Documentation
+- Every endpoint must have: method, path, description, request body, response body, error codes
+- OpenAPI 3.x spec as source of truth — code generates from spec or spec generates from code

package/kits/api/teardown.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+set -euo pipefail
+
+echo "=== Praxis: Removing api kit ==="
+echo ""
+echo "This kit has no npm skills or MCP servers to remove."
+echo ""
+echo "To fully remove:"
+echo "  1. Remove /kit:api from any project CLAUDE.md '## Active kit' sections"
+echo "  2. Delete this directory: rm -rf ~/.claude/kits/api"
+echo ""
+echo "=== api kit removed ==="
+echo ""

package/kits/data/KIT.md

@@ -0,0 +1,48 @@
+---
+name: data
+version: 1.0.0
+description: "Data engineering — schema design, migration planning, query optimization"
+activation: /kit:data
+deactivation: /kit:off
+skills_chain:
+  - phase: schema
+    skills: []
+    status: planned
+  - phase: migration
+    skills: []
+    status: planned
+  - phase: query
+    skills: []
+    status: planned
+mcp_servers: []
+rules:
+  - data.md
+removal_condition: >
+  Remove when data operations are fully handled by a dedicated DBA tool
+  with no manual Claude-driven operations remaining.
+---
+
+# Data Kit
+
+## Purpose
+Enforce data engineering best practices for schema design, migrations,
+and query optimization across SQL and NoSQL databases.
+
+## Skills Chain
+
+| # | Phase | Command | What It Provides |
+|---|-------|---------|-----------------|
+| 1 | Schema | `/data:schema` | Schema design review with normalization analysis |
+| 2 | Migration | `/data:migration` | Migration planning with rollback strategy |
+| 3 | Query | `/data:query` | Query optimization and N+1 detection |
+
+## Workflow Integration
+
+This kit operates WITHIN the Praxis workflow:
+- **Praxis** structures the work (discuss → plan → execute → verify → simplify → ship)
+- **This kit** adds data-specific rules and commands
+
+## Prerequisites
+
+Run `install.sh` in this directory to check for required CLI tools.
+Verify with `/kit:data` after install.

package/kits/data/commands/migration-plan.md

@@ -0,0 +1,23 @@
+---
+description: "Plan a database migration with rollback strategy and safety checks"
+---
+
+# data:migration
+
+## Steps
+
+1. **Understand the change** — what schema changes are needed and why
+2. **Classify risk level:**
+   - **Low**: add nullable column, add index, add table
+   - **Medium**: rename column, add NOT NULL with default, modify index
+   - **High**: drop column/table, change column type, data transformation
+3. **Generate migration:**
+   - Up script (apply changes)
+   - Down script (reverse changes)
+   - Data migration script (if needed, separate from schema migration)
+4. **Safety checklist:**
+   - [ ] Down migration tested?
+   - [ ] Production data volume considered? (large table ALTERs may lock)
+   - [ ] Backward compatible? (old code works with new schema during deploy)
+   - [ ] Indexes added for new query patterns?
+5. **Write plan** to vault `specs/migration-plan-{date}.md`

package/kits/data/commands/query-review.md

@@ -0,0 +1,21 @@
+---
+description: "Review SQL queries and data access patterns for performance and correctness"
+---
+
+# data:query
+
+## Steps
+
+1. **Identify queries** — scan for SQL in code, ORM queries, or user-provided queries
+2. **Analyze each query:**
+   - Missing indexes (check WHERE, JOIN, ORDER BY columns)
+   - N+1 patterns (loop with individual queries instead of batch)
+   - Unbounded results (missing LIMIT/pagination)
+   - SELECT * usage
+   - Correlated subqueries that could be joins
+3. **Check data access patterns:**
+   - Connection pooling configuration
+   - Transaction scope (too broad or too narrow)
+   - Read replica usage for read-heavy workloads
+4. **Suggest optimizations** with before/after examples
+5. **Write review** to vault `specs/query-review-{date}.md`

package/kits/data/commands/schema-design.md

@@ -0,0 +1,22 @@
+---
+description: "Review database schema design for normalization, indexing, and best practices"
+---
+
+# data:schema
+
+## Steps
+
+1. **Identify schema files** — find migration files, model definitions, or SQL schemas
+2. **Analyze structure:**
+   - Normalization level (1NF → 3NF)
+   - Primary key strategy
+   - Foreign key relationships and ON DELETE behavior
+   - Index coverage on foreign keys and query columns
+   - Missing created_at/updated_at timestamps
+3. **Check for anti-patterns:**
+   - God tables (>20 columns)
+   - Missing indexes on foreign keys
+   - Polymorphic associations without proper constraints
+   - Over-normalization causing excessive joins
+4. **Present findings** by severity
+5. **Write review** to vault `specs/schema-review-{date}.md`

package/kits/data/install.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+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
+}
+
+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 "jq"      "brew install jq  OR  apt-get install jq"
+
+echo ""
+echo "  $PASS/$TOTAL tools found"
+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 ""
+echo "Commands available: /data:schema, /data:migration, /data:query"
+echo ""
+echo "=== data kit check complete ==="
+echo "Activate with: /kit:data"
+echo ""

package/kits/data/rules/data.md

@@ -0,0 +1,43 @@
+# Data Engineering — Rules
+# Scope: Loads when data kit is active
+# Paths: **/*.sql, **/migrations/**, **/models/**, **/schema/**
+
+## Invariants — BLOCK on violation
+
+### Migration safety
+- Every migration must be reversible — include both up and down scripts
+- Never drop columns or tables in a single migration — deprecate first, remove later
+- Add columns as nullable or with defaults — never add NOT NULL without a default to existing tables
+- Test migrations against a copy of production data before applying
+- No data transformations in schema migrations — separate data migrations
+
+### Query safety
+- No `SELECT *` in production code — specify columns explicitly
+- No unbounded queries — always include LIMIT or pagination
+- No raw SQL string interpolation — use parameterized queries
+- Validate that DELETE/UPDATE statements have WHERE clauses
+
+### Schema design
+- Primary keys on every table — prefer UUIDs for distributed systems, auto-increment for single-node
+- Foreign keys with explicit ON DELETE behavior (CASCADE, SET NULL, RESTRICT)
+- Created/updated timestamps on every table
+- Indexes on all foreign keys and frequently queried columns
+
+## Conventions — WARN on violation
+
+### Naming
+- Tables: plural, snake_case (`user_accounts`, not `UserAccount`)
+- Columns: snake_case, descriptive (`created_at`, not `ts`)
+- Indexes: `idx_{table}_{columns}` pattern
+- Constraints: `fk_{table}_{ref_table}`, `uq_{table}_{columns}`
+
+### Performance
+- Detect N+1 query patterns — suggest eager loading or joins
+- Large tables (>1M rows estimated): require index analysis before new queries
+- Avoid correlated subqueries — prefer joins or CTEs
+- Connection pooling required for production applications
+
+### Normalization
+- Aim for 3NF unless denormalization is justified by read performance
+- Document denormalization decisions as ADRs in vault `specs/`
+- JSON columns acceptable for truly flexible schemas — not for avoiding normalization

package/kits/data/teardown.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+set -euo pipefail
+
+echo "=== Praxis: Removing data kit ==="
+echo ""
+echo "This kit has no npm skills or MCP servers to remove."
+echo "Database CLI tools are system-level and not managed by this kit."
+echo ""
+echo "To fully remove:"
+echo "  1. Remove /kit:data from any project CLAUDE.md '## Active kit' sections"
+echo "  2. Delete this directory: rm -rf ~/.claude/kits/data"
+echo ""
+echo "=== data kit removed ==="
+echo ""

package/kits/security/KIT.md

@@ -0,0 +1,49 @@
+---
+name: security
+version: 1.0.0
+description: "Security review — threat modeling, IAM audit, OWASP checks, secrets management"
+activation: /kit:security
+deactivation: /kit:off
+skills_chain:
+  - phase: threat-model
+    skills: []
+    status: planned
+  - phase: iam-review
+    skills: []
+    status: planned
+  - phase: audit
+    skills: []
+    status: planned
+mcp_servers: []
+rules:
+  - security.md
+removal_condition: >
+  Remove when security review is fully handled by a dedicated SAST/DAST pipeline
+  with no manual Claude-driven operations remaining.
+---
+
+# Security Kit
+
+## Purpose
+Structured security analysis for applications and infrastructure.
+Covers threat modeling, IAM policy review, and OWASP top 10 auditing.
+
+## Skills Chain
+
+| # | Phase | Command | What It Provides |
+|---|-------|---------|-----------------|
+| 1 | Threat Model | `/security:threat-model` | STRIDE-based threat modeling for the current system |
+| 2 | IAM Review | `/security:iam-review` | Review IAM policies, roles, permissions for least privilege |
+| 3 | Audit | `/security:audit` | OWASP top 10 check against codebase |
+
+## Workflow Integration
+
+This kit operates WITHIN the Praxis workflow:
+- **Praxis** structures the work (discuss → plan → execute → verify → simplify → ship)
+- **This kit** adds security-specific rules and commands
+- Extends the base `secret-scan` hook with deeper analysis
+
+## Prerequisites
+
+Run `install.sh` in this directory to check for required CLI tools.
+Verify with `/kit:security` after install.

package/kits/security/commands/iam-review.md

@@ -0,0 +1,19 @@
+---
+description: "Review IAM policies and permissions for least-privilege compliance"
+---
+
+# security:iam-review
+
+## Steps
+
+1. **Identify IAM scope** — cloud provider (AWS/Azure/GCP), service accounts, user roles
+2. **Collect policies** — read IAM policy files, role definitions, permission sets
+3. **Check for violations:**
+   - Wildcard permissions (`*` actions or resources)
+   - Overly broad roles (admin/owner where reader/contributor suffices)
+   - Service accounts with user-level permissions
+   - Cross-account access without justification
+   - Unused roles or permissions (if access logs available)
+4. **Present findings** by severity (Critical/Major/Minor)
+5. **Recommend** least-privilege alternatives for each violation
+6. **Write review** to vault `specs/iam-review-{date}.md`

package/kits/security/commands/security-audit.md

@@ -0,0 +1,23 @@
+---
+description: "OWASP top 10 check against the current codebase"
+---
+
+# security:audit
+
+## Steps
+
+1. **Scan codebase** for OWASP Top 10 (2021) vulnerabilities:
+   - A01: Broken Access Control
+   - A02: Cryptographic Failures
+   - A03: Injection (SQL, NoSQL, OS command, LDAP)
+   - A04: Insecure Design
+   - A05: Security Misconfiguration
+   - A06: Vulnerable and Outdated Components
+   - A07: Identification and Authentication Failures
+   - A08: Software and Data Integrity Failures
+   - A09: Security Logging and Monitoring Failures
+   - A10: Server-Side Request Forgery (SSRF)
+2. **Launch subagent** (follow `/subagent` protocol) with role: "Security auditor"
+3. **Run external tools** if available (trivy, semgrep) for additional coverage
+4. **Present findings** grouped by OWASP category with severity
+5. **Write audit report** to vault `specs/security-audit-{date}.md`

package/kits/security/commands/threat-model.md

@@ -0,0 +1,20 @@
+---
+description: "STRIDE-based threat modeling for the current system"
+---
+
+# security:threat-model
+
+## Steps
+
+1. **Identify system scope** — ask user for the component or feature to model
+2. **Map data flows** — identify trust boundaries, data stores, external entities, processes
+3. **Apply STRIDE** for each component crossing a trust boundary:
+   - **S**poofing — can identity be faked?
+   - **T**ampering — can data be modified in transit/at rest?
+   - **R**epudiation — can actions be denied without audit trail?
+   - **I**nformation Disclosure — can data leak to unauthorized parties?
+   - **D**enial of Service — can the component be overwhelmed?
+   - **E**levation of Privilege — can a user gain unauthorized access?
+4. **Rate each threat**: likelihood (1-3) × impact (1-3) = risk score
+5. **Recommend mitigations** for high-risk threats
+6. **Write threat model** to vault `specs/threat-model-{date}-{component}.md`

package/kits/security/install.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+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
+}
+
+echo "Checking optional CLI tools..."
+echo ""
+
+check "trivy"     "brew install trivy  OR  https://aquasecurity.github.io/trivy"
+check "semgrep"   "pip install semgrep  OR  brew install semgrep"
+check "rg"        "brew install ripgrep  OR  apt-get install ripgrep"
+
+echo ""
+echo "  $PASS/$TOTAL tools found"
+echo ""
+
+echo "Note: This kit uses Claude's built-in analysis for most checks."
+echo "External tools enhance scanning but are not required."
+echo ""
+echo "Commands available: /security:threat-model, /security:iam-review, /security:audit"
+echo ""
+echo "=== security kit check complete ==="
+echo "Activate with: /kit:security"
+echo ""

package/kits/security/rules/security.md

@@ -0,0 +1,57 @@
+# Security — Rules
+# Scope: Loads when security kit is active
+# Extends base secret-scan with deeper analysis
+
+## Invariants — BLOCK on violation
+
+### Input validation
+- Validate ALL user input at the boundary — never trust client data
+- Use allowlists over denylists for input validation
+- Parameterize all database queries — no string interpolation in SQL
+- Sanitize HTML output — prevent XSS via output encoding
+- Validate file uploads: type, size, content (not just extension)
+
+### Authentication
+- Hash passwords with bcrypt/argon2 — never MD5/SHA1
+- Enforce minimum password complexity at the application level
+- Implement account lockout after N failed attempts
+- Session tokens must be cryptographically random, sufficient length (128+ bits)
+- Invalidate sessions on logout and password change
+
+### Authorization
+- Enforce least privilege — default deny, explicit allow
+- Check authorization on every request — never rely on client-side checks
+- Use role-based (RBAC) or attribute-based (ABAC) access control
+- Validate object-level access — prevent IDOR (Insecure Direct Object Reference)
+- Log all authorization failures
+
+### Secrets
+- No secrets in code, config files, or environment variable defaults
+- Use secret managers (Vault, AWS Secrets Manager, Azure Key Vault)
+- Rotate secrets on schedule and on compromise
+- Audit secret access logs
+
+### Transport
+- TLS 1.2+ for all external communication
+- HSTS headers on all HTTP responses
+- Certificate pinning for mobile/critical APIs
+
+## Conventions — WARN on violation
+
+### CORS
+- Restrict `Access-Control-Allow-Origin` to specific domains — never `*` in production
+- Limit allowed methods and headers to what's needed
+
+### CSP
+- Content Security Policy headers on all HTML responses
+- No `unsafe-inline` or `unsafe-eval` in production CSP
+
+### Dependencies
+- Audit dependencies for known vulnerabilities before adding
+- Pin dependency versions — no floating ranges in production
+- Review transitive dependencies for supply chain risk
+
+### Logging
+- Log security events: auth failures, privilege escalations, input validation failures
+- Never log secrets, tokens, passwords, or PII
+- Structured logging with correlation IDs for incident investigation

package/kits/security/teardown.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+set -euo pipefail
+
+echo "=== Praxis: Removing security kit ==="
+echo ""
+echo "This kit has no npm skills or MCP servers to remove."
+echo "CLI tools (trivy, semgrep) are system-level and not managed by this kit."
+echo ""
+echo "To fully remove:"
+echo "  1. Remove /kit:security from any project CLAUDE.md '## Active kit' sections"
+echo "  2. Delete this directory: rm -rf ~/.claude/kits/security"
+echo ""
+echo "=== security kit removed ==="
+echo ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esoteric-logic/praxis-harness",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Layered Claude Code harness — workflow discipline, AI-Kits, persistent vault integration",
   "bin": {
     "praxis-harness": "./bin/praxis.js"
@@ -13,7 +13,7 @@
     "scripts/"
   ],
   "scripts": {
-    "test": "node --check bin/praxis.js"
+    "test": "node --check bin/praxis.js && bash scripts/test-harness.sh"
   },
   "repository": {
     "type": "git",

package/scripts/test-harness.sh

@@ -0,0 +1,172 @@
+#!/bin/bash
+set -euo pipefail
+
+# ════════════════════════════════════════════════════════════════
+#  Praxis — Harness Test Suite
+#  Functional tests beyond what lint-harness.sh covers:
+#  shellcheck, JSON validation, cross-skill refs, hook wiring
+# ════════════════════════════════════════════════════════════════
+
+REPO_PATH="${1:-$(cd "$(dirname "$0")/.." && pwd)}"
+
+ERRORS=0
+WARNINGS=0
+PASS=0
+TOTAL=0
+
+error() {
+  echo "  ✗ ERROR: $1"
+  ERRORS=$((ERRORS + 1))
+  TOTAL=$((TOTAL + 1))
+}
+
+warn() {
+  echo "  ⚠ WARN:  $1"
+  WARNINGS=$((WARNINGS + 1))
+  TOTAL=$((TOTAL + 1))
+}
+
+ok() {
+  echo "  ✓ $1"
+  PASS=$((PASS + 1))
+  TOTAL=$((TOTAL + 1))
+}
+
+echo "Praxis Harness Tests"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  Repo: $REPO_PATH"
+
+# ── 1. ShellCheck ──────────────────────────────────────────────
+echo ""
+echo "ShellCheck:"
+
+if command -v shellcheck &>/dev/null; then
+  while IFS= read -r -d '' script; do
+    name=$(echo "$script" | sed "s|$REPO_PATH/||")
+    if shellcheck -S warning "$script" &>/dev/null; then
+      ok "$name"
+    else
+      warn "$name has shellcheck warnings"
+    fi
+  done < <(find "$REPO_PATH" -name "*.sh" -not -path "*/node_modules/*" -print0 2>/dev/null)
+else
+  warn "shellcheck not installed — skipping (brew install shellcheck)"
+fi
+
+# ── 2. JSON Validation ────────────────────────────────────────
+echo ""
+echo "JSON validation:"
+
+for json_file in \
+  "$REPO_PATH/base/hooks/settings-hooks.json" \
+  "$REPO_PATH/templates/claude-progress.json" \
+  "$REPO_PATH/package.json"; do
+  if [[ -f "$json_file" ]]; then
+    name=$(echo "$json_file" | sed "s|$REPO_PATH/||")
+    if jq . "$json_file" >/dev/null 2>&1; then
+      ok "$name"
+    else
+      error "$name is invalid JSON"
+    fi
+  fi
+done
+
+# ── 3. Hook Wiring ────────────────────────────────────────────
+echo ""
+echo "Hook wiring (settings-hooks.json → scripts exist):"
+
+HOOKS_JSON="$REPO_PATH/base/hooks/settings-hooks.json"
+if [[ -f "$HOOKS_JSON" ]]; then
+  # Extract all .sh filenames referenced in hook commands
+  hook_scripts=$(jq -r '.. | .command? // empty' "$HOOKS_JSON" 2>/dev/null | grep -oE '[a-z-]+\.sh' || true)
+  for script in $hook_scripts; do
+    if [[ -f "$REPO_PATH/base/hooks/$script" ]]; then
+      ok "hooks/$script exists"
+    else
+      error "hooks/$script referenced in settings-hooks.json but not found"
+    fi
+  done
+fi
+
+# ── 4. Cross-Skill References ─────────────────────────────────
+echo ""
+echo "Cross-skill references:"
+
+# Skills that reference other skills — verify targets exist
+declare -A SKILL_REFS
+SKILL_REFS["verify"]="repair subagent"
+SKILL_REFS["review"]="subagent"
+SKILL_REFS["simplify"]="subagent"
+SKILL_REFS["verify-app"]="subagent"
+SKILL_REFS["repair"]="verify"
+SKILL_REFS["execute"]="verify discuss"
+
+for caller in "${!SKILL_REFS[@]}"; do
+  for target in ${SKILL_REFS[$caller]}; do
+    if [[ -d "$REPO_PATH/base/skills/$target" ]]; then
+      ok "$caller → $target"
+    else
+      error "$caller references skill '$target' which does not exist"
+    fi
+  done
+done
+
+# ── 5. Template Frontmatter ───────────────────────────────────
+echo ""
+echo "Template frontmatter:"
+
+for tmpl in "$REPO_PATH"/templates/*.md; do
+  if [[ -f "$tmpl" ]]; then
+    name=$(basename "$tmpl")
+    if head -1 "$tmpl" | grep -q "^---"; then
+      ok "$name has frontmatter"
+    else
+      error "$name missing YAML frontmatter"
+    fi
+  fi
+done
+
+# ── 6. Kit Structure ──────────────────────────────────────────
+echo ""
+echo "Kit structure:"
+
+for kit_dir in "$REPO_PATH"/kits/*/; do
+  if [[ -d "$kit_dir" ]]; then
+    kit_name=$(basename "$kit_dir")
+    for required in KIT.md install.sh teardown.sh; do
+      if [[ -f "$kit_dir/$required" ]]; then
+        ok "kits/$kit_name/$required"
+      else
+        error "kits/$kit_name/$required missing"
+      fi
+    done
+  fi
+done
+
+# ── 7. Installer Syntax ───────────────────────────────────────
+echo ""
+echo "Installer:"
+
+if node --check "$REPO_PATH/bin/praxis.js" 2>/dev/null; then
+  ok "bin/praxis.js syntax valid"
+else
+  error "bin/praxis.js has syntax errors"
+fi
+
+# ── Summary ───────────────────────────────────────────────────
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  Pass:     $PASS"
+echo "  Errors:   $ERRORS"
+echo "  Warnings: $WARNINGS"
+
+if [[ $ERRORS -gt 0 ]]; then
+  echo "  FAILED"
+  exit 1
+else
+  if [[ $WARNINGS -gt 0 ]]; then
+    echo "  PASSED with warnings"
+  else
+    echo "  PASSED"
+  fi
+fi