@wazir-dev/cli 1.0.0

package/docs/readmes/features/workflows/execute.md

@@ -0,0 +1,173 @@
+# execute
+
+**Phase 10 — Implement the plan. Nothing more, nothing less.**
+
+![Phase](https://img.shields.io/badge/phase-10%20of%2014-blue)
+![Role](https://img.shields.io/badge/role-executor-orange)
+![Status](https://img.shields.io/badge/status-stable-green)
+
+---
+
+## One-Line Purpose
+
+Implement the approved plan in ordered, verified batches — producing code and documentation changes that are provably traceable to spec acceptance criteria, with zero unauthorized scope additions.
+
+---
+
+## Pipeline Position
+
+```
+  PLAN-REVIEW
+    │
+    ▼
+┌─────────┐
+│ EXECUTE │  ◄── YOU ARE HERE
+└─────────┘
+    │
+    ▼
+  VERIFY  ★ gate
+    │
+    ▼
+  REVIEW ...
+```
+
+---
+
+## Role Responsible
+
+`executor`
+
+The executor implements. It does not plan, design, spec, or review. It works the approved task queue in order and verifies each task before moving to the next. The executor's job is to make the plan real with zero improvisation on scope and zero tolerance for hidden failures.
+
+---
+
+## Trigger
+
+All of the following are true:
+
+- Implementation plan artifact exists and is approved
+- Plan-review findings are resolved (no outstanding blocking findings)
+- Working branch is clean and ready
+
+---
+
+## Steps
+
+1. **Load the approved implementation plan.** The plan is the contract. Read every task before starting. Understand the full sequence and all dependencies.
+
+2. **Work tasks in sequence.** Start at Task 1. Complete it fully (including its verification step) before starting Task 2. Do not batch tasks without verifying each one.
+
+3. **For each task:**
+   a. Implement the change (file edits, new files, etc.)
+   b. Run the task's verification step
+   c. If verification passes — move to the next task
+   d. If verification fails — diagnose and fix before proceeding; do not move forward on a failing task
+
+4. **Log execution notes.** For each task, record: what was changed, what verification was run, and the outcome. This becomes the execution notes artifact consumed by `verify` and `review`.
+
+5. **No new scope.** If you identify something the plan did not address that appears to be a bug or gap, log it in execution notes as an out-of-scope observation. Do not fix it in this run without explicit approval.
+
+6. **Flag plan deviations.** If a task cannot be completed as written (e.g., a file does not exist as expected), stop, document the deviation, and surface it before proceeding. Do not silently substitute an alternative approach.
+
+7. **Produce the execution output.** Code changes on the working branch, docs changes, and execution notes artifact.
+
+---
+
+## Input Artifacts
+
+| Artifact | Location | Required |
+|----------|----------|----------|
+| Approved implementation plan | Run state | Yes |
+| Current branch state | Repo | Yes |
+| Design artifact (code scaffolds) | Run state | Required if design phase ran |
+
+---
+
+## Output Artifacts
+
+| Artifact | Description |
+|----------|-------------|
+| Code changes | All file edits and new files on the working branch |
+| Docs changes | Any documentation updates required by the plan |
+| Execution notes | Per-task log of changes made, verification run, and outcome |
+
+---
+
+## Approval Gate
+
+> [!NOTE]
+> Execute has a soft gate rather than a hard pre-execution gate. However:
+
+> [!IMPORTANT]
+> **No new scope may be added without explicit operator approval.** If mid-execution you identify work that was not in the plan, stop and surface it. The `loop_cap_guard` hook enforces maximum iteration counts to prevent runaway execution. Execution that silently expands scope is plan drift — the primary failure mode of this phase.
+
+---
+
+## Example Run
+
+**Approved plan (abbreviated):**
+```
+Task 1 — Extend CSS tokens
+Task 2 — Implement useDarkMode hook
+Task 3 — Implement DarkModeToggle component
+Task 4 — Wire toggle into dashboard nav
+Task 5 — Regression check
+```
+
+**Execution notes produced:**
+
+```
+## Task 1 — Extend CSS tokens
+Changed: src/styles/tokens.css
+Added [data-theme="dark"] selector with 12 token overrides from tokens.json.
+Verification: `npm run lint:css` ✓ (0 errors)
+Status: COMPLETE
+
+## Task 2 — Implement useDarkMode hook
+Created: src/hooks/useDarkMode.ts
+Wraps useLocalStorage('theme', 'light'). Applies data-theme attribute to
+document.documentElement on change. SSR guard added (typeof window check).
+Verification: `npm test src/hooks/useDarkMode.test.ts` ✓ (6 tests, 6 pass)
+Status: COMPLETE
+
+## Task 3 — Implement DarkModeToggle component
+Created: src/components/DarkModeToggle.tsx (from design scaffold)
+Updated: src/components/DarkModeToggle.test.tsx
+Touch target confirmed 44x44px at 768px. Focus ring applied via tokens.
+Verification: `npm test DarkModeToggle` ✓ (4 tests, 4 pass)
+Status: COMPLETE
+
+## Task 4 — Wire toggle into dashboard nav
+Changed: src/layouts/DashboardLayout.tsx (import + placement at line 47)
+Created: src/layouts/DashboardLayout.integration.test.tsx
+Verification: `npm test DashboardLayout.integration` ✓ (2 tests, 2 pass)
+Status: COMPLETE
+
+## Task 5 — Regression check
+Verification: `npm test` ✓ (147 tests, 147 pass, 0 skipped)
+Status: COMPLETE
+
+## Out-of-scope observations
+None.
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Impact | Prevention |
+|---------|--------|------------|
+| Skipping a task's verification step | Failures accumulate silently; verifier finds cascading issues | Verify each task before moving to the next — always |
+| Adding "while I'm in here" fixes | Scope expands without approval; plan diverges | Log all out-of-scope observations; fix nothing without approval |
+| Moving to the next task when verification fails | Downstream tasks build on broken foundations | A failing verification step is a full stop; diagnose and fix first |
+| Not logging execution notes | Verifier has no audit trail to confirm against | Execution notes are a required output, not optional commentary |
+| Silently substituting an alternative when a task assumption is wrong | Plan deviation is invisible; review cannot catch it | Flag plan deviations explicitly in execution notes before substituting |
+
+---
+
+## Related
+
+- [Overview — All Workflows](README.md)
+- [Previous: plan-review](plan-review.md)
+- [Next: verify](verify.md)
+- [Roles and Workflows](../../../concepts/roles-and-workflows.md)

package/docs/readmes/features/workflows/learn.md

@@ -0,0 +1,167 @@
+# learn
+
+**Phase 13 — Extract durable intelligence from the run so the next run starts smarter.**
+
+![Phase](https://img.shields.io/badge/phase-13%20of%2014-blue)
+![Role](https://img.shields.io/badge/role-learner-orange)
+![Gate](https://img.shields.io/badge/gate-hard%20%E2%98%85-red)
+![Status](https://img.shields.io/badge/status-stable-green)
+
+---
+
+## One-Line Purpose
+
+Extract scoped, reviewed, explicitly tagged learnings from this run's artifacts so that genuine improvements to patterns, practices, and process can be preserved — without silently mutating the agent's behavior from accepted knowledge.
+
+---
+
+## Pipeline Position
+
+```
+  REVIEW
+    │
+    ▼
+┌───────┐
+│ LEARN │  ◄── YOU ARE HERE
+└───────┘
+    │
+    ▼
+  PREPARE-NEXT  ★ gate (learnings require explicit review)
+    │
+    ▼
+  NEXT RUN
+```
+
+---
+
+## Role Responsible
+
+`learner`
+
+The learner synthesizes the run's artifacts into proposed learning artifacts. The key word is "proposed" — learnings are not automatically applied. They are produced, reviewed, scoped, and either accepted or rejected. The learner extracts signal from noise; it does not update behavior unilaterally.
+
+---
+
+## Trigger
+
+The review verdict is accepted — all blocking findings are resolved and the work is complete (or the run is being closed with a formal partial-completion artifact).
+
+---
+
+## Steps
+
+1. **Load run artifacts.** Spec, execution notes, review findings, verification proof. These are the raw material of the learning.
+
+2. **Identify pattern learnings.** What patterns were used that should be institutionalized? What anti-patterns appeared (even in advisory review findings) that should be flagged for future runs?
+
+3. **Identify process learnings.** Were there points in the pipeline where a step was slower or harder than it needed to be? Where did a phase produce a finding that an earlier phase should have caught?
+
+4. **Identify experiment outcomes.** Were any implementation approaches experimental (not the established pattern)? Did they succeed or fail? What is the confidence level of the outcome?
+
+5. **Write proposed learning artifacts.** Each learning artifact must include:
+   - Learning type: `pattern`, `anti-pattern`, `process`, or `experiment`
+   - Scope tag: which phase(s), role(s), or technology it applies to
+   - Evidence: which run artifact(s) support the learning
+   - Proposed action: "add to expertise module X", "update skill Y", "note in process docs"
+   - Status: `proposed` (all learnings start here)
+
+6. **Produce experiment summaries.** For experimental approaches, write a structured summary with hypothesis, outcome, conditions, and confidence.
+
+7. **Do not auto-apply.** No learning artifact may modify the codebase, skill files, or expertise modules directly. All changes are proposed. The operator reviews and accepts or rejects each learning.
+
+---
+
+## Input Artifacts
+
+| Artifact | Location | Required |
+|----------|----------|----------|
+| Run artifacts (full set) | Run state | Yes |
+| Review findings | Run state | Yes |
+| Verification proof | Run state | Yes |
+
+---
+
+## Output Artifacts
+
+| Artifact | Description |
+|----------|-------------|
+| Proposed learning artifacts | Typed, scoped, evidence-backed proposed learnings |
+| Experiment summaries | Structured outcomes for experimental approaches used in this run |
+
+---
+
+## Approval Gate
+
+> [!IMPORTANT]
+> **Accepted learnings require explicit review and scope tags before any action is taken.** A learning artifact in `proposed` status has no effect. The operator reviews each learning and either:
+> - **Accepts** it with a scope tag → triggers a specific action (update expertise module, update skill, add to process docs)
+> - **Rejects** it → archived, not applied
+> - **Defers** it → carried forward as a candidate for the next applicable run
+
+The failure mode of this phase is "auto-applied learning drift" — when learnings modify behavior without explicit review. This is prevented structurally: proposed learning artifacts cannot modify anything; they only describe.
+
+---
+
+## Example Run
+
+**Run review findings included:**
+- Finding 2 (advisory): `aria-pressed` not implemented on toggle
+- Finding 3 (advisory): execution notes did not echo test output
+
+**Proposed learning artifacts produced:**
+
+```
+## Learning L-001
+Type: anti-pattern
+Scope: executor role, accessibility, component implementation
+Evidence: review-findings.md Finding 2; DarkModeToggle.tsx:22
+Summary: Toggle button components without aria-pressed attribute fail
+screen-reader state communication. This was not caught in spec-challenge
+because the AC did not specify an accessibility standard explicitly.
+Proposed action: Add "toggle controls require aria-pressed" to expertise
+module accessibility/interactive-controls.md.
+Status: proposed
+
+## Learning L-002
+Type: process
+Scope: executor role, execution notes
+Evidence: review-findings.md Finding 3
+Summary: Execution notes that state the verification command but do not
+include captured output are incomplete. Review had to cross-reference
+the verification proof artifact manually. Execution notes should be
+self-contained verification records.
+Proposed action: Update executor role definition to require output
+capture in execution notes, not just command reference.
+Status: proposed
+
+## Experiment E-001
+Approach: CSS [data-theme] attribute for dark mode (vs. CSS class toggle)
+Hypothesis: attribute selector is more resilient than class-based toggle
+             because it cannot be accidentally overridden by className manipulation
+Outcome: SUCCESS — no conflicts found in 147-test run
+Conditions: Single-SPA app, no third-party theme manager present
+Confidence: medium (single data point)
+Proposed action: Note as preferred pattern in expertise/theming.md.
+Status: proposed
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Impact | Prevention |
+|---------|--------|------------|
+| Auto-applying learnings without review | Agent behavior silently mutates from a single run's observations | All outputs are `proposed`; nothing is applied without operator review |
+| Extracting lessons without evidence | Learning is opinion, not observation | Every learning must cite a specific run artifact |
+| Producing learnings too broadly scoped | Proposed change touches too many areas to be safely applied | Scope tags must be specific: which role, which phase, which technology |
+| Skipping the learn phase when review found only advisory issues | Advisory findings are the richest source of process learnings | Advisory findings are not minor — they are the signal the pipeline almost missed |
+| Writing experiment summaries without confidence levels | Future runs over-apply low-confidence results | Always state sample size and conditions that limit generalizability |
+
+---
+
+## Related
+
+- [Overview — All Workflows](README.md)
+- [Previous: review](review.md)
+- [Next: prepare-next](prepare-next.md)
+- [Roles and Workflows](../../../concepts/roles-and-workflows.md)

package/docs/readmes/features/workflows/plan-review.md

@@ -0,0 +1,165 @@
+# plan-review
+
+**Phase 9 — The last adversarial checkpoint before code gets written.**
+
+![Phase](https://img.shields.io/badge/phase-9%20of%2014-blue)
+![Role](https://img.shields.io/badge/role-reviewer-orange)
+![Gate](https://img.shields.io/badge/gate-hard%20%E2%98%85-red)
+![Status](https://img.shields.io/badge/status-stable-green)
+
+---
+
+## One-Line Purpose
+
+Adversarially review the implementation plan before execution starts — finding sequence gaps, missing verifications, scope mismatches, and unresolvable dependencies before they cost a full execution cycle.
+
+---
+
+## Pipeline Position
+
+```
+  PLAN
+    │
+    ▼
+┌─────────────┐
+│ PLAN-REVIEW │  ◄── YOU ARE HERE
+└─────────────┘
+    │
+    ▼
+  EXECUTE  ★ gate (blocking findings stop execution)
+    │
+    ▼
+  VERIFY ...
+```
+
+---
+
+## Role Responsible
+
+`reviewer`
+
+The reviewer is structurally independent from the planner. This is the third structural adversarial checkpoint in the pipeline (after `spec-challenge` and `design-review`). The reviewer's goal is to find execution blockers before they surface mid-implementation, when rework is expensive.
+
+---
+
+## Trigger
+
+A draft implementation plan artifact exists in run state. The plan has not yet been handed to the executor. `plan-review` runs immediately after `plan` completes.
+
+---
+
+## Steps
+
+1. **Load the draft plan and the approved spec.** The spec is the correctness baseline. The plan is correct when its tasks collectively satisfy every acceptance criterion.
+
+2. **Check AC coverage.** Does every acceptance criterion have at least one task that addresses it? Flag any AC with no corresponding task.
+
+3. **Check task sequence for gaps.** Are there tasks that depend on a file or function that a prior task has not yet created? Can every task be executed with only what exists before it in the sequence?
+
+4. **Check verification steps.** Does every task have a concrete, runnable verification step? Flag tasks where verification is "it should work" or "check visually" without a specific artifact.
+
+5. **Check for scope drift.** Does the plan introduce any tasks not traceable to a spec AC? Scope additions in planning are a red flag — they indicate the planner invented requirements.
+
+6. **Check for missing dependencies.** Does the plan assume library availability, environment configuration, or file existence that is not confirmed by the research artifact?
+
+7. **Check task granularity.** Are any tasks so large that a single task failure mid-execution leaves the codebase in an ambiguous intermediate state? Flag over-large tasks.
+
+8. **Produce findings with severity.** Each finding must include:
+   - Severity: `blocking` (execution cannot start) or `advisory` (proceed with awareness)
+   - Which task(s) are affected
+   - What the problem is
+   - Required resolution (task revision, re-sequencing, or verification addition)
+
+9. **Issue a verdict.** No-findings verdict if all checks pass. Blocking verdict if any blocking finding exists.
+
+---
+
+## Input Artifacts
+
+| Artifact | Location | Required |
+|----------|----------|----------|
+| Draft implementation plan | Run state | Yes |
+| Approved spec artifact | Run state | Yes |
+
+---
+
+## Output Artifacts
+
+| Artifact | Description |
+|----------|-------------|
+| Plan review findings | Structured findings with severity, task reference, and required resolution |
+| Revised tasks | Updated task definitions when findings require task rewrites |
+
+---
+
+## Approval Gate
+
+> [!IMPORTANT]
+> **Execution cannot begin until all blocking findings are closed or explicitly accepted by the operator.** Advisory findings may proceed with acknowledgement. A plan that survives `plan-review` with blocking findings silently accepted is a plan that will generate execution failures.
+
+If blocking findings require plan revision, the planner must update the plan artifact and re-submit for review. This loop may iterate but must converge.
+
+---
+
+## Example Run
+
+**Plan under review (abbreviated tasks):**
+
+```
+Task 3 — Implement DarkModeToggle component
+  Verification: npm test DarkModeToggle passes; Storybook renders at 768px.
+
+Task 4 — Wire toggle into dashboard nav
+  Verification: Integration test: toggle visible at 320px and 1280px.
+```
+
+**Plan review findings:**
+
+```
+## Finding 1 — BLOCKING
+Task 4 references an integration test that does not exist in the current codebase
+(research artifact confirms: no integration tests for DashboardLayout.tsx).
+If Task 4 verification requires a new integration test to be written, that test
+must be part of Task 4's definition — otherwise the verification step cannot
+be completed as written.
+Resolution: Add sub-step to Task 4: "Write integration test for toggle visibility
+at 320px and 1280px before implementing the wiring."
+
+## Finding 2 — BLOCKING
+AC-6 (no existing light mode styles broken) has no dedicated task and no
+regression verification step. Task 5 addresses this but is listed after
+Task 4 — however, Task 3's component implementation could break light mode
+styles at import time if the CSS token extension in Task 1 is not complete.
+The sequence implicitly assumes Task 1 completes before Task 3's import runs,
+but this is not stated as a dependency.
+Resolution: Add explicit dependency note: "Task 3 requires Task 1 complete."
+
+## Finding 3 — ADVISORY
+Task 2's unit test description ("preference persists across simulated page reload")
+is ambiguous — what is the simulation mechanism? jsdom localStorage mock or actual
+window.location reload?
+Resolution: Specify test method in Task 2 verification step.
+
+## Verdict: BLOCKING — plan requires revision before execution.
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Impact | Prevention |
+|---------|--------|------------|
+| Approving a plan that has no coverage for one AC | That AC fails verification; review finds it; execution must restart | Map every AC to at least one task; flag gaps explicitly |
+| Missing sequence dependency analysis | Executor hits "file not found" mid-implementation | Trace every task's file dependencies to earlier tasks in the sequence |
+| Accepting "visual check" as a verification step | Verifier has no deterministic proof | Visual checks are acceptable only when paired with a screenshot comparison command |
+| Skimming the plan quickly | Sequence gaps and missing verifications survive into execution | Review each task individually, then review the sequence as a whole |
+| Not loading the research artifact | Missing dependencies go undetected | Research confirms what is available; plan must stay within those bounds |
+
+---
+
+## Related
+
+- [Overview — All Workflows](README.md)
+- [Previous: plan](plan.md)
+- [Next: execute](execute.md)
+- [Roles and Workflows](../../../concepts/roles-and-workflows.md)

package/docs/readmes/features/workflows/plan.md

@@ -0,0 +1,170 @@
+# plan
+
+**Phase 8 — Translate the approved spec into an execution-grade implementation plan with no ambiguity left for the executor to resolve.**
+
+![Phase](https://img.shields.io/badge/phase-8%20of%2014-blue)
+![Role](https://img.shields.io/badge/role-planner-orange)
+![Gate](https://img.shields.io/badge/gate-hard%20%E2%98%85-red)
+![Status](https://img.shields.io/badge/status-stable-green)
+
+---
+
+## One-Line Purpose
+
+Translate the approved spec (and design artifact, if present) into an ordered, dependency-resolved implementation plan where every task has a verification step — so that the executor has nothing left to decide except how to type.
+
+---
+
+## Pipeline Position
+
+```
+  DESIGN-REVIEW (or SPEC-CHALLENGE if design skipped)
+    │
+    ▼
+┌──────┐
+│ PLAN │  ◄── YOU ARE HERE
+└──────┘
+    │
+    ▼
+  PLAN-REVIEW  ★ gate
+    │
+    ▼
+  EXECUTE ...
+```
+
+---
+
+## Role Responsible
+
+`planner`
+
+The planner works from the approved spec and design artifact. It does not invent requirements — it sequences their implementation. A plan that introduces implementation decisions not grounded in the spec or design is a plan that has exceeded its mandate. A plan that is too high-level to execute is a plan that has failed its purpose.
+
+---
+
+## Trigger
+
+All of the following are true:
+
+- Spec artifact exists, approved, challenge findings resolved
+- Design artifact exists and design-review passed (or design phase was explicitly skipped)
+- Current repo state is available (branch, file structure, test coverage status)
+
+---
+
+## Steps
+
+1. **Load all upstream artifacts.** Spec, research, and design artifact (if present). The plan must be traceable to these sources.
+
+2. **Assess current repo state.** What is the current branch? What files are relevant? What tests currently pass? What is the existing code structure that implementation will touch?
+
+3. **Identify all implementation tasks.** For each acceptance criterion, enumerate the concrete code changes required. Tasks are specific file-and-function level, not feature-level.
+
+4. **Sequence tasks by dependency.** A task that depends on another task must come after it. Sequence gaps are a plan failure mode — `plan-review` will catch them, but the planner should find them first.
+
+5. **Assign verification steps to each task.** Every task must have a concrete verification step: a test command, a visual check, a lint check. "It should work" is not a verification step.
+
+6. **Identify risks and mitigations.** For each high-risk task, note the risk and the mitigation strategy.
+
+7. **Produce the implementation plan artifact.** Structured document: ordered tasks, per-task verification, risk notes, and traceability back to AC numbers.
+
+---
+
+## Input Artifacts
+
+| Artifact | Location | Required |
+|----------|----------|----------|
+| Approved spec artifact | Run state | Yes |
+| Research artifact | Run state | Yes |
+| Design artifact | Run state | Required if design phase ran |
+| Current repo state | Repo | Yes |
+
+---
+
+## Output Artifacts
+
+| Artifact | Description |
+|----------|-------------|
+| Implementation plan artifact | Ordered tasks with verification steps and AC traceability |
+| Task list | Flat ordered list of tasks (used by executor as the execution queue) |
+
+---
+
+## Approval Gate
+
+> [!IMPORTANT]
+> **Explicit human approval is required before execution begins.** The plan is the binding execution contract. Once approved, the executor implements only what is in the plan. New scope requires a new approval cycle — no executor-side plan expansion.
+
+Plan approval follows `plan-review`. Both the plan and the plan-review findings must be resolved before execution starts.
+
+---
+
+## Example Run
+
+**Spec inputs (abbreviated):**
+- AC-1: Toggle visible at all viewport widths
+- AC-2: Toggle switches scheme within one render cycle
+- AC-3: Preference persists in localStorage across sessions and new tabs
+- AC-4: Correct rendering at 768px breakpoint
+- AC-5: Toggling back to light restores original scheme
+- AC-6: No existing light mode styles broken
+
+**Design artifact:** `dashboard-dark-mode.fig`, `DarkModeToggle.tsx`, `tokens.json`
+
+**Implementation plan produced:**
+
+```
+## Task Sequence
+
+### Task 1 — Extend CSS tokens (AC-2, AC-5, AC-6)
+File: src/styles/tokens.css
+Add [data-theme="dark"] selector with dark token overrides.
+Use tokens from design artifact tokens.json.
+Verification: `npm run lint:css` passes; visual diff of /dashboard in both themes.
+
+### Task 2 — Implement useDarkMode hook (AC-2, AC-3)
+File: src/hooks/useDarkMode.ts (new file)
+Wraps useLocalStorage (existing hook). Sets/reads 'theme' key.
+Applies [data-theme] attribute to document.documentElement.
+Verification: Unit test: preference persists across simulated page reload.
+
+### Task 3 — Implement DarkModeToggle component (AC-1, AC-4)
+File: src/components/DarkModeToggle.tsx
+Use design artifact export as scaffold. 44x44 touch target at mobile.
+Aria-label: "Toggle dark mode". Focus ring per tokens.
+Verification: `npm test DarkModeToggle` passes; Storybook renders at 768px.
+
+### Task 4 — Wire toggle into dashboard nav (AC-1, AC-4)
+File: src/layouts/DashboardLayout.tsx
+Import DarkModeToggle; place in nav bar top-right.
+Verification: Integration test: toggle visible at 320px and 1280px.
+
+### Task 5 — Regression check (AC-6)
+Run full test suite. Visual regression on /dashboard light mode.
+Verification: `npm test` all green; no visual diff on light theme screenshots.
+
+## Risks
+R1: useLocalStorage hook — if it uses JSON.stringify, 'light' string must
+    not be double-encoded. Verify at Task 2.
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Impact | Prevention |
+|---------|--------|------------|
+| Tasks at feature granularity, not file granularity | Executor has to decompose the plan mid-execution (plan drift) | Each task names a specific file and a specific change |
+| Missing verification steps | Executor cannot confirm task completion; verifier has no checkpoints | Every task has a runnable verification command or explicit visual check |
+| No AC traceability in tasks | Verifier cannot map proof to acceptance criteria | Tag each task with the AC(s) it addresses |
+| Sequencing tasks without dependency analysis | Executor hits a blocker because a dependency is missing | Draw the dependency graph before writing the sequence |
+| Plan introduces new requirements | Scope expands silently; spec is now wrong | Every task must trace to a spec AC or a non-goal removal |
+
+---
+
+## Related
+
+- [Overview — All Workflows](README.md)
+- [Previous: design-review](design-review.md)
+- [Next: plan-review](plan-review.md)
+- [Roles and Workflows](../../../concepts/roles-and-workflows.md)