@wazir-dev/cli 1.0.0 → 1.2.0

package/docs/reference/skill-tiers.md

@@ -0,0 +1,147 @@
+# Skill Tier Classification
+
+Audit of Wazir skills against Superpowers v4.3.1 skills.
+Each skill is classified into one of three tiers:
+
+- **Delegate** -- use superpowers skill as-is, delete Wazir fork
+- **Augment** -- use superpowers skill + inject Wazir context addendum (strictly additive, no overrides). **NOTE:** R2 validation found this tier is not implementable -- see [Augment Mechanism](#augment-mechanism) below.
+- **Own** -- Wazir-original or structurally rewritten skill, rename to `wz:` prefix
+
+---
+
+## Classification Table
+
+| Wazir Skill | Superpowers Equivalent | Tier | Rationale | Risk Notes |
+|---|---|---|---|---|
+| brainstorming | brainstorming | **Own** | Structurally rewritten. Superpowers version is a linear checklist (explore context, ask questions, propose approaches, present design, write doc, invoke writing-plans). Wazir replaces the entire process: adds Command Routing and Codebase Exploration preambles, replaces the design-doc step with a design-review loop (`--mode design-review` with canonical dimensions), outputs to `.wazir/runs/latest/clarified/design.md` instead of `docs/plans/`, and adds a complete Agent Teams multi-agent brainstorming mode (Free Thinker / Grounder / Synthesizer / Arbiter pattern using TeamCreate/SendMessage). None of the superpowers process steps survive intact. | Dropping the Agent Teams mode would lose Wazir's most differentiated brainstorming capability. |
+| clarifier | _(none)_ | **Own** | Wazir-original. No superpowers counterpart exists. | -- |
+| debugging | systematic-debugging | **Own** | Structurally rewritten. Superpowers has a 4-phase process (Root Cause Investigation with 5 substeps, Pattern Analysis, Hypothesis and Testing, Implementation) totaling ~300 lines with detailed examples, rationalization tables, and supporting technique references. Wazir condenses this to a 4-step observe-hypothesize-test-fix loop (~75 lines), replaces all codebase exploration with Wazir CLI symbol-first exploration (`wazir index search-symbols`, `wazir recall symbol` and `wazir recall file`), adds loop cap awareness (pipeline mode with `wazir capture loop-check` vs. standalone mode), and removes all superpowers examples, rationalization tables, and red-flag lists. The methodology is fundamentally different in structure despite sharing the spirit of "root cause first." | Delegating would lose Wazir CLI integration and loop cap awareness. Superpowers version is far more detailed on anti-patterns and may be worth referencing separately. |
+| design | _(none)_ | **Own** | Wazir-original. No superpowers counterpart exists. | -- |
+| dispatching-parallel-agents | dispatching-parallel-agents | **Own** | Reclassified from Augment to Own (R2). Skill shadowing is full-override, so Augment tier is not implementable via `~/.claude/skills/`. Wazir already carries the full content: superpowers core (When to Use decision tree, The Pattern with 4 steps, Agent Prompt Structure, Common Mistakes section) plus Wazir additions (Command Routing preamble, Codebase Exploration preamble, philosophical paragraph in Overview, Problem/Fix format for Common Mistakes). Drops superpowers-only sections: "When NOT to Use," "Real Example from Session," "Key Benefits," "Verification," "Real-World Impact." | Superpowers informational sections (Real Example, Key Benefits, Verification, Real-World Impact) not carried forward. Low risk -- these are teaching content, not behavioral. |
+| executing-plans | executing-plans | **Own** | Structurally rewritten. Superpowers uses batch execution (default first 3 tasks) with report-and-wait checkpoints and explicit batch feedback loops. Wazir replaces batching with per-task execution, adds a per-task review loop (`--mode task-review` with 5 task-execution dimensions, Codex integration, review log filenames, loop cap tracking via `wazir capture loop-check`), adds standalone vs. pipeline mode detection, and adds a note recommending wz:subagent-driven-development when subagents are available. The batch-vs-per-task change is a core behavioral difference. All integration references point to `wz:` skills. | Delegating would lose per-task review loops and pipeline mode integration. |
+| executor | _(none)_ | **Own** | Wazir-original. No superpowers counterpart exists. | -- |
+| finishing-a-development-branch | finishing-a-development-branch | **Own** | Reclassified from Augment to Own (R2). Skill shadowing is full-override, so Augment tier is not implementable via `~/.claude/skills/`. Wazir already carries the full content: superpowers process (5 steps: verify tests, determine base branch, present 4 options, execute choice, cleanup worktree) preserved with identical structure and identical option semantics. Wazir adds Command Routing and Codebase Exploration preambles. Minor cosmetic changes: `<N>` removed from failure template, `<base-branch>` shortened to `<base>`, emoji checkmarks replaced with Y/-, `<commit-list>` changed to `<count>`, PR body simplified. Red Flags and Integration sections trimmed but no behavioral contradiction. | Low risk. The superpowers version has more detailed Red Flags and Integration sections not carried forward. |
+| humanize | _(none)_ | **Own** | Wazir-original. No superpowers counterpart exists. | -- |
+| init-pipeline | _(none)_ | **Own** | Wazir-original. No superpowers counterpart exists. | -- |
+| prepare-next | _(none)_ | **Own** | Wazir-original. No superpowers counterpart exists. | -- |
+| receiving-code-review | receiving-code-review | **Own** | Structurally rewritten. Superpowers has extensive sections: Forbidden Responses, Source-Specific Handling, YAGNI Check, Implementation Order, When To Push Back, Acknowledging Correct Feedback (with detailed anti-patterns for gratitude), Gracefully Correcting Pushback, Common Mistakes table, Real Examples, and GitHub Thread Replies. Wazir preserves the core Response Pattern and Forbidden Responses but: (1) adds Loop Tracking section (pipeline mode with `wazir capture loop-check` and standalone pass counts), (2) restructures Implementation Order to a 4-tier priority (blocking, functional, quality, nice-to-have) instead of 3-tier, (3) adds a Quick Reference decision table, (4) removes the entire "Acknowledging Correct Feedback" anti-gratitude section, the "Gracefully Correcting Pushback" section, the Common Mistakes table, all Real Examples, the "When To Push Back" enumeration, and the GitHub Thread Replies section. The Loop Tracking addition and structural deletions make this a substantive rewrite. | Delegating would lose loop tracking. The removed anti-gratitude and pushback sections from superpowers are valuable behavioral guardrails worth preserving. |
+| requesting-code-review | requesting-code-review | **Own** | Structurally rewritten. Both skills share the same When to Request triggers and Example structure. But Wazir: (1) replaces `superpowers:code-reviewer` with `wz:code-reviewer`, (2) adds explicit review loop parameters (`--mode`, depth-aware dimensions, pass number), (3) adds `codex review --uncommitted` and `codex review --base` commands, (4) adds Codex Error Handling section, (5) adds `{REVIEW_MODE}` placeholder, (6) changes Integration section to reference per-task review checkpoints instead of batch review, (7) adds "Dispatch review without explicit `--mode`" to Red Flags. The Codex integration and review loop parameter system are structural additions that change how reviews are dispatched. | Delegating would lose Codex integration and review loop protocol. |
+| reviewer | _(none)_ | **Own** | Wazir-original. No superpowers counterpart exists. | -- |
+| run-audit | _(none)_ | **Own** | Wazir-original. No superpowers counterpart exists. | -- |
+| scan-project | _(none)_ | **Own** | Wazir-original. No superpowers counterpart exists. | -- |
+| self-audit | _(none)_ | **Own** | Wazir-original. No superpowers counterpart exists. | -- |
+| subagent-driven-development | subagent-driven-development | **Own** | Structurally rewritten. Both share the same high-level process (fresh subagent per task, two-stage review, spec then quality). But Wazir: (1) adds `Capture PRE_TASK_SHA` step to the process flowchart for diff scoping, (2) adds Code Review Scoping section (`codex review --base <pre-task-sha>`), (3) adds Review Loop Alignment section (explicit `--mode task-review`, task-scoped log filenames, loop cap via `wazir capture loop-check`), (4) adds Codex Error Handling section, (5) adds standalone mode fallback, (6) changes all skill references from `superpowers:` to `wz:`, (7) adds "Review the wrong diff" to Red Flags, (8) removes the Example Workflow, Advantages detail, and Cost breakdown from superpowers. The diff-scoping and review-loop integration are structural process changes. | Delegating would lose diff-scoped reviews and Codex integration. The removed Example Workflow from superpowers is a useful teaching tool. |
+| tdd | test-driven-development | **Own** | Structurally rewritten. Superpowers has an exhaustive treatment (~370 lines): detailed Red-Green-Refactor with Good/Bad code examples, Iron Law with explicit "delete and start over" rules, a Verification Checklist, extensive Why Order Matters section, Common Rationalizations table, When Stuck guide, Testing Anti-Patterns reference, and Debugging Integration. Wazir condenses to ~45 lines with 3 steps (RED, GREEN, REFACTOR), adds a single-pass test quality check in RED phase ("Are these tests testing the right behavior? Are they real assertions?"), and removes all examples, rationalization tables, and elaboration. Different description and name (`wz:tdd` vs `test-driven-development`). | Delegating would lose the test quality check. The superpowers version's extensive rationalization prevention and examples are valuable for discipline enforcement but costly in tokens. |
+| using-git-worktrees | using-git-worktrees | **Own** | Reclassified from Augment to Own (R2). Skill shadowing is full-override, so Augment tier is not implementable via `~/.claude/skills/`. Wazir already carries the full content: superpowers core process (directory selection priority, safety verification with `git check-ignore`, creation steps, project setup auto-detection, clean baseline verification) preserved structurally intact. Wazir adds: Command Routing preamble, Codebase Exploration preamble, global directory changed from `~/.config/superpowers/worktrees/` to `~/.wazir/worktrees/`, Cleanup and Common Issues sections (submodules, lock files, stale worktrees). Drops superpowers-only sections: Example Workflow, Quick Reference table, Common Mistakes, Red Flags, Integration. | Dropped superpowers sections (Quick Reference, Common Mistakes, Red Flags, Integration) reduce operational guardrails. Could be recovered into the Own skill. |
+| using-skills | using-superpowers | **Own** | Structurally rewritten. Both enforce the same core rule (invoke skills before any response, even at 1% chance). But Wazir: (1) renames from `using-superpowers` to `using-skills`, (2) changes all internal skill references from `superpowers:` to `wz:` throughout flowchart and examples, (3) removes the Skill Types section detail about "Rigid vs Flexible" elaboration, (4) removes User Instructions elaboration. The name change and systematic `wz:` prefix replacement throughout the flowchart make this a namespace-level rewrite. | Could potentially be Augment if namespace mapping were handled at a routing layer rather than in-skill. |
+| verification | verification-before-completion | **Own** | Structurally rewritten. Superpowers has an exhaustive treatment (~140 lines): Iron Law, Gate Function (5-step IDENTIFY/RUN/READ/VERIFY/CLAIM), Common Failures table, Red Flags list, Rationalization Prevention table, Key Patterns (tests, regression, build, requirements, agent delegation), Why This Matters section with 24 failure memories, and When To Apply section. Wazir condenses to ~35 lines with 3 bullet requirements (what was verified, exact command, actual result), a minimum rule, and a brief "when verification fails" section. Different name (`wz:verification` vs `verification-before-completion`). | Delegating would lose the concise Wazir format. The superpowers version's extensive rationalization prevention is valuable for discipline but token-expensive. The Wazir version may be too terse to enforce the discipline effectively. |
+| wazir | _(none)_ | **Own** | Wazir-original. No superpowers counterpart exists. | -- |
+| writing-plans | writing-plans | **Own** | Structurally rewritten. Superpowers focuses on plan document format (header template, task structure with bite-sized steps, code examples in plan, execution handoff to subagent-driven or parallel session). Wazir: (1) changes inputs to "approved design or approved clarified direction" instead of "spec or requirements", (2) adds pipeline-aware output paths (`.wazir/runs/latest/clarified/execution-plan.md` and `.wazir/runs/latest/tasks/task-NNN/spec.md` vs. standalone `docs/plans/`), (3) removes the plan document format template entirely (no header template, no task structure template, no code examples), (4) adds Plan Review Loop section with `wz:reviewer --mode plan-review`, Codex integration via stdin pipe, Codex error handling, depth-aware pass counts, and standalone fallback. The plan review loop and pipeline path system are structural additions; the removal of the format template is a structural deletion. | Delegating would lose pipeline integration and plan review loop. The removed format template from superpowers is valuable for plan quality and could be worth recovering. |
+| writing-skills | writing-skills | **Own** | Structurally rewritten. Both share the TDD-for-skills philosophy and RED-GREEN-REFACTOR mapping. But Wazir: (1) condenses from ~650 lines to ~170 lines, (2) removes the extensive SKILL.md Structure template, CSO (Claude Search Optimization) section, Flowchart Usage guidelines, Code Examples guidelines, Token Efficiency section, File Organization examples, Testing All Skill Types section (discipline/technique/pattern/reference), Common Rationalizations for Skipping Testing table, Bulletproofing Skills Against Rationalization section (with Cialdini psychology reference), Skill Creation Checklist, Discovery Workflow, Anti-Patterns section, and STOP deployment gate, (3) adds "Be Prescriptive, Not Descriptive" guidance, "Use Rationalization Prevention" example, "Include Decision Trees" guidance, and skill reference syntax. The massive content reduction and different teaching approach make this a structural rewrite. | Delegating would lose the concise prescriptive format. The superpowers version's CSO guidelines, testing methodology, and anti-pattern catalog are extremely valuable reference material. |
+
+---
+
+## Superpowers Skills with No Wazir Counterpart
+
+These superpowers skills have no Wazir fork. They could be used as-is via the superpowers plugin.
+
+| Superpowers Skill | Status | Notes |
+|---|---|---|
+| using-superpowers | Replaced by `wz:using-skills` | See using-skills row above. |
+
+All 14 superpowers skills have a Wazir counterpart (using-superpowers maps to using-skills, systematic-debugging maps to debugging, test-driven-development maps to tdd, verification-before-completion maps to verification).
+
+---
+
+## Summary by Tier
+
+| Tier | Count | Skills |
+|---|---|---|
+| **Own** | 25 | brainstorming, clarifier, debugging, design, dispatching-parallel-agents, executing-plans, executor, finishing-a-development-branch, humanize, init-pipeline, prepare-next, receiving-code-review, requesting-code-review, reviewer, run-audit, scan-project, self-audit, subagent-driven-development, tdd, using-git-worktrees, using-skills, verification, wazir, writing-plans, writing-skills |
+| **Augment** | 0 | _(none -- tier not implementable, see [Augment Mechanism](#augment-mechanism))_ |
+| **Delegate** | 0 | _(none)_ |
+
+---
+
+## Common Wazir Additions (Appear in All Forked Skills)
+
+Every Wazir fork of a superpowers skill adds these two preamble sections:
+
+1. **Command Routing** -- routes large commands to context-mode tools and small commands to native Bash, following `hooks/routing-matrix.json`.
+2. **Codebase Exploration** -- prescribes symbol-first exploration via `wazir index search-symbols` and `wazir recall`, with fallback to direct file reads.
+
+These preambles alone would justify **Augment** tier for any skill where no other structural changes exist.
+
+---
+
+## Augment Mechanism
+
+**Research date:** 2026-03-19 (R2: Composition Infrastructure Validation)
+
+### Finding: Augment tier is not implementable
+
+The Augment tier assumed that placing a Wazir addendum at `~/.claude/skills/<skill-name>/SKILL.md` would layer Wazir context on top of the superpowers base skill. This assumption is wrong. **Skill shadowing is full-override, not merge/append.**
+
+### Evidence
+
+**1. `skills-core.js` `resolveSkillPath()` (superpowers v4.3.1)**
+
+The function at `lib/skills-core.js:108-140` checks personal skills directory first. If `~/.claude/skills/<name>/SKILL.md` exists, it returns that file immediately and never reads the superpowers version. There is no content merging.
+
+```
+// Try personal skills first (unless explicitly superpowers:)
+if (!forceSuperpowers && personalDir) {
+    const personalSkillFile = path.join(personalDir, actualSkillName, 'SKILL.md');
+    if (fs.existsSync(personalSkillFile)) {
+        return { skillFile: personalSkillFile, sourceType: 'personal', ... };
+        // ^^^ returns here -- superpowers version never consulted
+    }
+}
+```
+
+**2. Superpowers test suite confirms override behavior**
+
+`tests/opencode/test-skills-core.sh` line 336 asserts:
+```
+[PASS] Personal skills shadow superpowers skills
+```
+
+The test creates `personal-skills/shared-skill/SKILL.md` and `superpowers-skills/shared-skill/SKILL.md`, resolves `shared-skill`, and verifies `sourceType` is `"personal"` -- the superpowers version is invisible.
+
+**3. Superpowers RELEASE-NOTES.md v3.3.0**
+
+Line 385 documents the behavior explicitly: "Personal skills override superpowers skills when names match."
+
+**4. The `superpowers:` prefix bypass is not available in Claude Code**
+
+`skills-core.js` supports `superpowers:skill-name` syntax to force resolution to the superpowers version even when a personal skill shadows it. However, `skills-core.js` is only used by the OpenCode plugin (`/.opencode/plugins/superpowers.js`). Claude Code's native `Skill` tool has its own built-in resolution logic that does not expose this prefix bypass.
+
+### Alternatives Considered
+
+| Approach | Viable? | Why |
+|---|---|---|
+| Place addendum in `~/.claude/skills/<name>/` | No | Full override -- base skill content lost |
+| Merge base + addendum in SKILL.md at install time | Partial | Would work but creates a maintenance coupling: every superpowers update requires re-merging. This is functionally identical to Own tier. |
+| Inject Wazir context via CLAUDE.md | No | CLAUDE.md is project-scoped; skill behavior should be global across all projects |
+| Use `superpowers:` prefix to load base, then append | No | Prefix only works in OpenCode's `skills-core.js`, not in Claude Code's native Skill tool |
+| Propose upstream merge/append feature | Future | Would require a superpowers or Claude Code platform change |
+
+### Conclusion
+
+The Augment tier is architecturally impossible with the current skill discovery mechanism. All three former Augment skills (dispatching-parallel-agents, finishing-a-development-branch, using-git-worktrees) are reclassified to **Own** tier. Since the Wazir versions already carry the full superpowers base content plus Wazir additions, no content is lost -- the skills simply cannot delegate to a shared base.
+
+If superpowers or Claude Code introduces a composition/layering mechanism in the future (e.g., `extends: superpowers:dispatching-parallel-agents` in frontmatter), the Augment tier could be revisited.
+
+---
+
+## Observations
+
+1. **No Delegate candidates exist.** Every Wazir fork adds at minimum the Command Routing and Codebase Exploration preambles, which prevents pure delegation.
+
+2. **Augment tier is not implementable.** R2 validation (2026-03-19) found that skill shadowing in both superpowers `skills-core.js` and Claude Code's native Skill tool is full-override: placing a SKILL.md in `~/.claude/skills/<name>/` completely replaces the superpowers skill with the same name. There is no merge or append mechanism. The three former Augment candidates (dispatching-parallel-agents, finishing-a-development-branch, using-git-worktrees) have been reclassified to Own. See [Augment Mechanism](#augment-mechanism) for full analysis.
+
+3. **All 14 forked skills are Own** because either (a) they introduce structural process changes (review loops, pipeline mode, Codex integration, Agent Teams, content restructuring) or (b) the Augment composition mechanism does not exist in the platform.
+
+4. **Token cost tradeoff is significant.** Several Wazir Own skills (tdd, verification, debugging, writing-skills) are dramatically shorter than their superpowers counterparts. The superpowers versions contain valuable rationalization prevention tables, detailed examples, and anti-pattern catalogs that enforce discipline. The Wazir versions trade this for token efficiency. This tradeoff should be revisited -- some of the removed discipline content may be worth recovering as separate reference files.
+
+5. **The `wz:` prefix is already applied** in skill names within the Wazir SKILL.md frontmatter for all forked skills, consistent with the Own tier convention.

package/docs/reference/tooling-cli.md

@@ -15,6 +15,7 @@ The `wazir` CLI is minimal on purpose. It exists to validate and export the host
 | `wazir validate commits` | implemented | Validates conventional commit format for commits in the range `--base..--head` (or auto-detected base to HEAD). |
 | `wazir validate changelog` | implemented | Validates `CHANGELOG.md` structure; with `--require-entries` and `--base`, enforces new entries since the base. |
 | `wazir validate docs-drift` | implemented | Detects when source files (roles, workflows, skills, hooks) change without corresponding documentation updates. Advisory by default; `--strict` exits non-zero on drift. |
+| `wazir validate skills` | implemented | Validates skill frontmatter and checks for name conflicts with superpowers skills (requires `wz:` prefix). Rejects any `CONTEXT.md` files (augment tier concluded not implementable in R2). |
 | `wazir validate artifacts` | reserved | Exits `2` until artifact-template and example validation expands. |
 | `wazir export build` | implemented | Generates host packages under `exports/hosts/*` from canonical sources. |
 | `wazir export --check` | implemented | Verifies generated host packages still match current canonical source hashes. |
@@ -28,19 +29,22 @@ The `wazir` CLI is minimal on purpose. It exists to validate and export the host
 | `wazir recall file` | implemented | Returns an exact line-bounded slice from an indexed file. Supports `--tier L0\|L1` for summary recall. |
 | `wazir recall symbol` | implemented | Returns an exact slice for an indexed symbol match. Supports `--tier L0\|L1` for summary recall. |
 | `wazir doctor` | implemented | Validates the active repo surface for manifest, hooks, state-root policy, and host export directory presence. |
-| `wazir status` | implemented | Reads run status directly from `<state-root>/runs/<run-id>/status.json`. |
+| `wazir status` | implemented | Reads run status directly from `<state-root>/runs/<run-id>/status.json`. Includes a one-line context savings summary when usage data is available. |
+| `wazir stats` | implemented | Shows token savings statistics for a run, including total queries, estimated tokens saved, bytes avoided, per-tool breakdown, and overall savings ratio. |
 | `wazir capture init` | implemented | Creates a run ledger with `status.json`, `events.ndjson`, and a captures directory under the configured state root. |
 | `wazir capture event` | implemented | Appends a run event and can update phase, status, and loop counts in `status.json`. |
 | `wazir capture route` | implemented | Reserves a run-local capture file path for large tool output. |
 | `wazir capture output` | implemented | Writes captured tool output to a run-local file and records a `post_tool_capture` event. |
 | `wazir capture summary` | implemented | Writes `summary.md` and records the chosen summary or handoff event. |
 | `wazir capture usage` | implemented | Generates a token savings report for a run, showing capture routing statistics and context window savings. |
+| `wazir capture loop-check` | implemented | Records a loop iteration event and evaluates the loop cap guard. Exits 43 if the phase loop cap is exceeded. Accepts `--task-id` for task-scoped cap tracking. In standalone mode (no status.json), exits 0. |
 
 ## Exit codes
 
 - `0`: requested check passed
 - `1`: invalid input or validation failure
 - `2`: command surface exists but the implementation is intentionally not complete yet
+- `43`: phase loop cap exceeded (returned by `wazir capture loop-check`)
 
 ## Root discovery
 

package/docs/truth-claims.yaml

@@ -130,6 +130,12 @@
   subject: wazir status
   verifier: command_registry
   required: true
+- id: command-stats
+  file: docs/reference/tooling-cli.md
+  claim_type: command
+  subject: wazir stats
+  verifier: command_registry
+  required: true
 - id: command-capture-family
   file: docs/reference/tooling-cli.md
   claim_type: command
@@ -184,6 +190,12 @@
   subject: wazir capture usage
   verifier: command_registry
   required: true
+- id: command-capture-loop-check
+  file: docs/reference/tooling-cli.md
+  claim_type: command
+  subject: wazir capture loop-check
+  verifier: command_registry
+  required: true
 - id: command-validate-branches
   file: docs/reference/tooling-cli.md
   claim_type: command
@@ -196,6 +208,12 @@
   subject: wazir validate docs-drift
   verifier: command_registry
   required: true
+- id: command-validate-skills
+  file: docs/reference/tooling-cli.md
+  claim_type: command
+  subject: wazir validate skills
+  verifier: command_registry
+  required: true
 - id: generated-claude-package
   file: docs/reference/host-exports.md
   claim_type: generated_file

package/expertise/antipatterns/process/ai-coding-antipatterns.md

@@ -3,7 +3,7 @@
 > AI coding agents produce code that compiles, passes superficial review, and reads authoritatively -- yet harbors systematic defects that human-written code rarely exhibits. These anti-patterns arise from the fundamental mechanics of next-token prediction operating without ground truth, persistent memory, or genuine understanding. A 2026 CodeRabbit analysis of 470 open-source repositories found AI-generated code contains 1.7x more bugs than human code, with 75% more logic errors and 57% more security findings per pull request. A USENIX Security 2025 study of 576,000 code samples found 20% of AI-recommended packages do not exist. This module catalogs the 20 most damaging patterns, grounded in documented incidents and empirical research.
 
 > **Domain:** Process -- AI-Assisted Development
-> **Anti-patterns covered:** 20
+> **Anti-patterns covered:** 22
 > **Highest severity:** Critical
 > **Primary audience:** AI agents performing self-evaluation; human reviewers auditing AI output
 
@@ -823,6 +823,100 @@ An AI coding agent should ask itself these questions before submitting generated
 
 15. **Continuity check:** After a session break, have I reviewed existing code for conventions before generating new code?
 
+### AP-21: Pipeline Phase Skipping
+
+**Also known as:** Rationalized Bypass, "The Spec Is Clear Enough", Shortcut Execution
+**Frequency:** Common
+**Severity:** Critical
+**Detection difficulty:** Low
+
+**What it looks like:**
+
+The agent receives a detailed briefing or spec and jumps directly to implementation, skipping the pipeline's clarification, specification, design, and planning phases. Typical rationalization: "The input is already detailed enough — I don't need to clarify further."
+
+```
+User: /wazir Build a caching layer for the API
+Agent: [reads detailed input] This is clear. Let me start implementing...
+       [spawns parallel agents for implementation]
+       [skips clarify → specify → design → plan entirely]
+```
+
+**Why AI agents do it:**
+
+When the input appears complete, the agent's next-token prediction favors the most "productive" action: writing code. The pipeline phases (clarify, specify, design, plan) feel redundant when the input already describes what to build. The agent lacks the meta-awareness that the pipeline exists precisely to catch what the input does NOT say — unstated assumptions, missing edge cases, architectural trade-offs, and scope boundaries. Skipping phases is the single most damaging process failure because it invalidates every downstream quality gate.
+
+**Detection signals:**
+
+- Implementation starts without `clarification.md`, `spec-hardened.md`, `design.md`, or `execution-plan.md` artifacts in the run directory
+- Agent jumps from input scanning to code writing without user checkpoints
+- Rationalization language in conversation: "this is already clear", "the spec is detailed enough", "we can skip clarification"
+- `wazir capture event --phase executor` returns exit 44 (phase prerequisite gate failed)
+- No `phase_exit` events for clarifier phase in `events.ndjson`
+
+**Root cause:**
+
+No enforcement mechanism between pipeline phases. The agent can read the pipeline skill and choose to interpret it loosely. Without hard gates (file-existence checks, CLI validation), the pipeline is advisory, not mandatory.
+
+**Remediation:**
+
+1. **Skill-level hard gates** — each phase skill contains a prerequisite check section that lists required artifacts and instructs the agent to STOP if any are missing
+2. **CLI-level validation** — `wazir capture event --phase executor` validates that prior phases completed before allowing `phase_enter`
+3. **Anti-rationalization instruction** — skill text explicitly names and blocks the rationalization pattern: "Do NOT skip phases because the input looks clear enough"
+
+**Related:** Wazir pipeline enforcement (item #18), `skills/executor/SKILL.md` Phase Prerequisites section, `tooling/src/guards/phase-prerequisite-guard.js`
+
+---
+
+### AP-22: Autonomous Scope Reduction
+
+**Also known as:** Silent Tiering, Unilateral Deferral, Scope Halving
+**Frequency:** Common (observed in real pipeline runs)
+**Severity:** Critical
+**Detection difficulty:** Moderate
+
+**What it looks like:**
+
+The AI agent autonomously reduces the user's requested scope by tiering, deferring, or deprioritizing items without explicit user approval. The user asks for 10 items; the agent delivers 5 and calls the rest "future work."
+
+**Why AI agents do it:**
+
+Agent optimizes for completion over coverage. Large input overwhelms the context, and the agent triages by perceived difficulty. The agent confuses "prioritization suggestion" with "scope decision." No hard gate prevents the reduction.
+
+**What goes wrong:**
+
+User loses trust — they asked for X, got X/2. Repeated runs required to cover what should have been one run. Agent appears to make product decisions above its authority.
+
+**Detection signals:**
+
+- Input has N items, execution plan has fewer than N tasks
+- Words like "deferred", "future tier", "out of scope for this run" appear without user approval
+- Post-run review reveals missing deliverables
+
+**The fix:**
+
+1. **Hard gate:** `items_in_plan >= items_in_input` enforced by scope coverage guard
+2. **Clarifier check:** Count input items vs plan items before presenting plan
+3. **Explicit approval required:** Agent can SUGGEST prioritization but CANNOT decide it
+4. **Anti-rationalization language:** "The input looks detailed enough to skip some items" is NOT valid reasoning
+
+**Example:**
+
+Bad:
+```
+Input: "Implement items 1-10"
+Plan: "Tier 1 (this run): items 1-5. Tier 2 (future): items 6-10."
+```
+
+Good:
+```
+Input: "Implement items 1-10"
+Plan: "10 tasks covering all 10 items. Suggested order: [...]"
+```
+
+**Related:** CrewAI Task Guardrails (mandatory task completion enforcement), AP-21 (Pipeline Phase Skipping — related pattern of skipping required steps), `tooling/src/guards/phase-prerequisite-guard.js` (`evaluateScopeCoverageGuard`)
+
+---
+
 ## Code Smell Quick Reference
 
 | Anti-Pattern | Severity | Frequency | Key Signal | First Action |
@@ -847,6 +941,8 @@ An AI coding agent should ask itself these questions before submitting generated
 | AP-18 Fake Progress | High | Common | Hardcoded return values | Ban pass/TODO in production |
 | AP-19 Over-Mocking | High | Common | More mocks than assertions | Require integration tests |
 | AP-20 Resumption Errors | High | Common | Mixed ID types across files | Architecture file in every session |
+| AP-21 Pipeline Phase Skipping | Critical | Common | Missing clarified/* artifacts | Enforce hard gates in skills + CLI |
+| AP-22 Autonomous Scope Reduction | Critical | Common | Plan has fewer tasks than input items | Scope coverage guard + user approval |
 
 ---
 

package/exports/hosts/claude/.claude/agents/clarifier.md

@@ -30,6 +30,7 @@ Default approach: recall L1 (structural summaries)
 - clarification artifact
 - unresolved questions list
 - scope summary with cited sources
+- emits clarification artifact for reviewer loops
 
 ## Escalation Rules
 
@@ -40,3 +41,5 @@ Default approach: recall L1 (structural summaries)
 - leaves material ambiguity unresolved without escalation
 - mutates `input/`
 - invents constraints or facts without evidence
+- self-reviews own output instead of delegating to reviewer
+- performs substantial discovery research inline without delegating to the discover workflow when delegation is required

package/exports/hosts/claude/.claude/agents/designer.md

@@ -35,6 +35,9 @@ Default approach: recall L1 (structural summaries)
   - exported HTML + CSS scaffold
   - design tokens JSON (colors, spacing, typography)
   - screenshot PNGs of key frames
+- emits design artifact for design-review loop
+
+Design is not approved for planning until it survives the design-review loop owned by the reviewer role.
 
 ## Git-Flow Responsibilities
 

package/exports/hosts/claude/.claude/agents/executor.md

@@ -31,6 +31,7 @@ Default approach: direct file read (full content)
 - code and docs changes
 - execution notes
 - verification evidence
+- submits per-task output for review before commit
 
 ## Git-Flow Responsibilities
 
@@ -53,3 +54,4 @@ All text outputs (code comments, commit messages, PR descriptions, CHANGELOG ent
 - unwired paths
 - fake tests
 - writes to protected paths outside approved flows
+- commits before review passes

package/exports/hosts/claude/.claude/agents/planner.md

@@ -32,6 +32,9 @@ Default approach: recall L1 (structural summaries)
 - implementation plan artifact
 - ordered task list
 - verification plan per section
+- emits plan artifact for plan-review loop
+
+Plan is not approved until it survives the plan-review loop owned by the reviewer role.
 
 ## Git-Flow Responsibilities
 

package/exports/hosts/claude/.claude/agents/researcher.md

@@ -31,6 +31,7 @@ Default approach: recall L1 (structural summaries)
 - research artifact with citations
 - finding summaries linked to sources
 - open risks and unknowns
+- submits research artifact for reviewer evaluation before it flows downstream
 
 ## Escalation Rules
 
@@ -41,3 +42,4 @@ Default approach: recall L1 (structural summaries)
 - unsupported claims
 - stale or missing citations
 - substituting confidence for evidence
+- research artifact used downstream without passing review

package/exports/hosts/claude/.claude/agents/reviewer.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Perform adversarial review to find correctness, scope, wiring, verification, and drift failures.
+Perform adversarial review to find correctness, scope, wiring, verification, and drift failures. Owns all review loops: research-review, clarification-review, spec-challenge, design-review, plan-review, task-review, and final review.
 
 ## Inputs
 
@@ -17,6 +17,7 @@ Perform adversarial review to find correctness, scope, wiring, verification, and
 - source-backed comparison to spec/plan
 - secondary model review when available
 - Wazir CLI recall and index commands (see Context retrieval)
+- review loop pattern (see docs/reference/review-loop-pattern.md)
 
 ## Context retrieval
 
@@ -32,6 +33,9 @@ Default approach: recall L1, escalate to direct read for flagged issues
 - findings with severity
 - rationale tied to evidence
 - explicit no-findings verdict when applicable
+- review loop pass logs with source attribution ([Wazir], [Codex], [Both])
+
+Review mode is always passed explicitly by the caller (--mode). The reviewer does not auto-detect mode from artifact availability.
 
 ## Git-Flow Responsibilities
 

package/exports/hosts/claude/.claude/agents/specifier.md

@@ -31,6 +31,9 @@ Default approach: recall L1 (structural summaries)
 - spec artifact
 - measurable acceptance criteria
 - explicit non-goals and assumptions
+- emits spec artifact for spec-challenge review loop
+
+Spec is not approved until it survives the spec-challenge loop owned by the reviewer role.
 
 ## Writing Quality
 

package/exports/hosts/claude/.claude/commands/clarify.md

@@ -24,6 +24,10 @@ On entering this phase, run:
 - unresolved questions list
 - scope summary
 
+## Review Loop
+
+Clarification artifact is reviewed by the reviewer role using the review loop pattern with spec/clarification dimensions. The reviewer is invoked with `--mode clarification-review`. The clarifier resolves findings. Clarification does not flow to specify until all review passes complete.
+
 ## Approval Gate
 
 - no formal approval gate, but unresolved material ambiguity must be escalated

package/exports/hosts/claude/.claude/commands/design-review.md

@@ -39,6 +39,10 @@ On rejection: `wazir capture event --run <run-id> --event gate_rejected --phase
 On completing this phase, run:
 `wazir capture event --run <run-id> --event phase_exit --phase <phase-name> --status completed`
 
+## Loop Structure
+
+Follows the review loop pattern in `docs/reference/review-loop-pattern.md` with the canonical design-review dimensions (spec coverage, design-spec consistency, accessibility, visual consistency, exported-code fidelity). The designer role resolves findings. Starts when the approved design artifact enters the `design_review` phase. Pass count determined by depth. No extension.
+
 ## Failure Conditions
 
 - vague findings without visual evidence

package/exports/hosts/claude/.claude/commands/design.md

@@ -33,6 +33,10 @@ On entering this phase, run:
 
 - explicit human approval required before design-review
 
+## Review Loop
+
+After user approval, design artifact is reviewed via the design-review workflow (`workflows/design-review.md`) using the review loop pattern with the canonical design-review dimensions (spec coverage, design-spec consistency, accessibility, visual consistency, exported-code fidelity). The reviewer is invoked with `--mode design-review`. Design does not flow to planning until all review passes complete.
+
 ## Phase exit
 
 On completing this phase, run:

package/exports/hosts/claude/.claude/commands/discover.md

@@ -23,6 +23,10 @@ On entering this phase, run:
 - research artifact
 - cited findings
 
+## Review Loop
+
+Research artifact is reviewed by the reviewer role using the review loop pattern (`docs/reference/review-loop-pattern.md`) with research dimensions (coverage, source quality, relevance, gaps, contradictions). The reviewer is invoked with `--mode research-review`. The researcher resolves findings. Research does not flow to specify until all review passes complete.
+
 ## Approval Gate
 
 - no formal approval gate, but unsupported research cannot flow forward

package/exports/hosts/claude/.claude/commands/execute.md

@@ -34,6 +34,10 @@ If either check fails:
 - code and docs changes
 - execution notes
 
+## Per-Task Review
+
+Each task's output is reviewed using the review loop pattern with the 5 task-execution dimensions (correctness, tests, wiring, drift, quality). The reviewer is invoked with `--mode task-review --task-id <NNN>`. This is NOT the final review -- it is a per-task gate. Review happens BEFORE commit. Review logs use task-scoped filenames: `<phase>-task-<NNN>-review-pass-<N>.md`. See `docs/reference/review-loop-pattern.md` for code review scoping rules.
+
 ## Approval Gate
 
 - no new scope without explicit approval

package/exports/hosts/claude/.claude/commands/plan-review.md

@@ -37,6 +37,10 @@ On rejection: `wazir capture event --run <run-id> --event gate_rejected --phase
 On completing this phase, run:
 `wazir capture event --run <run-id> --event phase_exit --phase <phase-name> --status completed`
 
+## Loop Structure
+
+Follows the review loop pattern in `docs/reference/review-loop-pattern.md` with plan dimensions. The planner role resolves findings. Pass count determined by depth. No extension.
+
 ## Failure Conditions
 
 - sequence gaps survive review

package/exports/hosts/claude/.claude/commands/plan.md

@@ -25,6 +25,10 @@ On entering this phase, run:
 - implementation plan artifact
 - ordered tasks and verification steps
 
+## Review Loop
+
+Plan artifact is reviewed via the plan-review workflow (`workflows/plan-review.md`) using the review loop pattern with plan dimensions. The reviewer is invoked with `--mode plan-review`.
+
 ## Approval Gate
 
 - explicit human approval required before execution

package/exports/hosts/claude/.claude/commands/spec-challenge.md

@@ -36,6 +36,10 @@ On rejection: `wazir capture event --run <run-id> --event gate_rejected --phase
 On completing this phase, run:
 `wazir capture event --run <run-id> --event phase_exit --phase <phase-name> --status completed`
 
+## Loop Structure
+
+This workflow IS a review loop. Follows the pattern in `docs/reference/review-loop-pattern.md` with spec/clarification dimensions. The specifier role resolves findings. Loop count tracked via `wazir capture loop-check --mode spec-challenge`. Pass count determined by depth (quick=3, standard=5, deep=7). No extension beyond depth pass count.
+
 ## Failure Conditions
 
 - rubber-stamp review

package/exports/hosts/claude/.claude/commands/specify.md

@@ -24,6 +24,10 @@ On entering this phase, run:
 - acceptance criteria
 - assumptions and non-goals
 
+## Review Loop
+
+Spec artifact is reviewed via the spec-challenge workflow (`workflows/spec-challenge.md`) using the review loop pattern with spec dimensions. The reviewer is invoked with `--mode spec-challenge`. The specifier resolves findings.
+
 ## Approval Gate
 
 - explicit human approval required before planning

package/exports/hosts/claude/.claude/commands/verify.md

@@ -32,6 +32,10 @@ On entering this phase, run:
 On completing this phase, run:
 `wazir capture event --run <run-id> --event phase_exit --phase <phase-name> --status completed`
 
+## Relationship to Review Loops
+
+Verification is invoked per-task during execution, not as a review loop. It produces deterministic proof, not adversarial findings.
+
 ## Failure Conditions
 
 - stale or partial verification

package/exports/hosts/claude/.claude/settings.json

@@ -9,6 +9,15 @@
             "command": "./hooks/protected-path-write-guard"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/context-mode-router"
+          }
+        ]
       }
     ],
     "SessionStart": [

package/exports/hosts/claude/CLAUDE.md

@@ -6,7 +6,7 @@ This host package is generated from the canonical Wazir sources.
 
 - project: Wazir
 - hosts: claude, codex, gemini, cursor
-- phases: clarify, discover, specify, spec_challenge, author, design, design_review, plan, plan_review, execute, verify, review, learn, prepare_next
+- phases: init, clarifier, executor, final_review
 - roles: clarifier, researcher, specifier, content-author, designer, planner, executor, verifier, reviewer, learner
 - protected paths: input, roles, workflows, schemas, exports/hosts
 - state root default: ~/.wazir/projects/{project_slug}