@esoteric-logic/praxis-harness 2.11.0 → 2.13.0

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-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-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.
 

package/base/skills/px-doc-lint/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: px-doc-lint
+disable-model-invocation: true
+description: "Fast structural markdown check. No subagent — pure pattern matching. Completes in under 5 seconds. Fires inside px-quality-gate for staged *.md files, or on-demand via /px-doc-lint."
+---
+
+# px-doc-lint — Fast Structural Markdown Check
+
+## Purpose
+
+Lightweight structural validation for markdown files. No subagent.
+Pure pattern matching. Completes in under 5 seconds.
+Use as a quick pre-save check or let px-quality-gate invoke it automatically.
+
+## When It Fires
+
+1. Automatically inside px-quality-gate for every staged `*.md` file
+2. On-demand: `/px-doc-lint {filepath}`
+3. On-demand batch: `/px-doc-lint {directory}` (all .md files in directory)
+
+## Checks by Document Type
+
+### All markdown files
+
+```bash
+# 1. Frontmatter check — if present, must be valid
+head -1 "$f" | grep -q '^---$' && {
+  awk '/^---$/{c++} c==2{found=1; exit} END{if(!found) print "BLOCK: unclosed frontmatter"}' "$f"
+}
+
+# 2. No trailing whitespace
+grep -nE ' +$' "$f" && echo "WARN: trailing whitespace"
+
+# 3. No consecutive blank lines (more than 2)
+awk '/^$/{blank++; if(blank>2) print "WARN: line "NR": excessive blank lines"} /^.+$/{blank=0}' "$f"
+
+# 4. Headers must increment by one level (no h1 -> h3 skip)
+grep -E '^#{1,6} ' "$f" | awk '{
+  level = length($0) - length(gensub(/^#+/, "", 1, $0)) - 1
+  if (prev > 0 && level > prev + 1)
+    print "WARN: header level skip at: "$0
+  prev = level
+}'
+
+# 5. No empty headers
+grep -nE '^#{1,6}\s*$' "$f" && echo "BLOCK: empty header"
+
+# 6. Fluff kill list (same as px-quality-gate prose check)
+grep -inE "$FLUFF_PATTERN" "$f" && echo "BLOCK: fluff phrases detected"
+```
+
+### Design docs (DESIGN-*.md, *-design.md)
+
+```bash
+for section in "## Problem" "## Decision" "## Tradeoffs" "## Acceptance Criteria"; do
+  grep -q "$section" "$f" || echo "BLOCK: missing required section: $section"
+done
+
+tradeoff_count=$(awk '/## Tradeoffs/,/## /' "$f" | grep -c '^- ' || true)
+if [[ "$tradeoff_count" -lt 2 ]]; then
+  echo "BLOCK: Tradeoffs section needs at least 2 items (found: $tradeoff_count)"
+fi
+```
+
+### ADRs (ADR-*.md)
+
+```bash
+for field in "Status:" "Date:" "## Context" "## Decision" "## Consequences"; do
+  grep -q "$field" "$f" || echo "BLOCK: missing required field: $field"
+done
+
+status=$(grep -oE 'Status: .*' "$f" | head -1)
+echo "$status" | grep -qE '(Proposed|Accepted|Deprecated|Superseded)' || \
+  echo "BLOCK: invalid ADR status. Must be: Proposed | Accepted | Deprecated | Superseded by ADR-NNN"
+
+grep -q '### Positive' "$f" || echo "BLOCK: missing Consequences > Positive"
+grep -q '### Negative' "$f" || echo "BLOCK: missing Consequences > Negative"
+```
+
+### READMEs (README.md)
+
+```bash
+for section in "## Install\|## Setup" "## Run" "## Test"; do
+  grep -qE "$section" "$f" || echo "BLOCK: missing required section matching: $section"
+done
+
+awk '/^```/,/^```/' "$f" | grep -E '\{placeholder\}|\{TODO\}|\{TBD\}' && \
+  echo "BLOCK: placeholder found inside code block"
+```
+
+## Output Format
+
+```
+px-doc-lint: {filename}
+Type: {Design Doc | ADR | README | General}
+  [PASS] frontmatter valid
+  [PASS] no trailing whitespace
+  [BLOCK] missing required section: ## Tradeoffs
+  [WARN] header level skip at: ### Details
+Result: BLOCK (1 error, 1 warning)
+```
+
+## Performance Contract
+
+- Single file: under 2 seconds
+- Batch (10 files): under 5 seconds
+- No network calls. No subagent. Pure grep/awk/sed.

package/base/skills/px-prose-review/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: px-prose-review
+disable-model-invocation: true
+description: "Deep document review using an isolated subagent. Checks argument quality, clarity, completeness, and adherence to writing-quality.md. Use for design docs, ADRs, READMEs, specs. More thorough than px-doc-lint."
+---
+
+# px-prose-review — Deep Document Review
+
+## Purpose
+
+Performs deep quality review on prose documents using an isolated subagent.
+More thorough than px-doc-lint — checks argument quality, clarity, completeness,
+and adherence to writing-quality.md standards.
+
+## When It Fires
+
+1. On-demand: `/px-prose-review {filepath}`
+2. Automatic: during `/px-ship` against the PR description
+3. Recommended: before finalizing any design doc, ADR, or spec
+
+## Subagent Configuration
+
+The review runs in an isolated context with zero conversation history.
+The subagent receives ONLY the document content and the review instructions.
+
+### Subagent persona
+
+```
+You are a ruthless technical editor. Your job is to make this document
+shorter, clearer, and more precise. You have no loyalty to the author's
+feelings. You have total loyalty to the reader's time.
+
+Rules:
+- Every sentence must earn its place. If it restates something already said, cut it.
+- Every paragraph must have exactly one idea. If it has two, split it.
+- Every claim must be specific. "Improves performance" is not a claim.
+  "Reduces p99 latency from 200ms to 50ms" is.
+- Active voice on all decisions and actions.
+- No fluff words (see kill list in writing-quality.md).
+- No hedging on decided things. "will" not "should" or "might".
+```
+
+The full fluff kill list from writing-quality.md is injected into the subagent prompt.
+
+## Document Type Detection
+
+The subagent detects document type from filename and content:
+
+| Pattern | Type | Structural checks applied |
+| ------- | ---- | ------------------------- |
+| `DESIGN-*.md`, `*-design.md` | Design Doc | Problem, Decision, Tradeoffs, Acceptance Criteria |
+| `ADR-*.md` | ADR | Status, Date, Context, Decision, Consequences (Positive + Negative) |
+| `README.md` | README | First paragraph, Install/Setup, Run, Test |
+| `*.md` in PR context | PR Description | What, Why, How to verify, Breaking changes |
+| All other `*.md` | General prose | Sentence limits, fluff, voice, hedging |
+
+## Review Output Format
+
+```
+## px-prose-review: {filename}
+Type detected: {Design Doc | ADR | README | PR Description | General}
+
+### Structure
+- [PASS|BLOCK] {section}: {detail}
+
+### Clarity
+- Line {N}: {issue} → {suggested fix}
+
+### Fluff
+- Line {N}: "{flagged phrase}" → {replacement or "delete"}
+
+### Voice
+- Line {N}: passive on decision → {active rewrite}
+
+### Verdict
+{CLEAN | {N} issues found — {M} auto-fixable}
+```
+
+## Auto-Fix Flow
+
+For minor issues (fluff deletion, passive-to-active rewrites on clear cases):
+1. Subagent proposes the fix with before/after
+2. Operator is shown the diff
+3. Operator approves or rejects each fix individually
+4. Approved fixes are applied in-place
+
+For structural issues (missing sections, incomplete analysis):
+- Subagent flags the gap and describes what is needed
+- Operator writes the content — subagent does NOT generate missing sections
+- Rationale: the subagent lacks project context to write accurate content
+
+## Limitations
+
+- Does not verify technical accuracy of claims — only prose quality
+- Does not check code blocks inside markdown — only surrounding prose
+- Does not run on files outside the repo (external links, references)

package/base/skills/px-quality-gate/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: px-quality-gate
+disable-model-invocation: true
+description: "Code style and prose quality gate. Checks what linters cannot: naming, doc completeness, prose clarity, structural patterns. Integrated into px-verify as Step 1 item 5b. Also available standalone via /px-quality-gate."
+---
+
+# px-quality-gate — Style and Prose Quality Enforcement
+
+## Purpose
+
+Runs automated style checks against changed files. Catches issues that linters and
+test suites do not: generic variable names, missing docstrings, prose quality,
+structural violations, and import verification.
+
+Integrated into `/px-verify` as Step 1 item 5b (after security scan, before functional check).
+Also available standalone via `/px-quality-gate`.
+
+## When It Fires
+
+1. Automatically inside `/px-verify` after security scan
+2. As the first step of `/px-ship`
+3. On-demand via `/px-quality-gate` for ad-hoc checks
+
+## Scope
+
+Checks run against staged or changed files only (not the full codebase).
+Use `/px-complexity-audit` for full codebase scans.
+
+## Verdicts
+
+- **BLOCK**: violation found — must fix before proceeding. Commit blocked.
+- **WARN**: advisory issue found — commit allowed, fix recommended.
+- **PASS**: all checks clear.
+
+## Check Categories
+
+### 1. Code Structure Checks
+
+Run against all changed code files (exclude vendor/, node_modules/, .git/).
+
+#### File size
+
+```bash
+for f in $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(go|ts|tsx|js|jsx|py|rs|java|sh|sql)$'); do
+  lines=$(wc -l < "$f")
+  if [[ "$lines" -gt 300 ]]; then
+    echo "BLOCK: $f is $lines lines (limit: 300). Split before committing."
+  fi
+done
+```
+
+#### TODO/FIXME/HACK detection
+
+```bash
+for f in $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(go|ts|tsx|js|jsx|py|rs|java|sh|sql)$'); do
+  hits=$(grep -nE 'TODO|FIXME|HACK' "$f" || true)
+  if [[ -n "$hits" ]]; then
+    echo "BLOCK: $f contains banned markers. Use QUALITY: with a ticket number instead."
+    echo "$hits"
+  fi
+done
+```
+
+#### Nesting depth heuristic
+
+```bash
+for f in $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(go|ts|tsx|js|jsx|py|rs|java)$'); do
+  deep=$(grep -nE '^\s{16,}\S|^\t{4,}\S' "$f" || true)
+  if [[ -n "$deep" ]]; then
+    echo "WARN: $f may have deep nesting. Review these lines:"
+    echo "$deep"
+  fi
+done
+```
+
+#### Generic variable names
+
+```bash
+git diff --cached -U0 | grep '^+' | grep -v '^+++' | \
+  grep -oE '\b(data|result|info|temp|tmp|obj|val|item|stuff|thing|ret|res)\b' | \
+  sort | uniq -c | sort -rn | head -10
+```
+
+If any appear 3+ times: WARN with suggestion to use domain-specific names.
+
+#### Missing docstrings on new public functions
+
+```bash
+git diff --cached -U3 | grep -E '^\+.*(func |def |export function |export const .* = )' | \
+  while read -r line; do
+    echo "CHECK: verify doc comment exists for: $line"
+  done
+```
+
+### 2. Prose Checks
+
+Run against all changed markdown files.
+
+#### AI fluff detection
+
+```bash
+FLUFF_PATTERN='leverage|utilize|facilitate|moving forward|going forward|at this point in time|comprehensive solution|robust solution|seamlessly|cutting-edge|best-in-class|in order to|due to the fact that|at the end of the day|synergy|holistic|empower|streamline'
+
+for f in $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.md$'); do
+  hits=$(grep -inE "$FLUFF_PATTERN" "$f" || true)
+  if [[ -n "$hits" ]]; then
+    echo "BLOCK: $f contains fluff phrases. Remove or replace per writing-quality.md."
+    echo "$hits"
+  fi
+done
+```
+
+#### Passive voice on decisions
+
+```bash
+for f in $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.md$'); do
+  hits=$(grep -inE '(it was decided|was implemented|was chosen|was selected|has been determined)' "$f" || true)
+  if [[ -n "$hits" ]]; then
+    echo "WARN: $f uses passive voice on decisions. Rewrite in active voice."
+    echo "$hits"
+  fi
+done
+```
+
+#### Sentence length check
+
+```bash
+for f in $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.md$'); do
+  awk 'BEGIN{RS="[.!?]"} NF>30 {print NR": "NF" words: "$0}' "$f" | head -5
+done
+```
+
+#### Unreplaced placeholders
+
+```bash
+for f in $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.md$'); do
+  hits=$(grep -nE '\{placeholder\}|\{TODO\}|\{TBD\}|\[INSERT\]|\[TBD\]|XXX' "$f" || true)
+  if [[ -n "$hits" ]]; then
+    echo "BLOCK: $f contains unreplaced placeholders."
+    echo "$hits"
+  fi
+done
+```
+
+### 3. Context7 Import Check
+
+```bash
+NEW_IMPORTS=$(git diff --cached -U0 | grep -E '^\+.*(import |require\(|using |use )' | grep -v '^+++' | grep -v '^//\|^#')
+
+if [[ -n "$NEW_IMPORTS" ]]; then
+  echo "GATE: New external imports detected. Each requires a Context7 lookup:"
+  echo "$NEW_IMPORTS"
+  echo ""
+  echo "Confirm each import was verified via Context7 in this session."
+  echo "Internal packages (same repo/module) are excluded."
+fi
+```
+
+## Output Format
+
+```
+━━━ QUALITY GATE ━━━━━━━━━━━━━━━━━━━
+Code checks:   PASS | WARN | BLOCK
+Prose checks:  PASS | WARN | BLOCK
+Import check:  PASS | WARN | BLOCK
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Overall:       PASS | WARN | BLOCK
+
+Details:
+  [BLOCK] services/auth.go: 342 lines (limit: 300)
+  [BLOCK] docs/DESIGN-auth.md: contains "comprehensive solution" (fluff)
+  [WARN]  handlers/login.go: possible deep nesting at line 47
+  [PASS]  All other checks
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Rules
+
+- Any single BLOCK = overall BLOCK. Commit prevented.
+- WARN-only = overall WARN. Commit allowed. Fix recommended.
+- Gate re-runs on re-stage. Fix the issue, `git add`, gate runs again.
+- Do NOT bypass the gate. There is no `--force` flag.

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

@@ -9,7 +9,10 @@ You are adding a risk register entry for the current project.
 **Step 1 — Detect project and existing risks**
 - Read vault_path from `~/.claude/praxis.config.json`
 - Detect project from CWD
-- Run: `obsidian search query="risk register {project-slug}" limit=3`
+- Search vault for existing risks using configured backend:
+  - If `obsidian`: run `obsidian search query="risk register {project-slug}" limit=3`
+  - If `ripgrep`: run `rg --files-with-matches "risk" {vault_path}/specs/`
+  - If vault search fails: proceed without blocking
 - Check if `{vault_path}/specs/risk-register.md` exists
 - If found: read it to determine next sequential risk ID (R-01, R-02, etc.)