@wazir-dev/cli 1.1.0 → 1.3.0

package/skills/reviewer/SKILL.md

@@ -5,10 +5,40 @@ description: Run the review phase — adversarial review of implementation again
 
 # Reviewer
 
-Run Phase 3 (Review) for the current project.
+## Model Annotation
+When multi-model mode is enabled:
+- **Sonnet** for internal review passes (internal-review)
+- **Opus** for final review mode (final-review)
+- **Opus** for spec-challenge mode (spec-harden)
+- **Opus** for design-review mode (design)
+
+## Command Routing
+Follow the Canonical Command Matrix in `hooks/routing-matrix.json`.
+- Large commands (test runners, builds, diffs, dependency trees, linting) → context-mode tools
+- Small commands (git status, ls, pwd, wazir CLI) → native Bash
+- If context-mode unavailable, fall back to native Bash with warning
+
+## Codebase Exploration
+1. Query `wazir index search-symbols <query>` first
+2. Use `wazir recall file <path> --tier L1` for targeted reads
+3. Fall back to direct file reads ONLY for files identified by index queries
+4. Maximum 10 direct file reads without a justifying index query
+5. If no index exists: `wazir index build && wazir index summarize --tier all`
+
+Run the Final Review phase — or any review mode invoked by other phases.
 
 The reviewer role owns all review loops across the pipeline: research-review, clarification-review, spec-challenge, design-review, plan-review, per-task execution review, and final review. Each uses phase-specific dimensions from `docs/reference/review-loop-pattern.md`.
 
+**Key principle for `final` mode:** Compare implementation against the **ORIGINAL INPUT** (briefing + input files), NOT the task specs. The executor's per-task reviewer already validated against task specs — that concern is covered. The final reviewer catches drift: does what we built match what the user actually asked for?
+
+**Reviewer-owned responsibilities** (callers must NOT replicate these):
+1. **Two-tier review** — internal review first (fast, cheap, expertise-loaded), Codex second (fresh eyes on clean code)
+2. **Dimension selection** — the reviewer selects the correct dimension set for the review mode and depth
+3. **Pass counting** — the reviewer tracks pass numbers and enforces the depth-based cap (quick=3, standard=5, deep=7)
+4. **Finding attribution** — each finding is tagged `[Internal]`, `[Codex]`, or `[Both]` based on source
+5. **Dimension set recording** — each review pass file records which canonical dimension set was used, enabling Phase Scoring (first vs final delta)
+6. **Learning pipeline** — ALL findings (internal + Codex) feed into `state.sqlite` and the learning system
+
 ## Review Modes
 
 The reviewer operates in different modes depending on the phase. Mode MUST be passed explicitly by the caller (`--mode <mode>`). The reviewer does NOT auto-detect mode from artifact availability. If `--mode` is not provided, ask the user which review to run.
@@ -18,7 +48,7 @@ The reviewer operates in different modes depending on the phase. Mode MUST be pa
 | `final` | After execution + verification | Completed task artifacts, approved spec/plan/design | 7 final-review dims, scored 0-70 | Scored verdict (PASS/FAIL) |
 | `spec-challenge` | After specify | Draft spec artifact | 5 spec/clarification dims | Pass/fix loop, no score |
 | `design-review` | After design approval | Design artifact, approved spec | 5 design-review dims (canonical) | Pass/fix loop, no score |
-| `plan-review` | After planning | Draft plan artifact | 7 plan dims | Pass/fix loop, no score |
+| `plan-review` | After planning | Draft plan artifact | 8 plan dims (7 + input coverage) | Pass/fix loop, no score |
 | `task-review` | During execution, per task | Uncommitted changes or `--base` SHA | 5 task-execution dims (correctness, tests, wiring, drift, quality) | Pass/fix loop, no score |
 | `research-review` | During discover | Research artifact | 5 research dims | Pass/fix loop, no score |
 | `clarification-review` | During clarify | Clarification artifact | 5 spec/clarification dims | Pass/fix loop, no score |
@@ -34,6 +64,23 @@ In `task-review` and `final` modes, flag missing CHANGELOG entries for user-faci
 Prerequisites depend on the review mode:
 
 ### `final` mode
+
+**Phase Prerequisites (Hard Gate):** Before proceeding, verify ALL of these artifacts exist. If ANY is missing, **STOP** and report which are missing.
+
+- [ ] `.wazir/runs/latest/clarified/clarification.md`
+- [ ] `.wazir/runs/latest/clarified/spec-hardened.md`
+- [ ] `.wazir/runs/latest/clarified/design.md`
+- [ ] `.wazir/runs/latest/clarified/execution-plan.md`
+- [ ] `.wazir/runs/latest/artifacts/verification-proof.md`
+
+If any file is missing:
+
+> **Cannot run final review: missing prerequisite artifacts.**
+>
+> Missing: [list missing files]
+>
+> Run `/wazir:clarifier` (for clarified/* files) or `/wazir:executor` (for verification-proof.md) first.
+
 1. Check `.wazir/runs/latest/artifacts/` has completed task artifacts. If not, tell the user to run `/wazir:executor` first.
 2. Read the approved spec, plan, and design from `.wazir/runs/latest/clarified/`.
 3. Read `.wazir/state/config.json` for depth and multi_tool settings.
@@ -41,22 +88,42 @@ Prerequisites depend on the review mode:
 ### `task-review` mode
 1. Uncommitted changes exist for the current task, or a `--base` SHA is provided for committed changes.
 2. Read `.wazir/state/config.json` for depth and multi_tool settings.
+3. **Commit discipline check:** If uncommitted changes span work from multiple tasks (e.g., files from task N and task N+1 are both modified), REJECT immediately: "REJECTED: Multiple tasks in single commit. Split into per-task commits before review." This is a blocking finding — no other dimensions are evaluated until resolved.
+4. **Security sensitivity check:** Run `detectSecurityPatterns` from `tooling/src/checks/security-sensitivity.js` against the diff. If `triggered === true`, add the 6 security review dimensions (injection, auth bypass, data exposure, CSRF/SSRF, XSS, secrets leakage) to the standard 5 task-execution dimensions for this review pass. Security findings use severity levels: critical (exploitable), high (likely exploitable), medium (defense-in-depth gap), low (best-practice deviation).
 
 ### `spec-challenge`, `design-review`, `plan-review`, `research-review`, `clarification-review` modes
 1. The appropriate input artifact for the mode exists.
 2. Read `.wazir/state/config.json` for depth and multi_tool settings.
+3. **`plan-review` additional dimension — Input Coverage:**
+   - Read the original input/briefing from `.wazir/input/briefing.md` and any `input/*.md` files
+   - Count distinct items/requirements in the input
+   - Count tasks in the execution plan
+   - If `tasks_in_plan < items_in_input` → **HIGH** finding: "Plan covers [N] of [M] input items. Missing: [list of uncovered items]"
+   - If `tasks_in_plan >= items_in_input` → dimension passes
+   - One task MAY cover multiple input items if justified in the task description
+   - This is the review-level enforcement of the "no scope reduction" rule
 
 ## Review Process (`final` mode)
 
+**Before starting this phase, output to the user:**
+
+> **Final Review** — About to run adversarial 7-dimension review comparing your implementation against the original input, not just the task specs. The executor's per-task reviewer already validated correctness per-task — this catches drift between what you asked for and what was actually built.
+>
+> **Why this matters:** Without this, implementation drift ships undetected. Per-task review confirms each task matches its spec, but cannot catch: tasks that collectively miss the original intent, scope creep that added unrequested features, or acceptance criteria that were rewritten to match implementation instead of input.
+>
+> **Looking for:** Logic errors, missing features, dead code, unsubstantiated "it works" claims, scope creep, security gaps, stale documentation
+
+**Input:** Read the ORIGINAL user input (`.wazir/input/briefing.md`, `input/` directory files) and compare against what was built. This catches intent drift that task-level review misses.
+
 Perform adversarial review across 7 dimensions:
 
-1. **Correctness** — Does the code do what the spec says?
-2. **Completeness** — Are all acceptance criteria met?
-3. **Wiring** — Are all paths connected end-to-end?
-4. **Verification** — Is there evidence (tests, type checks) for each claim?
-5. **Drift** — Does the implementation match the approved plan?
-6. **Quality** — Code style, naming, error handling, security
-7. **Documentation** — Changelog entries, commit messages, comments
+1. **Correctness** — Does the code do what the original input asked for? *(catches: logic errors, wrong behavior, spec violations)*
+2. **Completeness** — Are all requirements from the original input met? *(catches: missing features, unimplemented acceptance criteria, partially delivered items)*
+3. **Wiring** — Are all paths connected end-to-end? *(catches: dead code, disconnected paths, missing imports, orphaned routes)*
+4. **Verification** — Is there evidence (tests, type checks) for each claim? *(catches: false claims of "it works" without evidence, untested code paths, missing type coverage)*
+5. **Drift** — Does the implementation match what the user originally requested? (not just the plan — the INPUT) *(catches: scope creep, plan deviations, unauthorized changes, gold-plating)*
+6. **Quality** — Code style, naming, error handling, security *(catches: security vulnerabilities, poor error handling, inconsistent naming, missing input validation)*
+7. **Documentation** — Changelog entries, commit messages, comments *(catches: missing changelogs, wrong commit messages, stale comments, undocumented breaking changes)*
 
 ## Context Retrieval
 
@@ -76,11 +143,28 @@ Score each dimension 0-10. Total out of 70.
 | **NEEDS REWORK** | 28-41 | Re-run affected tasks |
 | **FAIL** | 0-27 | Fundamental issues |
 
-## Secondary Review
+## Two-Tier Review Flow
+
+The review process has two tiers. Internal review catches ~80% of issues quickly and cheaply. Codex review provides fresh eyes on clean code.
+
+### Tier 1: Internal Review (Fast, Cheap, Expertise-Loaded)
+
+1. **Compose expertise:** Load relevant expertise modules from `expertise/composition-map.yaml` into context based on the review mode and detected stack. This gives the internal reviewer domain-specific knowledge.
+2. **Run internal review** using the dimension set for the current mode. When multi-model is enabled, use **Sonnet** (not Opus) for internal review passes — it's fast and good enough for pattern matching against expertise.
+3. **Produce findings:** Each finding is tagged `[Internal]` with severity (blocking, warning, note).
+4. **Fix cycle:** If blocking findings exist, the executor fixes them. Re-run internal review. Repeat until clean or cap reached.
+
+Internal review passes are logged to `.wazir/runs/latest/reviews/<mode>-internal-pass-<N>.md`.
+
+### Tier 2: External Review (Fresh Eyes on Clean Code)
+
+Only runs AFTER Tier 1 produces a clean pass (no blocking findings).
 
-Read `.wazir/state/config.json`. If `multi_tool.tools` includes external reviewers, run them **after** your own review and **before** producing the final verdict.
+Read `.wazir/state/config.json`. If `multi_tool.tools` includes external reviewers:
 
-### Codex Review
+#### Codex Review
+
+**For detailed Codex CLI usage, see `wz:codex-cli` skill.**
 
 If `codex` is in `multi_tool.tools`:
 
@@ -101,10 +185,10 @@ If `codex` is in `multi_tool.tools`:
      2>&1 | tee .wazir/runs/latest/reviews/codex-review.md
    ```
 
-2. Read the Codex findings from `.wazir/runs/latest/reviews/codex-review.md`
-3. Incorporate Codex findings into your scoring — if Codex flags something you missed, add it. If you disagree with a Codex finding, note it with your rationale.
+2. **Extract findings only** (context protection): After tee, use `execute_file` to extract only the final findings from the Codex output (everything after the last `codex` marker). If context-mode is unavailable, use `tac <file> | sed '/^codex$/q' | tac | tail -n +2`. If no marker found, fail closed (0 findings, warn user). See `docs/reference/review-loop-pattern.md` "Codex Output Context Protection" for full protocol.
+3. Incorporate extracted Codex findings into your scoring — if Codex flags something you missed, add it. If you disagree with a Codex finding, note it with your rationale.
 
-**Codex error handling:** If codex exits non-zero (auth/rate-limit/transport failure), log the full stderr, mark the pass as `codex-unavailable` in the review log, and use self-review findings only for that pass. Do NOT treat a Codex failure as a clean review. Do NOT skip the pass. The next pass still attempts Codex (transient failures may recover).
+**Codex error handling:** If codex exits non-zero (auth/rate-limit/transport failure), log the full stderr, mark the pass as `codex-unavailable` in the review log, and use internal review findings only for that pass. Do NOT treat a Codex failure as a clean review. Do NOT skip the pass. The next pass still attempts Codex (transient failures may recover).
 
 **Code review scoping by mode:**
 - Use `--uncommitted` when reviewing uncommitted changes (`task-review` mode).
@@ -112,16 +196,69 @@ If `codex` is in `multi_tool.tools`:
 - Use `codex exec -c model="$CODEX_MODEL"` with stdin pipe for non-code artifacts (`spec-challenge`, `design-review`, `plan-review`, `research-review`, `clarification-review` modes).
 - See `docs/reference/review-loop-pattern.md` for code review scoping rules.
 
-### Gemini Review
+#### Gemini Review
+
+If `gemini` is in `multi_tool.tools`, follow the same pattern using the Gemini CLI when available. **For detailed Gemini CLI usage, see `wz:gemini-cli` skill.**
+
+### Fix Cycle (Codex Findings)
 
-If `gemini` is in `multi_tool.tools`, follow the same pattern using the Gemini CLI when available.
+If Codex produces blocking findings:
+1. Executor fixes the Codex findings
+2. Re-run internal review (quick pass) to verify fixes didn't introduce regressions
+3. Optionally re-run Codex for a clean pass
 
 ### Merging Findings
 
 The final review report must clearly attribute each finding:
-- `[Wazir]` — found by primary review
-- `[Codex]` — found by Codex secondary review
-- `[Both]` — found independently by both
+- `[Internal]` — found by Tier 1 internal review
+- `[Codex]` — found by Tier 2 Codex review
+- `[Gemini]` — found by Tier 2 Gemini review
+- `[Both]` — found independently by multiple sources
+
+### Finding Persistence (Learning Pipeline)
+
+ALL findings from both tiers are persisted to `state.sqlite` for cross-run learning:
+
+```javascript
+// After each review pass
+const { insertFinding, getRecurringFindingHashes } = require('tooling/src/state/db');
+const db = openStateDb(stateRoot);
+
+for (const finding of allFindings) {
+  insertFinding(db, {
+    run_id: runId,
+    phase: reviewMode,
+    source: finding.attribution, // 'internal', 'codex', 'gemini'
+    severity: finding.severity,
+    description: finding.description,
+    finding_hash: hashFinding(finding.description),
+  });
+}
+
+// Check for recurring patterns
+const recurring = getRecurringFindingHashes(db, 2);
+// Recurring findings → auto-propose as learnings in the learn phase
+```
+
+This is how Wazir evolves — findings that recur across runs become accepted learnings injected into future executor context, preventing the same mistakes.
+
+## Interaction Mode Awareness
+
+Read `interaction_mode` from run-config:
+
+- **`auto`:** No user checkpoints. Present verdict and let gating agent decide. On escalation, write reason and STOP.
+- **`guided`:** Standard behavior — present verdict, ask user how to proceed.
+- **`interactive`:** Discuss findings with user: "I found a potential auth bypass in `src/auth.js:42` — here's why I rated it high severity. Do you agree, or is there context I'm missing?" Show detailed reasoning for each dimension score.
+
+## CLI/Context-Mode Enforcement
+
+In ALL review modes, check for these violations:
+
+1. **Index usage enforcement:** If the agent performed >5 direct file reads (Read tool) without a preceding `wazir index search-symbols` query, flag as **[warning]** finding: "Agent performed [N] direct file reads without using wazir index. Use `wazir index search-symbols <query>` before reading files to reduce context consumption."
+
+2. **Context-mode enforcement:** If the agent ran a large-category command (test runners, builds, diffs, dependency trees, linting — as classified by `hooks/routing-matrix.json`) using native Bash instead of context-mode tools (when context-mode is available), flag as **[warning]** finding: "Large command `[cmd]` run without context-mode. Route through `mcp__plugin_context-mode_context-mode__execute` to reduce context usage."
+
+These are warnings, not blocking findings — they improve efficiency but don't affect correctness.
 
 ## Task-Review Log Filenames
 
@@ -137,15 +274,223 @@ Save review results to `.wazir/runs/latest/reviews/review.md` with:
 - Score breakdown
 - Verdict
 
+Run the phase report and display it to the user:
+```bash
+wazir report phase --run <run-id> --phase <review-mode>
+```
+
+Output the report content to the user in the conversation.
+
+## Phase Report Generation
+
+After completing any review pass, generate a phase report following `schemas/phase-report.schema.json`:
+
+1. **`attempted_actions`** — Populate from the review findings. Each finding becomes an action entry:
+   - `description`: the finding summary
+   - `outcome`: `"success"` if the finding passed, `"fail"` if it is a blocking issue, `"uncertain"` if ambiguous
+   - `evidence`: the rationale or evidence supporting the outcome
+
+2. **`drift_analysis`** — Compare review findings against the approved spec:
+   - `delta`: count of deviations between implementation and spec (0 = no drift)
+   - `description`: summary of any drift detected and its impact
+
+3. **`quality_metrics`** — Populate from test, lint, and type-check results gathered during review:
+   - `test_pass_count`, `test_fail_count`: from test runner output
+   - `lint_errors`: from linter output
+   - `type_errors`: from type checker output
+
+4. **`risk_flags`** — Populate from any high-severity findings:
+   - `severity`: `"low"`, `"medium"`, or `"high"`
+   - `description`: what the risk is
+   - `mitigation`: recommended mitigation (if known)
+
+5. **`decisions`** — Populate from any scope or approach decisions made during the review:
+   - `description`: what was decided
+   - `rationale`: why
+   - `alternatives_considered`: other options evaluated (optional)
+   - `source`: `"[Wazir]"`, `"[Codex]"`, or `"[Both]"` (optional)
+
+6. **`verdict_recommendation`** — Set based on the gating rules in `config/gating-rules.yaml`:
+   - `verdict`: `"continue"` (PASS), `"loop_back"` (NEEDS MINOR FIXES / NEEDS REWORK), or `"escalate"` (FAIL with fundamental issues)
+   - `reasoning`: brief explanation of why this verdict was chosen
+
+### Report Output Paths
+
+Save reports to two formats under the run directory:
+- `.wazir/runs/<id>/reports/phase-<name>-report.json` — machine-readable, validated against `schemas/phase-report.schema.json`
+- `.wazir/runs/<id>/reports/phase-<name>-report.md` — human-readable Markdown summary
+
+The gating agent (`tooling/src/gating/agent.js`) consumes the JSON report to decide: **continue**, **loop_back**, or **escalate**.
+
+### Report Fields Reference
+
+All required fields per `schemas/phase-report.schema.json`:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `phase_name` | string | yes | Review mode name (e.g., `"final"`, `"task-review"`) |
+| `run_id` | string | yes | Current run identifier |
+| `timestamp` | string (date-time) | yes | ISO 8601 timestamp of report generation |
+| `attempted_actions` | array | yes | Findings mapped to action outcomes |
+| `drift_analysis` | object | yes | Spec-vs-implementation drift summary |
+| `quality_metrics` | object | yes | Test/lint/type results |
+| `risk_flags` | array | yes | High-severity risk items |
+| `decisions` | array | yes | Scope/approach decisions made |
+| `verdict_recommendation` | object | no | Gating verdict based on `config/gating-rules.yaml` |
+
+## Post-Review: Learn (final mode only)
+
+After the final review verdict, extract durable learnings using the **learner role** (`roles/learner.md`).
+
+### Step 1: Gather all findings
+
+Collect review findings from ALL sources in this run:
+- `.wazir/runs/<run-id>/reviews/` — all review pass logs (task-review, final review)
+- Codex findings (attributed `[Codex]` or `[Both]`)
+- Self-audit findings (if `run_audit` was enabled)
+
+### Step 2: Identify learning candidates
+
+A finding becomes a learning candidate if:
+- It recurred across 2+ review passes within this run (same issue found repeatedly)
+- It matches a finding from a prior run (check `memory/learnings/proposed/` and `accepted/` for similar patterns)
+- It represents a class of mistake, not just a single instance (e.g., "missing error handling in async functions" vs "missing try-catch on line 42")
+
+### Step 3: Write learning proposals
+
+For each candidate, write a proposal to `memory/learnings/proposed/<run-id>-<NNN>.md`:
+
+```markdown
+---
+artifact_type: proposed_learning
+phase: learn
+role: learner
+run_id: <run-id>
+status: proposed
+sources:
+  - <review-file-1>
+  - <review-file-2>
+approval_status: required
+---
+
+# Proposed Learning: <title>
+
+## Scope
+- **Roles:** [which roles should receive this learning — e.g., executor, reviewer]
+- **Stacks:** [which tech stacks — e.g., node, react, or "all"]
+- **Concerns:** [which concerns — e.g., error-handling, testing, security]
+
+## Evidence
+- [finding from review pass N: description]
+- [finding from review pass M: same pattern]
+- [optional: similar finding from prior run <run-id>]
+
+## Learning
+[The concrete, actionable instruction that should be injected into future executor context]
+
+## Expected Benefit
+[What this prevents in future runs]
+
+## Confidence
+- **Level:** low | medium | high
+- **Basis:** [single run observation | multi-run recurrence | user correction]
+```
+
+### Step 4: Report
+
+Present proposed learnings to the user:
+
+> **Learnings proposed:** [count]
+> - [title 1] (confidence: high, scope: executor/node)
+> - [title 2] (confidence: medium, scope: reviewer/all)
+>
+> Proposals saved to `memory/learnings/proposed/`. Review and accept with `/wazir audit learnings`.
+
+Learnings are NEVER auto-applied. They require explicit user acceptance before being injected into future runs.
+
+## Post-Review: Prepare Next (final mode only)
+
+After learning extraction, invoke the `prepare-next` skill to prepare the handoff:
+
+### Handoff document
+
+Write to `.wazir/runs/<run-id>/handoff.md`:
+
+```markdown
+# Handoff — <run-id>
+
+**Status:** [Completed | Partial]
+**Branch:** <branch-name>
+**Date:** YYYY-MM-DD
+
+## What Was Done
+[List of completed tasks with commit hashes]
+
+## Test Results
+[Test count, pass/fail, validator status]
+
+## Review Score
+[Final review verdict and score]
+
+## What's Next
+[Pending items, deferred work, follow-up tasks]
+
+## Open Bugs
+[Any known issues discovered during this run]
+
+## Learnings From This Run
+[Key insights — what worked, what didn't, what to change]
+```
+
+### Cleanup
+
+- Archive verbose intermediate review logs (compress to summary)
+- Update `.wazir/runs/latest` symlink if creating a new run
+- Do NOT mutate `input/` — it belongs to the user
+- Do NOT auto-load proposed learnings into the next run
+
+## Reasoning Output
+
+Throughout the reviewer phase, produce reasoning at two layers:
+
+**Conversation (Layer 1):** Before each review pass, explain what dimensions are being checked and why. After findings, explain the reasoning behind severity assignments.
+
+**File (Layer 2):** Write `.wazir/runs/<id>/reasoning/phase-reviewer-reasoning.md` with structured entries:
+- **Trigger** — what prompted the finding (e.g., "diff adds SQL query without parameterization")
+- **Options considered** — severity options, fix approaches
+- **Chosen** — assigned severity and recommendation
+- **Reasoning** — why this severity level
+- **Confidence** — high/medium/low
+- **Counterfactual** — what would ship if this finding were missed
+
+Key reviewer reasoning moments: severity assignments, PASS/FAIL decisions, dimension score justifications, and escalation decisions.
+
 ## Done
 
+**After completing this phase, output to the user:**
+
+> **Final Review complete.**
+>
+> **Found:** [N] findings across 7 dimensions — [N] blocking, [N] warnings, [N] notes. Score: [score]/70 ([VERDICT]).
+>
+> **Without this phase:** [N] blocking issues would have shipped — including [specific examples: e.g., "missing error handler on /api/users endpoint", "auth middleware not wired to 3 routes", "CHANGELOG missing entry for breaking API change"]
+>
+> **Changed because of this work:** [List of issues caught and fixed during review passes, score improvement from first to final pass]
+
 Present the verdict and offer next steps:
 
 > **Review complete: [VERDICT] ([score]/70)**
 >
 > [Score breakdown and findings summary]
 >
-> **What would you like to do?**
-> 1. **Create a PR** (if PASS)
-> 2. **Auto-fix and re-review** (if MINOR FIXES)
-> 3. **Review findings in detail**
+> **Learnings proposed:** [count] (see `memory/learnings/proposed/`)
+> **Handoff:** `.wazir/runs/<run-id>/handoff.md`
+
+Ask the user via AskUserQuestion:
+- **Question:** "How would you like to proceed with the review results?"
+- **Options:**
+  1. "Create a PR" *(Recommended if PASS)*
+  2. "Auto-fix and re-review" *(Recommended if MINOR FIXES)*
+  3. "Review findings in detail"
+
+Wait for the user's selection before continuing.

package/skills/run-audit/SKILL.md

@@ -5,6 +5,19 @@ description: Run a structured audit on your codebase — security, code quality,
 
 # Run Audit — Structured Codebase Audit Pipeline
 
+## Command Routing
+Follow the Canonical Command Matrix in `hooks/routing-matrix.json`.
+- Large commands (test runners, builds, diffs, dependency trees, linting) → context-mode tools
+- Small commands (git status, ls, pwd, wazir CLI) → native Bash
+- If context-mode unavailable, fall back to native Bash with warning
+
+## Codebase Exploration
+1. Query `wazir index search-symbols <query>` first
+2. Use `wazir recall file <path> --tier L1` for targeted reads
+3. Fall back to direct file reads ONLY for files identified by index queries
+4. Maximum 10 direct file reads without a justifying index query
+5. If no index exists: `wazir index build && wazir index summarize --tier all`
+
 ## Overview
 
 This skill runs a structured audit on your codebase. It collects three parameters interactively (audit type, scope, output mode), then feeds them through the pipeline: Research → Audit → Report or Plan.

package/skills/scan-project/SKILL.md

@@ -5,6 +5,19 @@ description: Build a project profile from manifests, docs, tests, and `input/` s
 
 # Scan Project
 
+## Command Routing
+Follow the Canonical Command Matrix in `hooks/routing-matrix.json`.
+- Large commands (test runners, builds, diffs, dependency trees, linting) → context-mode tools
+- Small commands (git status, ls, pwd, wazir CLI) → native Bash
+- If context-mode unavailable, fall back to native Bash with warning
+
+## Codebase Exploration
+1. Query `wazir index search-symbols <query>` first
+2. Use `wazir recall file <path> --tier L1` for targeted reads
+3. Fall back to direct file reads ONLY for files identified by index queries
+4. Maximum 10 direct file reads without a justifying index query
+5. If no index exists: `wazir index build && wazir index summarize --tier all`
+
 Inspect the smallest set of repo surfaces needed to answer:
 
 - what kind of project this is