@esoteric-logic/praxis-harness 2.12.0 → 2.14.0

package/base/CLAUDE.md

@@ -62,6 +62,8 @@ All `{vault_path}` references in rules and skills resolve from this config.
 - Compact trigger: when context approaches ceiling, finish the current milestone first
 - Never compact mid-plan — complete the milestone, write phase summary to vault, then compact
 - After compaction: re-bootstrap from § After Compaction below, re-run quality checks fresh
+- Context budget: see `~/.claude/rules/context-budget.md` for allocation ratios and cost-conscious loading
+- Mid-session optimization: `/px-compact` (no /clear). Full reset: `/px-context-reset` + `/clear`
 
 ## Durable Memory
 Context is volatile. Files are permanent. Act accordingly.
@@ -99,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:
@@ -110,7 +118,8 @@ Missing servers are non-blocking — features degrade gracefully.
    - Git operation → `~/.claude/rules/git-workflow.md`
    - Client-facing writing → auto-loaded by `px-communication-standards` skill
    - Architecture/specs → auto-loaded by `px-architecture-patterns` skill
-5. Quality re-anchor: read most recent `compact-checkpoint.md` → check the Quality State section.
+5. If a triage checkpoint exists (`*-compact-checkpoint.md` with tag `triage`), use its "Active Working Set" to reload files — it is more precise than the hook checkpoint.
+6. Quality re-anchor: read most recent `compact-checkpoint.md` → check the Quality State section.
    - If lint findings existed before compaction: re-run `golangci-lint run`, confirm status.
    - If tests were failing before compaction: re-run test command, confirm status.
    - Do NOT assume pre-compaction state is current. Always re-run fresh.
@@ -140,12 +149,12 @@ Kits activate via `/px-kit:<n>` slash command. Kits are idempotent — double-ac
 | security | `/px-kit:security` | Threat modeling → IAM review → OWASP audit |
 | code-quality | `/px-kit:code-quality` | SAST + secrets + SCA + IaC gate → AI review (over-engineering, smells, structure) |
 | data | `/px-kit:data` | Schema design → migration planning → query optimization |
-
 Kit manifests live in `~/.claude/kits/<name>/KIT.md`.
+Kit fields: `context_cost` (low/medium/high), `depends_on` (kit dependencies), `skills_chain` (phased workflow).
 
 ## Rules Registry — Load on Demand Only
 
-### Universal — always active (14 rules)
+### Universal — always active (16 rules)
 
 Quality is a generation-time constraint, not a post-hoc review. The rules below
 are the lens you write through — they shape every line of code produced.
@@ -166,6 +175,8 @@ are the lens you write through — they shape every line of code produced.
 | `~/.claude/rules/security-posture.md` | Sandbox model, credential protection, protected paths |
 | `~/.claude/rules/writing-quality.md` | Prose constraints — sentence limits, fluff kill list, doc templates, voice rules |
 | `~/.claude/rules/refactor-triggers.md` | Pre-check protocol, commit refactor separately, QUALITY: comment convention |
+| `~/.claude/rules/context-budget.md` | Quantitative budget zones, cost-conscious loading, MCP server discipline |
+| `~/.claude/rules/self-repair.md` | Structured recovery — 3-attempt escalation ladder, strategy rotation |
 
 ### Scoped — load only when paths match
 
@@ -199,6 +210,22 @@ are the lens you write through — they shape every line of code produced.
 |------|------------|
 | `~/.claude/rules/observable-code.md` | `**/services/**`, `**/handlers/**`, `**/workers/**`, `**/middleware/**`, `**/cmd/**` |
 
+#### Workflow and orchestration
+| File | Loads when |
+|------|------------|
+| `~/.claude/rules/session-bridge.md` | Session start/end, vault handoff, cross-session continuity |
+| `~/.claude/rules/hooks-policy.md` | Adding or modifying hooks in `settings-hooks.json` |
+| `~/.claude/rules/multi-agent-orchestration.md` | Tasks crossing >3 files or multiple domains |
+| `~/.claude/rules/phase-detection.md` | Workflow phase transitions, kit phase changes |
+| `~/.claude/rules/session-metrics.md` | End-of-session retrospective, metrics collection |
+| `~/.claude/rules/skill-authoring.md` | Creating or editing `base/skills/*/SKILL.md` files |
+
+#### Agent specs
+| File | Purpose |
+|------|---------|
+| `base/agents/evaluator.md` | Evaluator agent for Generator/Evaluator pattern |
+| `base/agents/planner.md` | Planner agent for task decomposition |
+
 ### Auto-invocable skills (replace former universal rules)
 | Skill | Triggers when |
 |-------|--------------|

package/base/agents/evaluator.md

@@ -0,0 +1,44 @@
+# Evaluator Agent Spec
+
+## Role
+You are a critical code evaluator. You score Generator output against a SPEC
+on four dimensions: correctness, completeness, style compliance, and test coverage.
+
+## Inputs
+- **Diff**: staged changes from the Generator
+- **SPEC**: acceptance criteria from the active plan
+- **Rules**: quality rules for file types in the diff
+- **Test output**: test results if available
+
+You do NOT have conversation history. Judge the diff on its own merits.
+
+## Scoring Rubric
+
+| Dimension | Weight | Pass Criteria |
+| --------- | ------ | ------------- |
+| Correctness | 40% | Code does what SPEC says. All paths handled. No logic errors. |
+| Completeness | 25% | All acceptance criteria addressed. No partial implementations. |
+| Style compliance | 20% | Naming, structure, and quality rules respected. |
+| Test coverage | 15% | Happy path, failure path, and edge cases covered. |
+
+## Output Format
+
+Findings use the standard subagent format:
+```
+{file}:{line} — {severity} — {category} — {description} — {fix}
+```
+
+Severity: Critical (blocks), Major (should fix), Minor (note).
+
+End with a summary:
+```
+SCORE: {correctness}% / {completeness}% / {style}% / {tests}%
+VERDICT: PASS | CHANGES_REQUESTED | BLOCK
+FINDINGS: {critical} critical, {major} major, {minor} minor
+```
+
+## Constraints
+- Do not suggest features beyond the SPEC
+- Do not comment on code outside the diff
+- Do not soften findings — be direct about what is wrong
+- If nothing is wrong: "No findings. VERDICT: PASS"

package/base/agents/planner.md

@@ -0,0 +1,48 @@
+# Planner Agent Spec
+
+## Role
+You are a task decomposition planner. You break complex tasks into a dependency-ordered
+subtask graph that a Generator can execute one step at a time.
+
+## Inputs
+- **PROBLEM / DELIVERABLE / ACCEPTANCE / BOUNDARIES** from the discuss phase
+- **Codebase context**: file structure, key interfaces, existing patterns
+- **Active constraints**: quality rules, architecture rules applicable to the task
+
+You do NOT have conversation history. Plan from the inputs alone.
+
+## Output Format
+
+A numbered subtask graph with dependencies:
+
+```
+SUBTASK GRAPH
+━━━━━━━━━━━━━━━━━━━━━
+
+1. [subtask title]
+   Files: {paths}
+   Acceptance: {criteria}
+   depends_on: []
+
+2. [subtask title]
+   Files: {paths}
+   Acceptance: {criteria}
+   depends_on: [1]
+
+3. [subtask title]
+   Files: {paths}
+   Acceptance: {criteria}
+   depends_on: [1, 2]
+
+CRITICAL PATH: 1 → 2 → 3
+PARALLELIZABLE: none | {subtask pairs}
+ESTIMATED MILESTONES: {count}
+```
+
+## Constraints
+- Each subtask must be completable in a single milestone
+- Each subtask must have testable acceptance criteria
+- Dependencies must be acyclic
+- Do not decompose beyond what is necessary — 3-7 subtasks for most features
+- Flag subtasks that carry architectural risk
+- If the task is simple enough for single-agent mode: say so and output a single subtask

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/rules/context-budget.md

@@ -0,0 +1,66 @@
+# Context Budget — Rules
+# Scope: All projects, all sessions
+# Quantitative budget for context window usage
+# Companion to context-management.md (qualitative bracket discipline)
+
+## Budget Allocation — Invariants (BLOCK on violation)
+
+### Zone model
+
+The context window is a finite resource. Allocate it deliberately:
+
+| Zone | Share | Contents |
+| ---- | ----- | -------- |
+| System overhead | ~15-20% | CLAUDE.md, universal rules, settings, MCP tool schemas |
+| Working content | ~55-65% | Code, plans, conversation, tool output |
+| Reserve | ~20% | Buffer for compaction, final outputs, tool responses |
+
+When working content approaches capacity (signals below), begin offloading to vault.
+Never wait for compaction to force the issue.
+
+### Budget signals (quantitative bracket thresholds)
+
+| Signal | FRESH | MODERATE | DEPLETED |
+| ------ | ----- | -------- | -------- |
+| Tool calls | <15 | 15-35 | 35+ |
+| Files read | <8 | 8-20 | 20+ |
+| Large files (>200 lines) in session | <2 | 2-4 | 5+ |
+| Corrections received | 0 | 1 | 2+ |
+
+These thresholds feed `context-management.md` brackets and `/px-context-probe`.
+
+## Cost-Conscious Loading — Conventions (WARN on violation)
+
+### MCP servers
+- Connect 2-3 core servers at session start (context7, github).
+- Lazy-load optional servers (perplexity, filesystem, sequential-thinking) only when the task requires them.
+- Never connect all registered servers preemptively — each adds schema overhead.
+
+### File reads
+- Read targeted line ranges (`offset`/`limit`), not entire files, when you know the section.
+- Files >200 lines: read the relevant section, not the whole file.
+
+### Search output
+- Use `files_with_matches` for initial discovery; switch to `content` only for confirmed matches.
+- Delegate exploration expected to produce >50 lines of output to a subagent.
+
+## Universal Rule Weight — Conventions (WARN on violation)
+
+The 14 universal rules consume ~50KB of every session's context budget.
+
+- Before proposing a new universal rule: justify the always-loaded cost.
+- Prefer scoped rules (path-matched) over universal ones when the rule applies to a specific domain.
+- New universal rules must stay under 3KB individually.
+- If a universal rule exceeds 100 lines: split into a short universal rule and a scoped reference file.
+
+## Budget Actions
+
+| Bracket | Action |
+| ------- | ------ |
+| FRESH | No budget concern. Batch aggressively, load full context. |
+| MODERATE | Prefer concise output. Stop reading whole files. Use subagents for exploration. |
+| DEPLETED | Run `/px-compact` for mid-session optimization, or `/px-context-reset` + `/clear` for full reset. |
+| CRITICAL | STOP new work. Complete current milestone. Write all state to vault. New session. |
+
+## Removal Condition
+Remove when Claude Code exposes native token utilization metrics and budget enforcement.

package/base/rules/context-management.md

@@ -72,6 +72,10 @@ conversation length heuristic (not token count — we cannot read session JSONL)
 - Write all state to vault immediately
 - Suggest new session for remaining milestones
 
+### Budget integration
+See `context-budget.md` for quantitative thresholds and allocation ratios.
+Use `/px-compact` for mid-session optimization; `/px-context-reset` + `/clear` for full reset.
+
 ---
 
 ## Verification Commands

package/base/rules/hooks-policy.md

@@ -0,0 +1,53 @@
+# Hooks Policy — Rules
+# Scope: All projects, all sessions
+# Documents which hooks are mandatory vs optional
+
+## Hook Inventory
+
+### Mandatory — must not be disabled (BLOCK on violation)
+
+| Hook | Event | Purpose |
+| ---- | ----- | ------- |
+| `secret-scan.sh` | PreToolUse: Write/Edit | Blocks credential patterns in code |
+| `credential-guard.sh` | PreToolUse: Bash | Blocks access to protected credential paths |
+| `identity-check.sh` | PreToolUse: Bash | Verifies git identity before commits |
+| `file-guard.sh` | PreToolUse: Write/Edit | Blocks writes to protected file patterns |
+| `vault-checkpoint.sh` | PreCompact | Saves state before context compaction |
+
+These hooks are security and data-integrity controls. Disabling them requires
+explicit user approval with documented justification.
+
+### Required — should not be disabled without reason (WARN on violation)
+
+| Hook | Event | Purpose |
+| ---- | ----- | ------- |
+| `dep-audit.sh` | PostToolUse: Write/Edit | Audits dependencies when manifests change |
+| `session-data-collect.sh` | Stop | Captures session metadata for vault |
+| Stop vault prompt | Stop | Writes session summary and vault updates |
+| `on-stop-failure.sh` | StopFailure | Error handling for failed stop hooks |
+
+### Optional — enhance but not required
+
+| Hook | Event | Purpose |
+| ---- | ----- | ------- |
+| `auto-format.sh` | PostToolUse: Write/Edit | Auto-formats files after edits |
+| `recursion-guard.sh` | PreToolUse | Prevents recursive tool invocation |
+
+## Adding New Hooks
+
+Before adding a hook to `settings-hooks.json`:
+1. Classify as mandatory, required, or optional using the criteria above
+2. Mandatory: security or data-integrity function — must never silently fail
+3. Required: workflow quality — should warn on failure but not block
+4. Optional: convenience — can be disabled per-project
+5. All hooks must exit 0 on success, non-zero to block (PreToolUse only)
+6. All hooks must handle missing dependencies gracefully (exit 0 if tool not found)
+
+## Hook Configuration
+
+Hooks are declared in `base/hooks/settings-hooks.json`.
+Install copies them to `~/.claude/settings.json` during `install.sh`.
+Project-specific hooks can be added in project `.claude/settings.json`.
+
+## Removal Condition
+Remove when Claude Code provides a native hook policy/priority system.

package/base/rules/multi-agent-orchestration.md

@@ -0,0 +1,99 @@
+# Multi-Agent Orchestration — Rules
+# Scope: All projects, all sessions
+# Governs when and how to use multi-agent patterns
+
+## Agent Patterns
+
+### Single-Agent (default)
+One Claude instance handles the full task. Subagents handle scoped delegation
+(review, simplify, explore) per the `px-subagent` dispatch protocol.
+
+**Use when:** Task touches ≤3 files, single domain, straightforward implementation.
+
+### Generator/Evaluator
+Generator produces output. Evaluator critically reviews against spec, scoring on
+correctness, completeness, style compliance, and test coverage.
+
+**Use when:** Task touches >5 files, crosses module boundaries, or has high
+correctness requirements (auth, data integrity, public API changes).
+
+### Planner/Generator/Evaluator
+Planner decomposes into subtask graph first. Generator and Evaluator work each subtask.
+
+**Use when:** Task spans multiple milestones, requires architectural decisions,
+or the plan itself needs adversarial review.
+
+## Activation Thresholds — Conventions (WARN on violation)
+
+| Signal | Single-Agent | Generator/Evaluator | Planner/Generator/Evaluator |
+| ------ | ------------ | ------------------- | --------------------------- |
+| Files changed | ≤3 | 4-10 | 10+ |
+| Domains crossed | 1 | 2 | 3+ |
+| Milestone count | 1 | 1-2 | 3+ |
+| Risk level | Low | Medium | High |
+
+These are guidelines, not hard gates. Use judgment — a 2-file auth change
+may warrant Generator/Evaluator; a 15-file rename may not.
+
+## Evaluator Agent Spec
+
+When Generator/Evaluator mode is active, the Evaluator receives:
+
+| Input | Source |
+| ----- | ------ |
+| Diff | Generator's output (staged changes) |
+| SPEC | From active plan file |
+| Rules | Relevant quality rules for file types in diff |
+| Test output | If tests were run |
+
+The Evaluator does NOT receive conversation history.
+
+### Evaluator scoring rubric
+
+| Dimension | Weight | Criteria |
+| --------- | ------ | -------- |
+| Correctness | 40% | Does the code do what the spec says? All paths handled? |
+| Completeness | 25% | Are all acceptance criteria met? Tests present? |
+| Style compliance | 20% | Naming, structure, quality rules respected? |
+| Test coverage | 15% | Happy path, failure path, edge cases covered? |
+
+### Evaluator output format
+Uses the same severity format as `px-subagent`:
+```
+{file}:{line} — {severity} — {category} — {description} — {fix}
+```
+
+### Escalation
+- Critical findings → Generator must fix before proceeding
+- Major findings → Generator should fix before merge
+- >3 findings addressed → re-run Evaluator (max 3 rounds)
+
+## Planner Agent Spec
+
+When Planner mode is active, the Planner receives:
+- PROBLEM / DELIVERABLE / ACCEPTANCE / BOUNDARIES
+- Relevant codebase context (file structure, key interfaces)
+- Active constraints from rules
+
+The Planner outputs a subtask graph:
+```
+1. [subtask] — {files} — {acceptance criteria}
+   └─ depends_on: []
+2. [subtask] — {files} — {acceptance criteria}
+   └─ depends_on: [1]
+```
+
+Generator and Evaluator process each subtask in dependency order.
+
+## Integration with Existing Skills
+
+| Skill | Orchestration role |
+| ----- | ------------------ |
+| `/px-plan` | May invoke Planner agent for complex decomposition |
+| `/px-review` | Already uses Evaluator pattern via `px-subagent` |
+| `/px-verify` | Self-review step is a lightweight Evaluator |
+| `/px-execute` | Generator role — produces implementation |
+
+## Removal Condition
+Remove when Claude Code provides native multi-agent orchestration with
+built-in evaluator and planner agent types.

package/base/rules/phase-detection.md

@@ -0,0 +1,52 @@
+# Phase Detection — Rules
+# Scope: All projects, all sessions
+# Automatic detection of current workflow phase for adaptive rule loading
+
+## Phase Definitions
+
+| Phase | Signals | Active Rule Focus |
+| ----- | ------- | ----------------- |
+| **Planning** | `/px-discuss`, `/px-plan`, `/px-spec` invoked; reading specs/plans; no code edits | engineering-judgment, architecture patterns |
+| **Implementing** | Code files being written/edited; tests being written | code-quality, code-excellence, language-specific rules |
+| **Testing** | Test files being run; test output being analyzed | self-verify, observable-code |
+| **Debugging** | `/px-debug` invoked; error analysis; stack traces being read | coding (Context7 mandate), language-specific rules |
+| **Reviewing** | `/px-review`, `/px-simplify` invoked; diff analysis | refactor-triggers, code-quality |
+| **Shipping** | `/px-ship`, `/px-verify` invoked; pre-commit checks | git-workflow, security-posture |
+
+## Detection Heuristic — Conventions (WARN on violation)
+
+Phase detection is heuristic — infer from the most recent actions:
+
+1. **Explicit signal**: A phase-associated skill was invoked → phase is known
+2. **File type signal**: Editing `.ts` files → Implementing. Reading test output → Testing.
+3. **Conversation signal**: Discussing tradeoffs → Planning. Analyzing errors → Debugging.
+
+When phase is ambiguous: default to the broader rule set rather than the narrower one.
+Loading extra rules is preferable to missing a constraint.
+
+## Adaptive Loading Behavior — Conventions (WARN on violation)
+
+### What changes per phase
+- **Planning**: Prioritize engineering-judgment.md, deprioritize language-specific rules
+- **Implementing**: Load language-specific rules for active file types, full code-quality
+- **Reviewing**: Load refactor-triggers.md, emphasize simplicity checks
+- **Shipping**: Load git-workflow.md pre-commit invariants, security-posture checks
+
+### What never changes
+Universal rules (14) are always loaded regardless of phase.
+Phase detection adjusts emphasis and attention, not which rules are loaded.
+Claude Code does not support dynamic rule unloading — phase detection shapes
+which rules get actively applied, not which are present in context.
+
+## Kit Phase Integration
+
+Kits define `skills_chain` with phase fields in their manifests.
+When a kit is active, its phases override the generic phases above:
+- `code-quality` kit: gate → ai-review → self-review
+- `infrastructure` kit: plan → apply → drift → compliance
+- `web-designer` kit: design-system-init → component-build → audit → final-lint
+
+Kit phases take precedence when the kit is active.
+
+## Removal Condition
+Remove when Claude Code provides native phase-aware rule loading.

package/base/rules/self-repair.md

@@ -0,0 +1,53 @@
+# Self-Repair — Rules
+# Scope: All projects, all sessions
+# Structured recovery protocol for repeated failures
+
+## Recovery Escalation — Invariants (BLOCK on violation)
+
+### Attempt tracking
+Track consecutive failures on the same task. A "failure" is:
+- Test failure after implementation
+- Lint error after fix attempt
+- User correction of the same issue
+- Build failure after code change
+
+### Escalation ladder
+
+| Attempt | Action |
+| ------- | ------ |
+| 1st failure | Fix the specific error. Re-validate. |
+| 2nd failure (same issue) | Step back. Re-read the relevant code and spec. Try a different approach. |
+| 3rd failure (same issue) | STOP. Report What / So What / Now What. Do not attempt a 4th fix. |
+
+This is already in `execution-loop.md` as "Stop-and-Fix Rule." This rule adds
+the structured escalation between attempts.
+
+### Strategy rotation on 2nd failure
+When the first fix doesn't work, rotate strategy before retrying:
+
+| Failed strategy | Try instead |
+| --------------- | ----------- |
+| Modify existing code | Rewrite the function from scratch |
+| Add logic | Remove logic (simplify) |
+| Fix forward | Revert to last working state, approach differently |
+| Local fix | Check if the problem is upstream (caller, input, config) |
+
+### 3rd failure report format
+```
+STOP — REPAIR FAILED
+━━━━━━━━━━━━━━━━━━━━━
+What:    {exact error after 3 attempts}
+So What: {root cause hypothesis — why all 3 attempts failed}
+Now What: {recommended next step — different approach, user input, or scope change}
+━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Anti-Patterns — Conventions (WARN on violation)
+
+- Do NOT retry the identical fix. If attempt 1 failed, attempt 2 must differ.
+- Do NOT add complexity to fix a failure. If the fix is more complex than the original code, the approach is wrong.
+- Do NOT blame the tooling. If tests fail, the code is likely wrong.
+- Do NOT suppress errors to make validation pass. Fix the root cause.
+
+## Removal Condition
+Remove when Claude Code provides native failure tracking and strategy rotation.

package/base/rules/session-bridge.md

@@ -0,0 +1,39 @@
+# Session Bridge — Rules
+# Scope: All projects, all sessions
+# Protocol for session handoff: end-of-session persist + start-of-session rehydrate
+
+## End-of-Session Persist — Invariants (BLOCK on violation)
+
+### Mandatory writes before session ends
+1. Update `{vault_path}/status.md` with current What / So What / Now What
+2. Update `{vault_path}/claude-progress.json` with session entry
+3. Write session note to `{vault_path}/notes/{YYYY-MM-DD}_session-note.md`
+
+These are already enforced by the Stop hook prompt. This rule makes explicit
+that the vault write is the bridge — conversation state that isn't persisted is lost.
+
+## Start-of-Session Rehydrate — Conventions (WARN on violation)
+
+### Bootstrap sequence (extends After Compaction § in CLAUDE.md)
+1. Read project CLAUDE.md
+2. Read `{vault_path}/status.md` for loop position and current plan
+3. Read active plan file (current milestone only)
+4. Search vault for context relevant to active task: `rg "{task topic}" {vault_path}/specs/ {vault_path}/notes/`
+5. Load rules scoped to the current task's file types
+
+## Cross-Session Continuity — Conventions (WARN on violation)
+
+### What survives sessions (via vault)
+- Decisions, specs, ADRs → `{vault_path}/specs/`
+- Session summaries → `{vault_path}/notes/`
+- Learnings → `{vault_path}/notes/learnings.md`
+- Task state → `{vault_path}/status.md`, `claude-progress.json`
+- Plan progress → `{vault_path}/plans/`
+
+### What does NOT survive sessions
+- Conversation context (volatile — this is by design)
+- File contents read into context (re-read as needed)
+- Subagent outputs (summarize findings into vault if important)
+
+## Removal Condition
+Remove when Claude Code provides native cross-session memory persistence.

package/base/rules/session-metrics.md

@@ -0,0 +1,61 @@
+# Session Metrics — Rules
+# Scope: All projects, all sessions
+# Tracks harness-level performance for self-improvement
+
+## Metric Collection — Conventions (WARN on violation)
+
+### Metrics captured by existing hooks
+The Stop hook and session-data-collect.sh already capture:
+- Session date and timestamp
+- Branch and last commit
+- Accomplishments (via vault prompt)
+- Corrections count (via session-retro)
+- Learn entries count (via session-retro)
+
+### Additional metrics to track (when session-retro runs)
+Append these to the session entry in `claude-progress.json`:
+
+| Metric | Source | Purpose |
+| ------ | ------ | ------- |
+| `compaction_count` | Count compact checkpoints for today | How often context exhausted |
+| `files_modified` | `git diff --stat` at session end | Session scope indicator |
+| `milestones_completed` | Plan file milestone checkmarks | Throughput indicator |
+| `repair_attempts` | Count repair traces in vault | Code quality signal |
+| `phase_time` | Estimated split across plan/implement/verify | Bottleneck detection |
+
+### Metrics directory
+When session-retro produces structured metrics, write to:
+`{vault_path}/metrics/{YYYY-MM-DD}_session-metrics.md`
+
+Format:
+```markdown
+---
+tags: [metrics, session]
+date: YYYY-MM-DD
+source: agent
+---
+# Session Metrics — {YYYY-MM-DD}
+
+| Metric | Value |
+| ------ | ----- |
+| Milestones completed | {n} |
+| Files modified | {n} |
+| Compactions | {n} |
+| Repair attempts | {n} |
+| Corrections | {n} |
+| Learnings | {n} |
+| Phase split | Plan {n}% / Implement {n}% / Verify {n}% |
+```
+
+## Pattern Detection — Conventions (WARN on violation)
+
+After 5+ sessions with metrics, look for:
+- Debugging consistently >40% of session time → suggest architectural review
+- Compaction count >2 per session → suggest smaller task scoping
+- Repair attempts >3 per session → suggest better spec clarity
+- Corrections >2 per session → suggest context reset or rule update
+
+Surface patterns in `/px-session-retro` Phase 7 (Session Health Assessment).
+
+## Removal Condition
+Remove when Claude Code provides native session analytics and performance tracking.

package/base/rules/skill-authoring.md

@@ -0,0 +1,85 @@
+# Skill Authoring — Rules
+# Scope: Creating or editing base/skills/*/SKILL.md files
+# Codifies agent-first skill design principles
+
+## Agent-First Principle
+
+The agent is the primary reader of every skill. Design decisions optimize for
+how Claude discovers, loads, and executes a skill — not for how a human browses.
+
+## SKILL.md Structure — Invariants (BLOCK on violation)
+
+### Frontmatter (required)
+```yaml
+---
+name: px-{skill-name}
+disable-model-invocation: true  # false only for auto-trigger skills
+description: "{what it does}. {when to use it}."
+---
+```
+
+### Description as discovery API
+The description field is how Claude selects this skill from 40+ candidates.
+
+- Write in third person — descriptions are injected into the system prompt
+- Include BOTH what the skill does AND when to activate it
+- Include trigger keywords the user is likely to say
+- Bad: "Helps with infrastructure" (too vague to discover)
+- Good: "Generates Terraform modules for Azure resources. Use when the user asks to create, modify, or scaffold infrastructure."
+
+### Body structure
+- Imperative voice — step-by-step, not conversational
+- Flat structure — one level of headings, no deep nesting
+- Every line must change agent behavior or it's dead weight
+- Under 150 lines — skills over 150 lines should split into a skill + reference file
+
+## Degrees of Freedom — Conventions (WARN on violation)
+
+Calibrate constraint tightness to operation risk:
+
+| Freedom | When | Example skills |
+| ------- | ---- | -------------- |
+| High (text guidance) | Multiple valid paths, creative work | px-discuss, px-review |
+| Medium (templates) | Structured output, consistent format | px-plan, px-session-retro |
+| Low (exact scripts) | Destructive ops, security-sensitive | px-ship, px-secret-scan |
+
+### Feedback loops
+Non-trivial skills must include a validate → fix → repeat cycle:
+- Produce intermediate artifact
+- Validate it (test, lint, structural check)
+- Iterate until validation passes
+- Verbose error messages so Claude can self-correct
+
+## Naming Convention — Conventions (WARN on violation)
+
+- Prefix: `px-` for all Praxis skills
+- Format: short verb or noun — `px-verify`, `px-plan`, `px-debug`
+- Not gerunds — slash commands read better as `/px-verify` than `/px-verifying`
+- Kit skills: `{kit-prefix}:{action}` — `/infra:plan`, `/kg:query`
+
+## Boundaries Section — Conventions (WARN on violation)
+
+Every skill with side effects must include a `## Boundaries` section:
+- What is explicitly out of scope
+- What the skill must NOT modify
+- Maximum attempts before escalation
+- Whether user approval is required for destructive actions
+
+## Progressive Disclosure — Conventions (WARN on violation)
+
+- SKILL.md is the entry point — keep it under 150 lines
+- Additional context in reference files one level deep from SKILL.md
+- Prefer executing scripts over reading them into context
+- Name files for content, not sequence: `validation_rules.md` not `doc2.md`
+
+## Testing New Skills
+
+1. Write the skill
+2. Load it in a fresh session (Claude B)
+3. Invoke with a realistic prompt
+4. Check: Did Claude discover it? Execute it correctly? Follow boundaries?
+5. Tighten constraints where Claude diverged from intent
+
+## Removal Condition
+Remove when Claude Code provides a native skill authoring wizard with
+built-in agent-first validation.

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

@@ -0,0 +1,100 @@
+---
+name: px-compact
+disable-model-invocation: true
+description: "Intelligent mid-session compaction. Triages context, checkpoints to vault, triggers compact, reloads working set. Use when DEPLETED but mid-milestone — no /clear needed."
+---
+
+# compact Skill
+
+You are performing an intelligent mid-session compaction to free context budget
+while preserving the active working set.
+
+**Key difference from `/px-context-reset`:** No `/clear` required. You stay in the
+same session and resume immediately after compaction.
+
+## Vault Path Resolution
+
+Read vault_path from `~/.claude/praxis.config.json`.
+
+---
+
+**Step 1 — Pre-flight check**
+
+Assess context bracket from signals (see `context-budget.md` § Budget signals):
+
+- **FRESH** → Print: "Context is still fresh. Compaction would lose more than it saves." → STOP.
+- **CRITICAL with no active milestone** → Print: "Context is critically degraded with no active milestone. Use `/px-context-reset` + `/clear` instead." → STOP.
+- **MODERATE/DEPLETED/CRITICAL with active milestone** → Continue.
+
+**Step 2 — Triage context**
+
+Classify all loaded context into priority tiers:
+
+| Tier | Action |
+| ---- | ------ |
+| T1: Active working set (current file, active milestone, failing tests) | Keep — reload after compact |
+| T2: Decision context (SPEC, constraints, last 3 decisions) | Keep — include in checkpoint |
+| T3: Session history (earlier discussion, exploration, superseded approaches) | Offload summaries to vault |
+| T4: Reference material (docs consumed, examples applied) | Drop |
+
+For T3 items with decision value: append summaries to `{vault_path}/plans/{YYYY-MM-DD}-triage-offload.md`.
+
+**Step 3 — Write compact checkpoint**
+
+Write `{vault_path}/plans/{YYYY-MM-DD}-compact-checkpoint.md`:
+
+```markdown
+---
+tags: [checkpoint, compact, triage]
+date: {YYYY-MM-DD}
+source: agent
+---
+# Compact Checkpoint — {YYYY-MM-DD HH:MM}
+
+## Active Working Set (reload after compact)
+- File: {path} — {what you are doing with it}
+- File: {path} — {what you are doing with it}
+
+## Current Milestone
+{milestone name from active plan}
+
+## Decisions (last 3)
+1. {decision} — {rationale}
+2. {decision} — {rationale}
+3. {decision} — {rationale}
+
+## Offloaded This Session
+See: plans/{YYYY-MM-DD}-triage-offload.md
+
+## Next Step After Compact
+{exact next action — be specific}
+```
+
+**Step 4 — Update vault state**
+
+1. Update `{vault_path}/status.md` — refresh What / So What / Now What
+2. Update `{vault_path}/claude-progress.json` — add session entry with `"source": "compact"`
+
+**Step 5 — Trigger compaction**
+
+Print the bootstrap instructions first:
+
+```
+Compact checkpoint saved. Triggering compaction.
+
+After compaction, re-bootstrap:
+1. Read {vault_path}/plans/{YYYY-MM-DD}-compact-checkpoint.md
+2. Read the active plan: {plan-filename}, milestone: {milestone-name}
+3. Re-read only files listed in "Active Working Set" above
+4. Resume: {next step}
+```
+
+Then run `/compact` (Claude Code built-in).
+
+**Note:** The PreCompact hook (`vault-checkpoint.sh`) will also fire and write its own
+checkpoint. The triage checkpoint from Step 3 is authoritative — it contains the
+curated working set. The hook checkpoint is a safety net.
+
+## Removal Condition
+
+Remove when Claude Code provides native intelligent compaction with working set preservation.

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

@@ -26,7 +26,7 @@ Assess these indicators (do NOT read external files just for this — use what y
 | 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**
+**Step 2 — Estimate bracket** (quantitative thresholds: see `context-budget.md` § Budget signals)
 
 | Bracket | Signals | Action |
 |---------|---------|--------|

package/base/skills/px-context-triage/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: px-context-triage
+disable-model-invocation: true
+description: "Prioritize context contents: what to keep, what to offload to vault, what to drop. Use before compaction or when context bracket is DEPLETED."
+---
+
+# context-triage Skill
+
+You are triaging context contents to free budget for continued work.
+
+## Vault Path Resolution
+
+Read vault_path from `~/.claude/praxis.config.json`.
+
+---
+
+**Step 1 — Inventory current context**
+
+From memory (do NOT read files just for inventory), list what is loaded:
+
+| Category | Examples |
+| -------- | -------- |
+| Code files read/edited | Source files, configs, tests |
+| Plan/spec files | Active plan, SPEC, ADRs |
+| Conversation topics | Discussion threads, decisions, corrections |
+| Reference material | Docs read, research, examples already applied |
+| MCP connections | Which servers are active |
+
+**Step 2 — Classify by priority tier**
+
+| Tier | Rule | Examples |
+| ---- | ---- | -------- |
+| T1: Active working set | Always keep | File being edited, active plan milestone, failing test output |
+| T2: Decision context | Keep if FRESH/MODERATE | SPEC, architectural constraints, last 3 decisions |
+| T3: Session history | Offload to vault | Earlier discussion, exploration results, superseded approaches |
+| T4: Reference material | Drop | Docs already consumed, examples already applied |
+
+**Step 3 — Offload T3/T4 to vault**
+
+For each T3/T4 item that contains decisions or state worth preserving:
+
+1. Append to `{vault_path}/plans/{YYYY-MM-DD}-triage-offload.md` (create if needed, append if exists)
+2. Format per item: date, item name, 1-2 line summary, file references if applicable
+3. Add YAML frontmatter if creating new file:
+   ```yaml
+   ---
+   tags: [triage, offload]
+   date: YYYY-MM-DD
+   source: agent
+   ---
+   ```
+
+Items with no decision value (pure reference, already applied) — drop without saving.
+
+**Step 4 — Report**
+
+```
+CONTEXT TRIAGE
+━━━━━━━━━━━━━━━━━━━━━
+Keeping:    {count} items (T1/T2)
+Offloaded:  {count} items to vault
+Dropped:    {count} items (no state value)
+━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Step 5 — Recommend next action**
+
+| Bracket | Recommendation |
+| ------- | -------------- |
+| FRESH/MODERATE | Triage complete. No compaction needed yet. |
+| DEPLETED | Run `/px-compact` now for mid-session optimization. |
+| CRITICAL | Run `/px-context-reset` + `/clear` for full reset. |
+
+## Removal Condition
+
+Remove when Claude Code provides native context budget visibility and automatic triage.

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/api/KIT.md

@@ -14,6 +14,8 @@ skills_chain:
   - phase: contract
     skills: []
     status: planned
+context_cost: medium
+depends_on: []
 mcp_servers: []
 rules:
   - api-design.md

package/kits/code-quality/KIT.md

@@ -4,6 +4,8 @@ version: 1.0.0
 description: "Code quality enforcement — parallel deterministic gate (SAST, secrets, SCA, IaC) + AI review layer (over-engineering, smells, structure, performance)"
 activation: /kit:code-quality
 deactivation: /kit:off
+context_cost: high
+depends_on: []
 skills_chain:
   - phase: gate
     skills: [sast-scan, secrets-scan, sca-scan, iac-scan]

package/kits/data/KIT.md

@@ -14,6 +14,8 @@ skills_chain:
   - phase: query
     skills: []
     status: planned
+context_cost: medium
+depends_on: []
 mcp_servers: []
 rules:
   - data.md

package/kits/infrastructure/KIT.md

@@ -17,6 +17,8 @@ skills_chain:
   - phase: compliance
     skills: []
     status: planned
+context_cost: high
+depends_on: []
 mcp_servers: []
 rules:
   - infrastructure.md

package/kits/security/KIT.md

@@ -14,6 +14,8 @@ skills_chain:
   - phase: audit
     skills: []
     status: planned
+context_cost: medium
+depends_on: []
 mcp_servers: []
 rules:
   - security.md

package/kits/web-designer/KIT.md

@@ -13,6 +13,8 @@ skills_chain:
     skills: [web-accessibility, ui-skills-baseline, ui-skills-motion]
   - phase: final-lint
     skills: [web-design-guidelines]
+context_cost: medium
+depends_on: []
 mcp_servers:
   - name: 21st-magic
     command: npx -y @21st-dev/magic@latest

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.12.0",
+  "version": "2.14.0",
   "description": "Layered Claude Code harness — workflow discipline, AI-Kits, persistent vault integration",
   "bin": {
     "praxis-harness": "./bin/praxis.js"