@wazir-dev/cli 1.0.0

package/docs/readmes/features/hooks/stop-handoff-harvest.md

@@ -0,0 +1,125 @@
+# stop_handoff_harvest
+
+> `PostToolUse` / Session end · Observability · Harvests final handoff notes and persists stop-time observability data when a session ends.
+
+| Property | Value |
+|---|---|
+| **Hook ID** | `stop_handoff_harvest` |
+| **Trigger event** | Session ends (agent stop event) |
+| **Failure mode** | `capture` — exits 0, session ends regardless |
+| **Exit codes** | `0` always |
+
+## What It Guards
+
+`stop_handoff_harvest` is the final observability event in every session. When the agent stops, this hook ensures that the handoff document and stop-time state are persisted to the run's state directory — so the next session can start with full context rather than reconstructing what happened from memory.
+
+Without this hook, session state is lost at disconnect. The next session starts cold.
+
+## Trigger Event
+
+Fires once when the agent session ends — immediately before the process terminates or the connection closes.
+
+## Logic
+
+1. **Receive run ID** — identify the current session's state directory.
+2. **Read current `status.json`** — capture the final run state.
+3. **Append a stop event** — write a terminal event to `events.ndjson` with timestamp and session summary.
+4. **Write `summary.md`** — produce a structured stop-time handoff summary.
+5. **Exit 0** — session ends cleanly.
+
+## Configuration
+
+| Parameter | Required | Description |
+|---|---|---|
+| `run_id` | Yes | The current session run identifier |
+
+## What Happens on Violation
+
+This hook does not block — session termination is not affected by hook behavior.
+
+| Condition | Outcome |
+|---|---|
+| State directory not found | Warning logged; session ends |
+| Write fails | Error to stderr; handoff data may be partial |
+| Hook encounters an error | Session ends; handoff data may not be persisted |
+
+**Side effects produced:**
+
+| Artifact | Location | Description |
+|---|---|---|
+| `events.ndjson` (stop event) | `~/.wazir/projects/<slug>/events.ndjson` | Final stop event appended |
+| `summary.md` | `~/.wazir/projects/<slug>/summary.md` | Stop-time handoff summary |
+
+## Summary Format
+
+The stop-time `summary.md` produced by this hook:
+
+```markdown
+# Session Handoff — run-42 — stopped 2026-03-13T11:30:00Z
+
+## Status at Stop
+- Phase: execute (section 3 of 5 complete)
+- Last verified: Section 3 — router wiring (PASS)
+
+## Completed This Session
+- Section 1: Redis client setup — VERIFIED
+- Section 2: Rate-limit middleware — VERIFIED
+- Section 3: Router wiring — VERIFIED
+
+## Blocked / Incomplete
+- Section 4: Redis integration tests — blocked (no Docker in CI)
+- Section 5: Load test — not started
+
+## Required Approvals for Next Session
+- Decision: mock Redis in tests OR add Docker to CI
+
+## Total Tool Executions: 12
+## Captures: 3 files (72KB)
+```
+
+## Example
+
+**Scenario:** Agent disconnects mid-plan after completing 3 of 5 sections.
+
+```
+Session running. Agent completes sections 1-3.
+Section 4 blocked (no Docker). Agent session ends.
+
+stop_handoff_harvest fires:
+  → Reads status.json (phase: execute, loop: 3)
+  → Reads events.ndjson (12 events)
+  → Appends stop event: { "type": "session_stop", "ts": "...", "run_id": "run-42" }
+  → Writes summary.md with completed work, blockers, approvals needed
+
+Next session starts:
+  → Agent reads ~/.wazir/projects/myapp/summary.md
+  → Immediately knows: sections 1-3 done, section 4 needs Docker decision
+  → No cold start reconstruction needed
+```
+
+## Testing
+
+```bash
+# Initialize a session and simulate stop
+wazir capture init
+wazir capture event --command "npm test" --exit-code 0
+wazir capture summary
+
+# Verify summary.md exists
+cat ~/.wazir/projects/wazir/summary.md
+
+# Validate hook definition
+node tooling/src/cli.js validate hooks
+```
+
+> [!TIP]
+> `stop_handoff_harvest` and the `prepare-next` skill are complementary. `prepare-next` is the agent-authored structured handoff document. `stop_handoff_harvest` is the machine-generated observability record. Use both.
+
+## Host Fallback
+
+| Host | Fallback |
+|---|---|
+| Claude | `native_hook` |
+| Codex | `wrapper_command` |
+| Gemini | `wrapper_command` |
+| Cursor | `native_or_wrapper` |

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

@@ -0,0 +1,157 @@
+# Wazir Roles
+
+![Status](https://img.shields.io/badge/status-alpha-orange) ![Version](https://img.shields.io/badge/version-0.1.0-blue) ![License](https://img.shields.io/badge/license-MIT-green) ![Hosts](https://img.shields.io/badge/hosts-Claude%20%7C%20Codex%20%7C%20Gemini%20%7C%20Cursor-purple)
+
+**Ten canonical roles. One coherent engineering pipeline. Zero ambiguity about who does what.**
+
+---
+
+## What is this?
+
+Wazir roles are the backbone of the system. Every role is a **canonical contract** — a precise definition of purpose, allowed tools, required outputs, escalation rules, and failure conditions. They are not personas or guidelines; they are enforceable, machine-readable operating boundaries.
+
+When you run Wazir on Claude, Codex, Gemini, or Cursor, the agent is always operating as one of these ten roles. The role determines what the agent is allowed to do, what it must produce, and when it must stop and escalate.
+
+This makes multi-phase, multi-agent engineering work **predictable, auditable, and composable**.
+
+---
+
+## The Ten Roles
+
+| Role | One-Line Purpose | Pipeline Position |
+|------|-----------------|-------------------|
+| [clarifier](clarifier.md) | Turn operator input into a scoped, question-resolved brief | Phase 1 — Entry |
+| [researcher](researcher.md) | Fill knowledge gaps with source-backed findings | Phase 2 — Discovery |
+| [specifier](specifier.md) | Produce a measurable, reviewable spec | Phase 3 — Specification |
+| [designer](designer.md) | Transform the approved spec into visual designs | Phase 6 — Design |
+| [content-author](content-author.md) | Write and package all non-code content artifacts | Phase 5 — Authoring |
+| [planner](planner.md) | Convert the approved spec into an execution-grade task plan | Phase 8 — Planning |
+| [executor](executor.md) | Implement the approved plan slice by slice | Phase 10 — Execution |
+| [verifier](verifier.md) | Run deterministic checks and produce proof bundles | Phase 11 — Verification |
+| [reviewer](reviewer.md) | Perform adversarial review for correctness and drift | Phase 12 — Review |
+| [learner](learner.md) | Extract durable scoped learnings from the completed run | Phase 13 — Learning |
+
+---
+
+## How Roles Fit the Pipeline
+
+```
+operator input
+      │
+      ▼
+ [clarifier]  ──► clarification artifact, open questions
+      │
+      ▼
+ [researcher] ──► research artifact, citations, risks
+      │
+      ▼
+ [specifier]  ──► spec artifact, acceptance criteria, non-goals
+      │
+      ▼
+ [designer]   ──► .fig file, JSX/CSS scaffolds, design tokens
+      │
+      ▼
+ [content-author] ──► microcopy, i18n keys, glossary, seed data
+      │
+      ▼
+  [planner]   ──► implementation plan, ordered tasks, verification plan
+      │
+      ▼
+  [executor]  ──► code changes, execution notes, verification evidence
+      │
+      ▼
+  [verifier]  ──► proof bundle, pass/fail status, command results
+      │
+      ▼
+  [reviewer]  ──► findings with severity, explicit verdict
+      │
+      ▼
+  [learner]   ──► learning artifacts, experiment summaries
+```
+
+Each role hands off a **named artifact** to the next. No role invents inputs — everything is traceable to an upstream artifact or operator approval.
+
+---
+
+## Role Contract Structure
+
+Every role contract defines the same six sections:
+
+```
+Purpose        — What problem this role solves
+Inputs         — What it consumes (artifacts, files, state)
+Allowed Tools  — What it is permitted to use
+Required Outputs — What it must produce before handing off
+Escalation Rules — When to stop and surface a decision
+Failure Conditions — What constitutes a broken contract
+```
+
+This uniformity makes roles composable. Any agent on any host can pick up a role contract and know exactly what to do and what not to do.
+
+---
+
+## Key Design Principles
+
+**Roles are not phases.** A single workflow phase may invoke multiple roles (e.g., `review` invokes the reviewer; `verify` invokes the verifier). Phases are the entrypoints; roles are the contracts.
+
+**Roles do not self-assign.** The workflow or operator routes an agent into a role. An agent operating as executor cannot unilaterally decide to also act as reviewer.
+
+**Escalation is mandatory, not optional.** Each role has explicit escalation rules. When those conditions are met, the role must surface the decision rather than making an assumption and continuing.
+
+**Protected paths are enforced at the role level.** The clarifier cannot mutate `input/`. The executor cannot write to protected paths outside approved flows. Violations are failure conditions, not warnings.
+
+**Artifacts are the handoff currency.** Roles do not hand off context blobs or verbal summaries — they produce named, schema-validated artifact files. The next role reads those artifacts.
+
+---
+
+## Canonical Source
+
+Role contracts live in `roles/` and are the single source of truth. Host-specific exports are generated from these contracts and must not be edited directly.
+
+```
+roles/
+  clarifier.md
+  researcher.md
+  specifier.md
+  designer.md
+  content-author.md
+  planner.md
+  executor.md
+  verifier.md
+  reviewer.md
+  learner.md
+```
+
+> [!NOTE]
+> `roles/` is a **protected path**. The `protected_path_write_guard` hook prevents direct writes from execution phases. All changes to role contracts go through a PR with explicit reviewer approval.
+
+---
+
+## Workflows That Invoke Roles
+
+| Workflow | Primary Role(s) |
+|----------|----------------|
+| `clarify` | clarifier |
+| `discover` | researcher |
+| `specify` | specifier |
+| `spec-challenge` | specifier + reviewer |
+| `author` | content-author |
+| `design` | designer |
+| `design-review` | reviewer |
+| `plan` | planner |
+| `plan-review` | reviewer |
+| `execute` | executor |
+| `verify` | verifier |
+| `review` | reviewer |
+| `learn` | learner |
+| `prepare-next` | learner + clarifier |
+
+---
+
+## Related
+
+- [Architecture](../../../concepts/architecture.md)
+- [Roles & Workflows](../../../concepts/roles-and-workflows.md)
+- [Workflows](../workflows/) _(coming soon)_
+- [Skills](../skills/) _(coming soon)_
+- [Hooks](../hooks/) _(coming soon)_

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

@@ -0,0 +1,152 @@
+# Clarifier
+
+![Role](https://img.shields.io/badge/role-clarifier-blue) ![Phase](https://img.shields.io/badge/phase-1%20%E2%80%94%20entry-lightgrey) ![Status](https://img.shields.io/badge/status-stable-green)
+
+**The first gate every task must pass through — turning noise into a scoped, question-resolved brief.**
+
+---
+
+## What is this?
+
+The clarifier is the entry-point role in the Wazir pipeline. Its job is to take raw operator input — a briefing file, a feature request, a problem statement — and produce a clarification artifact that resolves ambiguity, documents open questions, and defines a viable path forward.
+
+Every task that enters the pipeline must be clarified before any research, specification, or implementation begins. This isn't bureaucracy — it's the difference between building the right thing and building the wrong thing fast. Ambiguity caught at clarification costs minutes. Ambiguity caught at review costs days.
+
+---
+
+## Key Capabilities
+
+- Reads and processes `input/` briefing files without mutating them
+- Extracts and categorizes open questions by impact (architecture, feasibility, acceptance criteria)
+- Produces a scope summary with cited sources, not invented assumptions
+- Identifies constraints — technical, temporal, organisational — from available evidence
+- Maps viable paths forward when multiple approaches exist
+- Escalates immediately when ambiguity would change architecture or acceptance criteria
+
+---
+
+## How It Fits in the Pipeline
+
+The clarifier is **Phase 1**. It is the first role invoked by the `clarify` workflow and has no upstream role dependency.
+
+```
+[operator input / briefing files]
+            │
+            ▼
+       [clarifier]
+            │
+            ├──► clarification artifact
+            ├──► unresolved questions list
+            └──► scope summary with citations
+            │
+            ▼
+       [researcher]  (if open questions require research)
+       [specifier]   (if scope is already clear)
+```
+
+**Triggered by:** `clarify` workflow, or `prepare-next` workflow at the start of a new iteration.
+
+**Feeds into:** researcher (if knowledge gaps exist), specifier (if scope is clear and research is not required).
+
+---
+
+## Input / Output Contract
+
+| | Details |
+|---|---|
+| **Inputs** | `input/` briefing files, prior approved artifacts for the current run |
+| **Allowed tools** | Local file reads, scoped repo inspection, source-backed research inputs |
+| **Output: clarification artifact** | Resolved scope, constraints, assumptions, citations |
+| **Output: unresolved questions list** | Every open question that still needs an answer, with impact assessment |
+| **Output: scope summary** | A concise statement of what is in scope, what is out, and why |
+
+---
+
+## Example
+
+Given this briefing in `input/brief.md`:
+
+```markdown
+Add rate limiting to the public API. We've had some abuse.
+Users should not be able to make more than X requests per minute.
+```
+
+The clarifier produces:
+
+**Clarification artifact (excerpt):**
+
+```markdown
+## Scope
+Add per-user rate limiting to the public API.
+
+## Resolved Constraints
+- Feature branch off `develop`
+- Must not break existing authenticated client integrations
+
+## Open Questions
+1. What is the value of X? (BLOCKING — affects acceptance criteria)
+   Impact: Cannot write testable acceptance criteria without this.
+2. Should rate limit headers (X-RateLimit-*) be exposed to clients?
+   Impact: Affects API surface. Default: yes, per RFC 6585.
+3. Is the limit per-IP, per-API-key, or per-user-account?
+   Impact: Affects data model and storage choice.
+
+## Viable Paths
+A. Token bucket in Redis (recommended for distributed deployments)
+B. Fixed window counter in DB (simpler, suitable for low-scale)
+C. In-process sliding window (only viable for single-instance deployments)
+
+## Cited Sources
+- input/brief.md
+- src/api/routes/index.ts (current route structure, read-only inspection)
+```
+
+---
+
+## Configuration
+
+The clarifier does not have runtime configuration options. Its behavior is governed by:
+
+| Setting | Location | Effect |
+|---------|----------|--------|
+| `protected_path_write_guard` hook | `hooks/` | Prevents clarifier from writing to `input/` |
+| `input/` path | `wazir.manifest.yaml` → `paths.input` | Canonical location of briefing files |
+| Escalation threshold | `roles/clarifier.md` | Ambiguity that changes architecture, feasibility, or acceptance criteria triggers escalation |
+
+---
+
+## When to Use / When NOT to Use
+
+**Use the clarifier when:**
+- Starting any new task, feature, or investigation
+- Resuming a task after a significant gap or scope change
+- The briefing is ambiguous, incomplete, or contains conflicting requirements
+- You need to establish a shared understanding of scope before spending time on research or spec
+
+**Do NOT invoke the clarifier when:**
+- The task is already fully clarified with an approved clarification artifact
+- You are mid-execution and need a small decision — escalate from the executor instead
+- You want to use it as a stalling tactic; if the scope is clear, move to specifier
+
+> [!NOTE]
+> The clarifier **must not** invent constraints or facts. Every constraint in the clarification artifact must be traceable to a source (briefing file, existing code, operator statement). Invented constraints are a failure condition.
+
+---
+
+## Failure Conditions
+
+| Condition | Why It Matters |
+|-----------|----------------|
+| Leaves material ambiguity unresolved without escalation | Downstream roles will build on false assumptions |
+| Mutates `input/` | Briefing files are the operator's immutable record of intent |
+| Invents constraints or facts without evidence | Corrupts the artifact chain with untraceable assumptions |
+
+---
+
+## Related
+
+- [Roles Overview](README.md)
+- [researcher](researcher.md) — next role if knowledge gaps exist
+- [specifier](specifier.md) — next role if scope is clear
+- [Clarify Workflow](../workflows/clarify.md) _(coming soon)_
+- [Prepare-Next Workflow](../workflows/prepare-next.md) _(coming soon)_

package/docs/readmes/features/roles/content-author.md

@@ -0,0 +1,190 @@
+# Content Author
+
+![Role](https://img.shields.io/badge/role-content--author-blue) ![Phase](https://img.shields.io/badge/phase-5%20%E2%80%94%20authoring-lightgrey) ![Status](https://img.shields.io/badge/status-stable-green)
+
+**From approved spec to production-ready content — before a single pixel is designed or line of code is written.**
+
+---
+
+## What is this?
+
+The content author writes and packages all non-code content artifacts for downstream consumption by the designer, planner, and executor. It produces microcopy tables, i18n keys, seed data, terminology glossaries, asset metadata, notification templates, and a content coverage matrix — all before design begins.
+
+This phase prevents the second most common cause of implementation rework: designing and building UI around placeholder text. When the designer and executor receive not just a spec but also finalized copy, locale keys, and a glossary, they are implementing against real content constraints — not lorem ipsum that will break layouts when replaced with production strings.
+
+The content author sits between `spec-challenge` (approved spec) and `design` (visual design). It is optional for tasks with no user-facing content and mandatory for any feature with UI text, notifications, or locale-sensitive output.
+
+---
+
+## Key Capabilities
+
+- Produces microcopy tables covering all UI states (empty, loading, error, success, edge cases)
+- Generates i18n key definitions with values for all required locales
+- Creates seed and fixture content values for development, testing, and demos
+- Builds a terminology glossary to ensure consistent domain language across the feature
+- Produces an asset metadata manifest (image alt text, icon labels, ARIA descriptions)
+- Writes notification and transactional content templates (email, push, in-app)
+- Generates a content coverage matrix mapping every screen to every key to every locale
+- Validates content against brand and style guidelines when available
+- Flags layout-breaking copy (long translations, RTL considerations) for designer awareness
+- Uses web research for terminology accuracy and domain-specific data
+- Escalates when content decisions require product or business input not present in the spec
+
+---
+
+## How It Fits in the Pipeline
+
+The content author is **Phase 5**. It runs after spec-challenge approval and before design.
+
+```
+[approved spec artifact]
+[research artifacts]
+[existing glossary/locale sources]
+[brand/style guidelines]
+            |
+            v
+    [content-author]
+            |
+            |---> microcopy tables (all UI states)
+            |---> i18n keys with locale values
+            |---> seed/fixture content
+            |---> terminology glossary
+            |---> asset metadata manifest
+            |---> notification/transactional templates
+            |---> content coverage matrix
+            |
+            v
+    [designer]  --> designs with real content, not placeholders
+            |
+            v
+    [planner]
+```
+
+**Triggered by:** `author` workflow.
+
+**Feeds into:** `design` workflow (designer role), then planner and executor.
+
+---
+
+## Input / Output Contract
+
+| | Details |
+|---|---|
+| **Inputs** | Approved spec artifact, research artifacts, existing glossary/locale sources, brand/style guidelines (if available) |
+| **Allowed tools** | Local file reads, web research for terminology and domain data, translation reference tools |
+| **Output: microcopy tables** | All UI text for every state (empty, loading, error, success, edge cases) |
+| **Output: i18n keys** | Key definitions with values for all required locales |
+| **Output: seed/fixture content** | Development, testing, and demo content values |
+| **Output: terminology glossary** | Consistent domain language definitions for the feature |
+| **Output: asset metadata manifest** | Image alt text, icon labels, ARIA descriptions |
+| **Output: notification templates** | Email, push, and in-app transactional content |
+| **Output: content coverage matrix** | Screen-to-key-to-locale mapping for completeness verification |
+
+---
+
+## Example
+
+Given a spec for a rate limit exceeded error state:
+
+**Author artifact (excerpt):**
+
+```markdown
+# Author Artifact: Rate Limit UI Content
+
+## Microcopy Table
+
+| Screen | State | Key | en-US | es-ES |
+|--------|-------|-----|-------|-------|
+| API Playground | Rate limited | rate_limit.banner.title | Rate limit exceeded | Limite de velocidad excedido |
+| API Playground | Rate limited | rate_limit.banner.body | You have exceeded your API rate limit. Retry in {retryAfter} seconds. | Ha excedido su limite de velocidad de API. Reintente en {retryAfter} segundos. |
+| API Playground | Rate limited | rate_limit.banner.action | View usage | Ver uso |
+| Dev Tools | Headers visible | rate_limit.headers.title | Rate Limit Headers | Encabezados de limite de velocidad |
+
+## Terminology Glossary
+
+| Term | Definition | Usage Note |
+|------|-----------|------------|
+| Rate limit | Maximum number of API requests allowed in a time window | Always "rate limit" (two words), never "ratelimit" or "rate-limit" in UI copy |
+| Retry-After | HTTP header indicating seconds until quota resets | Hyphenated in header context; "retry after" in prose |
+
+## Content Coverage Matrix
+
+| Screen | Keys | en-US | es-ES | Notes |
+|--------|------|-------|-------|-------|
+| API Playground — rate limited | 3 | 3/3 | 3/3 | Complete |
+| Dev Tools — headers | 1 | 1/1 | 1/1 | Complete |
+
+## Layout Flags
+
+- es-ES `rate_limit.banner.body` is 18% longer than en-US — designer should verify banner auto-height
+```
+
+---
+
+## Git-Flow Responsibilities
+
+The content author follows a strict commit convention:
+
+```bash
+feat(content): add rate limit UI microcopy and i18n keys
+```
+
+Content artifacts live in the **run-local state directory** (`~/.wazir/projects/<project-slug>/author/`), not in the repository. Only exported i18n key files and glossary entries committed to the repo follow the project's existing locale file structure.
+
+---
+
+## Configuration
+
+| Setting | Location | Effect |
+|---------|----------|--------|
+| `author` workflow | `workflows/` | Gates design phase behind content approval |
+| Brand/style guidelines | `input/` or project docs | Constrains tone, terminology, and formatting; content author reads but does not mutate |
+| Locale configuration | `wazir.manifest.yaml` or project config | Defines which locales must have complete coverage |
+
+> [!NOTE]
+> The author phase is **optional**. It is not required for tasks with no user-facing content. Tasks without UI text, notifications, or locale-sensitive output skip the author phase entirely and proceed from `spec-challenge` directly to `design` (or `plan` if design is also skipped).
+
+---
+
+## When to Use / When NOT to Use
+
+**Use the content author when:**
+- The spec describes user-facing text, notifications, or locale-sensitive output
+- You need to prevent layout breakage caused by placeholder-to-production text swaps
+- Multiple locales must be supported and coverage must be verified before design
+- Terminology consistency matters across the feature (domain-specific language)
+- Notification or transactional email templates need authoring
+
+**Do NOT invoke the content author when:**
+- The task is purely backend, infrastructure, or CLI with no user-facing text — skip to design or plan
+- Content already exists in the project's locale files and only needs wiring — that is executor work
+- You are in mid-execution and want to change copy — that is an out-of-scope change requiring a new spec
+
+> [!WARNING]
+> Content drift from the approved spec is a failure condition. The content author must write copy that implements what the spec describes, not what sounds better or covers additional states. Any divergence must be escalated before the author artifact is produced.
+
+---
+
+## Failure Conditions
+
+| Condition | Why It Matters |
+|-----------|----------------|
+| Incomplete state coverage (missing copy for any UI state) | Designer creates frames without text; executor hardcodes placeholders |
+| Missing locale entries (key exists in one locale but not others) | Shipped feature shows raw keys or fallback text in some locales |
+| Placeholder or dummy text (lorem ipsum, test123, John Doe) | Placeholders leak to production; reviewer will reject |
+| Glossary conflicts (same term defined differently) | Inconsistent terminology confuses users and breaks search/filter |
+| Copy that violates brand constraints | Brand team rejects post-ship; rework required |
+| Untraceable copy (no screen-to-key mapping) | Executor cannot wire content; verifier cannot prove coverage |
+| Layout-breaking copy not flagged for designer awareness | Long translations break layouts discovered only in QA |
+
+---
+
+## Related
+
+- [Roles Overview](README.md)
+- [specifier](specifier.md) — upstream role (produces the approved spec)
+- [designer](designer.md) — downstream role (designs with authored content)
+- [planner](planner.md) — downstream role (plans implementation with content artifacts)
+- [executor](executor.md) — uses i18n keys and content directly
+- [reviewer](reviewer.md) — validates content coverage in review
+- [Author Workflow](../workflows/author.md)