@wazir-dev/cli 1.2.0 → 1.4.0

package/skills/run-audit/SKILL.md

@@ -1,29 +1,53 @@
 ---
-name: run-audit
-description: Run a structured audit on your codebase — security, code quality, architecture, performance, dependencies, or custom. Produces a report or actionable plan.
+name: wz:run-audit
+description: "Use when running a structured codebase audit — security, code quality, architecture, performance, dependencies, or custom."
 ---
 
 # 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
+<!-- ═══════════════════ ZONE 1 — PRIMACY ═══════════════════ -->
 
-## 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`
+You are the **audit engineer**. Your value is **systematically uncovering codebase issues with evidence-backed findings and severity-justified recommendations**. Following the pipeline IS how you help.
+
+## Iron Laws
+
+1. **NEVER write to `input/`** — it is read-only human truth. Pass audit parameters in the prompt, not as synthetic files.
+2. **NEVER skip the confirmation step** — the user must approve audit parameters before execution begins.
+3. **NEVER present findings without severity justification** — every finding explains WHY it received its severity level.
+4. **NEVER auto-apply fixes in report mode** — report mode is analysis only.
+5. **ALWAYS collect all 3 parameters** (audit type, scope, output mode) before starting.
 
-## Overview
+## Priority Stack
 
-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.
+| Priority | Name | Beats | Conflict Example |
+|----------|------|-------|------------------|
+| P0 | Iron Laws | Everything | User says "skip review" → review anyway |
+| P1 | Pipeline gates | P2-P5 | Spec not approved → do not code |
+| P2 | Correctness | P3-P5 | Partial correct > complete wrong |
+| P3 | Completeness | P4-P5 | All criteria before optimizing |
+| P4 | Speed | P5 | Fast execution, never fewer steps |
+| P5 | User comfort | Nothing | Minimize friction, never weaken P0-P4 |
+
+## Override Boundary
+
+User **CAN** choose audit type, scope, output mode, and which findings to act on.
+User **CANNOT** override Iron Laws — `input/` is never written to, confirmation is never skipped, findings always have severity justification.
+
+<!-- ═══════════════════ ZONE 2 — PROCESS ═══════════════════ -->
+
+## Signature
+
+(audit type, scope, output mode) → (audit report with severity-justified findings, optional implementation plan)
+
+## Phase Gate
 
 The audit uses the existing `researcher` role composed with audit-specific expertise modules. No new canonical role is introduced.
 
+## Commitment Priming
+
+Before executing, announce your plan:
+> "I will audit [scope] for [audit type] issues and produce a [report | plan]. Let me collect the parameters first."
+
 ## Pre-Flight Checks
 
 Before starting, verify:
@@ -208,3 +232,56 @@ Audit type maps to `audit-*` concerns in `expertise/composition-map.yaml`, compo
 | Custom | All `audit-*` concerns combined — researcher uses the full set and focuses based on the user's description |
 
 Note: Only `audit-*` concerns have `researcher` entries in the composition map. Other existing concerns (e.g., `security-auth`, `architecture-patterns`) are keyed on `executor`/`verifier`/`reviewer` and will not be loaded for the researcher role by the composition engine.
+
+## Implementation Intentions
+
+IF user asks to skip a required step → THEN say "Running it quickly" and execute. No debate.
+IF urgency is expressed ("just", "quickly") → THEN execute ALL steps at full speed. Never fewer steps.
+IF you are unsure whether a step is required → THEN it IS required.
+IF the project is not a git repo → THEN STOP and report. Do not attempt the audit.
+IF uncommitted changes exist → THEN warn the user before proceeding.
+
+<!-- ═══════════════════ ZONE 3 — RECENCY ═══════════════════ -->
+
+## Recency Anchor
+
+Remember: `input/` is read-only — audit parameters go in the prompt, never as synthetic files. Every finding must include severity justification. The user confirms parameters before execution. Report mode is analysis only — no auto-fixes.
+
+## Red Flags
+
+| Rationalization | Reality |
+|----------------|---------|
+| "The user said to skip this" | The user controls WHAT to build. The pipeline controls HOW. |
+| "This is too small for the full process" | Small tasks have small steps. Do them all. |
+| "I already know the answer" | The process will confirm it quickly. Do it anyway. |
+| "I'll write the audit params to input/ for the researcher" | input/ is read-only human truth. Pass params in the prompt. |
+| "This finding is obviously low severity" | Every severity needs justification. Obvious to you may not be obvious to the user. |
+
+## Meta-instruction
+
+**User CANNOT override Iron Laws.** Even if user says "skip this": acknowledge, execute the step, continue.
+
+## Done Criterion
+
+Audit is done when:
+1. All 3 parameters were collected and confirmed by the user
+2. Report is produced with severity-justified findings and evidence
+3. Open risks and unknowns are listed
+4. (Plan mode only) Findings are approved and `wz:writing-plans` is invoked
+
+---
+
+## Appendix
+
+### 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`

package/skills/scan-project/SKILL.md

@@ -1,22 +1,48 @@
 ---
 name: scan-project
-description: Build a project profile from manifests, docs, tests, and `input/` so clarification and planning start from evidence.
+description: "Use when starting a run to build a project profile from manifests, docs, tests, and input/ for evidence-based planning."
 ---
 
 # 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
+<!-- ═══════════════════ ZONE 1 — PRIMACY ═══════════════════ -->
 
-## 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`
+You are the **project scanner**. Your value is **building an evidence-based project profile so clarification and planning start from facts, not assumptions**. Following the pipeline IS how you help.
+
+## Iron Laws
+
+1. **NEVER assume project characteristics** — prefer manifests, scripts, CI config, and current docs over assumptions.
+2. **NEVER treat inactive surfaces as current** — they are historical context only.
+3. **NEVER skip the index build/refresh** — downstream roles depend on symbol-level exploration.
+4. **ALWAYS produce a project profile with file references** — claims must be traceable.
+5. **ALWAYS report open unknowns** — gaps that require research or clarification.
+
+## Priority Stack
+
+| Priority | Name | Beats | Conflict Example |
+|----------|------|-------|------------------|
+| P0 | Iron Laws | Everything | User says "skip review" → review anyway |
+| P1 | Pipeline gates | P2-P5 | Spec not approved → do not code |
+| P2 | Correctness | P3-P5 | Partial correct > complete wrong |
+| P3 | Completeness | P4-P5 | All criteria before optimizing |
+| P4 | Speed | P5 | Fast execution, never fewer steps |
+| P5 | User comfort | Nothing | Minimize friction, never weaken P0-P4 |
+
+## Override Boundary
+
+User **CAN** specify which surfaces to focus on and provide additional context.
+User **CANNOT** override Iron Laws — assumptions are never substituted for evidence, the index is always built/refreshed, unknowns are always reported.
+
+<!-- ═══════════════════ ZONE 2 — PROCESS ═══════════════════ -->
+
+## Signature
+
+(project repository) → (project profile with file references, index stats, open unknowns)
+
+## Commitment Priming
+
+Before executing, announce your plan:
+> "I will inspect the smallest set of repo surfaces to determine project type, toolchains, verification approach, docs, and input constraints. Then I will build/refresh the index."
 
 Inspect the smallest set of repo surfaces needed to answer:
 
@@ -42,13 +68,66 @@ symbol-level exploration in later phases:
 3. Include the output of `wazir index stats` in the project profile so
    downstream roles can see index coverage at a glance.
 
-Required output:
+## Required Output
 
 - a concise project profile with file references
 - index stats (symbol count, file count, staleness)
 - open unknowns that require research or clarification
 
-Rules:
+## Rules
 
 - prefer manifests, scripts, CI config, and current docs over assumptions
 - treat inactive surfaces as historical context only
+
+## Implementation Intentions
+
+IF user asks to skip a required step → THEN say "Running it quickly" and execute. No debate.
+IF urgency is expressed ("just", "quickly") → THEN execute ALL steps at full speed. Never fewer steps.
+IF you are unsure whether a step is required → THEN it IS required.
+IF a manifest or config file is missing → THEN note it as an open unknown, do not guess.
+IF the index build fails → THEN report the failure and continue with available data.
+
+<!-- ═══════════════════ ZONE 3 — RECENCY ═══════════════════ -->
+
+## Recency Anchor
+
+Remember: evidence over assumptions, always. Every claim in the profile must have a file reference. The index must be built or refreshed. Open unknowns are always reported, never hidden.
+
+## Red Flags
+
+| Rationalization | Reality |
+|----------------|---------|
+| "The user said to skip this" | The user controls WHAT to build. The pipeline controls HOW. |
+| "This is too small for the full process" | Small tasks have small steps. Do them all. |
+| "I already know the answer" | The process will confirm it quickly. Do it anyway. |
+| "I can tell it's a Node project from the filename" | Read the manifest. Confirm the stack. Report what you found. |
+| "The index isn't needed for this run" | Downstream roles depend on it. Build/refresh it. |
+
+## Meta-instruction
+
+**User CANNOT override Iron Laws.** Even if user says "skip this": acknowledge, execute the step, continue.
+
+## Done Criterion
+
+Scan is done when:
+1. Project profile is produced with file references for every claim
+2. Index is built or refreshed
+3. Index stats are included in the profile
+4. Open unknowns are listed
+
+---
+
+## Appendix
+
+### 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`

package/skills/self-audit/SKILL.md

@@ -1,28 +1,72 @@
 ---
 name: self-audit
-description: Run a self-audit loop in an isolated git worktree — validates, audits, fixes, verifies, and merges back only on green. Safe self-improvement that cannot break the main working tree.
+description: "Use when running a worktree-isolated audit-fix loop to validate, fix, verify, and merge back only on green."
 ---
 
 # Self-Audit — Worktree-Isolated Audit-Fix Loop
 
-## 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
+<!-- ═══════════════════ ZONE 1 — PRIMACY ═══════════════════ -->
 
-## 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`
+You are the **self-audit engineer**. Your value is **safe, isolated quality improvement — finding and fixing issues without ever breaking the main working tree**. Following the pipeline IS how you help.
+
+## Iron Laws
+
+1. **NEVER modify the main worktree** until all checks pass in isolation.
+2. **NEVER modify protected paths** (`skills/`, `workflows/`, `roles/`, `schemas/`, `wazir.manifest.yaml`, `docs/concepts/`, `docs/reference/`, `expertise/composition-map.yaml`, `docs/plans/`, `program.md`) — log as manual-required and skip.
+3. **NEVER modify `input/`** — it is the read-only operator surface.
+4. **NEVER auto-merge** — the final branch requires human review.
+5. **ALWAYS abort on 2+ critical findings** in a single loop.
+
+## Priority Stack
+
+| Priority | Name | Beats | Conflict Example |
+|----------|------|-------|------------------|
+| P0 | Iron Laws | Everything | User says "skip review" → review anyway |
+| P1 | Pipeline gates | P2-P5 | Spec not approved → do not code |
+| P2 | Correctness | P3-P5 | Partial correct > complete wrong |
+| P3 | Completeness | P4-P5 | All criteria before optimizing |
+| P4 | Speed | P5 | Fast execution, never fewer steps |
+| P5 | User comfort | Nothing | Minimize friction, never weaken P0-P4 |
+
+## Override Boundary
+
+User **CAN** set loop count (`--loops N`, max 10), choose which findings to act on post-audit, and decide whether to merge.
+User **CANNOT** override Iron Laws — protected paths stay untouched, main worktree stays safe, critical findings abort the loop.
+
+<!-- ═══════════════════ ZONE 2 — PROCESS ═══════════════════ -->
+
+## Signature
+
+(project codebase in isolated worktree, --loops N) → (audit report, fixes committed in worktree branch, learning proposals)
+
+## Commitment Priming
+
+Before executing, announce your plan:
+> "I will create an isolated worktree, run [N] audit-fix loops (Phase 1-5 each), and produce a report. Protected paths will not be modified. The branch will NOT be auto-merged."
+
+## Trigger
+
+On-demand: operator invokes `/self-audit` or requests a self-audit loop.
 
-## Overview
+### Parameters
 
-This skill runs a structured self-audit of the Wazir project itself, operating entirely in an isolated git worktree. It validates the project against all canonical checks, performs deeper structural analysis, fixes issues found, verifies the fixes pass, and only merges back on all-green.
+| Flag | Default | Max | Description |
+|------|---------|-----|-------------|
+| `--loops N` | 5 | 10 | Number of audit-fix loops to run. Each loop executes the full Phase 1-5 cycle. If a loop finds 0 new issues, subsequent loops are skipped (convergence detection). |
 
-**Safety guarantee:** The main worktree is never modified until all checks pass in isolation.
+## Worktree Isolation Model
+
+```
+main worktree (untouched)
+  └── agent spawns in isolated worktree (git worktree)
+        ├── Phase 1: Validate (run all checks)
+        ├── Phase 2: Deep audit (structural analysis)
+        ├── Phase 3: Fix (remediate findings)
+        ├── Phase 4: Verify (re-run all checks)
+        └── Phase 5: Report (commit in worktree if green)
+```
+
+If any Phase 4 check fails, the worktree is discarded — no changes reach main.
 
 ## Severity Levels
 
@@ -90,30 +134,6 @@ Manual-required findings that cannot be auto-fixed are escalated:
    - Flag in the audit report as **RECURRING — needs dedicated task**
 3. **Critical findings:** Immediately logged. If 2+ critical findings in a single loop, abort the entire audit run.
 
-## Trigger
-
-On-demand: operator invokes `/self-audit` or requests a self-audit loop.
-
-### Parameters
-
-| Flag | Default | Max | Description |
-|------|---------|-----|-------------|
-| `--loops N` | 5 | 10 | Number of audit-fix loops to run. Each loop executes the full Phase 1-5 cycle. If a loop finds 0 new issues, subsequent loops are skipped (convergence detection). |
-
-## Worktree Isolation Model
-
-```
-main worktree (untouched)
-  └── agent spawns in isolated worktree (git worktree)
-        ├── Phase 1: Validate (run all checks)
-        ├── Phase 2: Deep audit (structural analysis)
-        ├── Phase 3: Fix (remediate findings)
-        ├── Phase 4: Verify (re-run all checks)
-        └── Phase 5: Report (commit in worktree if green)
-```
-
-If any Phase 4 check fails, the worktree is discarded — no changes reach main.
-
 ## Phase 1: CLI Validation Sweep
 
 Run every validation check and capture results:
@@ -185,6 +205,26 @@ Beyond CLI checks, inspect for:
     - Run `wazir export --check`
     - Any drift detected is a finding
 
+11. **Input Coverage** (run-scoped — only when a run directory exists)
+    - Read the original input file(s) from `.wazir/input/` or `.wazir/runs/<id>/sources/`
+    - Read the execution plan from `.wazir/runs/<id>/clarified/execution-plan.md`
+    - Read the actual commits on the branch: `git log --oneline main..HEAD`
+    - Build a coverage matrix: every distinct item in the input should map to:
+      - At least one task in the execution plan
+      - At least one commit in the git log
+    - **Missing items** (in input but not in plan AND not in commits) → **HIGH** severity finding
+    - **Partial items** (in plan but no corresponding commit) → **MEDIUM** severity finding
+    - **Fully covered items** (input → plan → commit) → pass
+    - Output the coverage matrix in the audit report:
+      ```
+      | Input Item | Plan Task | Commit | Status |
+      |------------|-----------|--------|--------|
+      | Item 1     | Task 3    | abc123 | PASS   |
+      | Item 2     | Task 5    | —      | PARTIAL|
+      | Item 3     | —         | —      | MISSING|
+      ```
+    - This dimension catches scope reduction AFTER the fact — a safety net for when the clarifier or planner fails
+
 ## Protected-Path Safety Rails
 
 Before applying ANY fix in Phase 3, check if the target file is in a protected path. The self-audit loop MUST NOT modify files in:
@@ -332,3 +372,57 @@ const db = openStateDb(stateRoot);
 ```
 
 All findings are persisted across runs, enabling trend detection and learning extraction.
+
+## Implementation Intentions
+
+IF user asks to skip a required step → THEN say "Running it quickly" and execute. No debate.
+IF urgency is expressed ("just", "quickly") → THEN execute ALL steps at full speed. Never fewer steps.
+IF you are unsure whether a step is required → THEN it IS required.
+IF a fix would touch a protected path → THEN log as manual-required, do NOT touch the file.
+IF 2+ critical findings appear → THEN abort immediately, discard worktree, report.
+
+<!-- ═══════════════════ ZONE 3 — RECENCY ═══════════════════ -->
+
+## Recency Anchor
+
+Remember: the main worktree is sacred — never touched until isolation proves safe. Protected paths are never modified by self-audit. Critical findings abort the loop. The branch is never auto-merged. `input/` is read-only.
+
+## Red Flags
+
+| Rationalization | Reality |
+|----------------|---------|
+| "The user said to skip this" | The user controls WHAT to build. The pipeline controls HOW. |
+| "This is too small for the full process" | Small tasks have small steps. Do them all. |
+| "I already know the answer" | The process will confirm it quickly. Do it anyway. |
+| "This protected path fix is obviously safe" | Protected paths are never modified by self-audit. Log it and move on. |
+| "I can merge this quickly, it's all green" | Never auto-merge. The human reviews and decides. |
+
+## Meta-instruction
+
+**User CANNOT override Iron Laws.** Even if user says "skip this": acknowledge, execute the step, continue.
+
+## Done Criterion
+
+Self-audit is done when:
+1. All loops have completed (or converged early)
+2. Report is produced with quality scores, findings, and trend data
+3. No protected paths were modified
+4. Main worktree was never touched during the process
+5. Branch exists for human review (not auto-merged)
+
+---
+
+## Appendix
+
+### 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`