@wazir-dev/cli 1.0.0

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

@@ -0,0 +1,182 @@
+# Planner
+
+![Role](https://img.shields.io/badge/role-planner-blue) ![Phase](https://img.shields.io/badge/phase-8%20%E2%80%94%20planning-lightgrey) ![Status](https://img.shields.io/badge/status-stable-green)
+
+**No surprises during execution. The planner turns an approved spec into a task list so complete that the executor never has to guess.**
+
+---
+
+## What is this?
+
+The planner converts the approved spec (and optional design artifacts) into an implementation plan — an ordered, dependency-aware, verification-per-section task list that the executor can follow without ambiguity.
+
+A good implementation plan eliminates the most damaging pattern in AI-assisted engineering: the executor who goes off-piste because the plan had gaps. The planner's job is to close every gap in advance. If a step requires an invention that was not in the spec, that is an escalation, not an assumption.
+
+---
+
+## Key Capabilities
+
+- Reads the approved spec, research artifacts, and current repo state to ground the plan in reality
+- Produces an ordered task list with explicit dependencies (no hidden coupling)
+- Assigns verification criteria per task section — not just at the end
+- Inspects the live codebase to avoid planning work that has already been done or that conflicts with existing structure
+- Specifies target branch per task (feature/codex from develop, hotfix from main)
+- Includes `commit_message` in task frontmatter using conventional commit format
+- Escalates when dependencies, sequencing, or feasibility require guessing
+
+---
+
+## How It Fits in the Pipeline
+
+The planner is **Phase 8**. It runs after spec-challenge, author, and design-review approval (author and design phases are optional).
+
+```
+[approved spec artifact]
+[research artifacts]
+[design artifacts — optional]
+[current repo state]
+            │
+            ▼
+       [planner]
+            │
+            ├──► implementation plan artifact
+            ├──► ordered task list (with dependencies)
+            └──► verification plan per section
+            │
+            ▼
+  [plan-review]  ──► reviewer validates plan against spec
+            │
+            ▼
+       [executor]
+```
+
+**Triggered by:** `plan` workflow.
+
+**Feeds into:** `plan-review` workflow (reviewer role), then executor.
+
+---
+
+## Input / Output Contract
+
+| | Details |
+|---|---|
+| **Inputs** | Approved spec, research artifacts, current repo state |
+| **Allowed tools** | Local file reads, codebase inspection, source-backed comparison with approved references |
+| **Output: implementation plan artifact** | Full task plan with order, dependencies, branch, and commit message per task |
+| **Output: ordered task list** | Each task numbered, with explicit depends-on references |
+| **Output: verification plan** | Per-section verification commands and pass criteria |
+
+---
+
+## Example
+
+Building on the rate limiting spec:
+
+**Implementation plan (excerpt):**
+
+```markdown
+# Implementation Plan: Per-User API Rate Limiting
+
+## Target Branch
+feature/rate-limiting — branch from develop
+
+## Tasks
+
+### Task 1: Install and configure rate-limiter-flexible
+- depends_on: []
+- commit_message: "chore(deps): add rate-limiter-flexible ^3.0.0"
+- work:
+  - npm install rate-limiter-flexible
+  - Add Redis client config for rate limiter in src/infrastructure/rateLimiter.ts
+- verification:
+  - `npm ls rate-limiter-flexible` shows correct version
+  - TypeScript compiles without errors: `npm run build`
+
+### Task 2: Implement rate limit middleware
+- depends_on: [Task 1]
+- commit_message: "feat(api): add per-key token bucket rate limiting middleware"
+- work:
+  - Create src/middleware/rateLimit.ts
+  - Apply to public API router in src/api/routes/index.ts
+  - Inject X-RateLimit-* headers on every response
+  - Return 429 + Retry-After when limit is exceeded
+  - Fail-open when Redis unavailable, emit metric
+- verification:
+  - Unit tests pass: `npm test src/middleware/rateLimit.test.ts`
+  - Integration test: 101 requests in 60s window — expect 1× 429
+  - Redis failure test: mock Redis down — expect pass-through + alert
+
+### Task 3: Update CHANGELOG
+- depends_on: [Task 2]
+- commit_message: "docs(changelog): record rate limiting feature under [Unreleased]"
+- work:
+  - Add entry to CHANGELOG.md [Unreleased] section
+
+## Verification Plan Summary
+- All unit tests green: `npm test`
+- Integration suite: `npm run test:integration`
+- Branch naming: `wazir validate branches`
+- Commit format: `wazir validate commits`
+- Changelog entries: `wazir validate changelog --require-entries`
+```
+
+---
+
+## Git-Flow Responsibilities
+
+The planner does not commit code, but it is responsible for specifying the git-flow structure that the executor will follow:
+
+- Specify `target_branch` in every task definition
+- Use `feature/codex` branches for features, `hotfix` for critical fixes from main
+- Include `commit_message` in task frontmatter in conventional commit format
+- The executor may not merge to develop or main — the planner's task list ends at the PR
+
+---
+
+## Configuration
+
+| Setting | Location | Effect |
+|---------|----------|--------|
+| `plan-review` workflow | `workflows/` | Gates execution behind plan review |
+| `verification-proof` validation check | `wazir.manifest.yaml` | Requires verification plan to exist before execution |
+| Branch naming rules | `hooks/` | `loop_cap_guard` enforces iteration caps; `protected_path_write_guard` enforces path rules |
+
+---
+
+## When to Use / When NOT to Use
+
+**Use the planner when:**
+- You have an approved spec and need a concrete, ordered, verifiable task list before execution begins
+- The implementation touches multiple files, layers, or systems with non-obvious dependencies
+- You need to ensure the executor doesn't have to make architectural decisions mid-flight
+- A plan-review gate is required before code is written
+
+**Do NOT invoke the planner when:**
+- The spec is not yet approved — plan from an unapproved spec is wasted work
+- You want to plan incrementally during execution — the plan must be complete before execution starts
+- The task is trivial enough that a plan adds more overhead than value (single-file, single-function fixes)
+
+> [!NOTE]
+> Hidden coupling is the planner's most dangerous failure mode. If Task 3 secretly depends on a side-effect of Task 1 that is not documented as a dependency, the executor will hit an invisible wall. Every dependency must be explicit in the task list.
+
+---
+
+## Failure Conditions
+
+| Condition | Why It Matters |
+|-----------|----------------|
+| Hidden coupling | Executor hits unexpected blockers; may make unapproved scope decisions to unblock |
+| Missing verification | Verifier has no plan to run; proof bundle will be incomplete |
+| Step gaps that require invention during execution | Executor must invent solutions not in the spec — plan drift begins |
+
+---
+
+## Related
+
+- [Roles Overview](README.md)
+- [specifier](specifier.md) — upstream role (produces the approved spec)
+- [designer](designer.md) — upstream role when design phase is present
+- [executor](executor.md) — downstream role that implements the plan
+- [reviewer](reviewer.md) — validates plan in `plan-review` workflow
+- [Plan Workflow](../workflows/plan.md) _(coming soon)_
+- [Plan-Review Workflow](../workflows/plan-review.md) _(coming soon)_

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

@@ -0,0 +1,164 @@
+# Researcher
+
+![Role](https://img.shields.io/badge/role-researcher-blue) ![Phase](https://img.shields.io/badge/phase-2%20%E2%80%94%20discovery-lightgrey) ![Status](https://img.shields.io/badge/status-stable-green)
+
+**Evidence over assumption. Source-backed findings that make every downstream decision defensible.**
+
+---
+
+## What is this?
+
+The researcher fills the knowledge gaps that the clarifier surfaces. When a task touches an unfamiliar library, an undocumented API surface, a performance constraint, or an architectural decision that needs grounding in evidence — the researcher is the role that goes and finds out.
+
+The defining constraint of this role is epistemic discipline: **every finding must be traceable to a source**. No assertions without citations. No "I believe" without a reference. No confidence substituted for evidence. This isn't pedantry — it's what separates a research artifact that the specifier can build on from a context blob that injects unverifiable assumptions into the pipeline.
+
+---
+
+## Key Capabilities
+
+- Reads and synthesizes local files, codebase structure, and documentation
+- Conducts source-backed web research for external libraries, standards, and patterns
+- Targets specific areas of the codebase for deep inspection
+- Produces structured finding summaries linked to cited sources
+- Identifies open risks and unknowns explicitly — not just what was found, but what couldn't be confirmed
+- Escalates when a required source is unverifiable or when findings materially change direction
+
+---
+
+## How It Fits in the Pipeline
+
+The researcher is **Phase 2**. It runs after clarification when the clarification artifact contains open questions that require investigation.
+
+```
+[clarification artifact]
+[open questions list]
+            │
+            ▼
+       [researcher]
+            │
+            ├──► research artifact (findings + citations)
+            ├──► open risks and unknowns
+            └──► finding summaries per research question
+            │
+            ▼
+       [specifier]
+```
+
+**Triggered by:** `discover` workflow.
+
+**Feeds into:** specifier (always), planner (when research findings affect implementation approach).
+
+> [!NOTE]
+> Research is not always required. If the clarification artifact resolves all open questions from existing knowledge and codebase inspection, the pipeline can proceed directly to specifier. The researcher is invoked only when knowledge gaps exist.
+
+---
+
+## Input / Output Contract
+
+| | Details |
+|---|---|
+| **Inputs** | Clarified scope, explicit research questions, active source documents, verified external sources |
+| **Allowed tools** | Local file reads, source-backed web research, targeted codebase inspection |
+| **Output: research artifact** | All findings, each linked to a source, structured by research question |
+| **Output: finding summaries** | Concise per-question summaries that the specifier can consume directly |
+| **Output: open risks and unknowns** | Explicit list of what could not be confirmed, with risk assessment |
+
+---
+
+## Example
+
+Given this open question from the clarification artifact:
+
+```
+Q: Which rate limiting algorithm should we use?
+   Redis token bucket vs. fixed window counter vs. sliding window log?
+   Impact: Affects storage, accuracy under burst, and implementation complexity.
+```
+
+The researcher produces:
+
+**Research artifact (excerpt):**
+
+```markdown
+## Research Question
+Which rate limiting algorithm is most appropriate for our use case?
+
+## Findings
+
+### Token Bucket (Redis)
+- Allows bursts up to bucket capacity, then enforces steady rate
+- Redis-native implementation via `redis-rate-limiter` (npm, MIT license)
+- Requires Redis cluster; our infrastructure already runs Redis 7.x
+- Source: https://redis.io/glossary/rate-limiting/ (verified 2026-03-13)
+- Source: src/infrastructure/redis.config.ts (Redis client confirmed present)
+
+### Fixed Window Counter
+- Simpler implementation, O(1) Redis ops
+- Known boundary issue: can allow 2x rate at window boundary
+- Acceptable for our abuse-prevention use case (not billing-critical)
+- Source: https://www.figma.com/blog/an-alternative-approach-to-rate-limiting/ (Figma eng blog)
+
+### Sliding Window Log
+- Most accurate, but O(n) per request at high volume
+- Not recommended given our projected 10k req/min scale
+- Source: RFC 6585 + internal load test results in docs/performance/2025-11.md
+
+## Recommendation
+Token bucket via Redis. Matches infrastructure, handles burst gracefully,
+well-understood operational model.
+
+## Open Risks
+- Redis availability: rate limiting falls open if Redis is unreachable.
+  Risk: MEDIUM. Mitigation: fail-open with logging, add circuit breaker.
+- `redis-rate-limiter` last release 8 months ago — check for maintenance status.
+  Risk: LOW. Mitigation: fork or use `rate-limiter-flexible` (actively maintained).
+```
+
+---
+
+## Configuration
+
+The researcher has no dedicated runtime configuration. Relevant settings:
+
+| Setting | Location | Effect |
+|---------|----------|--------|
+| `loop_cap_guard` hook | `hooks/` | Prevents unbounded research loops; caps iterations |
+| `pre_tool_capture_route` hook | `hooks/` | Routes tool outputs through capture for traceability |
+| External adapters | `wazir.manifest.yaml` → `adapters` | `context_mode` is an optional research accelerator |
+
+---
+
+## When to Use / When NOT to Use
+
+**Use the researcher when:**
+- The clarification artifact contains open questions that cannot be resolved from existing knowledge
+- The task touches an external dependency, library, or standard that needs verification
+- Architecture decisions need grounding in current best practice or benchmark data
+- Security or performance properties need evidence, not assertion
+
+**Do NOT invoke the researcher when:**
+- All open questions in the clarification artifact are already resolved
+- You are tempted to research indefinitely as a form of scope avoidance — timebox research and surface unknowns explicitly
+- You want to validate implementation choices mid-execution — that is a verifier or reviewer concern
+
+> [!NOTE]
+> The most common researcher failure is **substituting confidence for evidence**. If you cannot find a source, the output should be an open risk entry — not a confident assertion. Downstream roles depend on the distinction.
+
+---
+
+## Failure Conditions
+
+| Condition | Why It Matters |
+|-----------|----------------|
+| Unsupported claims | Specifier and planner will build on false premises |
+| Stale or missing citations | Findings cannot be independently verified or updated |
+| Substituting confidence for evidence | The worst failure — undetectable false premises enter the artifact chain |
+
+---
+
+## Related
+
+- [Roles Overview](README.md)
+- [clarifier](clarifier.md) — upstream role that defines research questions
+- [specifier](specifier.md) — downstream role that consumes research findings
+- [Discover Workflow](../workflows/discover.md) _(coming soon)_

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

@@ -0,0 +1,184 @@
+# Reviewer
+
+![Role](https://img.shields.io/badge/role-reviewer-blue) ![Phase](https://img.shields.io/badge/phase-12%20%E2%80%94%20review-lightgrey) ![Status](https://img.shields.io/badge/status-stable-green)
+
+**Adversarial by design. The reviewer finds what the executor missed and the verifier couldn't see.**
+
+---
+
+## What is this?
+
+The reviewer performs adversarial review. It is not a rubber-stamp; it is the final checkpoint before work is accepted. It reads the diffs, compares against the approved spec and plan, inspects the verification evidence, and produces findings with severity and rationale tied to evidence — not opinions.
+
+The word "adversarial" is intentional. The reviewer's job is to find failures, not to validate effort. A finding that blocks a feature is a success for the pipeline, not a failure. The failure mode is the opposite: vague findings, uncited criticism, or rubber-stamp approval that lets broken or drifted work through.
+
+The reviewer operates in multiple phases: it challenges the spec (`spec-challenge`), validates designs (`design-review`), reviews the plan (`plan-review`), and performs final code review (`review`). Same role contract, different inputs.
+
+---
+
+## Key Capabilities
+
+- Inspects diffs against approved spec and plan to detect drift and unapproved scope
+- Reads changed files to assess correctness, wiring, and completeness
+- Evaluates verification evidence — checks it is fresh, complete, and accurate
+- Uses secondary model review when available for higher-confidence assessments
+- Produces findings with severity (blocking, non-blocking, informational)
+- Issues an explicit no-findings verdict when applicable — not silence, a positive statement
+- Flags git-flow violations: missing/low-quality changelog entries, non-conventional commits, user-facing changes without changelog records
+
+---
+
+## How It Fits in the Pipeline
+
+The reviewer is **Phase 12** in the main flow, but also appears earlier in challenge phases.
+
+```
+[changed files]
+[approved spec and plan]
+[verification evidence]
+            │
+            ▼
+       [reviewer]
+            │
+            ├──► findings with severity (BLOCKING / NON-BLOCKING / INFO)
+            ├──► rationale tied to evidence (file, line, artifact reference)
+            └──► explicit verdict (APPROVED / APPROVED WITH CONDITIONS / BLOCKED)
+            │
+            ▼
+  APPROVED: [learner] / merge / deploy
+  BLOCKED:  [executor] fixes → [verifier] re-runs → [reviewer] re-reviews
+```
+
+**Also invoked in:**
+- `spec-challenge` — adversarially challenges the spec artifact
+- `design-review` — validates design artifacts against spec and accessibility
+- `plan-review` — validates plan against spec, checks for gaps and hidden coupling
+
+**Triggered by:** `review`, `spec-challenge`, `design-review`, or `plan-review` workflows.
+
+---
+
+## Input / Output Contract
+
+| | Details |
+|---|---|
+| **Inputs** | Changed files (diffs), approved spec and plan, verification evidence |
+| **Allowed tools** | Diff inspection, targeted file reads, source-backed comparison to spec/plan, secondary model review |
+| **Output: findings** | Each finding has: severity, description, evidence citation, recommendation |
+| **Output: rationale** | Every finding is tied to a specific file, line, artifact section, or command output |
+| **Output: verdict** | Explicit APPROVED, APPROVED WITH CONDITIONS, or BLOCKED — never silence |
+
+---
+
+## Example
+
+**Review findings (excerpt):**
+
+```markdown
+# Review: Per-User API Rate Limiting
+Date: 2026-03-13
+Spec: spec/rate-limiting-v1.md
+Plan: plan/rate-limiting-v1.md
+Verification: proof/rate-limiting-v1-proof.md
+
+## Findings
+
+### FINDING-1 [NON-BLOCKING]
+**Description:** X-RateLimit-Reset header returns Unix timestamp; spec does not specify format.
+**Evidence:** src/middleware/rateLimit.ts:67 — `headers['X-RateLimit-Reset'] = resetTime.getTime() / 1000`
+**Spec reference:** Spec §Behavior — "includes X-RateLimit-Reset header" (format unspecified)
+**Recommendation:** Log as assumption in execution notes; follow up in next spec iteration
+with explicit format decision (Unix timestamp vs. ISO 8601 vs. delta-seconds per RFC 7231).
+
+### FINDING-2 [BLOCKING]
+**Description:** Fail-open path emits to console.log, not to the alerting system described in spec.
+**Evidence:** src/middleware/rateLimit.ts:89 — `console.log('Redis unavailable, failing open')`
+**Spec reference:** Spec §Behavior — "emit an alert" (not console.log)
+**Recommendation:** Replace console.log with the existing alert service at
+src/services/alerting.ts. This is a one-line fix.
+
+## Git-Flow Checks
+- Commit format: PASS — all 3 commits in conventional format
+- Changelog: PASS — [Unreleased] entry present and descriptive
+- Changelog quality: NON-BLOCKING — entry describes the feature but omits the
+  fail-open behavior. Consider adding: "Fails open when Redis is unavailable."
+
+## Verdict: BLOCKED
+1 blocking finding must be resolved before approval.
+FINDING-1 is non-blocking and can be addressed in a follow-up task.
+```
+
+---
+
+## Severity Guide
+
+| Severity | Meaning | Effect on Verdict |
+|----------|---------|-------------------|
+| BLOCKING | Correctness failure, spec violation, security issue, fake test, plan drift | Blocks approval |
+| NON-BLOCKING | Quality issue, style inconsistency, minor spec ambiguity | Does not block; should be noted |
+| INFO | Observation, question, suggestion for future improvement | No action required |
+
+---
+
+## Git-Flow Responsibilities
+
+The reviewer enforces git-flow quality — not just format:
+
+```
+- Flag missing changelog entries as BLOCKING if the change is user-facing
+- Flag low-quality changelog entries as NON-BLOCKING with a suggested improvement
+- Flag user-facing changes without any changelog entry as BLOCKING
+- Verify commit message content accurately describes the change (not just format compliance)
+```
+
+A commit message that passes `wazir validate commits` on format but says "fix things" when it adds a new API surface is a NON-BLOCKING finding.
+
+---
+
+## Configuration
+
+| Setting | Location | Effect |
+|---------|----------|--------|
+| `review-loop` validation check | `wazir.manifest.yaml` | Tracks review iteration count |
+| `loop_cap_guard` hook | `hooks/` | Caps review loops to prevent stalemate cycles |
+| Secondary model review | host capability | When available, enables two-model review for higher confidence |
+
+---
+
+## When to Use / When NOT to Use
+
+**Use the reviewer when:**
+- Any artifact produced by the pipeline needs validation before the next phase begins
+- Execution and verification are complete and work needs a formal verdict
+- The spec or plan needs adversarial challenge before execution starts
+
+**Do NOT invoke the reviewer when:**
+- You want a quick sanity check during execution — that's not adversarial review, it's just reading the code
+- You expect approval as a default — the reviewer will BLOCK if evidence supports it
+- You want to use it to delay a decision — APPROVED WITH CONDITIONS and INFO findings allow progress
+
+> [!NOTE]
+> The reviewer's most important output is a **no-findings verdict**, not a list of findings. An explicit "no findings — APPROVED" is a positive signal that the pipeline is working. Silence is not an approval.
+
+---
+
+## Failure Conditions
+
+| Condition | Why It Matters |
+|-----------|----------------|
+| Vague findings | Executor cannot fix what is not precisely described |
+| Uncited criticism | Findings without evidence cannot be evaluated or contested |
+| Rubber-stamp approval | Broken work ships; the entire pipeline's integrity depends on this role |
+
+---
+
+## Related
+
+- [Roles Overview](README.md)
+- [verifier](verifier.md) — upstream role (produces the proof bundle)
+- [executor](executor.md) — implements fixes when reviewer blocks
+- [learner](learner.md) — downstream role (processes review findings as learning inputs)
+- [specifier](specifier.md) — reviewer challenges spec in `spec-challenge`
+- [designer](designer.md) — reviewer validates design in `design-review`
+- [planner](planner.md) — reviewer validates plan in `plan-review`
+- [Review Workflow](../workflows/review.md) _(coming soon)_

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

@@ -0,0 +1,162 @@
+# Specifier
+
+![Role](https://img.shields.io/badge/role-specifier-blue) ![Phase](https://img.shields.io/badge/phase-3%20%E2%80%94%20specification-lightgrey) ![Status](https://img.shields.io/badge/status-stable-green)
+
+**If it can't be tested, it's not a spec. The specifier turns research into a contract the whole pipeline can build on.**
+
+---
+
+## What is this?
+
+The specifier transforms clarified scope and research findings into a spec artifact: a precise, reviewable, measurable definition of what the system should do. Not how it should do it — that's the planner's job — but what it must do, how correctness will be verified, and what is explicitly out of scope.
+
+A good spec artifact is the single most valuable document in any engineering pipeline. It is what separates a shared understanding from a series of individual interpretations. The specifier's job is to make that shared understanding concrete, testable, and resistant to scope creep.
+
+---
+
+## Key Capabilities
+
+- Synthesizes clarification and research artifacts into a single coherent spec
+- Produces measurable, testable acceptance criteria — not prose descriptions of success
+- Makes assumptions and non-goals explicit, not implicit
+- Reads schemas and templates to produce spec artifacts in the correct format
+- Escalates when acceptance criteria cannot be made testable or when scope is still unstable
+- Refuses to overbuild — the spec covers only what has been approved
+
+---
+
+## How It Fits in the Pipeline
+
+The specifier is **Phase 3**. It runs after clarification and (optionally) research. Its output — the approved spec artifact — is the foundation for every downstream role.
+
+```
+[clarification artifact]
+[research artifacts]
+[operator constraints and approvals]
+            │
+            ▼
+       [specifier]
+            │
+            ├──► spec artifact
+            ├──► measurable acceptance criteria
+            └──► explicit non-goals and assumptions
+            │
+            ▼
+  [spec-challenge review]  ──► reviewer adversarially challenges the spec
+            │
+            ▼
+       [designer]  (if visual design is required)
+       [planner]   (if no design phase)
+```
+
+**Triggered by:** `specify` workflow.
+
+**Feeds into:** `spec-challenge` workflow (reviewer role), then designer or planner.
+
+---
+
+## Input / Output Contract
+
+| | Details |
+|---|---|
+| **Inputs** | Clarification artifact, research artifacts, operator constraints and approvals |
+| **Allowed tools** | Local file reads, schema/template inspection, targeted repo reads |
+| **Output: spec artifact** | Full feature specification — scope, behavior, acceptance criteria, non-goals, assumptions |
+| **Output: acceptance criteria** | Each criterion is measurable and maps to a verifiable test or check |
+| **Output: non-goals and assumptions** | Explicit list of what is out of scope and what is assumed true without investigation |
+
+---
+
+## Example
+
+Building on the rate limiting clarification and research:
+
+**Spec artifact (excerpt):**
+
+```markdown
+# Spec: Per-User API Rate Limiting
+
+## Scope
+Implement per-API-key token bucket rate limiting on all public API endpoints.
+Rate limit: 100 requests per 60-second window per API key.
+
+## Behavior
+- Every request includes rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
+- When a key exceeds the limit, the API returns HTTP 429 with a Retry-After header
+- Rate limit state is stored in Redis using the token bucket algorithm
+- If Redis is unreachable, the request is allowed (fail-open) and an alert is emitted
+
+## Acceptance Criteria
+1. [ ] A key making 100 requests within 60s receives HTTP 200 for all 100
+2. [ ] The 101st request within 60s receives HTTP 429 with Retry-After header
+3. [ ] After the window resets, the key can make 100 requests again
+4. [ ] All 200 responses include X-RateLimit-* headers with correct values
+5. [ ] Redis failure test: mock Redis unavailable → requests pass through, alert fires
+6. [ ] Existing authenticated client integration tests continue to pass unchanged
+
+## Non-Goals
+- Per-IP rate limiting (not in scope for this iteration)
+- Rate limit tiers per subscription plan (future iteration)
+- Admin UI for rate limit configuration (future iteration)
+
+## Assumptions
+- Redis 7.x is available in all deployment environments
+- API keys are already present in request context via existing auth middleware
+- `rate-limiter-flexible` npm package is acceptable (MIT license, actively maintained)
+
+## Cited Sources
+- input/brief.md
+- research/2026-03-13-rate-limiting.md
+- src/middleware/auth.ts (API key context confirmed)
+```
+
+---
+
+## Configuration
+
+| Setting | Location | Effect |
+|---------|----------|--------|
+| `artifact-schema` validation check | `wazir.manifest.yaml` | Validates spec artifact schema before handoff |
+| `docs-required` validation check | `wazir.manifest.yaml` | Enforces that spec artifact is present before plan phase |
+| Spec templates | `templates/` | Canonical structure for spec artifacts |
+
+---
+
+## When to Use / When NOT to Use
+
+**Use the specifier when:**
+- Clarification and research are complete and you need a reviewable definition of done
+- You need to establish explicit non-goals to prevent scope creep during execution
+- Multiple stakeholders need to agree on what will be built before work begins
+- The task is complex enough that "I'll figure it out as I go" will cause problems in review
+
+**Do NOT invoke the specifier when:**
+- Scope is still unstable — go back to clarifier or escalate
+- You want to use it to spec out ideas that have not received operator approval
+- The spec becomes a place to embed implementation decisions — those belong in the plan
+
+> [!WARNING]
+> Overbuilding is a specifier failure condition. The spec covers exactly what has been approved. Sneaking in "nice to have" features, undiscussed API changes, or unscoped improvements is a contract violation — the reviewer will flag it and the executor must not implement it.
+
+---
+
+## Failure Conditions
+
+| Condition | Why It Matters |
+|-----------|----------------|
+| Unverifiable acceptance criteria | Verifier cannot produce proof; reviewer cannot make a verdict |
+| Hidden assumptions | Planner and executor build on false premises without knowing it |
+| Overbuilding beyond approved scope | Downstream roles implement unapproved work; review will reject it |
+
+---
+
+## Related
+
+- [Roles Overview](README.md)
+- [clarifier](clarifier.md) — upstream role
+- [researcher](researcher.md) — upstream role
+- [designer](designer.md) — next role when visual design is required
+- [planner](planner.md) — next role when no design phase
+- [reviewer](reviewer.md) — challenges the spec in `spec-challenge` workflow
+- [Specify Workflow](../workflows/specify.md) _(coming soon)_
+- [Spec-Challenge Workflow](../workflows/spec-challenge.md) _(coming soon)_