@esoteric-logic/praxis-harness 2.1.1 → 2.3.0

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.1",
+  "version": "2.3.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",