@wazir-dev/cli 1.0.0

package/docs/plans/2026-03-15-docs-enforcement-plan.md

@@ -0,0 +1,238 @@
+# Implementation Plan: Documentation & Enforcement (Batches D-G)
+
+**Date:** 2026-03-15
+**Scope:** 14 tasks (017-030) across 4 batches
+**Branch:** `feat/docs-enforcement`
+
+---
+
+## Overview
+
+This plan covers four batches of work that bring documentation up to date with the CLI pipeline integration (Batches A-C) and close enforcement gaps. The work is organized around three key documentation themes:
+
+1. **Code quality for huge tasks** -- 14-phase pipeline, 9 approval gates, adversarial review, TDD, verification-before-completion
+2. **Token savings** -- tiered recall (L0/L1/L2), 60-80% reduction, capture routing, usage reporting
+3. **Ease of use** -- install once, session-start bootstrap, run recovery, audit trail
+
+---
+
+## Pre-flight Checklist
+
+Before starting any task, confirm the following:
+
+- [ ] `npm test` passes on clean `main`
+- [ ] `wazir validate` passes on clean `main` (docs, changelog, brand, branches, commits)
+- [ ] Working branch created: `git checkout -b feat/docs-enforcement`
+- [ ] No uncommitted changes from prior work
+- [ ] Verify current expertise module count: `find expertise -name '*.md' | wc -l` (needed by tasks 022, 023)
+- [ ] Confirm `command-registry.js` already has `wazir capture usage` registered (task 017 context)
+- [ ] Confirm no `prepare` script exists in `package.json` (task 026 pre-condition)
+
+---
+
+## Batch D: Validation-Critical (truth claims + changelog)
+
+**Must go first.** These tasks fix validation gaps that affect subsequent tasks' verify steps.
+
+| Task | Title | Priority | Deps | Est. Files |
+|------|-------|----------|------|------------|
+| 017 | Add truth claim for `capture usage` command | P0 | none | 2 |
+| 018 | Add CHANGELOG.md [Unreleased] entries (Batches A-C) | P0 | none | 1 |
+
+**Parallelizable:** Yes -- 017 and 018 touch different files (`truth-claims.yaml` + `tooling-cli.md` vs `CHANGELOG.md`).
+
+**Execution order:**
+
+```
+017 ──┐
+      ├── both in parallel
+018 ──┘
+```
+
+**Suggested commits:**
+
+```
+docs(capture): add truth claim for capture usage command
+docs(changelog): add [Unreleased] entries for CLI pipeline integration
+```
+
+**Estimated files changed:** 3 (truth-claims.yaml, tooling-cli.md, CHANGELOG.md)
+
+---
+
+## Batch E: Documentation (stale docs)
+
+**Goes second.** Updates all reference and concept docs to reflect current system state.
+
+| Task | Title | Priority | Deps | Est. Files |
+|------|-------|----------|------|------------|
+| 019 | Update tooling-cli.md (run recovery, token savings) | P1 | 017 | 1 |
+| 020 | Update roles-reference.md (context retrieval defaults) | P1 | none | 1 |
+| 021 | Update hooks.md (CLI bootstrap guidance) | P1 | none | 1 |
+| 022 | Update architecture.md (token savings section) | P1 | none | 1 |
+| 023 | Update README.md (token savings, code quality, ease of use) | P1 | none | 1 |
+| 024 | Update skills.md (debugging OBSERVE, scan-project) | P1 | none | 1 |
+| 025 | Update indexing-and-recall.md (pipeline integration) | P1 | 020 | 1 |
+
+**Parallelizable:** Mostly yes. Each task modifies a different file. Two constraints:
+
+1. Task 019 depends on 017 (capture usage row must exist for `validate docs`)
+2. Task 025 depends on 020 (cross-file anchor link `#context-retrieval-defaults`)
+
+**Execution order:**
+
+```
+            ┌── 020 ──── 025
+            │
+017 ── 019  ├── 021
+            │
+            ├── 022
+            │
+            ├── 023
+            │
+            └── 024
+
+Tasks 020, 021, 022, 023, 024 can all run in parallel.
+Task 019 starts after 017 completes.
+Task 025 starts after 020 completes.
+```
+
+**Theme coverage across Batch E:**
+
+| Theme | Tasks |
+|-------|-------|
+| Code quality | 023 (new dedicated README section: "How Wazir Handles Complex Tasks") |
+| Token savings | 019 (tooling-cli), 022 (architecture), 023 (README bullet), 025 (indexing pipeline) |
+| Ease of use | 021 (hooks bootstrap), 023 (README bullet), 019 (run recovery) |
+
+**Suggested commits:**
+
+```
+docs(cli): add run recovery and token savings sections to tooling-cli reference
+docs(roles): add context retrieval tier defaults to roles reference
+docs(hooks): add CLI bootstrap guidance section to hooks reference
+docs(architecture): expand context and indexing section with token savings detail
+docs(readme): add token savings, code quality, and ease of use sections
+docs(skills): update debugging OBSERVE and scan-project descriptions
+docs(indexing): add pipeline integration section to indexing and recall conceptual doc
+```
+
+**Estimated files changed:** 7 (one per task, all different docs)
+
+---
+
+## Batch F: Enforcement Gaps
+
+**Goes third.** Adds enforcement tooling that protects the documentation and code quality.
+
+| Task | Title | Priority | Deps | Est. Files |
+|------|-------|----------|------|------------|
+| 026 | Add Husky pre-push hook | P2 | none | 2 |
+| 027 | Extend changelog enforcement to fix/ branches | P2 | none | 1 |
+| 028 | Add doc-drift detection command | P2 | 026 | 7 |
+| 030 | Add CHANGELOG entries for Batches F-G | P2 | 026, 027, 028, 029 | 1 |
+
+**Critical sequencing for package.json:** Tasks 026, 028, and 029 all modify `package.json`. They must run sequentially to avoid merge conflicts: 026 -> 028 -> 029.
+
+Task 027 is independent (modifies only `ci.yml`) and can run in parallel with 026.
+
+Task 030 runs last after all other Batch F-G tasks complete.
+
+**Execution order:**
+
+```
+026 ────── 028 ────── (029 in Batch G)
+                              │
+027 ──────────────────────────┤
+                              │
+                         030 ─┘  (after all F-G tasks)
+```
+
+**Suggested commits:**
+
+```
+feat(hooks): add Husky pre-push hook for branch, commit, and test validation
+fix(ci): require changelog entries for fix/ branches
+feat(validate): add docs-drift detection for source-to-doc staleness
+docs(changelog): add [Unreleased] entries for Batches F-G features
+```
+
+**Estimated files changed:** 11 (package.json, .husky/pre-push, ci.yml, docs-drift.js, docs-drift.test.js, validate.js, command-registry.js, truth-claims.yaml, tooling-cli.md, CHANGELOG.md, and removal of .husky/pre-commit)
+
+---
+
+## Batch G: Coverage
+
+**Goes last.** Adds coverage enforcement on top of all prior work.
+
+| Task | Title | Priority | Deps | Est. Files |
+|------|-------|----------|------|------------|
+| 029 | Add c8 coverage reporting with thresholds | P3 | 028 | 3 |
+
+**Suggested commit:**
+
+```
+feat(coverage): add c8 coverage reporting with threshold enforcement
+```
+
+**Estimated files changed:** 3 (package.json, .c8rc.json, ci.yml)
+
+---
+
+## Full Dependency DAG
+
+```
+017 ─────────── 019
+
+018
+
+020 ─────────── 025
+
+021
+
+022
+
+023
+
+024
+
+026 ─────────── 028 ────── 029
+                               \
+027 ────────────────────────── 030
+```
+
+**Total tasks:** 14
+**Total estimated file changes:** ~24 (some files modified by multiple tasks)
+**Critical path:** 026 -> 028 -> 029 -> 030 (4 sequential tasks)
+
+---
+
+## Execution Summary
+
+| Phase | Batch | Tasks | Parallel? | Constraint |
+|-------|-------|-------|-----------|------------|
+| 1 | D | 017, 018 | Yes | Must go first (validation-critical) |
+| 2 | E | 020, 021, 022, 023, 024 | Yes | All independent, start immediately after Batch D |
+| 2b | E | 019 | No | Waits for 017 |
+| 2c | E | 025 | No | Waits for 020 |
+| 3 | F | 026, 027 | Yes | 026 and 027 are independent |
+| 3b | F | 028 | No | Waits for 026 (package.json) |
+| 4 | G | 029 | No | Waits for 028 (package.json) |
+| 5 | F | 030 | No | Waits for 026, 027, 028, 029 (describes their features) |
+
+**Estimated total commits:** 14 (one per task, all conventional commit format)
+
+---
+
+## Verification Gate
+
+After all 14 tasks complete, run the full validation suite:
+
+```bash
+npm test
+wazir validate
+wazir validate docs-drift --base main --head HEAD
+npm run test:coverage
+```
+
+All four commands must exit 0 before the branch is ready for PR.

package/docs/readmes/INDEX.md

@@ -0,0 +1,99 @@
+# Wazir README Index
+
+> 60 world-class README files covering every feature, workflow, role, skill, hook, and package.
+
+## Main README
+
+| File | Description |
+|------|-------------|
+| [`/README.md`](../../README.md) | Root landing page — 738-line comprehensive project README |
+
+## Features
+
+### Roles (`features/roles/`)
+| File | Description |
+|------|-------------|
+| [README.md](features/roles/README.md) | Roles system overview — pipeline diagram, all 10 roles, design principles |
+| [clarifier.md](features/roles/clarifier.md) | Clarifier role — turns vague requests into precise specifications |
+| [researcher.md](features/roles/researcher.md) | Researcher role — fills knowledge gaps before planning |
+| [specifier.md](features/roles/specifier.md) | Specifier role — writes formal spec artifacts with acceptance criteria |
+| [designer.md](features/roles/designer.md) | Designer role — produces implementation designs and visual wireframes |
+| [content-author.md](features/roles/content-author.md) | Content Author role — writes microcopy, i18n keys, glossary, and seed data |
+| [planner.md](features/roles/planner.md) | Planner role — breaks designs into ordered, verifiable task plans |
+| [executor.md](features/roles/executor.md) | Executor role — implements plans with TDD and conventional commits |
+| [verifier.md](features/roles/verifier.md) | Verifier role — proves every acceptance criterion is met |
+| [reviewer.md](features/roles/reviewer.md) | Reviewer role — scores artifacts for quality and completeness |
+| [learner.md](features/roles/learner.md) | Learner role — extracts learnings and prevents future drift |
+
+### Workflows (`features/workflows/`)
+| File | Description |
+|------|-------------|
+| [README.md](features/workflows/README.md) | Workflows overview — full pipeline diagram, phase reference table |
+| [clarify.md](features/workflows/clarify.md) | Phase 1: Clarify — resolve ambiguity before doing anything |
+| [discover.md](features/workflows/discover.md) | Phase 2: Discover — research the problem space |
+| [specify.md](features/workflows/specify.md) | Phase 3: Specify — produce a formal spec artifact |
+| [spec-challenge.md](features/workflows/spec-challenge.md) | Phase 4: Spec Challenge — adversarial spec hardening |
+| [author.md](features/workflows/author.md) | Phase 5: Author — write microcopy, i18n keys, and content artifacts |
+| [design.md](features/workflows/design.md) | Phase 6: Design — create implementation designs |
+| [design-review.md](features/workflows/design-review.md) | Phase 7: Design Review — validate designs before planning |
+| [plan.md](features/workflows/plan.md) | Phase 8: Plan — break design into ordered tasks |
+| [plan-review.md](features/workflows/plan-review.md) | Phase 9: Plan Review — validate the plan before execution |
+| [execute.md](features/workflows/execute.md) | Phase 10: Execute — TDD implementation with commits |
+| [verify.md](features/workflows/verify.md) | Phase 11: Verify — prove every acceptance criterion |
+| [review.md](features/workflows/review.md) | Phase 12: Review — quality gate and scoring |
+| [learn.md](features/workflows/learn.md) | Phase 13: Learn — extract and persist learnings |
+| [prepare-next.md](features/workflows/prepare-next.md) | Phase 14: Prepare Next — clean state for next cycle |
+| [run-audit.md](features/workflows/run-audit.md) | Out-of-band: Run Audit — on-demand quality audits |
+
+### Skills (`features/skills/`)
+| File | Description |
+|------|-------------|
+| [README.md](features/skills/README.md) | Skills system overview — all 11 skills, type table, invocation rules |
+| [using-skills.md](features/skills/using-skills.md) | Bootstrap skill — enforces skill-check-before-action |
+| [brainstorming.md](features/skills/brainstorming.md) | Design gate skill — ideas into designs before implementation |
+| [writing-plans.md](features/skills/writing-plans.md) | Plan production skill — specs into bite-sized task files |
+| [tdd.md](features/skills/tdd.md) | TDD skill — RED/GREEN/REFACTOR for every sub-task |
+| [debugging.md](features/skills/debugging.md) | Debugging skill — systematic 4-phase debug protocol |
+| [verification.md](features/skills/verification.md) | Verification skill — evidence before completion claims |
+| [design.md](features/skills/design.md) | Design skill — open-pencil MCP visual design workflow |
+| [scan-project.md](features/skills/scan-project.md) | Scan project skill — builds project profile for auto-resolution |
+| [run-audit.md](features/skills/run-audit.md) | Run audit skill — 6-step interactive audit pipeline |
+| [self-audit.md](features/skills/self-audit.md) | Self-audit skill — worktree-isolated drift detection |
+| [prepare-next.md](features/skills/prepare-next.md) | Prepare next skill — clean handoff between sessions |
+
+### Hooks (`features/hooks/`)
+| File | Description |
+|------|-------------|
+| [README.md](features/hooks/README.md) | Hooks system overview — full roster, categories, exit codes |
+| [session-start.md](features/hooks/session-start.md) | Session Start hook — skill bootstrap injection on session init |
+| [pre-tool-capture-route.md](features/hooks/pre-tool-capture-route.md) | Pre Tool Capture Route hook — routes tool output to capture |
+| [post-tool-capture.md](features/hooks/post-tool-capture.md) | Post Tool Capture hook — streams tool events to session log |
+| [pre-compact-summary.md](features/hooks/pre-compact-summary.md) | Pre Compact Summary hook — persists summary before compaction |
+| [stop-handoff-harvest.md](features/hooks/stop-handoff-harvest.md) | Stop Handoff Harvest hook — harvests session artifacts at stop |
+| [protected-path-write-guard.md](features/hooks/protected-path-write-guard.md) | Protected Path Write Guard — blocks writes to canonical files |
+| [loop-cap-guard.md](features/hooks/loop-cap-guard.md) | Loop Cap Guard — stops runaway agent loops |
+| [post-tool-lint.md](features/hooks/post-tool-lint.md) | Post Tool Lint — syntax-checks JS files after every write |
+
+### Other Features
+| File | Description |
+|------|-------------|
+| [expertise/README.md](features/expertise/README.md) | Expertise system — 308 modules across 11 domains |
+| [schemas/README.md](features/schemas/README.md) | Schema system — 16 JSON schemas for artifact validation |
+| [tooling/README.md](features/tooling/README.md) | CLI tooling — all commands with options and examples |
+| [exports/README.md](features/exports/README.md) | Host exports — Claude, Codex, Gemini, Cursor packages |
+
+## Packages (`packages/`)
+
+| File | Package | Description |
+|------|---------|-------------|
+| [README.md](packages/README.md) | — | Package index with versions and reading order |
+| [ajv.md](packages/ajv.md) | `ajv@^8.18.0` | JSON Schema 2020-12 validation |
+| [gray-matter.md](packages/gray-matter.md) | `gray-matter@^4.0.3` | YAML frontmatter parsing for skill files |
+| [yaml.md](packages/yaml.md) | `yaml@^2.0.0` | YAML 1.2 serialization for manifests |
+| [node-test.md](packages/node-test.md) | `node:test` | Zero-dependency built-in test runner |
+| [context-mode.md](packages/context-mode.md) | `context-mode` plugin | Context compression for large outputs |
+
+## Research
+
+| File | Description |
+|------|-------------|

package/docs/readmes/features/expertise/README.md

@@ -0,0 +1,171 @@
+# Expertise System
+
+Wazir's expertise system is a curated library of **308 knowledge modules** spanning
+architecture, security, performance, design, and more. Modules are loaded selectively into
+agent prompts — giving the right knowledge to the right role at the right phase — without
+flooding context with irrelevant content.
+
+---
+
+## What It Is
+
+The `expertise/` directory is the knowledge base that agents consult during planning,
+specification, execution, and review. Every module is:
+
+- **Research-backed** — grounded in industry standards (OWASP, Core Web Vitals, SOLID,
+  12-Factor), real breach post-mortems, and authoritative framework documentation.
+- **Phase-scoped** — metadata in `expertise/index.yaml` declares which workflow phases
+  each module applies to, enabling targeted loading rather than brute-force context dumps.
+- **Antipattern-first for review** — the `antipatterns/` category is always consulted
+  before broader domain modules when the reviewer role runs.
+
+---
+
+## Module Structure
+
+Each module is a Markdown file with a frontmatter-style header block, cross-references,
+and structured sections:
+
+```
+# <Title> — <Category> Expertise Module
+
+> One-sentence purpose statement.
+> **Category:** <category>
+> **Complexity:** Simple | Moderate | Complex
+> **Applies when:** <scope description>
+
+**Cross-references:** [related-module], [related-module]
+
+---
+
+## What This Is (and What It Isn't)
+## When to Use It
+## <Domain-specific sections>
+## Anti-Patterns / Common Mistakes
+## References
+```
+
+Antipattern modules follow a parallel structure keyed on `AP-NN` identifiers:
+
+```
+### AP-01: <Pattern Name>
+**Frequency:** Common | Very Common
+**Severity:** Low | Medium | High | Critical
+**Detection difficulty:** Easy | Medium | Hard
+**What it looks like:** <code example>
+**Why developers do it:** ...
+**What goes wrong:** ...
+**The fix:** ...
+```
+
+---
+
+## Categories
+
+| Category | Path | Modules | Domain | Key Content |
+|---|---|---|---|---|
+| Architecture | `expertise/architecture/` | 40+ | system-design | DDD, SOLID, 12-Factor, microservices, CQRS, event-driven, CAP theorem, circuit breakers |
+| Backend | `expertise/backend/` | 8 | implementation | Node/TS, Python/FastAPI, Go, Rust, Java/Spring, Solidity, embedded firmware |
+| Frontend | `expertise/frontend/` | 9 | implementation | React, Vue, Angular, Flutter, iOS, Android, React Native, Electron |
+| Security | `expertise/security/` | 12+ | security | OWASP Top 10, IAM, cryptography, secrets management, smart-contract security, agentic identity |
+| Performance | `expertise/performance/` | 25+ | performance | API latency, Core Web Vitals, bundle optimization, mobile startup, connection pooling, CDN |
+| Design | `expertise/design/` | 20+ | product-design | Typography, color theory, design systems, cognitive load, microinteractions, behavioral nudges |
+| Quality | `expertise/quality/` | 8 | quality | Web/mobile/API testing, accessibility, evidence-based verification, ML model audit |
+| Infrastructure | `expertise/infrastructure/` | 6 | operations | AWS, GCP, Postgres, MongoDB, DevOps/CI-CD, cybersecurity |
+| i18n | `expertise/i18n/` | 30+ | product-quality | Unicode, RTL layout, pluralization, BiDi algorithm, Flutter/React/iOS/Android i18n |
+| Antipatterns | `expertise/antipatterns/` | 50+ | review | Code smells, async failures, security theater, AI coding pitfalls, architecture drift |
+
+---
+
+## Loading Policy
+
+Modules are not loaded all at once. `expertise/index.yaml` governs which modules belong to
+which phases:
+
+```
+                ┌─────────────────────────────────────────┐
+                │          expertise/index.yaml            │
+                │  id: architecture                        │
+                │  review_applicability: [specify, plan,   │
+                │                         review]          │
+                │  freshness_date: 2026-03-11              │
+                └─────────────────────────────────────────┘
+                          │
+          ┌───────────────┼───────────────┐
+          ▼               ▼               ▼
+     specify phase    plan phase     review phase
+  loads architecture  loads          loads antipatterns
+  + security slices   performance    FIRST, then domain
+                       + infra        modules as needed
+```
+
+Role-specific loading rules:
+
+- `clarify` / `discover` — `input/`, active docs, `docs/research/`
+- `specify` / `plan` — only expertise slices relevant to the current stack and risks
+- `review` — always loads `expertise/antipatterns/` first, then broader domain modules
+- `learn` — may propose expertise updates but may not silently rewrite existing modules
+
+---
+
+## How to Browse
+
+**By use case:**
+
+| Goal | Start here |
+|---|---|
+| Designing a new system | `expertise/architecture/foundations/` + `expertise/architecture/decisions/` |
+| Reviewing for vulnerabilities | `expertise/security/testing/` + `expertise/antipatterns/security/` |
+| Optimizing performance | `expertise/performance/foundations/` + platform-specific subdirectory |
+| Debugging code quality | `expertise/antipatterns/code/` |
+| Adding i18n or RTL support | `expertise/i18n/foundations/` + `expertise/i18n/rtl/` |
+| Designing user interfaces | `expertise/design/foundations/` + `expertise/design/psychology/` |
+| CI/CD pipeline work | `expertise/infrastructure/devops-cicd.md` |
+
+**By index:** `expertise/index.yaml` — machine-readable metadata with `domain`, `use_cases`,
+`review_applicability`, and `freshness_date` per module group.
+
+**Semantic map:** `expertise/index.md` — human-readable directory tour with per-subdirectory
+file maps and a reading guide.
+
+---
+
+## Antipatterns
+
+`expertise/antipatterns/` is a first-class review instrument. It covers seven sub-domains:
+
+| Sub-domain | Examples |
+|---|---|
+| `code/` | God classes, async anti-patterns, naming violations, testing flaws |
+| `backend/` | N+1 queries, cache stampedes, auth bypasses, API contract breaks |
+| `frontend/` | SPA over-fetching, CSS specificity wars, mobile UI jank |
+| `security/` | Security theater, secrets in env vars, weak session management |
+| `performance/` | Premature optimization, missing indexes, synchronous hot paths |
+| `design/` | Dark patterns, inaccessible color contrast, broken onboarding flows |
+| `process/` | Fake completion, shallow tests, AI-coding failure modes, review theater |
+
+The `process/` category captures AI-specific failure modes — patterns where agents
+produce plausible-looking output that silently fails to meet requirements.
+
+---
+
+## Adding a New Module
+
+1. Choose the correct category subdirectory (or create a new one with an `index.md`).
+2. Write the module in the standard structure: purpose block, cross-references, sections.
+3. Add an entry to `expertise/index.yaml` with `id`, `path`, `domain`, `use_cases`,
+   `review_applicability`, and `freshness_date`.
+4. The `learn` role may propose updates via standard artifact output; direct edits to
+   existing modules require explicit human approval.
+5. Run `wazir validate manifest` to confirm schema and path integrity after changes.
+
+---
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `expertise/index.yaml` | Machine-readable module registry with phase metadata |
+| `expertise/index.md` | Human-readable semantic map and reading guide |
+| `expertise/PROGRESS.md` | Authoring history: 32 modules, 255 total files, completion dates |
+| `expertise/README.md` | Directory contract: what is and is not allowed here |