@esoteric-logic/praxis-harness 2.11.0 → 2.12.0

package/base/CLAUDE.md

@@ -125,6 +125,9 @@ Missing servers are non-blocking — features degrade gracefully.
 - Commit with wrong git identity
 - Write a file with unreplaced {placeholders}
 - Use vault search when Obsidian is not running (obsidian backend requires Obsidian open)
+- Mix refactoring and feature changes in one commit — commit refactor separately
+- Copy-paste 3+ lines instead of extracting a shared function
+- Use `console.log`/`fmt.Println`/`print()` for production logging — use the structured logger
 
 ## AI-Kit Registry
 Kits activate via `/px-kit:<n>` slash command. Kits are idempotent — double-activate is a no-op.
@@ -142,7 +145,7 @@ Kit manifests live in `~/.claude/kits/<name>/KIT.md`.
 
 ## Rules Registry — Load on Demand Only
 
-### Universal — always active (12 rules)
+### Universal — always active (14 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.
@@ -161,6 +164,8 @@ are the lens you write through — they shape every line of code produced.
 | `~/.claude/rules/context-management.md` | Context anti-rot, phase scoping, context reset protocol |
 | `~/.claude/rules/memory-boundary.md` | Auto-memory boundary, MEMORY.md cap, dream integration |
 | `~/.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 |
 
 ### Scoped — load only when paths match
 
@@ -188,11 +193,19 @@ are the lens you write through — they shape every line of code produced.
 | `~/.claude/rules/live-docs-required.md` | Dependency manifests, files importing external packages |
 | `~/.claude/rules/desktop-protocol.md` | Claude Desktop ↔ Claude Code handoff sessions |
 
+#### Application observability
+
+| File | Loads when |
+|------|------------|
+| `~/.claude/rules/observable-code.md` | `**/services/**`, `**/handlers/**`, `**/workers/**`, `**/middleware/**`, `**/cmd/**` |
+
 ### Auto-invocable skills (replace former universal rules)
 | Skill | Triggers when |
 |-------|--------------|
 | `px-communication-standards` | Writing client-facing docs, proposals, status reports, commits, PRs |
 | `px-architecture-patterns` | Writing ADRs, specs, system design, risk docs, blocker reports |
+| `px-quality-gate` | Auto inside /px-verify (Step 1 item 5b) and before /px-ship — blocks on BLOCK findings |
+| `px-doc-lint` | Fast structural markdown check inside px-quality-gate for staged *.md files |
 
 ## Judgment & Research Commands
 

package/base/hooks/auto-format.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # PostToolUse hook — auto-formats files after edit.
 # Always exits 0 (advisory, never blocks).
-set -uo pipefail
+set -euo pipefail
 trap 'exit 0' ERR
 
 INPUT=$(cat)

package/base/hooks/dep-audit.sh

@@ -2,7 +2,7 @@
 # dep-audit.sh — PostToolUse:Write|Edit|MultiEdit hook
 # Runs dependency vulnerability checks when manifest files are modified.
 # Always exits 0 (advisory only — PostToolUse cannot hard-block).
-set -uo pipefail
+set -euo pipefail
 trap 'exit 0' ERR
 
 INPUT=$(cat)

package/base/hooks/file-guard.sh

@@ -6,7 +6,7 @@ set -euo pipefail
 INPUT=$(cat)
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty')
 
-if [ -z "$FILE_PATH" ]; then
+if [[ -z "$FILE_PATH" ]]; then
   exit 0
 fi
 
@@ -29,7 +29,7 @@ for pattern in "${PROTECTED_PATTERNS[@]}"; do
 done
 
 # Check project-level protected files from CLAUDE.md if it exists
-if [ -f "CLAUDE.md" ]; then
+if [[ -f "CLAUDE.md" ]]; then
   # Extract paths from ## Protected Files section
   IN_SECTION=false
   while IFS= read -r line; do
@@ -42,7 +42,7 @@ if [ -f "CLAUDE.md" ]; then
     fi
     if $IN_SECTION && echo "$line" | grep -qE "^- "; then
       PROTECTED=$(echo "$line" | sed 's/^- //' | sed 's/ *#.*//' | xargs)
-      if [ -n "$PROTECTED" ] && echo "$FILE_PATH" | grep -qE "$PROTECTED"; then
+      if [[ -n "$PROTECTED" ]] && echo "$FILE_PATH" | grep -qE "$PROTECTED"; then
         echo "BLOCKED: $FILE_PATH matches project-protected pattern '$PROTECTED'. Explain the intended change."
         exit 2
       fi

package/base/hooks/recursion-guard.sh

@@ -50,7 +50,13 @@ KEY="${KEY:0:300}"
 
 # ── Increment counter ──
 # Use a hash of the key for safe JSON field names
-KEY_HASH=$(echo -n "$KEY" | md5 2>/dev/null || echo -n "$KEY" | md5sum 2>/dev/null | cut -d' ' -f1 || echo "fallback")
+if command -v md5sum &>/dev/null; then
+  KEY_HASH=$(echo -n "$KEY" | md5sum | cut -d' ' -f1)
+elif command -v md5 &>/dev/null; then
+  KEY_HASH=$(echo -n "$KEY" | md5 -q)
+else
+  KEY_HASH="${KEY:0:32}"
+fi
 
 COUNT=$(jq -r --arg cat "$CATEGORY" --arg key "$KEY_HASH" \
   '.[$cat][$key] // 0' "$STATE_FILE" 2>/dev/null || echo "0")

package/base/hooks/session-data-collect.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Stop hook — collects structured session data and stages it for the Stop prompt.
 # Always exits 0 (advisory, never blocks session end).
-set -uo pipefail
+set -euo pipefail
 trap 'exit 0' ERR
 
 CONFIG_FILE="$HOME/.claude/praxis.config.json"

package/base/hooks/vault-checkpoint.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # PreCompact hook — writes minimal checkpoint to vault before context compaction.
 # Always exits 0 (advisory, never blocks compaction).
-set -uo pipefail
+set -euo pipefail
 trap 'exit 0' ERR
 
 CONFIG_FILE="$HOME/.claude/praxis.config.json"
@@ -19,7 +19,7 @@ PLANS_DIR="$VAULT_PATH/plans"
 mkdir -p "$PLANS_DIR"
 
 DATE=$(date +%Y-%m-%d)
-TIMESTAMP=$(date +"%Y-%m-%d %H:%M:%S")
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 CHECKPOINT_FILE="$PLANS_DIR/$DATE-compact-checkpoint.md"
 
 BRANCH=$(git --no-pager rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
@@ -40,16 +40,16 @@ fi
 LINT_STATE="unknown"
 TEST_STATE="unknown"
 
-if [ -f "go.mod" ] && command -v golangci-lint &>/dev/null; then
+if [[ -f "go.mod" ]] && command -v golangci-lint &>/dev/null; then
   LINT_COUNT=$(golangci-lint run ./... 2>&1 | grep -c "^" || true)
-  if [ "$LINT_COUNT" -eq 0 ]; then
+  if [[ "$LINT_COUNT" -eq 0 ]]; then
     LINT_STATE="clean"
   else
     LINT_STATE="$LINT_COUNT findings"
   fi
 fi
 
-if [ -f "go.mod" ] && command -v go &>/dev/null; then
+if [[ -f "go.mod" ]] && command -v go &>/dev/null; then
   if go test ./... -short 2>&1 | grep -q "^ok"; then
     TEST_STATE="passing"
   else

package/base/rules/code-excellence.md

@@ -74,3 +74,25 @@ A comment that says `// increment counter` above `counter++` is noise.
 A comment that says `// retry three times because the upstream API returns 503 on cold start`
 is knowledge that cannot be inferred from the code alone.
 Delete the first kind. Write more of the second kind.
+
+---
+
+## Reference Codebases — What Excellence Looks Like
+
+When you need a reference for what excellent code looks like, use these:
+
+| Domain | Reference | What to study |
+| ------ | --------- | ------------- |
+| C / systems | SQLite source (`sqlite.org/src`) | Discipline: 590x test-to-source ratio, 100% branch coverage, zero external deps |
+| C / network | Redis `src/ae.c`, `src/dict.c` | Naming, readability, data structures that document themselves |
+| Go | Go standard library (`pkg.go.dev/std`) | Idiomatic naming, error design, interface sizing — one method where possible |
+| Rust | `rustc_errors` crate | Error message design: what failed, where, what to do next |
+| Error messages | Elm compiler output | Kindest, most actionable errors in any compiled language |
+| API design | Stripe API (`docs.stripe.com`) | Naming consistency, versioning discipline, error schema |
+| Documentation | Go stdlib `net/http` package docs | Every exported symbol explained by what it does for the caller |
+
+When uncertain if code is good enough: "Would this survive a review from the SQLite team?"
+If the answer is no — simplify first.
+
+The SQLite standard: every line has a reason. Every function has one job.
+Every error has a message a human can act on.

package/base/rules/coding.md

@@ -13,6 +13,22 @@
 - If Context7 is unavailable: state that docs could not be verified and flag the
   specific method/API as "unverified against current version."
 
+### Import-trigger protocol
+
+Any commit diff that adds a new `import`, `require`, `using`, or `use` statement for an
+external package must have a corresponding Context7 lookup in the same session.
+
+Language-specific patterns matched:
+
+- JavaScript/TypeScript: `import ... from`, `require(...)`
+- Python: `import ...`, `from ... import`
+- Go: `import "..."` or `import (...)`
+- Rust: `use ...::...`
+- Java/C#: `import ...`, `using ...`
+
+Every new external import requires a Context7 verification before the gate clears.
+Internal packages (same repo, same module) are excluded.
+
 ### Tool preferences
 - Use Read/Edit/Write tools instead of cat/sed/echo.
 - Use `rg` (ripgrep) for searching code, not grep.

package/base/rules/observable-code.md

@@ -0,0 +1,87 @@
+# Observable Code — Instrumentation Constraints
+# Scope: **/services/**, **/handlers/**, **/workers/**, **/middleware/**, **/cmd/**
+# Active during code generation for service-layer code
+# Cross-reference: api-quality.md covers request-level logging and correlation IDs.
+#   This rule covers application-level observability: structured logging, metrics, traces.
+
+Code is not production-ready if it cannot be debugged without attaching a debugger.
+Observable code tells you what happened, when, and why — from logs, metrics, and traces alone.
+
+## Invariants — BLOCK on violation
+
+### Structured logging only
+- All log statements use structured format (key-value pairs, not string interpolation)
+- No `fmt.Println` / `console.log` / `print()` in production code paths — use the structured logger
+- Log at the point of failure, not at the catch site (log once, propagate)
+
+### Log levels are semantic
+- ERROR: something failed and a human needs to know immediately
+- WARN: something unexpected happened but the system recovered
+- INFO: a significant state transition (service started, job completed, user authenticated)
+- DEBUG: internal detail useful during development — must not appear in production by default
+
+### Structured log format — mandatory fields
+```json
+{
+  "timestamp": "ISO-8601 UTC",
+  "level": "error|warn|info|debug",
+  "service": "service-name",
+  "correlation_id": "request or trace identifier",
+  "message": "what happened — actionable, not generic",
+  "context": { "relevant_key": "relevant_value" }
+}
+```
+
+### What NOT to log
+- Passwords, tokens, secrets, full credit card numbers
+- Full request/response bodies in production (may contain PII)
+- DEBUG logs in production services (log level must be configurable)
+- The same event more than once in the same request path
+
+### External call discipline
+- Every external call (HTTP, DB, queue) has a timeout
+- Every external call logs duration on completion
+- Failed external calls log: target, duration, error type, and whether retry will occur
+
+## Conventions — WARN on violation
+
+### Metrics naming
+Format: `{service}_{subsystem}_{name}_{unit}`
+All lowercase, underscores as separators.
+
+Mandatory metrics per service:
+- `{service}_requests_total` — counter, labeled by method and status code
+- `{service}_errors_total` — counter, labeled by error type
+- `{service}_latency_seconds` — histogram, labeled by operation
+- `{service}_active_connections` or `{service}_queue_depth` — gauge (if applicable)
+
+GOOD: `auth_login_attempts_total`, `cache_hit_ratio`, `queue_messages_pending`
+BAD: `loginAttempts`, `CacheHitRatio`, `queue-messages-pending`
+
+### Trace spans (OpenTelemetry)
+Span naming: `{service}/{operation}` — lowercase, slash separator
+GOOD: `auth/validate-token`, `db/query-users`, `cache/get`
+BAD: `validateToken`, `DB Query`, `GET /users`
+
+Mandatory span attributes:
+- `service.name`
+- `http.method` and `http.status_code` for HTTP operations
+- `db.system` and `db.operation` for database calls
+- `error.type` and `error.message` on error spans
+
+### Health endpoints
+- Liveness: `/healthz` — "is the process alive?"
+- Readiness: `/readyz` — "can the process serve traffic?"
+- Both return structured JSON with component status
+
+### The Observability Contract
+An error is only production-observable if ALL three are true:
+1. It appears in structured logs with correlation_id and context
+2. It increments an error metric labeled by error type
+3. It is captured in a trace span with error attributes
+
+If only one or two are true: the code is not fully observable. Fix before shipping.
+
+## Removal Condition
+Remove when an observability linter or OpenTelemetry SDK auto-instrumentation
+replaces these generation-time constraints entirely.

package/base/rules/refactor-triggers.md

@@ -0,0 +1,59 @@
+# Refactor Triggers — Pre-Check Protocol
+# Scope: All code modifications
+# Always active during code generation
+# Cross-reference: code-quality.md defines the hard limits (30 lines, 3 nesting,
+#   4 params, 300-line files, no TODO/FIXME). This file defines WHEN and HOW
+#   to refactor — not the thresholds themselves.
+
+## Invariants — BLOCK on violation
+
+### Before touching any existing file
+Check the file against `code-quality.md` hard limits before adding code.
+If the file already violates limits:
+1. Do NOT add new code to it
+2. Refactor the file to compliance first
+3. THEN make the intended change
+4. Commit the refactor separately from the feature
+
+This is mandatory. Adding to an already-broken file compounds debt exponentially.
+
+### Commit refactor separately from feature
+- Refactoring commits use `refactor(scope):` prefix
+- Feature commits use `feat(scope):` prefix
+- Never mix structural changes and behavior changes in one commit
+- Rationale: reviewers cannot distinguish "moved code" from "changed behavior" in a mixed diff
+
+### Copy-paste detection
+If you find yourself copying 3+ lines from elsewhere in the same codebase: stop.
+Extract a shared function in a common location.
+Duplication is the root of divergent behavior bugs.
+
+## Conventions — WARN on violation
+
+### The QUALITY comment convention
+When you encounter a known violation in code you are NOT tasked with fixing:
+```
+// QUALITY: function exceeds 30 lines — refactor tracked in #123
+```
+
+Rules for QUALITY comments:
+- QUALITY: is the ONLY allowed debt marker. `TODO`, `FIXME`, and `HACK` are banned (see `code-quality.md`).
+- Every QUALITY comment MUST include a tracking reference (issue number, ADR, or ticket).
+- QUALITY comments are allowed in commits — unlike TODO/FIXME which are not.
+- A QUALITY comment is NOT a license to defer indefinitely. It is a documented acknowledgment.
+
+### Refactor vs rewrite decision gate
+- **Refactor** (preferred): same behavior, improved structure. Small, safe, incremental.
+- **Rewrite**: new behavior or complete structural replacement.
+
+If >50% of a file needs changing during a feature task:
+1. Stop. Do not incrementally refactor to the point of a full rewrite.
+2. File an issue for the rewrite.
+3. Complete the minimum viable refactor for the current feature.
+4. Propose the rewrite as a separate milestone with its own plan.
+
+Never rewrite during a feature task without an explicit plan.
+
+## Removal Condition
+Remove when automated refactoring tools (e.g., language-specific AST transforms)
+handle pre-check validation and commit separation automatically.

package/base/rules/writing-quality.md

@@ -0,0 +1,122 @@
+# Writing Quality — Prose Generation Constraints
+# Scope: All prose output — design docs, ADRs, READMEs, specs, PR descriptions,
+#         commit messages, code comments, status reports
+# Always active during prose generation
+
+## The Prime Directive for Prose
+Write for the engineer reading this at 11pm during an incident.
+They have 90 seconds. Every word must earn its place.
+
+## Invariants — BLOCK on violation
+
+### Sentence limits
+- Maximum 30 words per sentence. Count before writing long sentences.
+- Maximum 5 sentences per paragraph.
+- One idea per paragraph.
+
+### Fluff kill list — never write these words or phrases
+leverage (use: use), utilize (use: use), facilitate (use: enable, allow, help),
+moving forward, going forward, at this point in time, comprehensive solution,
+robust solution, seamlessly, cutting-edge, best-in-class,
+in order to (use: to), due to the fact that (use: because),
+at the end of the day, synergy, holistic, empower, streamline
+
+For additional banned AI-filler phrases, see `px-communication-standards` skill.
+That skill covers: "Certainly!", "Absolutely!", "Great question!", "I'd be happy to",
+"It's worth noting that", "In conclusion", "To summarize the above".
+Both lists are enforced. Neither is optional.
+
+### Voice on decisions
+- Active voice on decisions: "we decided" not "it was decided"
+- Active voice on architecture: "this service handles X" not "X is handled by"
+- Reserve passive voice for describing states: "the cache is invalidated when..."
+
+### Hedging on decided things
+- Decided things use "will", not "should" or "might"
+- Uncertain things are labeled explicitly: "open question:", "to be decided:"
+- Never hedge silently. If you are uncertain, say so.
+
+## Document Structure — Mandatory Templates
+
+### Design Doc (filename: DESIGN-*.md or *-design.md)
+Required sections — none optional, none empty:
+
+#### Problem
+- What is broken, missing, or painful? Past tense. Specific.
+- "The auth service does not rate-limit failed login attempts" — GOOD
+- "We need better authentication" — BAD (not specific, not a problem statement)
+
+#### Decision
+- What are we building? Active voice. One paragraph.
+- State what this is AND what it is NOT (explicit scope boundary).
+
+#### Tradeoffs
+- Minimum 2 items. For each: what we gain AND what we give up.
+- Not "pros and cons of the overall approach" — tradeoffs of THIS decision vs alternatives.
+
+#### Acceptance Criteria
+- Verifiable statements. Observable outcomes. Present tense.
+- GOOD: "The login endpoint returns 429 after 5 failed attempts within 60 seconds"
+- BAD: "The system handles failed logins correctly"
+- BAD: "Improved security posture"
+
+### ADR (filename: ADR-NNN-*.md)
+Required fields in this order:
+```
+# ADR-NNN: {title}
+Status: Proposed | Accepted | Deprecated | Superseded by ADR-NNN
+Date: YYYY-MM-DD
+
+## Context
+{past tense — what situation forced this decision}
+
+## Decision
+{active voice — what we decided}
+
+## Consequences
+### Positive
+- {at least one}
+### Negative
+- {at least one — if no negatives, the decision is not analyzed}
+```
+
+### README (filename: README.md)
+Required sections:
+- First paragraph: what does this do (3 sentences max, no jargon)
+- `## Install` or `## Setup` with exact commands
+- `## Run` with exact commands — no `{placeholder}` in code blocks
+- `## Test` with exact commands
+
+### PR Description
+Required sections:
+- **What**: one sentence — what changed
+- **Why**: one sentence — why this was needed
+- **How to verify**: exact steps a reviewer takes to confirm it works
+- **Breaking changes**: explicit "None" if none — do not omit
+
+## Commit Messages
+Format: `{type}({scope}): {what changed in imperative mood}`
+
+Types: feat, fix, refactor, test, docs, chore, perf, ci
+Scope: the module, package, or subsystem changed
+Subject: present tense imperative — "add retry logic" not "added retry logic"
+
+50-char subject limit. 72-char body line limit if body is present.
+Body explains WHY the change was needed, not what the diff shows.
+
+## Code Comments
+- WHY not WHAT. The code shows what.
+- GOOD: `// retry 3x — upstream returns 503 on cold start, recovers within 2s`
+- BAD: `// increment counter`
+- Zero tolerance for TODO/FIXME/HACK in committed code.
+  Use `// QUALITY: {issue} — tracked in #{issue-number}` if deferring.
+  See `refactor-triggers.md` for the QUALITY comment convention.
+
+## Cross-References
+- Document-level formatting (proposals, status reports, executive summaries): see `px-communication-standards` skill
+- Commit standards and git workflow: see `git-workflow.md`
+- Code comment rules: see `code-quality.md` § On comments
+
+## Removal Condition
+Remove when a prose linter (Vale or equivalent) runs as a generation-time hook
+on all markdown and prose output.

package/base/skills/px-complexity-audit/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: px-complexity-audit
+disable-model-invocation: true
+description: "Codebase debt scanner. Ranks files by complexity score (size, nesting, debt markers, generic names). Use at sprint start, before major features, or quarterly. Outputs heat map and refactor targets."
+---
+
+# px-complexity-audit — Codebase Debt Scanner
+
+## Purpose
+
+Scans the existing codebase for accumulated technical debt.
+Outputs a ranked heat map of files needing attention.
+Use before starting major feature work or at sprint boundaries.
+
+## When To Use
+
+1. Sprint start: identify cleanup targets before new work begins
+2. Pre-feature: assess the health of files you are about to modify
+3. Quarterly: full codebase scan, results written to vault
+4. On-demand: `/px-complexity-audit {directory}` for targeted scan
+
+## What It Scans
+
+### File-level metrics
+
+```bash
+FILE_LINES=$(wc -l < "$f")
+TODO_COUNT=$(grep -cE 'TODO|FIXME|HACK|QUALITY:' "$f" || echo 0)
+FUNC_COUNT=$(grep -cE '(func |def |function |const .* = )' "$f" || echo 0)
+DEEP_NEST=$(grep -cE '^\s{16,}\S|^\t{4,}\S' "$f" || echo 0)
+GENERIC_NAMES=$(grep -oE '\b(data|result|info|temp|tmp|obj|val|item|stuff|thing|ret|res)\b' "$f" | wc -l || echo 0)
+```
+
+### Debt score formula
+
+Each file receives a composite score (higher = more urgent):
+
+```
+debt_score = (
+  (file_lines / 300 * 30)           +  # Over size limit: 30 points at 300 lines
+  (todo_count * 10)                  +  # 10 points per debt marker
+  (deep_nest_lines * 5)             +  # 5 points per deeply nested line
+  (generic_name_count * 2)          +  # 2 points per generic name
+  (longest_function / 30 * 20)         # Over function limit: 20 points at 30 lines
+)
+```
+
+Thresholds:
+
+- Score 0-20: CLEAN — no action needed
+- Score 21-50: WATCH — consider cleanup if touching this file
+- Score 51-80: REFACTOR — clean up before adding features
+- Score 81+: CRITICAL — stop and refactor now
+
+### Potential dead code detection
+
+```bash
+for func_name in $(grep -ohE '(func|def|function)\s+\w+' "$f" | awk '{print $2}'); do
+  refs=$(rg -l "$func_name" --type-add 'code:*.{go,ts,py,js,rs,java}' -t code . | grep -v "$f" | wc -l || echo 0)
+  if [[ "$refs" -eq 0 ]]; then
+    echo "POTENTIAL_DEAD: $func_name in $f (0 external references)"
+  fi
+done
+```
+
+## Output Format
+
+### Heat Map (terminal output)
+
+```
+━━━ COMPLEXITY AUDIT ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Scanned: 47 files | CLEAN: 31 | WATCH: 9 | REFACTOR: 5 | CRIT: 2
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+TOP 5 REFACTOR TARGETS
+
+ Rank | File                        | Score | Primary Issue
+ ─────┼─────────────────────────────┼───────┼────────────────────
+  1   | services/auth/handler.go    |  94   | 342 lines, 4 TODOs
+  2   | services/billing/calc.py    |  87   | 60-line function
+  3   | handlers/api/v2/users.ts    |  73   | 5-level nesting
+  4   | lib/cache/redis.go          |  58   | 12 generic names
+  5   | cmd/worker/process.go       |  52   | 3 TODOs, 280 lines
+
+Estimated effort: ~4 hours for top 5
+```
+
+### Effort estimation heuristic
+
+| Action | Estimated time |
+| ------ | -------------- |
+| Split a 300+ line file | 30-45 min |
+| Extract a 30+ line function | 15-20 min |
+| Flatten deep nesting | 10-15 min per function |
+| Rename generic variables | 5-10 min per file |
+| Address a TODO with ticket | 5 min (triage) or 30+ min (fix) |
+
+### Vault output
+
+When run with `--write-vault` or during quarterly scan:
+
+```
+Output path: {vault_path}/specs/debt-audit-{YYYY-MM-DD}.md
+```
+
+Contents:
+
+- Full ranked file list with scores
+- Top 5 refactor targets with specific actions
+- Trend comparison if previous audit exists (score delta per file)
+- Recommended sprint allocation (hours) for debt reduction
+
+## Limitations
+
+- Dead code detection is heuristic — false positives on exported/public APIs
+- Nesting depth uses indentation as proxy — may miscount in some styles
+- Does not analyze cyclomatic complexity (would require AST parsing per language)
+- Effort estimates are rough guides, not commitments

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

@@ -10,7 +10,10 @@ You are running a structured technical discovery.
 - Read vault_path from `~/.claude/praxis.config.json`
 - What decision needs to be made? (one sentence)
 - What are the constraints? (compliance, performance, compatibility, cost)
-- What is already known? (run `obsidian search query="{topic}" limit=5`)
+- What is already known? Search vault using configured backend:
+  - If `obsidian`: run `obsidian search query="{topic}" limit=5`
+  - If `ripgrep`: run `rg --files-with-matches "{topic}" {vault_path}/`
+  - If vault search fails: proceed without blocking
 
 **Step 2 — Research options**
 - Identify 2-4 viable options. For each:

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

@@ -23,7 +23,10 @@ Do NOT present a template or form. Let them talk.
 
 **Step 3 — Search for related work**
 After the user describes the task, search vault for prior art:
-Run: `obsidian search query="{topic}" limit=5`
+Read `vault_backend` from `~/.claude/praxis.config.json`.
+- If `obsidian`: run `obsidian search query="{topic}" limit=5`
+- If `ripgrep`: run `rg --files-with-matches "{topic}" {vault_path}/`
+- If vault search fails (e.g., Obsidian not running): warn and proceed without blocking.
 If related specs, plans, or research exist: mention them briefly.
 If nothing exists: proceed silently.