@wazir-dev/cli 1.0.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wazir-dev/cli",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "Host-native engineering OS kit for AI coding agents — roles, phases, expertise modules, quality gates for Claude, Codex, Gemini & Cursor",
   "bin": {
@@ -29,7 +29,7 @@
   ],
   "scripts": {
     "test": "npm run test:active",
-    "test:active": "node --test tooling/test/cli.test.js tooling/test/validate.test.js tooling/test/index.test.js tooling/test/doctor-status.test.js tooling/test/guard-hooks.test.js tooling/test/export.test.js tooling/test/capture.test.js tooling/test/schema-examples.test.js tooling/test/git-flow-docs.test.js tooling/test/role-contracts.test.js tooling/test/ci-workflow.test.js tooling/test/contributing.test.js tooling/test/author-artifact.test.js tooling/test/capture/usage.test.js tooling/test/docs-drift.test.js",
+    "test:active": "node --test tooling/test/cli.test.js tooling/test/validate.test.js tooling/test/index.test.js tooling/test/doctor-status.test.js tooling/test/guard-hooks.test.js tooling/test/export.test.js tooling/test/capture.test.js tooling/test/schema-examples.test.js tooling/test/git-flow-docs.test.js tooling/test/role-contracts.test.js tooling/test/ci-workflow.test.js tooling/test/contributing.test.js tooling/test/author-artifact.test.js tooling/test/capture/usage.test.js tooling/test/adapters/composition-engine.test.js tooling/test/docs-drift.test.js tooling/test/init.test.js tooling/test/gating/agent.test.js tooling/test/guards/phase-prerequisite-guard.test.js tooling/test/hooks/context-mode-router.test.js tooling/test/hooks/session-start.test.js tooling/test/input-scanning.test.js tooling/test/init/auto-detect.test.js tooling/test/adapters/model-router.test.js tooling/test/state/db.test.js tooling/test/reports/phase-report.test.js tooling/test/logo-svg.test.js tooling/test/adapters/context-mode.test.js",
     "test:coverage": "c8 npm run test:active",
     "prepare": "husky"
   },
@@ -61,8 +61,8 @@
     "tdd"
   ],
   "dependencies": {
+    "@inquirer/prompts": "^8.3.2",
     "ajv": "^8.18.0",
-    "gray-matter": "^4.0.3",
     "yaml": "^2.0.0"
   },
   "devDependencies": {

package/roles/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/roles/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/roles/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/roles/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/roles/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/roles/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/roles/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/schemas/hook.schema.json

@@ -23,7 +23,8 @@
         "pre_compact_summary",
         "stop_handoff_harvest",
         "protected_path_write_guard",
-        "loop_cap_guard"
+        "loop_cap_guard",
+        "context_mode_router"
       ]
     },
     "description": { "type": "string", "minLength": 1 },

package/schemas/phase-report.schema.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wazir.dev/schemas/phase-report.schema.json",
+  "title": "Phase Report",
+  "type": "object",
+  "required": ["phase_name", "run_id", "timestamp", "attempted_actions", "drift_analysis", "quality_metrics", "risk_flags", "decisions"],
+  "properties": {
+    "phase_name": { "type": "string", "minLength": 1 },
+    "run_id": { "type": "string", "minLength": 1 },
+    "timestamp": { "type": "string", "format": "date-time" },
+    "attempted_actions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["description", "outcome", "evidence"],
+        "properties": {
+          "description": { "type": "string", "minLength": 1 },
+          "outcome": { "type": "string", "enum": ["success", "fail", "uncertain"] },
+          "evidence": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    },
+    "drift_analysis": {
+      "type": "object",
+      "required": ["delta"],
+      "properties": {
+        "delta": { "type": "integer", "minimum": 0 },
+        "description": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "quality_metrics": {
+      "type": "object",
+      "properties": {
+        "test_pass_count": { "type": "integer", "minimum": 0 },
+        "test_fail_count": { "type": "integer", "minimum": 0 },
+        "lint_errors": { "type": "integer", "minimum": 0 },
+        "type_errors": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": true
+    },
+    "risk_flags": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["severity", "description"],
+        "properties": {
+          "severity": { "type": "string", "enum": ["low", "medium", "high"] },
+          "description": { "type": "string", "minLength": 1 },
+          "mitigation": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    },
+    "decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["description", "rationale"],
+        "properties": {
+          "description": { "type": "string", "minLength": 1 },
+          "rationale": { "type": "string", "minLength": 1 },
+          "alternatives_considered": { "type": "array", "items": { "type": "string" } },
+          "source": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    },
+    "verdict_recommendation": {
+      "type": "object",
+      "properties": {
+        "verdict": { "type": "string", "enum": ["continue", "loop_back", "escalate"] },
+        "reasoning": { "type": "string" }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/usage.schema.json

@@ -4,7 +4,7 @@
   "title": "Usage Report",
   "description": "Per-run token usage tracking and context savings data.",
   "type": "object",
-  "required": ["schema_version", "run_id", "created_at", "updated_at", "phases", "roles", "savings", "totals"],
+  "required": ["schema_version", "run_id", "created_at", "updated_at", "phases", "roles", "savings", "routing", "totals"],
   "properties": {
     "schema_version": { "type": "integer", "const": 1 },
     "run_id": { "type": "string", "minLength": 1 },
@@ -81,6 +81,30 @@
             "post_compaction_tokens_est": { "type": "integer", "minimum": 0 }
           },
           "additionalProperties": false
+        },
+        "index_queries": {
+          "type": "object",
+          "properties": {
+            "count": { "type": "integer", "minimum": 0 },
+            "total_raw_bytes": { "type": "integer", "minimum": 0 },
+            "total_summary_bytes": { "type": "integer", "minimum": 0 },
+            "estimated_tokens_saved": { "type": "integer", "minimum": 0 },
+            "bytes_avoided": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "routing": {
+      "type": "object",
+      "properties": {
+        "total_commands": { "type": "integer", "minimum": 0 },
+        "context_mode_routed": { "type": "integer", "minimum": 0 },
+        "passthrough": { "type": "integer", "minimum": 0 },
+        "by_category": {
+          "type": "object",
+          "additionalProperties": { "type": "integer", "minimum": 0 }
         }
       },
       "additionalProperties": false

package/schemas/wazir-manifest.schema.json

@@ -87,6 +87,25 @@
       "uniqueItems": true,
       "minItems": 1
     },
+    "phase_prerequisites": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "required_artifacts": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "uniqueItems": true
+          },
+          "required_phase_exits": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "uniqueItems": true
+          }
+        },
+        "additionalProperties": false
+      }
+    },
     "roles": {
       "type": "array",
       "items": { "type": "string", "minLength": 1 },

package/skills/brainstorming/SKILL.md

@@ -5,6 +5,24 @@ description: Use before implementation work to turn operator briefings into an a
 
 # Brainstorming
 
+## Model Annotation
+When multi-model mode is enabled:
+- **Opus** for design exploration (brainstorm)
+- **Opus** for design decisions (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`
+
 Read `input/` first, then inspect only the repo surfaces needed to understand the request.
 
 Rules:
@@ -12,8 +30,8 @@ Rules:
 1. Do not write implementation code before the design is reviewed with the operator.
 2. Ask clarifying questions only when the ambiguity changes scope, architecture, or acceptance criteria.
 3. Propose 2-3 approaches with trade-offs and a recommendation.
-4. Write the approved design to `docs/plans/YYYY-MM-DD-<topic>-design.md`.
-5. Hand off to `wz:writing-plans` after approval.
+4. Write the approved design to `.wazir/runs/latest/clarified/design.md` (if inside a pipeline run) or `docs/plans/YYYY-MM-DD-<topic>-design.md` (if standalone).
+5. After user approves the design concept, the reviewer role runs the design-review loop with `--mode design-review` using canonical design-review dimensions (spec coverage, design-spec consistency, accessibility, visual consistency, exported-code fidelity). See `workflows/design-review.md` and `docs/reference/review-loop-pattern.md`. The designer resolves any findings. If the design-review loop completes all passes clean, hand off to `wz:writing-plans`. Planning does not start until design-review is complete.
 
 Required outputs:
 
@@ -21,57 +39,3 @@ Required outputs:
 - open questions or resolved assumptions
 - explicit recommendation and rejected alternatives
 
----
-
-## Team Mode: Structured Dialogue
-
-**Condition:** Only activate when `team_mode: parallel` in `.wazir/runs/latest/run-config.yaml`. Otherwise, use the default single-agent brainstorming above.
-
-When team mode is active, spawn a 3-agent team using Claude Code Agent Teams:
-
-### Agents
-
-| Agent | Role | Cognitive Mode |
-|-------|------|----------------|
-| **Free Thinker** | Proposes design directions, creative leaps, "what if..." scenarios. Speaks first, opens new threads. | Divergent generation |
-| **Grounder** | Challenges proposals, sorts signal from noise, picks winners, redirects dead ends. Responds to Free Thinker. | Convergent editing |
-| **Synthesizer** | Observes silently, maintains a running summary, produces the final design document. Never participates in dialogue. | Synthesis only |
-
-### Communication Protocol
-
-- Free Thinker and Grounder exchange via **broadcast** (all agents see every message)
-- Synthesizer **NEVER** participates in dialogue — only observes and writes to files
-- After each direction is explored (3-5 exchanges), the Grounder decides: pursue, park, or redirect
-
-### Dialogue Flow
-
-1. **Open a direction** — Free Thinker proposes (broadcast)
-2. **Deepen** — 3-5 exchanges between Free Thinker and Grounder
-3. **Decide** — Grounder calls it: pursue, park, or redirect
-4. **Next direction** — Free Thinker opens a new thread, aware of connections to prior threads
-
-Early rounds: more divergent. Later rounds: more convergent.
-
-### Depth-Bounded Behavior
-
-| Depth | Directions to explore | Exchanges per direction |
-|-------|-----------------------|------------------------|
-| Standard | 3-5 | 3 exchanges |
-| Deep | 5-8 | 5 exchanges |
-
-### Convergence
-
-The dialogue has converged when:
-1. Enough directions have been explored for the depth level
-2. The pursued directions have genuine range (not variations of the same idea)
-3. The Grounder signals satisfaction
-4. Further dialogue is producing diminishing returns
-
-### Output
-
-The Synthesizer produces the design document following the same format as single-agent brainstorming:
-- Design summary
-- Open questions or resolved assumptions
-- Explicit recommendation and rejected alternatives
-
-The Synthesizer then writes the design to `docs/plans/YYYY-MM-DD-<topic>-design.md` and hands off to `wz:writing-plans`.

package/skills/clarifier/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: wz:clarifier
+description: Run the clarification pipeline — research, clarify scope, brainstorm design, generate task specs and execution plan. Pauses for user approval between phases.
+---
+
+# Clarifier
+
+## 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 Clarifier phase — everything from reading input to having an approved execution plan.
+
+**Pacing rule:** This skill has mandatory user checkpoints between sub-workflows. Do NOT skip checkpoints. Do NOT combine sub-workflows. Complete each fully, present output, and wait for explicit user approval before advancing.
+
+Review loops follow the pattern in `docs/reference/review-loop-pattern.md`. All reviewer invocations use explicit `--mode`.
+
+**Standalone mode:** If no `.wazir/runs/latest/` exists, artifacts go to `docs/plans/` and review logs go alongside.
+
+## Prerequisites
+
+1. Check `.wazir/state/config.json` exists. If not, run `wazir init` first.
+2. Check `.wazir/input/briefing.md` exists. If not, ask the user what they want to build and save it there.
+3. Scan `input/` (project-level) and `.wazir/input/` (state-level) for additional input files. Present what's found.
+4. Read config for `default_depth` and `multi_tool` settings.
+5. **Load accepted learnings:** Glob `memory/learnings/accepted/*.md`. For each accepted learning, read scope tags. Inject learnings whose scope matches the current run's intent/stack into context. Limit: top 10 by confidence, most recent first. This is how prior run insights improve future runs.
+6. Create a run directory if one doesn't exist:
+   ```bash
+   mkdir -p .wazir/runs/run-YYYYMMDD-HHMMSS/{sources,tasks,artifacts,reviews,clarified}
+   ln -sfn run-YYYYMMDD-HHMMSS .wazir/runs/latest
+   ```
+
+---
+
+## Context-Mode Usage
+
+Read `context_mode` from `.wazir/state/config.json`:
+
+- **If `context_mode.enabled: true`:** Use `fetch_and_index` for URL fetching, `search` for follow-up queries on indexed content. Use `execute` or `execute_file` for large outputs instead of Bash.
+- **If `context_mode.enabled: false`:** Fall back to `WebFetch` for URLs and `Bash` for commands.
+
+---
+
+## Sub-Workflow 1: Research (discover workflow)
+
+Delegate to the discover workflow (`workflows/discover.md`):
+
+1. **Keyword extraction:** Read the briefing and extract concepts/terms that are vague, reference external standards, or use unfamiliar terminology.
+   - **When to research:** concept references an external standard by name, uses a tool/library not seen in the codebase, or is ambiguous enough that two agents could interpret it differently.
+   - **When NOT to research:** concept is fully defined in the input, or it's a well-known programming concept.
+2. **Fetch sources:** For each concept needing research:
+   - Use `fetch_and_index` (if context-mode available) or `WebFetch` to fetch the source.
+   - Save fetched content to `.wazir/runs/latest/sources/`.
+   - Track each fetch in `sources/manifest.json`.
+3. **Error handling:** 404/unreachable → log failure, continue. Research is best-effort.
+4. The **researcher role** produces the research artifact.
+5. The **reviewer role** runs the research-review loop with `--mode research-review`.
+6. Loop runs for `pass_counts[depth]` passes.
+
+Save result to `.wazir/runs/latest/clarified/research-brief.md`.
+
+### Checkpoint: Research Review
+
+> **Research complete. Here's what I found:**
+>
+> [Summary of codebase state, relevant architecture, external context]
+>
+> 1. **Looks good, continue** (Recommended)
+> 2. **Missing context** — let me add more information
+> 3. **Wrong direction** — let me clarify the intent
+
+**Wait for user response before continuing.**
+
+---
+
+## Sub-Workflow 2: Clarify (clarify workflow)
+
+### Input Preservation (before producing clarification)
+
+1. Glob `.wazir/input/tasks/*.md`. If files exist:
+   - Adopt those specs as the starting point — copy content verbatim into the clarification's item descriptions.
+   - Enhance with codebase scan + research findings. **Never remove detail — only add.**
+   - Every acceptance criterion from input must appear verbatim.
+   - Every API endpoint, color hex code, and UI dimension from input must appear in the relevant item section.
+2. If `.wazir/input/tasks/` is empty or missing, synthesize from `briefing.md` alone.
+
+### Clarification Production
+
+Read the briefing, research brief, and codebase context. Produce:
+
+- **What** we're building — concrete deliverables
+- **Why** — the motivation and business value
+- **Constraints** — technical, timeline, dependencies
+- **Assumptions** — what we're taking as given
+- **Scope boundaries** — what's IN and what's explicitly OUT
+- **Unresolved questions** — anything ambiguous
+
+Save to `.wazir/runs/latest/clarified/clarification.md`.
+
+Invoke `wz:reviewer --mode clarification-review`. Resolve findings before presenting to user.
+
+### Checkpoint: Clarification Review
+
+> **Here's the clarified scope:**
+>
+> [Full clarification]
+>
+> 1. **Approved — continue to spec hardening** (Recommended)
+> 2. **Needs changes** — [user provides corrections]
+> 3. **Missing important context** — [user adds information]
+
+**Wait for user response.** Route feedback: plan corrections → `user-feedback.md`, new requirements → `briefing.md`.
+
+---
+
+## Sub-Workflow 3: Spec Harden (specify + spec-challenge workflows)
+
+Delegate to the specify workflow (`workflows/specify.md`):
+
+1. The **specifier role** produces a measurable spec from clarification + research.
+2. Invoke `wz:reviewer --mode spec-challenge`.
+3. Loop runs for `pass_counts[depth]` passes.
+
+Save result to `.wazir/runs/latest/clarified/spec-hardened.md`.
+
+### Content-Author Detection
+
+After spec hardening, scan the spec for content needs. Auto-enable the `author` workflow if the spec mentions any of:
+- Database seeding, seed data, fixtures, sample records
+- Sample content, placeholder text, demo data
+- Test fixtures, mock API responses, test data files
+- Translations, i18n strings, localization
+- Copy (button labels, error messages, onboarding text)
+- Documentation content, user guides, API docs
+- Email templates, notification text
+
+If detected, set `workflow_policy.author.enabled = true` in the run config and note:
+> **Content needs detected.** The content-author workflow will run after design approval to produce: [list detected content types].
+
+### Checkpoint: Hardened Spec Review
+
+> **Spec hardened. Changes made:**
+>
+> [List of gaps found and how they were tightened]
+>
+> 1. **Approved — continue to brainstorming** (Recommended)
+> 2. **Disagree with a change** — [user specifies]
+> 3. **Found more gaps** — [user adds]
+
+**Wait for user response.**
+
+---
+
+## Sub-Workflow 4: Brainstorm (design + design-review workflows)
+
+Invoke the `brainstorming` skill (`wz:brainstorming`):
+
+1. Propose 2-3 viable approaches with explicit trade-offs
+2. For each approach: effort estimate, risk assessment, what it enables/prevents
+3. Recommend one approach with rationale
+
+### Checkpoint: Design Approval
+
+> **Which approach should we implement?**
+>
+> 1. **Approach A** — [one-line summary] (Recommended)
+> 2. **Approach B** — [one-line summary]
+> 3. **Approach C** — [one-line summary]
+> 4. **Modify an approach** — [user specifies changes]
+
+**Wait for user response.** This is the most important checkpoint.
+
+Save approved design to `.wazir/runs/latest/clarified/design.md`.
+
+After approval: design-review loop with `--mode design-review` (5 canonical dimensions: spec coverage, design-spec consistency, accessibility, visual consistency, exported-code fidelity).
+
+---
+
+## Sub-Workflow 5: Plan (plan + plan-review workflows)
+
+Delegate to `wz:writing-plans`:
+
+1. Planner produces a SINGLE execution plan at `.wazir/runs/latest/clarified/execution-plan.md` in spec-kit format.
+2. **Gap analysis exit gate:** Compare original input against plan. Invoke `wz:reviewer --mode plan-review`.
+3. Loop until clean or cap reached.
+
+### Checkpoint: Plan Review
+
+> **Implementation plan: [N] tasks**
+>
+> | # | Task | Complexity | Dependencies | Description |
+> |---|------|-----------|--------------|-------------|
+>
+> 1. **Approved — ready for execution** (Recommended)
+> 2. **Reorder or split tasks**
+> 3. **Missing tasks**
+> 4. **Too granular / too coarse**
+
+**Wait for user response.**
+
+---
+
+### Scope Coverage Gate (Hard Gate)
+
+Before presenting the plan to the user, verify ALL input items are covered:
+
+1. Count distinct items/deliverables in the input briefing (`.wazir/input/briefing.md` + any `input/*.md` files)
+2. Count tasks in the execution plan
+3. **If `tasks_in_plan < items_in_input`:** STOP and present:
+
+> **Scope reduction detected.** The input contains [N] items but the plan only covers [M].
+>
+> Missing items: [list]
+>
+> 1. **Add missing items to the plan** (Required)
+> 2. **User explicitly approves reduced scope** — only if user confirms
+
+**The clarifier MUST NOT autonomously drop items into "future tiers", "deferred", or "out of scope" without explicit user approval. This is a hard rule.**
+
+Invariant: `items_in_plan >= items_in_input` unless user explicitly approves reduction.
+
+---
+
+## Done
+
+When the plan is approved:
+
+> **Clarifier phase complete.**
+>
+> - Spec: `.wazir/runs/latest/clarified/spec-hardened.md`
+> - Design: `.wazir/runs/latest/clarified/design.md`
+> - Plan: `.wazir/runs/latest/clarified/execution-plan.md`
+>
+> **Next:** Run `/executor` to implement the plan.