@wazir-dev/cli 1.0.0

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

@@ -0,0 +1,193 @@
+# Designer
+
+![Role](https://img.shields.io/badge/role-designer-blue) ![Phase](https://img.shields.io/badge/phase-6%20%E2%80%94%20design-lightgrey) ![Status](https://img.shields.io/badge/status-stable-green) ![Adapter](https://img.shields.io/badge/adapter-open--pencil%20MCP-orange)
+
+**From approved spec to pixel-perfect visual source of truth — before a single line of implementation code is written.**
+
+---
+
+## What is this?
+
+The designer transforms the approved spec into visual designs. It uses open-pencil MCP tools to create Figma-compatible design files, export code scaffolds, and produce design tokens — all before planning or execution begins.
+
+This phase prevents the single most common cause of implementation rework: building the wrong UI. When the planner and executor receive not just a spec but also a `.fig` file, JSX scaffolds, and design tokens, they are implementing a defined visual contract, not interpreting a text description.
+
+The designer sits between `author` (content authoring, which is itself optional) and `plan` (implementation planning). It is optional for non-visual tasks and mandatory for any feature with a user interface.
+
+---
+
+## Key Capabilities
+
+- Creates Figma-compatible `.fig` design files via open-pencil MCP tools
+- Exports Tailwind JSX scaffolds ready for direct integration
+- Exports HTML + CSS scaffolds as fallback or alternative targets
+- Produces design tokens JSON (colors, spacing, typography, shadows) synchronized with visual source
+- Captures screenshot PNGs of all key frames for review and documentation
+- Escalates when spec is ambiguous about visual requirements or when brand constraints conflict with usability
+
+---
+
+## How It Fits in the Pipeline
+
+The designer is **Phase 6**. It runs after author approval (or spec-challenge if author is skipped) and before planning.
+
+```
+[approved spec artifact]
+[research artifacts]
+[brand/style guidelines]
+            │
+            ▼
+       [designer]
+            │
+            ├──► .fig design file
+            ├──► Tailwind JSX scaffold
+            ├──► HTML + CSS scaffold
+            ├──► design tokens JSON
+            └──► screenshot PNGs (key frames)
+            │
+            ▼
+  [design-review]  ──► reviewer validates against spec, accessibility, visual consistency
+            │
+            ▼
+       [planner]
+```
+
+**Triggered by:** `design` workflow.
+
+**Feeds into:** `design-review` workflow (reviewer role), then planner.
+
+---
+
+## Input / Output Contract
+
+| | Details |
+|---|---|
+| **Inputs** | Approved spec artifact, research artifacts, brand/style guidelines (if available) |
+| **Allowed tools** | open-pencil MCP tools (create, modify, export, analyze), local file reads, image export and screenshot capture |
+| **Output: .fig design file** | Figma-compatible visual source of truth |
+| **Output: Tailwind JSX scaffold** | Component structure with Tailwind classes, ready for executor |
+| **Output: HTML + CSS scaffold** | Alternative export for non-React targets |
+| **Output: design tokens JSON** | All design decisions as machine-readable tokens |
+| **Output: screenshot PNGs** | Visual snapshots of all key frames for review and audit |
+
+---
+
+## Example
+
+Given a spec for a rate limit exceeded error state:
+
+**Design artifact (excerpt):**
+
+```markdown
+# Design Artifact: Rate Limit UI
+
+## Frames Designed
+1. `rate-limit-429-banner` — inline error banner shown on API playground
+2. `rate-limit-headers-debug` — developer tools panel showing X-RateLimit-* headers
+
+## Design Tokens (excerpt)
+{
+  "color-error-bg": "#FEF2F2",
+  "color-error-border": "#FECACA",
+  "color-error-text": "#991B1B",
+  "spacing-banner-padding": "12px 16px",
+  "border-radius-banner": "6px"
+}
+
+## Tailwind JSX Scaffold (rate-limit-429-banner)
+```
+
+```jsx
+export function RateLimitBanner({ retryAfter }: { retryAfter: number }) {
+  return (
+    <div className="flex items-center gap-3 rounded-md border border-red-200 bg-red-50 px-4 py-3">
+      <AlertCircle className="h-4 w-4 shrink-0 text-red-600" />
+      <p className="text-sm text-red-800">
+        Rate limit exceeded. Retry in{" "}
+        <span className="font-semibold">{retryAfter}s</span>.
+      </p>
+    </div>
+  );
+}
+```
+
+```markdown
+## Accessibility Checks
+- Error state uses color + icon (not color alone) — WCAG 1.4.1 pass
+- Error text contrast ratio: 7.2:1 against bg-red-50 — WCAG AA pass
+- No interactive elements without keyboard focus states
+
+## Files
+- state/design/rate-limit-429-banner.fig
+- state/design/exports/rate-limit-banner.tsx
+- state/design/exports/rate-limit-banner.html
+- state/design/tokens/rate-limit.tokens.json
+- state/design/screenshots/rate-limit-429-banner.png
+```
+
+---
+
+## Git-Flow Responsibilities
+
+The designer follows a strict commit convention:
+
+```bash
+feat(design): add rate limit error states and design tokens
+```
+
+Design files live in the **run-local state directory** (`~/.wazir/projects/<project-slug>/design/`), not in the repository. Only exported code scaffolds and design token JSON files are committed to the repo.
+
+---
+
+## Configuration
+
+| Setting | Location | Effect |
+|---------|----------|--------|
+| `open_pencil` adapter | `wazir.manifest.yaml` → `adapters.open_pencil` | Enables open-pencil MCP tools (off by default) |
+| `design_review` workflow | `workflows/` | Gates plan phase behind design validation |
+| Brand/style guidelines | `input/` or project docs | Constrains visual decisions; designer reads but does not mutate |
+
+> [!NOTE]
+> open-pencil is an **optional adapter**. It is not required for core Wazir functionality. Tasks without a visual UI component skip the design phase entirely and proceed from `spec-challenge` directly to `plan`.
+
+---
+
+## When to Use / When NOT to Use
+
+**Use the designer when:**
+- The spec describes a user interface, dashboard, component, or visual output
+- You need to prevent implementation rework caused by UI misinterpretation
+- Design tokens need to be synchronized across multiple components
+- Accessibility compliance must be verified before code is written
+
+**Do NOT invoke the designer when:**
+- The task is purely backend, infrastructure, or CLI — skip to planner
+- open-pencil adapter is not available — note the absence in the artifact and proceed
+- You are in mid-execution and want to make visual tweaks — that is an out-of-scope change requiring a new spec
+
+> [!WARNING]
+> Design drift from the approved spec is a failure condition. The designer must implement what the spec describes, not what looks better or feels more complete. Any divergence must be escalated before the design artifact is produced.
+
+---
+
+## Failure Conditions
+
+| Condition | Why It Matters |
+|-----------|----------------|
+| Design drift from approved spec | Planner and executor implement the wrong thing; review will reject |
+| Inaccessible designs (missing alt text, insufficient contrast) | Ships a WCAG violation; design-review will flag |
+| Missing design tokens | Executor has no machine-readable design source; visual consistency breaks |
+| No exported code scaffolds | Executor must interpret visual designs manually; rework risk increases |
+
+---
+
+## Related
+
+- [Roles Overview](README.md)
+- [specifier](specifier.md) — upstream role (produces the approved spec)
+- [content-author](content-author.md) — upstream role (provides authored content for designs)
+- [reviewer](reviewer.md) — validates design in `design-review` workflow
+- [planner](planner.md) — downstream role (receives design artifacts)
+- [executor](executor.md) — uses JSX/CSS scaffolds directly
+- [Design Workflow](../workflows/design.md) _(coming soon)_
+- [Design-Review Workflow](../workflows/design-review.md) _(coming soon)_

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

@@ -0,0 +1,184 @@
+# Executor
+
+![Role](https://img.shields.io/badge/role-executor-blue) ![Phase](https://img.shields.io/badge/phase-10%20%E2%80%94%20execution-lightgrey) ![Status](https://img.shields.io/badge/status-stable-green)
+
+**Slice by slice. No drift. No invention. No fake tests.**
+
+---
+
+## What is this?
+
+The executor implements the approved plan. That's it. It writes code, runs tests, produces verification evidence, and follows the git-flow rules defined by the planner — without deviating from the approved artifacts, inventing scope, or writing tests that don't actually test anything.
+
+The executor is the role with the most tool access and the tightest operating constraints. It can edit code, run tests, execute build commands, and inspect the repo. It cannot merge branches, write to protected paths outside approved flows, or unilaterally expand scope when it hits a blocker.
+
+The key discipline: **the executor executes, it does not decide**. When it encounters something the plan does not cover, it escalates — it does not invent a solution and continue.
+
+---
+
+## Key Capabilities
+
+- Implements plan tasks slice by slice in the specified order
+- Writes code changes according to the approved spec and design artifacts
+- Runs tests after each slice and captures results as verification evidence
+- Follows conventional commit format for every commit
+- Updates `CHANGELOG.md` `[Unreleased]` section for every user-facing change
+- Creates feature/codex branches from develop (or hotfix from main) per plan specification
+- Produces execution notes documenting what was done, any surprises, and decisions made
+
+---
+
+## How It Fits in the Pipeline
+
+The executor is **Phase 10**. It runs after plan-review approval.
+
+```
+[approved implementation plan]
+[active canonical files]
+[current branch state]
+[design artifacts — if design phase ran]
+            │
+            ▼
+       [executor]
+            │
+            ├──► code and docs changes (committed to feature branch)
+            ├──► execution notes
+            └──► verification evidence (test runs, build output)
+            │
+            ▼
+       [verifier]
+```
+
+**Triggered by:** `execute` workflow.
+
+**Feeds into:** verifier.
+
+---
+
+## Input / Output Contract
+
+| | Details |
+|---|---|
+| **Inputs** | Approved implementation plan, active canonical files, current branch state |
+| **Allowed tools** | Code editing, test execution, build and verification commands, repo inspection |
+| **Output: code and docs changes** | All changes committed to feature branch in conventional commit format |
+| **Output: execution notes** | Summary of what was implemented, deviations from plan (escalated), surprises |
+| **Output: verification evidence** | Actual command output from test and build runs — not summaries |
+
+---
+
+## Example
+
+Executing Task 2 from the rate limiting plan:
+
+**Execution notes (excerpt):**
+
+```markdown
+## Task 2: Rate limit middleware
+
+### Branch
+feature/rate-limiting (created from develop at commit a3f9b2c)
+
+### Work Done
+- Created src/middleware/rateLimit.ts
+  - Token bucket via rate-limiter-flexible RateLimiterRedis
+  - Fail-open on Redis connection errors (logs to alerting)
+  - Injects X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset on all responses
+  - Returns 429 + Retry-After when bucket exhausted
+- Applied middleware in src/api/routes/index.ts at line 47
+  (after auth middleware, before route handlers — matches plan spec)
+- Updated src/middleware/index.ts to export rateLimit
+
+### Commit
+feat(api): add per-key token bucket rate limiting middleware
+
+### Verification Evidence
+$ npm test src/middleware/rateLimit.test.ts
+  ✓ allows 100 requests within window (234ms)
+  ✓ blocks 101st request with 429 (12ms)
+  ✓ includes X-RateLimit-* headers on all responses (8ms)
+  ✓ fail-open when Redis unavailable (45ms)
+  4 passing (299ms)
+
+### Surprises / Notes
+- Existing auth middleware already attaches req.apiKey — no additional
+  extraction needed. Plan assumption confirmed.
+- rate-limiter-flexible requires explicit keyPrefix to avoid Redis key
+  collisions with session store. Added keyPrefix: 'rl:' — within spec scope.
+```
+
+---
+
+## Git-Flow Responsibilities
+
+The executor is the role that actually produces commits. Its git-flow rules are strict:
+
+```bash
+# Branch naming (specified in plan)
+git checkout -b feature/rate-limiting
+
+# Every commit uses conventional format
+git commit -m "feat(api): add per-key token bucket rate limiting middleware"
+
+# CHANGELOG update for every user-facing change
+# Add to CHANGELOG.md [Unreleased] section before committing
+
+# Do NOT merge — merges happen post-review
+# Do NOT push to develop or main directly
+```
+
+| Rule | Why |
+|------|-----|
+| Conventional commit format | Enables automated changelog generation and `wazir validate commits` |
+| CHANGELOG update per user-facing change | `wazir validate changelog --require-entries` will fail if missing |
+| No merge to develop/main | Review and merge happen after verifier and reviewer sign off |
+| No writes to protected paths | `protected_path_write_guard` hook enforces this at runtime |
+
+---
+
+## Configuration
+
+| Setting | Location | Effect |
+|---------|----------|--------|
+| `loop_cap_guard` hook | `hooks/` | Caps execution iterations; prevents runaway loops |
+| `protected_path_write_guard` hook | `hooks/` | Blocks writes to `input/`, `roles/`, `workflows/`, `schemas/`, `exports/hosts/` |
+| `post_tool_capture` hook | `hooks/` | Routes all tool outputs to capture for audit trail |
+| Protected paths | `wazir.manifest.yaml` → `protected_paths` | Defines which paths are off-limits |
+
+---
+
+## When to Use / When NOT to Use
+
+**Use the executor when:**
+- You have an approved implementation plan and are ready to write code
+- All upstream artifacts (spec, plan, optionally design) have been reviewed and approved
+- The feature branch has been created and the working environment is clean
+
+**Do NOT invoke the executor when:**
+- The plan is not approved — executing from an unapproved plan is a contract violation
+- You want to "quickly hack something in" outside the pipeline — go back to clarifier
+- The plan has gaps that would require invention — resolve the gaps in plan-review first
+
+> [!WARNING]
+> **Fake tests are an unconditional failure condition.** A test that is structured to pass regardless of whether the feature works — empty assertions, hard-coded expected values, skipped assertions — is worse than no test at all. It produces false verification evidence that corrupts every downstream role's decisions.
+
+---
+
+## Failure Conditions
+
+| Condition | Why It Matters |
+|-----------|----------------|
+| Plan drift | Executor implements something not in the spec; reviewer will reject |
+| Unwired paths | Code exists but is not connected to anything; feature doesn't work in production |
+| Fake tests | False verification evidence corrupts verifier and reviewer decisions |
+| Writes to protected paths outside approved flows | Hook violation; execution is blocked |
+
+---
+
+## Related
+
+- [Roles Overview](README.md)
+- [planner](planner.md) — upstream role (produces the approved plan)
+- [verifier](verifier.md) — downstream role (validates the executor's output)
+- [reviewer](reviewer.md) — adversarial review after verification
+- [Execute Workflow](../workflows/execute.md) _(coming soon)_

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

@@ -0,0 +1,210 @@
+# Learner
+
+![Role](https://img.shields.io/badge/role-learner-blue) ![Phase](https://img.shields.io/badge/phase-13%20%E2%80%94%20learning-lightgrey) ![Status](https://img.shields.io/badge/status-stable-green)
+
+**The run is done. The learner makes sure the next run is smarter — without silently mutating the system.**
+
+---
+
+## What is this?
+
+The learner closes the feedback loop. After a run completes — or after a review surfaces significant findings — the learner reads the run artifacts, review findings, and verification evidence, and extracts durable, scoped learnings that can improve future runs.
+
+The key constraint is in the name: learnings are **proposed**, not auto-applied. The learner produces artifacts for human review. It does not silently update role contracts, operating rules, or shared defaults. Any proposed learning that is broad enough to affect the core system must be escalated.
+
+This discipline prevents one of the most dangerous failure modes in AI-assisted engineering: a system that "learns" its way into inconsistency by accumulating unreviewed mutations to its own operating rules.
+
+---
+
+## Key Capabilities
+
+- Synthesizes run artifacts, review findings, and verification evidence into proposed learnings
+- Structures learnings with confidence levels and explicit scope (project-local vs. system-wide)
+- Produces experiment summaries when the run tested a hypothesis or tried a new approach
+- Records git-flow violations (bad branch names, non-conventional commits, missing changelog) as learnings for injection into future executor prompts
+- Tracks patterns of violations across runs
+- Escalates when a proposed learning is broad enough to affect fresh-run defaults or core operating rules
+
+---
+
+## How It Fits in the Pipeline
+
+The learner is **Phase 13** — the final role in the pipeline. It runs after review.
+
+```
+[run artifacts]
+[review findings]
+[verification evidence]
+            │
+            ▼
+       [learner]
+            │
+            ├──► proposed learning artifacts
+            ├──► experiment summaries
+            └──► confidence and scope metadata
+            │
+            ▼
+  [operator review] ──► approve / reject / escalate each learning
+            │
+            ▼
+  [prepare-next] ──► approved learnings injected into next run context
+```
+
+**Triggered by:** `learn` workflow, or as part of `prepare-next`.
+
+**Feeds into:** operator review, then `prepare-next` workflow for the next task.
+
+> [!NOTE]
+> Approved learnings that are project-local are stored in `~/.wazir/projects/<project-slug>/memory/`. System-wide learnings require a PR to the core repo and explicit reviewer approval.
+
+---
+
+## Input / Output Contract
+
+| | Details |
+|---|---|
+| **Inputs** | Run artifacts (spec, plan, execution notes), review findings, verification evidence |
+| **Allowed tools** | Local file reads, artifact synthesis, experiment/result comparison |
+| **Output: proposed learning artifacts** | Each learning: observation, evidence, proposed change, confidence, scope |
+| **Output: experiment summaries** | For runs that tested an approach: hypothesis, result, conclusion |
+| **Output: confidence and scope metadata** | How certain is this learning? Where does it apply? |
+
+---
+
+## Learning Structure
+
+Each proposed learning follows a consistent structure:
+
+```markdown
+## Learning: [short title]
+
+### Observation
+What was observed across this run (or pattern of runs).
+
+### Evidence
+- review/findings.md → FINDING-2: alerting path used console.log instead of alert service
+- review/findings.md → FINDING pattern (3 of last 4 runs): Redis fail-open path omits alerting
+
+### Proposed Change
+Add to executor context for infrastructure tasks:
+"When implementing fail-open paths, use src/services/alerting.ts — not console.log.
+See src/services/alerting.ts for the interface."
+
+### Confidence
+MEDIUM — observed in 3 of 4 runs with Redis integration tasks.
+
+### Scope
+project-local — specific to this codebase's alerting pattern.
+Does NOT affect system-wide defaults.
+
+### Status
+PROPOSED — awaiting operator review.
+```
+
+---
+
+## Example
+
+After the rate limiting run review:
+
+**Proposed learning artifacts (excerpt):**
+
+```markdown
+# Proposed Learnings: Rate Limiting Run (2026-03-13)
+
+## Learning 1: Fail-open alerting path
+Observation: Executor used console.log for fail-open alert path.
+Evidence: FINDING-2 (BLOCKING) in review/rate-limiting-review.md
+Proposed change: Inject into executor context for Redis tasks:
+  "Fail-open paths must use alerting service, not console.log.
+   Interface: src/services/alerting.ts → alert(level, message, context)"
+Confidence: HIGH — clear pattern, single correct path in codebase.
+Scope: project-local.
+
+## Learning 2: Rate limit header format ambiguity
+Observation: X-RateLimit-Reset format was not specified in spec.
+Evidence: FINDING-1 (NON-BLOCKING) in review/rate-limiting-review.md
+Proposed change: Add to specifier context for API header tasks:
+  "Specify format for date/time headers explicitly:
+   Unix timestamp (seconds) | ISO 8601 | delta-seconds (RFC 7231 §7.1.3)"
+Confidence: MEDIUM — general principle, applies beyond this project.
+Scope: ESCALATE — broad enough to affect specifier defaults system-wide.
+
+## Experiment Summary: Token bucket vs. fixed window
+Hypothesis: Token bucket via rate-limiter-flexible would be simpler to implement
+  than building a fixed window counter from scratch.
+Result: Implementation took 2 tasks, 3 commits, 0 blocking review findings on the
+  algorithm itself. redis-rate-limiter-flexible API was straightforward.
+Conclusion: Confirmed. For future rate limiting tasks in this codebase,
+  rate-limiter-flexible is the recommended starting point.
+```
+
+---
+
+## Git-Flow Responsibilities
+
+The learner specifically tracks git-flow quality across runs:
+
+```
+Record:
+- Branch naming violations (e.g., "changes" instead of "feature/...")
+- Commits that failed conventional format on the first attempt
+- Missing changelog entries caught by verifier or reviewer
+
+Track:
+- Patterns across multiple runs (same executor, same task type)
+
+Propose:
+- Injecting reminders into executor context when patterns are detected
+- Escalating if a pattern suggests the executor's baseline prompt needs updating
+```
+
+This creates a self-improving loop: violations caught in review become learnings that prevent the same violation in future executions.
+
+---
+
+## Configuration
+
+| Setting | Location | Effect |
+|---------|----------|--------|
+| State root | `wazir.manifest.yaml` → `paths.state_root_default` | Approved project-local learnings stored at `~/.wazir/projects/<slug>/memory/` |
+| `memory/` path | repo `memory/` directory | Shared team learnings committed to repo |
+| `prepare_next` workflow | `workflows/` | Injects approved learnings into next run context |
+
+---
+
+## When to Use / When NOT to Use
+
+**Use the learner when:**
+- A run has completed (reached approved review verdict)
+- A review session surfaced significant findings — even if the run is not complete
+- You want to capture an experiment result while the evidence is fresh
+- Multiple runs have shown the same pattern and it needs to be captured before it is forgotten
+
+**Do NOT invoke the learner when:**
+- The run is still in progress — wait for review to complete
+- You want to use it to auto-apply changes to role contracts or operating rules — that requires escalation and PR review
+- You want to record opinions without evidence — every learning must be tied to an artifact or observation
+
+> [!WARNING]
+> **Auto-applied learning drift** is the most serious learner failure condition. A learning that silently changes a role contract, a default behavior, or a core operating rule — without going through escalation and operator review — corrupts the system in ways that are very hard to detect and reverse.
+
+---
+
+## Failure Conditions
+
+| Condition | Why It Matters |
+|-----------|----------------|
+| Auto-applied learning drift | Core system rules change without review; corruption is invisible and cumulative |
+| Missing evidence | Learning cannot be evaluated; may be noise or bias rather than signal |
+| Unscoped learnings | A project-specific pattern gets applied system-wide; wrong context, wrong effect |
+
+---
+
+## Related
+
+- [Roles Overview](README.md)
+- [reviewer](reviewer.md) — upstream role (produces findings that feed learner)
+- [clarifier](clarifier.md) — invoked in `prepare-next` with approved learnings injected
+- [Learn Workflow](../workflows/learn.md) _(coming soon)_
+- [Prepare-Next Workflow](../workflows/prepare-next.md) _(coming soon)_