@wazir-dev/cli 1.0.0

package/docs/readmes/features/workflows/prepare-next.md

@@ -0,0 +1,167 @@
+# prepare-next
+
+**Phase 14 — Close the current run cleanly so the next one starts from truth, not stale context.**
+
+![Phase](https://img.shields.io/badge/phase-14%20of%2014-blue)
+![Role](https://img.shields.io/badge/role-planner-orange)
+![Status](https://img.shields.io/badge/status-stable-green)
+
+---
+
+## One-Line Purpose
+
+Produce an explicit, scoped handoff artifact for the next run or next execution slice — capturing exactly what was done, what remains, what was learned, and what context is safe to carry forward — so that nothing stale, ambiguous, or unapproved silently poisons the next session.
+
+---
+
+## Pipeline Position
+
+```
+  LEARN
+    │
+    ▼
+┌──────────────┐
+│ PREPARE-NEXT │  ◄── YOU ARE HERE
+└──────────────┘
+    │
+    ▼
+  NEXT RUN (or session end)
+```
+
+---
+
+## Role Responsible
+
+`planner`
+
+The planner who closes a run is often the same role that will open the next one. But the job here is not planning — it is handoff. The planner summarizes what is true now, what is open, and what the next session needs to know. Nothing is assumed. Nothing is carried forward silently.
+
+---
+
+## Trigger
+
+One of:
+
+1. **Full completion** — All 14 phases are done, review is accepted, learnings are proposed. Prepare the next feature's starting point.
+2. **Partial completion** — The session is ending before the pipeline finishes. Prepare a mid-pipeline handoff so the next session can resume.
+3. **Slice boundary** — The approved plan is being executed in multiple slices. Prepare the handoff between slices.
+
+`prepare-next` must run before any session end where the pipeline is incomplete. It is not optional.
+
+---
+
+## Steps
+
+1. **Summarize what was completed.** List every task, phase, or acceptance criterion that reached a verified, accepted state in this run.
+
+2. **Summarize what remains.** List every task, phase, or acceptance criterion that is open, blocked, or unstarted.
+
+3. **Capture the current artifact state.** What is the state of each artifact (spec, plan, verification proof, etc.)? Is it final, draft, or superseded?
+
+4. **Identify context that is safe to carry forward.** Which facts, decisions, and constraints remain valid for the next run? Explicitly name them.
+
+5. **Identify context that is NOT safe to carry forward.** Which assumptions have been proven wrong? Which constraints have changed? Which artifacts are now stale?
+
+6. **Include accepted learnings (only).** If any proposed learnings from the `learn` phase were accepted by the operator in this session, include them in the handoff. Proposed-but-unreviewed learnings must not be included.
+
+7. **Produce the handoff artifact.** One document. Completion summary, open items, artifact state, safe context, unsafe context, accepted learnings.
+
+---
+
+## Input Artifacts
+
+| Artifact | Location | Required |
+|----------|----------|----------|
+| Current run summary | Run state | Yes |
+| Accepted learnings | Run state | Only if any were accepted |
+| All current run artifacts | Run state | Yes (to assess artifact state) |
+
+---
+
+## Output Artifacts
+
+| Artifact | Description |
+|----------|-------------|
+| Next-step handoff | Full handoff document: what's done, what's open, artifact state, context |
+| Scoped context summary | Distilled facts safe to carry into the next session |
+
+---
+
+## Approval Gate
+
+> [!NOTE]
+> There is no hard approval gate for `prepare-next` itself. However:
+
+> [!IMPORTANT]
+> **No implicit carry-forward of unapproved learnings.** If a proposed learning was not explicitly reviewed and accepted by the operator in this session, it must not appear in the handoff artifact. Carrying forward unreviewed learnings causes context drift — future sessions act on unvalidated observations as though they were established facts.
+
+---
+
+## Example Run
+
+**Scenario:** Dark mode feature partially complete. AC-1 through AC-5 verified. AC-6 regression test found a conflict with the admin panel CSS that was not caught in-scope. Session ending.
+
+**Handoff artifact produced:**
+
+```
+## Completion Summary
+AC-1: VERIFIED ✓ (DashboardLayout.integration.test.tsx)
+AC-2: VERIFIED ✓ (DarkModeToggle.test.tsx)
+AC-3: VERIFIED ✓ (useDarkMode.test.ts)
+AC-4: VERIFIED ✓ (DarkModeToggle 768px snapshot)
+AC-5: VERIFIED ✓ (useDarkMode.test.ts)
+AC-6: BLOCKED — see open items
+
+## Open Items
+AC-6: tokens.css [data-theme="dark"] selector is leaking into /admin routes
+because AdminLayout.tsx imports from the same tokens.css. Requires a scoping
+fix (either namespace the dark tokens or exclude admin from the data-theme
+attribute application).
+Blocker introduced: Review Finding 1 (tokens.css selector placement).
+
+## Artifact State
+spec.md: FINAL (approved, challenge resolved)
+plan.md: FINAL (approved, review passed)
+verification-proof.md: PARTIAL (AC-1–5 verified; AC-6 blocked)
+review-findings.md: ACTIVE (Finding 1 blocking; Finding 2–3 advisory)
+learnings/proposed/: 3 proposed artifacts (none accepted this session)
+
+## Context Safe to Carry Forward
+- useLocalStorage hook is the established persistence pattern (src/hooks/useLocalStorage.ts)
+- [data-theme] attribute approach is confirmed working for /dashboard
+- Dark palette tokens are defined and in use (tokens.json)
+- Current branch: feature/dark-mode-dashboard
+
+## Context NOT Safe to Carry Forward
+- Assumption A-3 ("dark mode does not affect /admin") is now invalidated —
+  the token scoping issue proves /admin is affected. Spec A-3 must be updated.
+
+## Accepted Learnings
+None accepted this session. 3 proposed learnings in run state (pending review).
+
+## Next Session Entry Point
+Enter at EXECUTE — resume at AC-6 fix.
+Required: load plan.md (Task 1 fix: scope tokens.css selector) and
+review-findings.md (Finding 1).
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Impact | Prevention |
+|---------|--------|------------|
+| Skipping prepare-next at session end | Next session inherits stale context and must re-discover state | Always run prepare-next before session end if the pipeline is open |
+| Carrying forward proposed (unreviewed) learnings | Future sessions treat hypotheses as facts | Only accepted learnings appear in the handoff |
+| Vague "what remains" section | Next session wastes time re-discovering open items | Name each open AC, task, or blocker explicitly |
+| Not invalidating stale assumptions | Next session operates on disproved context | Explicitly list context that is NOT safe to carry forward |
+| Treating handoff as a narrative summary | Next session has to parse prose to recover structured state | Handoff must be structured: completion status, open items, artifact state |
+
+---
+
+## Related
+
+- [Overview — All Workflows](README.md)
+- [Previous: learn](learn.md)
+- [First phase of next run: clarify](clarify.md)
+- [Roles and Workflows](../../../concepts/roles-and-workflows.md)

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

@@ -0,0 +1,169 @@
+# review
+
+**Phase 12 — The adversarial post-implementation review that stands between your code and completion.**
+
+![Phase](https://img.shields.io/badge/phase-12%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
+
+Run a hard adversarial review of the changed implementation and its evidence — checking correctness against spec, design alignment, verification quality, and code integrity — before declaring the work done.
+
+---
+
+## Pipeline Position
+
+```
+  VERIFY
+    │
+    ▼
+┌────────┐
+│ REVIEW │  ◄── YOU ARE HERE
+└────────┘
+    │
+    ▼
+  LEARN  ★ gate (blocking findings stop completion)
+    │
+    ▼
+  PREPARE-NEXT ...
+```
+
+---
+
+## Role Responsible
+
+`reviewer`
+
+This is the fourth structural adversarial checkpoint in the pipeline. The reviewer examines the full evidence set — changed files, verification proof, spec, plan, and design artifact — and produces findings. The reviewer's job is not to be satisfied with good intentions; it is to be satisfied with evidence.
+
+---
+
+## Trigger
+
+All of the following are true:
+
+- Execution batch(es) are complete
+- Verification proof artifact is fresh (produced against current branch state)
+- All upstream artifacts are available (spec, plan, design artifact if applicable)
+
+---
+
+## Steps
+
+1. **Load all review inputs.** Changed files, verification proof, approved spec, approved plan, and design artifact (if the design phase ran).
+
+2. **Verify the proof is fresh.** Confirm the verification proof was produced against the current branch state. If the proof is stale, stop and require fresh proof before continuing.
+
+3. **Review changed files against the spec.** For each acceptance criterion, confirm that the changed code satisfies it — not just that a test claims it does. Read the relevant code.
+
+4. **Review changed files against the plan.** Was execution faithful to the plan? Any task that was deviated from, skipped, or silently substituted is a finding.
+
+5. **Review for design-implementation alignment (when design phase ran).** Compare the implemented UI against the design artifact screenshots and exported scaffolds. Visual drift from the design that is not documented in execution notes is a finding.
+
+6. **Review the verification proof for completeness.** Does every AC have mapped proof? Is any AC "assumed passing" without evidence? Incomplete proof is itself a finding.
+
+7. **Review code quality within scope.** The review is not a free-form code audit — focus on correctness, safety, and spec compliance. Note structural issues as advisory findings.
+
+8. **Produce findings with severity.** Each finding must include:
+   - Severity: `blocking` (completion cannot proceed) or `advisory` (proceed with awareness)
+   - Which AC, task, or code change it applies to
+   - Specific file, line, or evidence reference
+   - Required resolution
+
+9. **Issue a verdict.** No-findings verdict if all checks pass. Blocking verdict if any blocking finding exists.
+
+---
+
+## Input Artifacts
+
+| Artifact | Location | Required |
+|----------|----------|----------|
+| Changed files | Repo (working branch) | Yes |
+| Verification proof artifact | Run state | Yes |
+| Approved spec artifact | Run state | Yes |
+| Approved plan artifact | Run state | Yes |
+| Design artifact | Run state | Required if design phase ran |
+
+---
+
+## Output Artifacts
+
+| Artifact | Description |
+|----------|-------------|
+| Review findings | Structured findings with severity, evidence reference, and resolution |
+| No-findings verdict | Explicit statement that all checks passed (if applicable) |
+
+---
+
+## Approval Gate
+
+> [!IMPORTANT]
+> **Unresolved blocking findings must stop completion.** Work cannot be declared done while blocking findings remain open. Advisory findings may be acknowledged and carried forward (as candidates for the `learn` phase or future work).
+
+If blocking findings require code changes, the executor must address them, a new verification proof must be produced, and review re-runs for the affected areas.
+
+---
+
+## Example Run
+
+**Review inputs:**
+- 147/147 tests passing (verification proof)
+- Changed files: tokens.css, useDarkMode.ts, DarkModeToggle.tsx, DashboardLayout.tsx
+- Design screenshots: dashboard-dark-desktop.png, dashboard-dark-mobile-768.png
+
+**Review findings:**
+
+```
+## Finding 1 — BLOCKING
+AC-6 (no existing light mode styles broken) has a passing test suite, but
+tokens.css review reveals that the [data-theme="dark"] block was added
+inside the @media (prefers-color-scheme: dark) query rather than as a
+standalone data attribute selector. This means dark mode only activates when
+the OS-level setting is also dark — it will not respond to the toggle alone.
+File: src/styles/tokens.css:48–72
+Resolution: Move [data-theme="dark"] block outside the @media query.
+Re-run verification after fix.
+
+## Finding 2 — ADVISORY
+DarkModeToggle.tsx does not implement the aria-pressed attribute on the
+toggle button. Screen readers cannot convey toggle state to visually
+impaired users. This does not block a spec AC (accessibility standard was
+marked advisory in design-review) but should be addressed before shipping.
+File: src/components/DarkModeToggle.tsx:22
+Resolution: Add aria-pressed={isDark} to the button element.
+
+## Finding 3 — ADVISORY
+Execution notes for Task 5 (regression check) list `npm test` as the
+verification command but do not include the captured output in the notes.
+The verification proof artifact does include the output — this is a
+documentation gap, not a proof gap.
+Resolution: Note for future runs: execution notes should echo test output,
+not just state the command.
+
+## Verdict: BLOCKING — fix required before completion.
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Impact | Prevention |
+|---------|--------|------------|
+| Accepting stale verification proof | Review is validating a different state than what will ship | Always check proof timestamp and branch against current state |
+| Skipping design-implementation alignment check | Design drift ships silently | When a design artifact exists, compare screenshots to running implementation |
+| Vague findings without file/line citations | Executor cannot action the finding | Every finding needs a specific file reference or evidence anchor |
+| Reviewing code style outside AC scope | Findings noise drowns real issues | Keep blocking findings to spec correctness, proof gaps, and safety issues |
+| Issuing a no-findings verdict too quickly | Defects reach completion | Take the time the review requires; a slow review that catches a bug is better than a fast one that misses it |
+
+---
+
+## Related
+
+- [Overview — All Workflows](README.md)
+- [Previous: verify](verify.md)
+- [Next: learn](learn.md)
+- [Roles and Workflows](../../../concepts/roles-and-workflows.md)

package/docs/readmes/features/workflows/run-audit.md

@@ -0,0 +1,191 @@
+# run-audit
+
+**Out-of-band — Structured codebase auditing that produces source-backed findings, not opinions.**
+
+![Phase](https://img.shields.io/badge/phase-out--of--band-grey)
+![Role](https://img.shields.io/badge/role-researcher-orange)
+![Status](https://img.shields.io/badge/status-stable-green)
+
+---
+
+## One-Line Purpose
+
+Perform a structured, source-backed audit of the codebase, a branch, or scoped paths — producing findings with severity, evidence, citations, and remediation — in either report mode (immediate deliverable) or plan mode (feeds the `plan` phase).
+
+---
+
+## Pipeline Position
+
+`run-audit` is an independent workflow. It does not require prior pipeline state and can be triggered at any time.
+
+```
+  (any point)
+       │
+       ▼
+┌───────────┐
+│ RUN-AUDIT │  ◄── INDEPENDENT ENTRY POINT
+└───────────┘
+       │
+       ├─── report mode ──► Audit report artifact (deliverable)
+       │
+       └─── plan mode ───► docs/plans/<audit-name>.md
+                                   │
+                                   ▼
+                             PLAN workflow (standard pipeline entry)
+```
+
+---
+
+## Role Responsible
+
+`researcher` (composed with audit-specific expertise from `audit-*` concern modules)
+
+The researcher role is used because auditing is fundamentally investigative work: collect evidence, assess against standards, cite sources, produce structured findings. The researcher does not implement fixes — it finds and documents.
+
+---
+
+## Trigger
+
+One of:
+- Operator requests a security, code-quality, architecture, performance, or dependency audit
+- A scheduled or milestone-triggered audit runs on a branch or scope
+- A custom audit scope is defined (specific paths, specific concerns)
+
+No prior pipeline run state is required.
+
+---
+
+## Steps
+
+1. **Receive audit parameters.** Three inputs define the audit:
+   - **Audit type**: `security`, `code-quality`, `architecture`, `performance`, `dependencies`, or `custom`
+   - **Audit scope**: `whole-project`, `branch` (diff only), or `paths` (explicit file list)
+   - **Output mode**: `report` (produce findings artifact) or `plan` (produce approved design doc in `docs/plans/`)
+
+2. **Load audit-specific expertise modules.** The relevant `audit-*` expertise modules are composed into the researcher context for the declared audit type.
+
+3. **Enumerate all files within scope.** Skipping any file within the declared scope is a failure condition. Every file must be examined.
+
+4. **Produce findings.** For each issue found:
+   - Assign a severity: `critical`, `high`, `medium`, `low`, `info`
+   - Cite evidence: file path, line number, code snippet
+   - Justify the severity rating
+   - Provide a specific remediation recommendation
+
+5. **Produce the output artifact.**
+   - **Report mode**: Structured audit report with artifact metadata (title, date, scope, audit type, findings table, executive summary)
+   - **Plan mode**: Approved design doc in `docs/plans/<name>.md` formatted for `wz:writing-plans` handoff into the `plan` workflow
+
+---
+
+## Input Artifacts
+
+| Artifact | Description | Required |
+|----------|-------------|----------|
+| Audit type | One of the defined audit types | Yes |
+| Audit scope | Scope definition (whole-project / branch / paths) | Yes |
+| Output mode | `report` or `plan` | Yes |
+
+---
+
+## Output Artifacts
+
+| Mode | Artifact | Description |
+|------|----------|-------------|
+| Report | Audit report artifact | Structured findings with severity, evidence, citations, remediation |
+| Plan | `docs/plans/<name>.md` | Design doc ready for `plan` workflow handoff |
+
+---
+
+## Approval Gate
+
+> [!IMPORTANT]
+> **No finding without source-backed evidence.** Every finding must include a file path, line number, code snippet, and citation. Assertions without evidence are not findings.
+>
+> **No severity rating without justification.** Every severity assignment must state why the finding warrants that severity level. "High because it is a security issue" is not a justification — the specific threat model or impact must be stated.
+
+---
+
+## Audit Types
+
+| Type | What is examined | Expertise modules applied |
+|------|-----------------|--------------------------|
+| `security` | Auth, input validation, secrets exposure, dependency vulns | `audit-security` |
+| `code-quality` | Complexity, dead code, test coverage, naming | `audit-code-quality` |
+| `architecture` | Layer separation, coupling, dependency flow, patterns | `audit-architecture` |
+| `performance` | Algorithmic complexity, N+1s, bundle size, caching | `audit-performance` |
+| `dependencies` | Outdated packages, license compliance, vulnerability flags | `audit-dependencies` |
+| `custom` | Operator-defined concern list | Operator-specified modules |
+
+---
+
+## Example Run
+
+**Audit request:**
+```
+Type: security
+Scope: whole-project
+Mode: report
+```
+
+**Audit report (abbreviated):**
+
+```
+# Security Audit — Wazir Dashboard
+Date: 2026-03-13
+Scope: whole-project
+Auditor: researcher (audit-security expertise)
+
+## Executive Summary
+3 findings: 1 high, 1 medium, 1 low. No critical issues.
+Primary concern: localStorage used for session token storage.
+
+## Findings
+
+### F-001 — HIGH
+Title: Session token stored in localStorage
+File: src/hooks/useAuth.ts:34
+Snippet: localStorage.setItem('session_token', token)
+Evidence: localStorage is accessible to any JavaScript running on the page,
+          making stored tokens vulnerable to XSS attacks.
+Citation: OWASP Web Storage Security, §3.2
+Severity justification: XSS + localStorage token = full session hijack.
+Remediation: Use httpOnly cookies for session tokens. Remove localStorage
+             storage of any credential material.
+
+### F-002 — MEDIUM
+Title: No Content-Security-Policy header configured
+File: src/server/middleware.ts (absent)
+Evidence: No CSP middleware found in codebase search.
+Citation: OWASP CSP Cheat Sheet
+Severity justification: Absence of CSP increases XSS blast radius.
+Remediation: Add CSP middleware with strict-dynamic policy.
+
+### F-003 — LOW
+Title: .env.example contains non-example credentials
+File: .env.example:7
+Snippet: STRIPE_SECRET_KEY=sk_test_4eC39Hq...
+Evidence: Key prefix sk_test_ indicates a real (test-mode) Stripe key.
+Severity justification: Test keys can make real API calls in test mode.
+Remediation: Replace with placeholder: STRIPE_SECRET_KEY=<your-stripe-secret-key>
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Impact | Prevention |
+|---------|--------|------------|
+| Producing findings without file/line citations | Finding cannot be actioned or verified | Every finding must have a specific file path and line number |
+| Assigning severity without justification | Severity is noise; remediation prioritization fails | State the threat model or impact that drives the severity |
+| Skipping files within declared scope | Audit coverage is incomplete; findings are not exhaustive | Enumerate every in-scope file before beginning; confirm all were examined |
+| Producing superficial findings ("add tests") | Report is not actionable | Findings must be specific enough to generate a concrete remediation task |
+| Using plan mode without knowing the plan workflow | Design doc format is wrong; plan phase cannot consume it | Review `plan` workflow and `wz:writing-plans` skill before selecting plan mode |
+
+---
+
+## Related
+
+- [Overview — All Workflows](README.md)
+- [Pipeline entry via plan mode: plan](plan.md)
+- [Roles and Workflows](../../../concepts/roles-and-workflows.md)

package/docs/readmes/features/workflows/spec-challenge.md

@@ -0,0 +1,159 @@
+# spec-challenge
+
+**Phase 4 — Adversarial review of the spec before a single line of design or code is written.**
+
+![Phase](https://img.shields.io/badge/phase-4%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
+
+Stress-test the draft spec for contradictions, silent omissions, untestable criteria, and fake completeness — before design, planning, or implementation locks in the spec's mistakes.
+
+---
+
+## Pipeline Position
+
+```
+  SPECIFY
+    │
+    ▼
+┌───────────────┐
+│ SPEC-CHALLENGE│  ◄── YOU ARE HERE
+└───────────────┘
+    │
+    ▼
+  DESIGN  ★ gate (findings must be resolved first)
+    │
+    ▼
+  PLAN ...
+```
+
+---
+
+## Role Responsible
+
+`reviewer`
+
+The reviewer is structurally independent from the specifier. This is the mechanism: the person who challenges the spec did not write it. The reviewer's job is to find every crack in the spec before it costs the project a full design-plan-execute cycle to discover.
+
+---
+
+## Trigger
+
+A draft spec artifact exists in run state. The spec has not yet been handed to the designer or planner. `spec-challenge` runs immediately after `specify` completes.
+
+---
+
+## Steps
+
+1. **Load the spec artifact and research artifact.** The research artifact is the ground truth. The spec must be consistent with it.
+
+2. **Check each acceptance criterion for testability.** Can every AC be confirmed true or false with a concrete, reproducible action? Flag any AC that relies on subjective judgment, undefined thresholds, or out-of-scope dependencies.
+
+3. **Check for contradictions.** Do any acceptance criteria contradict each other? Does any AC contradict an assumption? Does any assumption contradict a research finding?
+
+4. **Check for silent omissions.** What does the spec not address that the research suggests it should? What edge cases are conspicuously absent?
+
+5. **Check for fake completeness.** Does the spec appear thorough but actually defer all the hard decisions to the planner? Planners should receive a spec that is specific, not one that requires them to re-invent the requirements.
+
+6. **Check non-goals for correctness.** Are non-goals genuinely out of scope, or are they requirements being silently dropped?
+
+7. **Produce the challenge findings.** Each finding must include:
+   - Severity: `blocking` (spec cannot proceed) or `advisory` (proceed with awareness)
+   - Which AC, assumption, or section it applies to
+   - What the problem is
+   - What resolution is required
+
+8. **Issue a verdict.** Either: all findings are advisory and spec can proceed with acknowledgement; or: one or more blocking findings require spec revision before progression.
+
+---
+
+## Input Artifacts
+
+| Artifact | Location | Required |
+|----------|----------|----------|
+| Draft spec artifact | Run state | Yes |
+| Research artifact | Run state | Yes |
+
+---
+
+## Output Artifacts
+
+| Artifact | Description |
+|----------|-------------|
+| Spec challenge findings | Structured list of findings with severity, location, and required resolution |
+
+---
+
+## Approval Gate
+
+> [!IMPORTANT]
+> **The spec cannot be treated as approved until all blocking challenge findings are resolved or explicitly accepted by the operator.** Advisory findings may proceed with acknowledgement. A rubber-stamp review — one that generates no findings at all — is itself a failure mode. Every spec has something worth questioning.
+
+If blocking findings require spec revision, the specifier must update the spec artifact and re-submit for challenge. This loop may iterate.
+
+---
+
+## Example Run
+
+**Spec under challenge (abbreviated):**
+
+```
+AC-3: The dark mode preference survives a page reload.
+AC-4: At 768px viewport width, the toggle is accessible and the dark scheme
+      renders without layout breakage.
+A-2: Server-side preference sync is out of scope.
+```
+
+**Challenge findings produced:**
+
+```
+## Finding 1 — BLOCKING
+AC-3 says preference "survives a page reload" but does not specify the persistence
+mechanism. Research (Finding 2) established localStorage as the existing pattern,
+but the spec does not reference this. If an implementor uses sessionStorage instead,
+AC-3 would pass on a reload within the same tab but fail on a new tab.
+Resolution: Amend AC-3 to explicitly state "persists in localStorage across
+sessions and new tabs."
+
+## Finding 2 — ADVISORY
+AC-4 references "accessible" but does not define the accessibility standard.
+Does this mean WCAG 2.1 AA contrast ratio compliance on the toggle control itself?
+If so, add this as an explicit sub-criterion. If not, the verifier has no basis
+for confirming compliance.
+Resolution: Clarify or explicitly descope accessibility standard compliance.
+
+## Finding 3 — ADVISORY
+Non-goal A-2 (server-side preference sync) is correct but A-3 (admin panel) is
+not present in non-goals. Research did not cover the admin panel at all.
+If the admin panel shares the CSS token system, dark mode tokens may inadvertently
+render on /admin.
+Resolution: Add explicit non-goal: "Dark mode tokens must not apply to /admin routes."
+
+## Verdict: BLOCKING — spec requires revision before proceeding.
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Impact | Prevention |
+|---------|--------|------------|
+| Generating zero findings | Challenge is pure theater; spec defects survive into planning | Every non-trivial spec has something worth questioning. If you find nothing, look harder. |
+| Marking all findings as advisory | Blocking defects proceed silently | Use blocking severity when a defect would cause a verifier or reviewer to reach a wrong conclusion |
+| Challenging style, not substance | Findings waste review bandwidth | Challenge correctness, completeness, and testability — not phrasing preferences |
+| Not loading the research artifact | Challenge ignores ground truth | Always compare spec claims against research findings for consistency |
+| Closing the loop without revising the spec | The spec remains defective | Blocking findings require an updated spec artifact, not just an acknowledgement |
+
+---
+
+## Related
+
+- [Overview — All Workflows](README.md)
+- [Previous: specify](specify.md)
+- [Next: author](author.md)
+- [Roles and Workflows](../../../concepts/roles-and-workflows.md)