@wazir-dev/cli 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,15 +1,9 @@
-# [1.1.0](https://github.com/MohamedAbdallah-14/Wazir/compare/v1.0.0...v1.1.0) (2026-03-18)
-
-
-### Bug Fixes
-
-* address review findings — tests, Codex wiring, Teams, pipeline CLI integration ([0b03215](https://github.com/MohamedAbdallah-14/Wazir/commit/0b032150c4a7967ba070eccdced513f55343fc65))
-* CI changelog gate + CodeRabbit review findings ([0247941](https://github.com/MohamedAbdallah-14/Wazir/commit/024794136b7a44116ef2c4f5fcc23823bc72e7fc))
+# [1.3.0](https://github.com/MohamedAbdallah-14/Wazir/compare/v1.2.0...v1.3.0) (2026-03-20)
 
 
 ### Features
 
-* add core review loop pattern across all pipeline phases ([aa4c1d8](https://github.com/MohamedAbdallah-14/Wazir/commit/aa4c1d8400e69ab4fe943043705a862f9e5861f3))
+* 13 critical fixes + pipeline enforcement mechanisms ([#4](https://github.com/MohamedAbdallah-14/Wazir/issues/4)) ([9d0f3b0](https://github.com/MohamedAbdallah-14/Wazir/commit/9d0f3b0de63ace524bc48a513ab02ff377a9d354))
 
 # Changelog
 
@@ -19,18 +13,82 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ## [Unreleased]
 
+### Added
+- Workflow completion enforcement — `validateRunCompletion()` ensures all enabled workflows complete before run finalizes (`wazir capture summary --complete`)
+- Mandatory security gate — pattern-based diff scanner (`tooling/src/checks/security-sensitivity.js`) auto-adds 6 security review dimensions when auth/token/SQL/etc. patterns detected
+- Three interaction modes: `auto` (overnight, Codex-required), `guided` (default), `interactive` (co-design) via `/wazir auto|interactive ...`
+- User input capture — NDJSON logging of all user messages during a run (`tooling/src/capture/user-input.js`) with retention pruning
+- Two-layer reasoning chain output — concise conversation triggers + detailed file output at `reasoning/phase-<name>-reasoning.md`
+- Input Coverage dimension in self-audit (compares original input vs plan vs commits)
+- Input Coverage dimension in plan-review (8th dimension, catches scope reduction)
+- Two-level phase model — `parent_phase` and `workflow` fields in phase report schema, hierarchy display in `wazir status`
+- CLI/context-mode enforcement — reviewer flags >5 direct reads without index query and large commands without context-mode
+- Per-phase context savings display at phase boundaries via `wazir stats`
+- Overnight skill research skill (`skills/skill-research/SKILL.md`) for competitive analysis against superpowers and other frameworks
+- Anti-pattern docs: AP-23 (skipping enabled workflows), AP-24 (clarifier deciding scope without asking)
+
+### Changed
+- Clarifier Phase 1A rewritten — research runs first, then informed question batches (3-7 per batch), every scope exclusion requires user confirmation
+- Executor enforces one commit per task (hard rule, reviewer rejects multi-task batching)
+- Per-phase savings display added to clarifier and executor phase boundaries
+
+### Fixed
+- SQLite ExperimentalWarning suppressed via lazy dynamic imports in CLI entrypoint
+- `--complete` flag properly parsed in `wazir capture summary`
+- `validateRunCompletion` filters by `workflow_policy` (enabled workflows only), not full manifest list
+
+### Changed
+- Restructured pipeline from 14 micro-phases to 4 main phases: Init, Clarifier, Executor, Final Review
+- Removed depth and intent questions from pipeline init — depth defaults to standard (override via inline modifiers), intent inferred from request keywords
+- Enabled learn + prepare-next workflows by default (part of Final Review phase)
+- Renamed `phase_policy` to `workflow_policy` in run-config (legacy name still supported)
+- Input directory (`input/`) now scanned automatically at startup
+- Learning extraction with concrete proposal format in reviewer final mode
+- Accepted learnings injected into clarifier context (top 10 by confidence, scope-matched)
+- Prepare-next skill produces structured handoff document
+- All pipeline checkpoints now use AskUserQuestion pattern instead of numbered lists
+- Every pipeline phase outputs value-reporting text (before/after) explaining why the phase matters and what it found
+- Review dimensions annotated with "catches:" descriptions explaining what class of bugs each dimension prevents
+
+### Removed
+- `@inquirer/prompts` dependency and `--interactive` init path (always fails in non-TTY)
+- All Agent Teams references (team_mode, parallel_backend, TeamCreate/SendMessage/TeamDelete, Free Thinker/Grounder/Synthesizer)
+
+### Fixed
+- Router logs now write to manifest-derived state root instead of `_default` (Codex P1)
+- Routing log replay scoped to current run via timestamp filtering (Codex P2)
+- Index-query savings now computed from avoided bytes, not raw bytes (Codex P2)
+- Index-query savings included in savings-ratio denominator (Codex P2)
+- Cursor export now includes context-mode-router hook (Codex P2)
+- SessionStart hook uses correct `database_path` key for index freshness check
+- TabManager stop hook error documented as Claude Code internal (cannot fix from Wazir side)
+
 ### Added
 - Core review loop pattern across all pipeline phases with Codex CLI integration
 - `wazir capture loop-check` CLI subcommand with task-scoped cap tracking and run-config loader
-- `wazir init` interactive CLI command with arrow-key selection (depth, intent, teams, codex model)
+- `wazir init` zero-config auto-init (no prompts, infer everything)
 - `docs/reference/review-loop-pattern.md` canonical reference for the review loop pattern
 - Standalone skills: `/wazir:clarifier`, `/wazir:executor`, `/wazir:reviewer`
-- Agent Teams real implementation in brainstorming (TeamCreate, SendMessage, TeamDelete)
 - Codex prompt templates (artifact + code) with "Do NOT load skills" instruction
+- `tooling/src/verify/proof-collector.js` — detects project type (web/api/cli/library) and collects mechanical proof of implementation
+- Phase reports wired into pipeline — `wazir report phase` called after each phase exit and displayed to user
+- Proof-of-implementation in verify workflow — runnable vs non-runnable detection with evidence collection
 - Git branch enforcement in `/wazir` runner (validates branch, offers to create feature branch)
 - CLI wiring across pipeline phases (doctor gate, index build/refresh, capture events, validate gates)
 - CHANGELOG enforcement in executor and reviewer skills
 - 10 new tests: 7 for handleLoopCheck, 4 for init command (406 total)
+- Spec-kit task template (`templates/artifacts/tasks-template.md`) with checklist format, phase structure, parallel markers, MVP strategy
+- AC verification scaffold (`tooling/src/checks/ac-matrix.js`) — 111 automated acceptance criteria checks
+- Context-mode detection in `wazir init` (3 core tools + optional execute_file under MCP prefix)
+- Input preservation logic in clarifier (adopt input specs verbatim, never remove detail)
+- Gap analysis exit gate in clarifier (invoke wz:reviewer --mode plan-review, fix-and-loop)
+- Online research in clarifier Phase 0 (keyword extraction, fetch_and_index/WebFetch, error handling)
+- Codex output context protection (tee + extract via execute_file, fail-closed fallback)
+- Resume detection with staleness check and interactive checkpoint in /wazir runner
+- Usage capture at every phase_exit event
+- Run-scoped user feedback routing (plan corrections vs scope changes)
+- Phase scoring with canonical dimension sets and quality delta reporting
+- Full end-of-phase reports (7 sections: Summary, Key Changes, Quality Delta, Findings Log, Usage, Context Savings, Time Spent)
 
 ### Changed
 - All Codex CLI calls now read model from `config.multi_tool.codex.model` with fallback to `gpt-5.4`
@@ -41,3 +99,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 - `/wazir` runner pipeline rewritten with all manifest phases and review loops
 - Wazir CLI is now required (removed "Skip" option)
 - Fixed pass counts: quick=3, standard=5, deep=7 (no extension)
+- Clarifier now invokes `wz:reviewer --mode` explicitly instead of ad-hoc codex calls
+- Fix-and-loop pattern: re-submission after fixes is mandatory, "fix and continue" prohibited
+- Review loop escalation at cap: 3 user options (approve-with-issues, fix-manually, abort)
+- CHANGELOG/gitflow hard gates before PR (validate changelog + validate commits)
+- All checkpoints use numbered interactive options with (Recommended) markers
+- Reviewer documents 5 owned responsibilities (Codex integration, dimensions, pass counting, attribution, dimension set recording)

package/README.md

@@ -32,7 +32,7 @@
 I'm Mohamed Abdallah. I kept watching AI agents write confident code that broke in production, skip tests, and forget what we agreed on yesterday. So I stopped asking them to be better and built them an engineering department instead.
 
 **Wazir puts engineering discipline inside AI coding agents.**
-No wrapper. No server. Just structure -- inside Claude, Codex, Gemini, and Cursor. Built on 300+ research sources distilled into 261 curated expertise modules across 12 domains.
+No wrapper. No server. Just structure -- inside Claude, Codex, Gemini, and Cursor. Built on 300+ research sources distilled into 315 curated expertise modules across 12 domains.
 
 ---
 
@@ -77,7 +77,7 @@ AI agents love to announce they're finished. Wazir doesn't care. Every phase loo
 
 ## The Pipeline
 
-Every task flows through 14 phases. Three are adversarial review gates that block progress until the reviewer explicitly approves. Rejection loops back to the authoring phase.
+Every task flows through 15 workflows grouped into 4 phases. Three are adversarial review gates that block progress until the reviewer explicitly approves. Rejection loops back to the authoring phase.
 
 ```mermaid
 graph LR
@@ -122,9 +122,9 @@ Three concepts.
 
 **1 -- Roles are isolation boundaries, not personas.** Each of the 10 roles has defined inputs, allowed tools, required outputs, escalation rules, and failure conditions. An agent inside a role cannot write to protected paths, cannot skip required outputs, and must escalate when ambiguity conditions are met. The discipline is structural, not instructional. See [Roles & Workflows](docs/concepts/roles-and-workflows.md).
 
-**2 -- Phases are artifact checkpoints, not conversation stages.** Every phase consumes a named artifact from the previous phase and produces a named artifact for the next. Nothing flows through conversation history. A session can end, a new agent can pick up the artifacts, and delivery continues. The handoff is explicit, structured, and schema-validated against 18 JSON schemas. See [Architecture](docs/concepts/architecture.md).
+**2 -- Phases are artifact checkpoints, not conversation stages.** Every phase consumes a named artifact from the previous phase and produces a named artifact for the next. Nothing flows through conversation history. A session can end, a new agent can pick up the artifacts, and delivery continues. The handoff is explicit, structured, and schema-validated against 19 JSON schemas. See [Architecture](docs/concepts/architecture.md).
 
-**3 -- The composition engine loads the right expert automatically.** One agent pretending to be an expert in everything is an expert in nothing. A 4-layer system (always, auto, stacks, concerns) decides which of 261 expertise modules load into each role's context. The executor gets modules on how to build. The verifier gets modules on what to detect. The reviewer gets modules on what to flag. All resolved automatically from the task's declared stack and concerns. Max 15 modules per dispatch, token budget enforced.
+**3 -- The composition engine loads the right expert automatically.** One agent pretending to be an expert in everything is an expert in nothing. A 4-layer system (always, auto, stacks, concerns) decides which of 315 expertise modules load into each role's context. The executor gets modules on how to build. The verifier gets modules on what to detect. The reviewer gets modules on what to flag. All resolved automatically from the task's declared stack and concerns. Max 15 modules per dispatch, token budget enforced.
 
 ---
 
@@ -169,17 +169,17 @@ Run `wazir capture usage` at the end of a session to see the savings:
 
 **10 canonical role contracts.** Clarifier, researcher, specifier, content-author, designer, planner, executor, verifier, reviewer, learner. Each has enforceable inputs, outputs, and escalation rules. [Roles reference](docs/reference/roles-reference.md)
 
-**Adversarial review at three chokepoints.** Spec-challenge, plan-review, and final review run by the reviewer role, never the phase author. Nine hard approval gates span the 14-phase pipeline. Nothing advances without explicit clearance. [Architecture](docs/concepts/architecture.md)
+**Adversarial review at three chokepoints.** Spec-challenge, plan-review, and final review run by the reviewer role, never the phase author. Nine hard approval gates span the 15-workflow pipeline. Nothing advances without explicit clearance. [Architecture](docs/concepts/architecture.md)
 
-**261 curated expertise modules across 12 domains.** Loaded selectively per role per phase via a 4-layer composition engine. Max 15 modules per dispatch, token budget enforced. Wazir ships with 261. Yours could be next. [Expertise index](docs/reference/expertise-index.md)
+**315 curated expertise modules across 12 domains.** Loaded selectively per role per phase via a 4-layer composition engine. Max 15 modules per dispatch, token budget enforced. Wazir ships with 315. Yours could be next. [Expertise index](docs/reference/expertise-index.md)
 
 **Three-tier recall for token savings.** L0 (~~100 tokens), L1 (~~500-2k tokens), direct read for full source. Symbol-first exploration searches the index before reading source. Capture routing redirects large tool output to files. Result: 60-80% token reduction on exploration-heavy phases, measured per-session by `wazir capture usage`. [Indexing and Recall](docs/concepts/indexing-and-recall.md)
 
 **Structured learning.** Proposed learnings require explicit review and scope tagging before promotion. Only learnings whose file patterns overlap the current task get injected into context. The system improves per-project without drifting.
 
-**7 hook contracts for structural guardrails.** These enforce protected path writes (exit 42), loop caps (exit 43), and session observability. [Hooks](docs/reference/hooks.md)
+**8 hook contracts for structural guardrails.** These enforce protected path writes (exit 42), loop caps (exit 43), and session observability. [Hooks](docs/reference/hooks.md)
 
-**20+ callable skills.** `/wazir` runs the full pipeline. `/wazir audit security` runs a codebase audit. `/wazir prd` generates a product requirements document from completed runs. Plus TDD, verification, debugging, and more -- each enforcing an exact procedure with evidence at every step. [Skills](docs/reference/skills.md)
+**28 callable skills.** `/wazir` runs the full pipeline. `/wazir audit security` runs a codebase audit. `/wazir prd` generates a product requirements document from completed runs. Plus TDD, verification, debugging, and more -- each enforcing an exact procedure with evidence at every step. [Skills](docs/reference/skills.md)
 
 **Built-in text humanization.** The composition engine loads domain-specific language rules per role: code rules for the executor (commit messages, comments), content rules for the content-author (microcopy, glossary), and technical-docs rules for the specifier, planner, reviewer, and learner. A 61-item vocabulary blacklist, 24-pattern sentence taxonomy, and two-pass self-audit checklist keep all output sounding like it was written by a person.
 
@@ -189,19 +189,19 @@ Run `wazir capture usage` at the end of a session to see the savings:
 
 ## Compared to Other Tools
 
-The AI coding tool space is fragmenting. Developers bolt together separate plugins for workflow management, specification, memory, output compression, and orchestration. Not every project needs 14 phases. For a weekend hack, prompting is fine. For production, you want structure.
+The AI coding tool space is fragmenting. Developers bolt together separate plugins for workflow management, specification, memory, output compression, and orchestration. Not every project needs 15 workflows. For a weekend hack, prompting is fine. For production, you want structure.
 
 
 | Dimension              | Wazir                         | [Superpowers](https://github.com/obra/superpowers) | [Spec-Kit](https://github.com/github/spec-kit) | [Micro-Agent](https://github.com/BuilderIO/micro-agent) | [Distill](https://github.com/samuelfaj/distill) | [Claude-Mem](https://github.com/thedotmack/claude-mem) | [OMC](https://github.com/yeachan-heo/oh-my-claudecode) |
 | ---------------------- | ----------------------------- | -------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------ |
 | **Category**           | Engineering OS                | Skills framework                                   | Spec toolkit                                   | Code gen agent                                          | Output compressor                               | Memory plugin                                          | Orchestration layer                                    |
-| **Scope**              | Full lifecycle (14 phases)    | Dev workflow (~20 skills)                          | Specify / Plan / Implement                     | Single-file TDD loop                                    | CLI output compression                          | Session memory                                         | Multi-agent orchestration                              |
+| **Scope**              | Full lifecycle (15 workflows) | Dev workflow (~20 skills)                          | Specify / Plan / Implement                     | Single-file TDD loop                                    | CLI output compression                          | Session memory                                         | Multi-agent orchestration                              |
 | **Enforced roles**     | 10 canonical, contractual     | None (skills only)                                 | None                                           | None                                                    | None                                            | None                                                   | 32 agents (behavioral)                                 |
-| **Phase model**        | 14 explicit, artifact-gated   | 7-step (advisory)                                  | 3-step                                         | 1 (generate/test)                                       | N/A                                             | N/A                                                    | 5-step pipeline                                        |
+| **Phase model**        | 15 explicit, artifact-gated   | 7-step (advisory)                                  | 3-step                                         | 1 (generate/test)                                       | N/A                                             | N/A                                                    | 5-step pipeline                                        |
 | **Adversarial review** | 3 gate phases                 | Code review skill                                  | No                                             | No                                                      | No                                              | No                                                     | team-verify step                                       |
 | **Context management** | L0/L1 tiered recall           | None                                               | None                                           | None                                                    | LLM compression                                 | Vector DB (ChromaDB)                                   | Token routing                                          |
-| **Schema validation**  | 18 JSON schemas               | No                                                 | No                                             | No                                                      | No                                              | No                                                     | No                                                     |
-| **Guardrails**         | 7 hook contracts              | None                                               | None                                           | None                                                    | None                                            | 5 hooks (memory)                                       | Agent tracking                                         |
+| **Schema validation**  | 19 JSON schemas               | No                                                 | No                                             | No                                                      | No                                              | No                                                     | No                                                     |
+| **Guardrails**         | 8 hook contracts              | None                                               | None                                           | None                                                    | None                                            | 5 hooks (memory)                                       | Agent tracking                                         |
 | **External deps**      | None (host-native)            | None (prompt-only)                                 | Python CLI                                     | Node.js CLI                                             | Node.js + LLM                                   | ChromaDB, SQLite, Bun                                  | tmux, exp. teams API                                   |
 | **Host support**       | Claude, Codex, Gemini, Cursor | Claude, Codex, Gemini, Cursor, OpenCode            | Claude, Copilot, Gemini                        | Any LLM provider                                        | Any LLM                                         | Claude Code only                                       | Claude Code (+ workers)                                |
 
@@ -264,8 +264,8 @@ The pipeline, roles, and expertise modules are stable and used in production by
 
 What's solid:
 
-- The 14-phase pipeline and 10 role contracts
-- 261 expertise modules across 12 domains
+- The 15-workflow pipeline and 10 role contracts
+- 315 expertise modules across 12 domains
 - Host exports for Claude, Codex, Gemini, and Cursor
 - The composition engine and tiered recall system
 

package/assets/demo.cast

@@ -0,0 +1,47 @@
+{"version":3,"term":{"cols":387,"rows":85,"type":"xterm-256color","version":"Warp(v0.2026.03.04.08.20.stable_03)"},"timestamp":1773955554,"command":"bash assets/demo-script.sh","env":{"SHELL":"/bin/zsh"}}
+[0.008, "o", "$ wazir doctor\r\n"]
+[0.315, "o", "\u001b[1G"]
+[0.000, "o", "\u001b[0K⠙"]
+[0.081, "o", "\u001b[1G\u001b[0K⠹"]
+[0.080, "o", "\u001b[1G\u001b[0K⠸"]
+[0.082, "o", "\u001b[1G\u001b[0K⠼"]
+[0.081, "o", "\u001b[1G\u001b[0K⠴"]
+[0.080, "o", "\u001b[1G\u001b[0K⠦"]
+[0.082, "o", "\u001b[1G\u001b[0K⠧"]
+[0.082, "o", "\u001b[1G\u001b[0K⠇"]
+[0.081, "o", "\u001b[1G\u001b[0K⠏"]
+[0.080, "o", "\u001b[1G\u001b[0K⠋"]
+[0.080, "o", "\u001b[1G\u001b[0K⠙"]
+[0.025, "o", "\u001b[1G\u001b[0K"]
+[0.187, "o", "(node:20008) ExperimentalWarning: SQLite is an experimental feature and might change at any time\r\n(Use `node --trace-warnings ...` to show where the warning was created)\r\n"]
+[0.074, "o", "PASS manifest: Manifest is valid.\r\nPASS hooks: Hook definitions are valid.\r\nPASS state-root: /Users/mohamedabdallah/.wazir/projects/wazir stays outside the project root\r\nPASS host-exports: All required host export directories exist.\r\n"]
+[0.004, "o", "\u001b[1G\u001b[0K⠙"]
+[0.001, "o", "\u001b[1G\u001b[0K"]
+[2.010, "o", "\r\n$ wazir export build\r\n"]
+[0.287, "o", "\u001b[1G"]
+[0.000, "o", "\u001b[0K⠙"]
+[0.081, "o", "\u001b[1G\u001b[0K⠹"]
+[0.081, "o", "\u001b[1G\u001b[0K⠸"]
+[0.080, "o", "\u001b[1G\u001b[0K⠼"]
+[0.081, "o", "\u001b[1G\u001b[0K⠴"]
+[0.082, "o", "\u001b[1G\u001b[0K⠦"]
+[0.012, "o", "\u001b[1G\u001b[0K"]
+[0.164, "o", "(node:20085) ExperimentalWarning: SQLite is an experimental feature and might change at any time\r\n(Use `node --trace-warnings ...` to show where the warning was created)\r\n"]
+[0.070, "o", "Generated host exports for claude, codex, gemini, cursor.\r\n"]
+[0.004, "o", "\u001b[1G\u001b[0K⠙"]
+[0.000, "o", "\u001b[1G\u001b[0K"]
+[2.013, "o", "\r\n$ wazir index build\r\n"]
+[0.304, "o", "\u001b[1G"]
+[0.000, "o", "\u001b[0K⠙"]
+[0.081, "o", "\u001b[1G\u001b[0K⠹"]
+[0.080, "o", "\u001b[1G\u001b[0K⠸"]
+[0.081, "o", "\u001b[1G\u001b[0K⠼"]
+[0.081, "o", "\u001b[1G\u001b[0K⠴"]
+[0.081, "o", "\u001b[1G\u001b[0K⠦"]
+[0.081, "o", "\u001b[1G\u001b[0K⠧"]
+[0.018, "o", "\u001b[1G\u001b[0K"]
+[0.189, "o", "(node:20186) ExperimentalWarning: SQLite is an experimental feature and might change at any time\r\n(Use `node --trace-warnings ...` to show where the warning was created)\r\n"]
+[1.042, "o", "Indexed 889 files, 7493 symbols, and 26395 outlines.\r\n"]
+[0.005, "o", "\u001b[1G\u001b[0K⠙"]
+[0.001, "o", "\u001b[1G\u001b[0K"]
+[1.014, "x", "0"]

package/docs/anti-patterns/AP-23-skipping-enabled-workflows.md

@@ -0,0 +1,28 @@
+# AP-23: Selectively Skipping Enabled Workflows Within a Phase
+
+## Pattern
+
+An agent completes a phase but skips one or more enabled workflows. The run proceeds to completion without the skipped workflow's output. No error is raised because the phase gate only checks artifacts from explicitly required predecessors, not workflow-level completeness.
+
+## Example
+
+The final review phase has three workflows: `review`, `learn`, `prepare_next`. The agent completes `review` and presents the verdict, but skips `learn` and `prepare_next`. The run is marked complete. No learnings are captured, no handoff document is produced.
+
+## Harm
+
+- Learnings from the run are lost — the same mistakes repeat in future runs
+- Handoff documents are missing — the next session starts without context
+- Verification evidence is incomplete — claims cannot be audited
+- The user believes the pipeline ran fully when it did not
+
+## Detection
+
+`validateRunCompletion(runDir, manifestPath)` in `tooling/src/guards/phase-prerequisite-guard.js` checks that every workflow declared in `wazir.manifest.yaml` has a `phase_exit` event with `status: completed` in the run's `events.ndjson`.
+
+`wazir capture summary --complete` calls this check and refuses to finalize the run if any enabled workflow was skipped.
+
+## Fix
+
+1. Always emit `phase_exit` events for every workflow: `wazir capture event --run <id> --event phase_exit --phase <workflow> --status completed`
+2. Use `wazir capture summary --complete` instead of bare `wazir capture summary` at run end
+3. The wazir pipeline skill checks completion before presenting final results

package/docs/anti-patterns/AP-24-clarifier-deciding-scope.md

@@ -0,0 +1,34 @@
+# AP-24: Clarifier Making Scope Decisions Without Asking
+
+## Pattern
+
+The clarifier autonomously decides that certain items are "out of scope" without asking the user. This typically happens when the input doesn't explicitly mention something (e.g., documentation, i18n, testing strategy), and the clarifier assumes silence means exclusion.
+
+## Example
+
+User input: "Build a user authentication system with OAuth2."
+
+Clarifier produces: "Out of scope: documentation, i18n, rate limiting, password recovery."
+
+The user never agreed to exclude any of these. The clarifier decided unilaterally.
+
+## Harm
+
+- Items the user wanted are silently dropped
+- The user sees the final output and assumes the pipeline covered everything
+- 21 input items become 5 tasks because the clarifier excluded 16 without asking
+- Trust in the pipeline erodes when users discover missing features after delivery
+
+## Detection
+
+- Clarification document contains "out of scope" items that were never discussed with the user
+- Plan has fewer tasks than distinct items in the original input
+- Scope coverage guard (`evaluateScopeCoverageGuard`) flags plan < input items
+
+## Fix
+
+1. Research runs FIRST — the clarifier must have context before asking questions
+2. After research, ask INFORMED questions in batches of 3-7
+3. Every scope exclusion must reference an explicit user confirmation
+4. If the input is clear, zero questions is fine — but the clarifier must state "no ambiguities detected" rather than silently proceeding
+5. The clarification document must cite user responses for every scope boundary decision

package/docs/concepts/architecture.md

@@ -10,7 +10,7 @@ Wazir is a host-native engineering OS kit. The host environment (Claude, Codex,
 | Workflows | Phase entrypoints that sequence roles through delivery |
 | Skills | Reusable procedures (wz:tdd, wz:debugging, wz:verification, wz:brainstorming) |
 | Hooks | Guardrails enforcing protected paths, loop caps, and capture routing |
-| Expertise | 308 curated knowledge modules composed into agent prompts |
+| Expertise | 315 curated knowledge modules composed into agent prompts |
 | Templates | Artifact templates for phase outputs and handoff |
 | Schemas | Validation schemas for manifest, hooks, artifacts, and exports |
 | Exports | Generated host packages tailored per supported host |

package/docs/concepts/roles-and-workflows.md

@@ -31,6 +31,8 @@ The canonical workflow sequence is:
 13. **learn** — capture scoped learnings
 14. **prepare-next** — produce a clean handoff for the next run
 
+Additionally, **run-audit** is a standalone workflow that can be invoked outside the linear pipeline to perform structured codebase audits with source-backed findings.
+
 ## Role routing
 
 The orchestrator dispatches three roles per task: `executor`, `reviewer`, and `verifier`. By default, all three run for every task. The `required_roles` field in a task's YAML frontmatter controls which roles are dispatched, allowing the orchestrator to skip unnecessary roles and save context window budget.

package/docs/concepts/why-wazir.md

@@ -0,0 +1,59 @@
+# Why Wazir
+
+What makes Wazir the best engineering OS you can add to an AI coding agent.
+
+## 1. Measure Twice, Cut Once
+
+Wazir clarifies before coding. The pipeline forces research, spec hardening, design review, and plan approval before a single line of implementation code is written. Most AI agents jump straight to code and fix mistakes after. Wazir prevents the mistakes.
+
+## 2. Deep Research
+
+Every AI agent knows how to research. Users don't ask them to. Wazir makes research a mandatory phase — the researcher role scans the codebase, fetches external sources, and produces a research brief before clarification begins. The agent starts informed, not guessing.
+
+## 3. Clarifier + Task Planning
+
+A structured clarification pipeline turns vague requests into measurable specs. Spec hardening catches ambiguity, missing constraints, and untestable acceptance criteria before they become bugs. Task planning produces execution-grade task specs — not TODO lists.
+
+## 4. Content Author
+
+A dedicated role for any content need — database seeding, sample content, test fixtures, translations, copy, email templates, notification text. Most AI agents treat content as an afterthought bolted onto code tasks. Wazir gives content its own phase with editorial standards, i18n awareness, and humanization rules.
+
+## 5. Self-Audit
+
+The agent audits its own work in an isolated git worktree. Validates, finds structural issues, fixes what it can, verifies the fixes, and only merges on all-green. 5-loop cycle with convergence detection. Protected-path safety rails prevent the agent from modifying its own identity-defining files. Safe self-improvement.
+
+## 6. Composer
+
+315 curated expertise modules across 12 domains. The composition engine assembles task-specific agents by loading the right expertise for each role, stack, and concern. The executor building a Flutter RTL app gets Flutter patterns, RTL layout rules, and mobile antipatterns composed into its context. The reviewer gets the corresponding antipattern catalog. Every dispatched agent is a specialist, not a generalist pretending.
+
+## 7. Review Loops
+
+Multi-pass adversarial review at every pipeline checkpoint — not a single rubber-stamp at the end. Research-review, clarification-review, spec-challenge, design-review, plan-review, per-task execution review, and final review. Each uses phase-specific dimensions. Findings are resolved before advancing. The reviewer is an adversary, not a cheerleader.
+
+## 8. Continuous Learning
+
+Wazir evolves from its own mistakes. Review findings, audit findings, and user corrections feed into a learning system. Recurring issues become accepted learnings injected into future runs. A drift budget prevents learned behavior from diverging too far from the original design. The agent that builds your 10th feature is better than the one that built your 1st.
+
+## 9. Antipatterns
+
+A first-class antipattern catalog loaded into reviewer context BEFORE domain expertise. Catches AI-specific failure modes: fake completion, unwired abstractions, shallow tests, security theater, architecture drift. The reviewer's first lens is "what could go wrong" — not "does this look right."
+
+## 10. Multi-Host
+
+One canonical source, four host exports. Wazir works on Claude Code, Codex, Gemini, and Cursor from a single `wazir export build`. Roles, workflows, skills, and expertise are written once and compiled into each host's native format. Switch hosts without rewriting your engineering process.
+
+## 11. Context Efficiency
+
+AI agents waste most of their context window on brute-force file reads and verbose command output. Wazir's routing hook auto-routes large commands through context-mode. The index provides symbol-first exploration — query first, read only what's needed. Capture routing redirects large output to files. Result: 60-80% token reduction on exploration-heavy phases. The agent thinks more, reads less.
+
+## 12. Verification Before Completion
+
+No success claims without evidence. The verify phase produces deterministic proof — test results, lint output, type-check results — not "I believe it works." Every completion claim is backed by a command that was actually run and output that was actually checked. Evidence before assertions, always.
+
+## 13. Gating Agent
+
+Autonomous phase transition decisions. After each phase, a gating agent reads the phase report and decides: continue (all gates pass), loop back (specific failures with fix paths), or escalate to human (ambiguous trade-offs, scope changes). Default posture: escalate. The pipeline doesn't blindly advance — it stops when it should stop.
+
+## 14. Humanize
+
+Anti-AI-writing patterns across all text output. A vocabulary blacklist, domain-specific rules, and a self-audit checklist ensure that specs, plans, code comments, commit messages, and documentation read like they were written by a human engineer — not generated by an LLM. Because AI-sounding output erodes trust.