@wazir-dev/cli 1.0.0

package/docs/readmes/features/roles/verifier.md

@@ -0,0 +1,215 @@
+# Verifier
+
+![Role](https://img.shields.io/badge/role-verifier-blue) ![Phase](https://img.shields.io/badge/phase-11%20%E2%80%94%20verification-lightgrey) ![Status](https://img.shields.io/badge/status-stable-green)
+
+**No proof, no pass. The verifier runs the tests, reads the output, and produces evidence — not opinions.**
+
+---
+
+## What is this?
+
+The verifier produces proof. It runs deterministic checks — tests, builds, diffs, schema validation, branch and commit validation — and assembles the results into a verification proof artifact with an explicit pass/fail status.
+
+The key word is **deterministic**. The verifier does not evaluate subjective quality, architectural merit, or code style. It runs commands and reports what happened. If the tests pass, that is evidence. If the build fails, that is evidence. If a claimed outcome has no deterministic verification path, that is an escalation.
+
+This role exists because "the tests pass" is not evidence — a command output log is evidence. The distinction matters enormously when the reviewer, operator, or a future learner needs to understand whether something actually worked.
+
+---
+
+## Key Capabilities
+
+- Runs the full test suite and captures complete output (not summaries)
+- Executes build commands and captures results
+- Performs diff inspection to verify that changes match the approved plan
+- Validates artifact schemas for correctness
+- Runs Wazir's own validation commands (branches, commits, changelog)
+- Produces a proof bundle with explicit pass/fail status for every claimed outcome
+- Escalates when no deterministic verification path exists for a claimed outcome
+
+---
+
+## How It Fits in the Pipeline
+
+The verifier is **Phase 11**. It runs after execution is complete.
+
+```
+[changed files]
+[claimed outcomes from execution notes]
+[verification commands from plan]
+[acceptance criteria from spec]
+            │
+            ▼
+       [verifier]
+            │
+            ├──► verification proof artifact
+            ├──► command results (full output, not summaries)
+            └──► explicit pass/fail per claimed outcome
+            │
+            ▼
+       [reviewer]
+```
+
+**Triggered by:** `verify` workflow.
+
+**Feeds into:** reviewer.
+
+---
+
+## Input / Output Contract
+
+| | Details |
+|---|---|
+| **Inputs** | Changed files, claimed outcomes, verification commands from plan, acceptance criteria from spec |
+| **Allowed tools** | Test commands, build commands, diff inspection, schema validation |
+| **Output: verification proof artifact** | Full proof bundle — every check, its command, and its result |
+| **Output: command results** | Actual stdout/stderr output from every verification command |
+| **Output: pass/fail status** | Explicit PASS or FAIL for every acceptance criterion and git-flow check |
+
+---
+
+## Example
+
+**Verification proof artifact (excerpt):**
+
+```markdown
+# Verification Proof: Per-User API Rate Limiting
+Date: 2026-03-13
+Branch: feature/rate-limiting
+Commit: d7a2f91
+
+## Acceptance Criteria Results
+
+### AC1: 100 requests in 60s window — all HTTP 200
+Status: PASS
+Command: npm test src/middleware/rateLimit.test.ts -- --grep "allows 100 requests"
+Output:
+  ✓ allows 100 requests within window (234ms)
+  1 passing
+
+### AC2: 101st request — HTTP 429 + Retry-After
+Status: PASS
+Command: npm test src/middleware/rateLimit.test.ts -- --grep "blocks 101st request"
+Output:
+  ✓ blocks 101st request with 429 (12ms)
+  1 passing
+
+### AC3: Window reset — full quota restored
+Status: PASS
+Command: npm test src/middleware/rateLimit.test.ts -- --grep "restores quota"
+Output:
+  ✓ restores full quota after window reset (1204ms)
+  1 passing
+
+### AC5: Redis failure — fail-open + alert
+Status: PASS
+Command: npm test src/middleware/rateLimit.test.ts -- --grep "fail-open"
+Output:
+  ✓ fail-open when Redis unavailable (45ms)
+  1 passing
+
+### AC6: Existing integration tests unchanged
+Status: PASS
+Command: npm run test:integration
+Output:
+  43 passing (8.2s)
+  0 failing
+
+## Git-Flow Checks
+
+### Branch Naming
+Status: PASS
+Command: wazir validate branches
+Output: ✓ feature/rate-limiting — valid feature branch name
+
+### Commit Format
+Status: PASS
+Command: wazir validate commits
+Output: ✓ 3/3 commits in conventional format
+
+### Changelog Entries
+Status: PASS
+Command: wazir validate changelog --require-entries
+Output: ✓ 1 entry found under [Unreleased]
+
+## Build
+Status: PASS
+Command: npm run build
+Output: Built in 4.2s, 0 errors, 0 warnings
+
+## Overall Status: PASS
+All 6 acceptance criteria: PASS
+All git-flow checks: PASS
+Build: PASS
+```
+
+---
+
+## Git-Flow Responsibilities
+
+The verifier runs four Wazir validation commands as mandatory checks:
+
+```bash
+# Branch naming conventions
+wazir validate branches
+
+# Conventional commit format on all commits in branch
+wazir validate commits
+
+# Changelog format
+wazir validate changelog
+
+# Require at least one new entry on feature/codex/hotfix branches
+wazir validate changelog --require-entries
+```
+
+All four results must appear in the verification proof artifact.
+
+---
+
+## Configuration
+
+| Setting | Location | Effect |
+|---------|----------|--------|
+| `verification-proof` validation check | `wazir.manifest.yaml` | Enforces that proof artifact exists before review |
+| `review-loop` validation check | `wazir.manifest.yaml` | Tracks verification loop count |
+| `loop_cap_guard` hook | `hooks/` | Caps re-verification iterations to prevent infinite loops |
+| Acceptance criteria | spec artifact | Source of truth for what must be verified |
+| Verification commands | plan artifact | Specifies exact commands to run |
+
+---
+
+## When to Use / When NOT to Use
+
+**Use the verifier when:**
+- Execution is complete and you need a proof bundle before review begins
+- Re-running after the reviewer found failures that have been fixed
+- You need a formal verification record for audit, compliance, or handoff
+
+**Do NOT invoke the verifier when:**
+- Execution is still in progress — verify after the full plan slice is complete
+- You want to use it to check work-in-progress — run tests directly; the verifier produces a formal artifact
+- You are tempted to write "PASS" based on partial runs — every criterion must be run fresh
+
+> [!WARNING]
+> **Stale verification is a failure condition.** If the verifier runs tests, then code is changed, and the proof artifact is not regenerated — the proof is stale and invalid. The reviewer will check commit timestamps against proof timestamps and flag it.
+
+---
+
+## Failure Conditions
+
+| Condition | Why It Matters |
+|-----------|----------------|
+| Incomplete proof | Reviewer cannot make a defensible verdict; spec criteria go unvalidated |
+| Stale verification | Proof does not reflect actual current state of the code |
+| Claiming success without fresh evidence | The most critical failure — signs off on broken work |
+
+---
+
+## Related
+
+- [Roles Overview](README.md)
+- [executor](executor.md) — upstream role (produces the code to be verified)
+- [reviewer](reviewer.md) — downstream role (consumes the proof bundle)
+- [planner](planner.md) — defines verification commands per task
+- [specifier](specifier.md) — defines acceptance criteria that verification must cover
+- [Verify Workflow](../workflows/verify.md) _(coming soon)_

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

@@ -0,0 +1,178 @@
+# Schema Validation System
+
+Wazir enforces artifact quality through a suite of **JSON Schema Draft 2020-12**
+schemas. Every phase output — from a clarification through a review — must satisfy its
+schema before it can be used as a source for the next phase or included in a host export.
+
+Schemas prevent fake-green states: an artifact that looks complete but is missing required
+fields fails loudly at validation time rather than silently corrupting downstream phases.
+
+---
+
+## How It Works
+
+```
+Canonical source file                 Schema file
+(roles/*.md, artifacts, manifest)     (schemas/*.schema.json)
+         │                                      │
+         └──────────────┬───────────────────────┘
+                        ▼
+              schema-validator.js
+              (AJV, draft 2020-12)
+                        │
+          ┌─────────────┴──────────────┐
+          ▼                            ▼
+    PASS (exit 0)              FAIL (exit 1)
+    artifact accepted          actionable error output
+                               with field path + message
+```
+
+The validator is called by `wazir validate manifest`, `wazir export build`,
+and individual `wazir validate *` checks. It is also exercised by the full test
+suite via schema-backed example fixtures in `templates/examples/`.
+
+---
+
+## Schema Catalog
+
+| Schema file | Title | Required by |
+|---|---|---|
+| `wazir-manifest.schema.json` | Wazir Manifest v2 | `validate manifest`, `export build` |
+| `hook.schema.json` | Hook Definition | `validate hooks` |
+| `spec.schema.json` | Spec Artifact | `specifier` role output |
+| `implementation-plan.schema.json` | Implementation Plan Artifact | `planner` role output |
+| `review.schema.json` | Review Artifact | `reviewer` role output |
+| `verification-proof.schema.json` | Verification Proof | `verifier` role output |
+| `design-artifact.schema.json` | Design Artifact | `designer` role output |
+| `clarification.schema.json` | Clarification Artifact | `clarifier` role output |
+| `research.schema.json` | Research Artifact | `researcher` role output |
+| `spec-challenge.schema.json` | Spec Challenge Artifact | `spec_challenge` workflow |
+| `run-manifest.schema.json` | Run Manifest | `capture init` |
+| `export-manifest.schema.json` | Export Manifest | `export build` output |
+| `host-export-package.schema.json` | Host Export Package | per-host `host-package.json` |
+| `docs-claim.schema.json` | Docs Truth Claim | `validate docs` + `docs/truth-claims.yaml` |
+| `proposed-learning.schema.json` | Proposed Learning | `learner` role output |
+| `accepted-learning.schema.json` | Accepted Learning | `learn` workflow approval |
+
+---
+
+## Required Fields Pattern
+
+All artifact schemas share a common envelope of required fields:
+
+```json
+{
+  "phase":       "specify",           // must match exactly the declaring phase
+  "role":        "specifier",         // must match exactly the declaring role
+  "run_id":      "abc-123",           // ties the artifact to a specific run
+  "created_at":  "2026-03-13T...",    // ISO 8601 datetime
+  "sources":     ["input/brief.md"],  // files this artifact was derived from
+  "status":      "approved",          // current lifecycle state
+  "loop_number": 0                    // tracks refinement iteration
+}
+```
+
+Phase-specific fields are added on top. For example, `spec.schema.json` also requires
+`requirements`, `acceptance_criteria`, and `approval`. `review.schema.json` requires
+a `findings` array where each entry carries a `severity` and `title`.
+
+---
+
+## Schema Rules
+
+From `schemas/README.md` — these rules are enforced by convention and CI:
+
+- **Additive changes** preserve existing valid artifacts and keep `manifest_version` stable.
+- **Breaking changes** must update `manifest_version`, docs, templates, and verification
+  in the same change set.
+- **Breaking manifest bumps** must ship explicit upgrade guidance so older manifests fail
+  with actionable errors rather than opaque schema-only messages.
+- **Schema-backed examples** under `templates/examples/` must stay valid under automated
+  tests — they serve as both documentation and regression fixtures.
+- **No prose-only contracts** — if a contract cannot be machine-validated, it does not
+  belong in `schemas/`.
+
+---
+
+## Validating Against a Schema
+
+**Via CLI (recommended):**
+
+```bash
+# Validate the project manifest
+wazir validate manifest
+
+# Validate canonical hook definitions
+wazir validate hooks
+
+# Validate docs truth claims and markdown links
+wazir validate docs
+
+# Run all checks at once
+wazir doctor
+```
+
+**Programmatic (Node.js):**
+
+```js
+import { validateAgainstSchema } from './tooling/src/schema-validator.js';
+import { readJsonFile } from './tooling/src/loaders.js';
+
+const artifact = readJsonFile('path/to/my-spec.json');
+const result = validateAgainstSchema(artifact, 'spec');
+if (!result.valid) {
+  console.error(result.errors);
+}
+```
+
+**With a JSON Schema tool (standalone):**
+
+```bash
+npx ajv validate \
+  -s schemas/spec.schema.json \
+  -d path/to/my-spec.json \
+  --spec=draft2020
+```
+
+---
+
+## Example Validation Workflow
+
+```
+1. specifier produces spec artifact (YAML/JSON)
+        │
+        ▼
+2. wazir validate manifest          ← manifest gates export
+        │
+        ▼
+3. spec artifact validated against       ← spec.schema.json
+   spec.schema.json on phase handoff
+        │
+        ▼
+4. planner reads approved spec,
+   produces implementation-plan artifact
+        │
+        ▼
+5. plan artifact validated against        ← implementation-plan.schema.json
+   implementation-plan.schema.json
+        │
+        ▼
+6. wazir export build               ← validates + hashes all canonical sources
+        │
+        ▼
+7. CI: wazir export --check         ← fails if canonical sources changed since build
+```
+
+---
+
+## Adding a New Schema
+
+1. Create `schemas/<artifact-name>.schema.json` using JSON Schema Draft 2020-12.
+2. Include the common envelope fields (`phase`, `role`, `run_id`, `created_at`,
+   `sources`, `status`, `loop_number`) as required.
+3. Add a corresponding example fixture to `templates/examples/` and verify it passes
+   under `npm test`.
+4. Register any new `validate` sub-command in `tooling/src/checks/command-registry.js`
+   and document it in `docs/tooling-cli.md` + `docs/truth-claims.yaml`.
+5. If the change is breaking, bump `manifest_version` in `wazir-manifest.schema.json`
+   and write upgrade guidance in `docs/`.

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

@@ -0,0 +1,63 @@
+# Skills
+
+> Reusable in-host procedures that enforce disciplined engineering work across every AI agent session.
+
+Skills are the **operational layer** of Wazir. Where roles define who acts and workflows define what phases exist, skills define exactly how work gets done — step by step, with explicit rules and required outputs.
+
+## Skill Roster
+
+| Skill | ID | Type | Purpose |
+|---|---|---|---|
+| [Using Skills](using-skills.md) | `wz:using-skills` | Rigid | Skill discovery bootstrap — must fire before any response |
+| [Brainstorming](brainstorming.md) | `wz:brainstorming` | Rigid | Turn briefings into approved designs before implementation |
+| [Writing Plans](writing-plans.md) | `wz:writing-plans` | Rigid | Produce execution-grade implementation plans from approved designs |
+| [TDD](tdd.md) | `wz:tdd` | Rigid | Enforce RED → GREEN → REFACTOR with evidence at each step |
+| [Debugging](debugging.md) | `wz:debugging` | Rigid | Observe-hypothesize-test-fix loop instead of guesswork |
+| [Verification](verification.md) | `wz:verification` | Rigid | Require fresh command evidence before any completion claim |
+| [Design](design.md) | `wz:design` | Flexible | Guide designer role through open-pencil MCP visual design workflow |
+| [Scan Project](scan-project.md) | `scan-project` | Flexible | Build an evidence-based project profile from repo surfaces |
+| [Run Audit](run-audit.md) | `run-audit` | Flexible | Interactive structured codebase audit with report or fix-plan output |
+| [Self-Audit](self-audit.md) | `self-audit` | Flexible | Worktree-isolated audit-fix loop — safe self-improvement |
+| [Prepare Next](prepare-next.md) | `prepare-next` | Flexible | Produce a clean next-run handoff without stale context bleed |
+
+## Skill Types
+
+| Type | Meaning |
+|---|---|
+| **Rigid** | Follow exactly. The discipline is the point — do not adapt away the structure. |
+| **Flexible** | Adapt principles to context. The skill guides; judgment fills gaps. |
+
+## How Skills Work
+
+Skills are invoked via the `Skill` tool in Claude Code. When invoked, the skill's content is loaded and presented to the agent, which then follows it directly. Skills are **never** read via the `Read` tool on skill files — that bypasses the invocation contract.
+
+```
+User message received
+    → Check: might any skill apply? (even 1% chance = yes)
+    → Invoke Skill tool
+    → Announce: "Using [skill] to [purpose]"
+    → Follow skill exactly
+    → Respond
+```
+
+## Skill Priority
+
+When multiple skills could apply:
+
+1. **Process skills first** — `wz:brainstorming`, `wz:debugging` determine HOW to approach the task.
+2. **Implementation skills second** — `wz:tdd`, `wz:design` guide execution.
+
+## Rules
+
+- Skills must reference `input/`, canonical roles/workflows, or external state-root conventions.
+- Skills must not instruct running background services outside the canonical workflow surface.
+- When a skill contradicts the current operating model, it is removed — not left conflicting.
+- Only active skills belong in `skills/`.
+
+## Integration with Workflows
+
+```
+clarify → discover (scan-project) → specify → design (wz:design) → plan (wz:brainstorming + wz:writing-plans) → execute (wz:tdd) → verify (wz:verification) → review → learn → prepare-next
+```
+
+Skills activate within phases. A phase entrypoint does not replace skill invocation — both operate simultaneously.

package/docs/readmes/features/skills/brainstorming.md

@@ -0,0 +1,96 @@
+# wz:brainstorming
+
+> Turn operator briefings into approved designs with explicit trade-offs — before a single line of implementation code is written.
+
+| Property | Value |
+|---|---|
+| **ID** | `wz:brainstorming` |
+| **Type** | Rigid |
+| **Trigger** | "About to enter plan mode" OR any implementation request without an approved design |
+| **Failure mode** | Coding without a reviewed design — produces unvalidated output |
+
+## Purpose
+
+`wz:brainstorming` creates a mandatory design gate between "I want X" and "I'm building X". It forces the agent to surface trade-offs, resolve ambiguities that affect scope or architecture, and get operator approval before implementation starts. This prevents the most expensive failure mode in AI-assisted engineering: confident, well-executed work that solves the wrong problem.
+
+## When to Invoke
+
+- Any time the agent is about to enter plan mode and no approved design exists.
+- When an operator briefing describes a feature, change, or fix with architectural implications.
+- When the task scope is unclear and the ambiguity could change what gets built.
+
+> [!TIP]
+> `wz:using-skills` will route you here automatically when "Let's build X" or similar phrases appear. If you find yourself reaching for an editor before a design doc exists, this skill has not fired.
+
+## When NOT to Invoke
+
+- A trivial, fully-specified, single-file fix where no design decision exists (e.g., "fix the typo on line 14").
+- The design has already been approved and written to `docs/plans/` — proceed to `wz:writing-plans`.
+- Documentation-only changes with no behavioral implications.
+
+> [!WARNING]
+> Do not skip brainstorming because the implementation "feels obvious". The value is in surfacing the 20% of the problem that turns a clean solution into a rework cycle.
+
+## Phases
+
+1. **Read `input/`** — understand operator constraints, requirements, and context before touching the repo.
+2. **Inspect repo surfaces** — read only the minimum surfaces needed to understand the request (do not do a full scan).
+3. **Ask clarifying questions** — only for ambiguities that change scope, architecture, or acceptance criteria. One round only.
+4. **Propose 2-3 approaches** — each with trade-offs and a recommendation. Make the recommendation explicit.
+5. **Operator review** — wait for approval. Do not proceed past this point autonomously.
+6. **Write approved design** — to `docs/plans/YYYY-MM-DD-<topic>-design.md`.
+7. **Hand off** — invoke `wz:writing-plans` with the approved design as input.
+
+## Input
+
+- `input/` directory — operator-supplied requirements, constraints, context
+- Relevant repo surfaces (minimum necessary)
+
+## Output
+
+| Artifact | Location | Required |
+|---|---|---|
+| Design document | `docs/plans/YYYY-MM-DD-<topic>-design.md` | Yes |
+| Trade-off summary | Within design doc | Yes |
+| Open questions / resolved assumptions | Within design doc | Yes |
+| Explicit recommendation + rejected alternatives | Within design doc | Yes |
+
+## Example
+
+**Scenario:** Operator says "Add rate limiting to the API."
+
+```
+Agent: Invoking wz:brainstorming skill.
+Agent: "Using wz:brainstorming to turn the rate limiting briefing into an approved design."
+
+[Reads input/ — finds: target endpoint, expected traffic ~1k req/s, Redis available]
+[Reads src/api/ — finds Express middleware pattern already in use]
+
+Agent: "One clarifying question: should rate limiting apply per-IP, per-auth-token, or both?"
+Operator: "Per-auth-token."
+
+Agent proposes:
+  Option A: In-process sliding window (simple, no external dep, loses state on restart)
+  Option B: Redis token bucket (stateful, accurate, requires Redis client setup)
+  Option C: Upstream proxy-level (nginx, zero app code, loses per-token granularity)
+
+  Recommendation: Option B — Redis is already in the stack, token-based accuracy matches the stated need.
+
+[Operator approves Option B]
+
+Agent: Writing design to docs/plans/2026-03-13-rate-limiting-design.md
+Agent: Invoking wz:writing-plans...
+```
+
+## Integration
+
+`wz:brainstorming` is the mandatory first step in the plan → execute chain:
+
+```
+wz:brainstorming (design approved)
+    → wz:writing-plans (implementation plan produced)
+        → wz:tdd (RED/GREEN/REFACTOR execution)
+            → wz:verification (completion proof)
+```
+
+It also feeds `run-audit` in plan mode: when audit findings are approved by the operator, they become the equivalent of a brainstorming-approved design and flow directly into `wz:writing-plans`.