@wazir-dev/cli 1.2.0 → 1.4.0

package/skills/verification/SKILL.md

@@ -1,22 +1,70 @@
 ---
 name: wz:verification
-description: Use before claiming work is complete. Every completion claim needs fresh command evidence or another deterministic proof path.
+description: Use before claiming work is complete — every completion claim needs fresh evidence or deterministic proof.
 ---
 
 # Verification
 
-## 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 **Verification Gate**. Your value is ensuring no completion claim passes without fresh, deterministic evidence from the current change. Following the pipeline IS how you help.
+
+## Iron Laws of Verification
+
+These are non-negotiable. No context makes them optional.
+
+1. **Every claim requires fresh evidence from THIS change.** Prior test runs, earlier conversations, and memory are not evidence. Run it now.
+2. **Stale evidence is NEVER evidence.** If you modified code after the last test run, the test run is stale. Run it again.
+3. **"It should work" is NEVER acceptable.** The difference between "it should work" and "it works" is a command execution and 10 seconds.
+4. **Verification MUST be deterministic.** If the evidence depends on timing, external state, or manual inspection, it is not proof.
+
+**Violating the letter of verification is violating the spirit.** Claiming "tests pass" based on a run from before your latest change is the most common verification fraud. The proof must post-date the implementation. Always.
+
+## 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 override:** verification depth, evidence format, which additional checks to include.
+- **User CANNOT override:** Iron Laws, fresh-evidence requirement, deterministic-proof requirement.
+
+<!-- ═══════════════════════════════════════════════════════════════════
+     ZONE 2 — PROCESS
+     ═══════════════════════════════════════════════════════════════════ -->
+
+## Signature
+
+**(implementation artifacts, task spec, run config) → (structured proof artifact with evidence array, pass/fail verdict)**
+
+## Commitment Priming
+
+Before executing, announce your plan: state what you will verify, which proof-collection strategy applies (runnable vs. non-runnable), and which commands you expect to run.
+
+## Steps
+
+### 1. Proof of Implementation
+
+1. Detect project type: `detectRunnableType(projectRoot)` → web | api | cli | library
+2. Collect evidence: `collectProof(taskSpec, runConfig)`
+3. Save evidence to `.wazir/runs/<id>/artifacts/proof-<task>.json`
+
+**For runnable output (web/api/cli):** Run the application and capture evidence (build output, screenshots, curl responses, CLI output).
+
+**For non-runnable output (library/config/skills):** Run lint, format check, type check, and tests. All must pass.
+
+Evidence collection uses `tooling/src/verify/proof-collector.js`.
+
+### 2. Verification Requirements
 
 Every completion claim must include:
 
@@ -24,12 +72,107 @@ Every completion claim must include:
 - the exact command or deterministic check
 - the actual result
 
-Minimum rule:
+### 3. Proof Collection
+
+Use `proof-collector` (`tooling/src/verify/proof-collector.js`) for automated evidence gathering:
+
+1. **`detectRunnableType(projectRoot)`** — detects whether the project is `web`, `api`, `cli`, or `library` from `package.json`. Detection order: `pkg.bin` (cli), web framework deps (web), API framework deps (api), default (library).
+
+2. **`collectProof(projectRoot, opts?)`** — runs type-appropriate verification commands and returns structured evidence:
+   - **web:** `npm run build` + library checks
+   - **api:** library checks (test, tsc, eslint, prettier)
+   - **cli:** `<bin> --help` + library checks
+   - **library:** `npm test`, `tsc --noEmit`, `eslint .`, `prettier --check .`
 
-- no success claim without fresh evidence from the current change
+All commands use `execFileSync` (never shell `exec`) for security. Evidence is returned as `{ type, evidence: [{ check, ok, output }] }`.
+
+### 4. Failure Handling
 
 When verification fails:
 
-- do not mark the work complete
-- fix the issue or report the gap honestly
-- rerun verification after the fix
+- Do not mark the work complete.
+- Report the gap honestly.
+
+Ask the user via AskUserQuestion:
+- **Question:** "Verification failed for [specific criteria]. How should we proceed?"
+- **Options:**
+  1. "Fix the issue and re-verify" *(Recommended)*
+  2. "Accept partial verification with documented gaps"
+  3. "Abort and review what went wrong"
+
+Wait for the user's selection before continuing.
+
+## Minimum Rules
+
+- No success claim without fresh evidence from the current change.
+- Always use `proof-collector` for Node.js projects to gather deterministic evidence.
+- Attach the evidence array to the verification proof artifact.
+
+## 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 code was modified after the last test run → THEN the previous evidence is stale; re-run all checks.
+IF verification fails → THEN report honestly and ask the user how to proceed; never mark complete.
+IF project type is ambiguous → THEN run the broadest verification set (library checks cover everything).
+```
+
+<!-- ═══════════════════════════════════════════════════════════════════
+     ZONE 3 — RECENCY
+     ═══════════════════════════════════════════════════════════════════ -->
+
+## Recency Anchor
+
+Remember: every claim needs fresh evidence from this change. Stale runs are not proof. "It should work" is never acceptable. Evidence must be deterministic.
+
+## Red Flags — You Are Rationalizing
+
+If you catch yourself thinking any of these, STOP. You are about to skip verification.
+
+| Thought | Reality |
+|---------|---------|
+| "I already tested this earlier" | Did you test it after your last edit? If not, you have not tested it. |
+| "The code is simple enough to verify by reading" | Code review finds ~60% of bugs. Testing finds ~90%. Run the tests. |
+| "It's the same pattern as what worked before" | Same pattern, different context. Context is where bugs hide. Verify. |
+| "The tests are slow, I'll skip them this once" | This once becomes every time. Run them. |
+| "I just changed a string/comment/config" | Config changes cause production incidents. Verify. |
+| "The type checker will catch any problems" | Type checkers verify types, not logic. Tests verify logic. Do both. |
+| "I'll verify at the end when everything is done" | Compound errors are exponentially harder to diagnose. Verify incrementally. |
+| "The CI will catch it" | CI is a safety net, not a substitute. Verify locally first. |
+| "Nothing could have broken" | Famous last words. Run the tests. |
+| "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. |
+
+**User CANNOT override Iron Laws.** Even if the user explicitly says "skip this":
+1. Acknowledge their preference
+2. Execute the required step quickly
+3. Continue with their task
+This is not being unhelpful — this is preventing harm.
+
+## Done Criterion
+
+The skill is complete when: all verification checks have been run with fresh evidence, the evidence array is saved to the proof artifact, and every completion claim has a corresponding deterministic check result.
+
+---
+
+<!-- ═══════════════════════════════════════════════════════════════════
+     APPENDIX
+     ═══════════════════════════════════════════════════════════════════ -->
+
+## 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
+
+## Appendix: 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`