docs: add proposals CLI reference, webui /proposals, contract rework docs

- cli.md: add wave proposals subcommands (list/show/approve/reject)
- cli.md: add proposals to quick reference table
- web-dashboard.md: add /proposals section + API endpoints
- state-resumption.md: add rework (test guard) failure mode
- webhooks-worksource-overlap.md: F4 analysis (informational)

Author: nextlevelshit

docs/guides/state-resumption.md

@@ -123,6 +123,7 @@ Recovery hints:
 | Failure Mode | What Happens | Recovery |
 |-------------|-------------|----------|
 | **Contract validation** | Step output doesn't match schema. Step is marked failed. | Fix the issue, then `--from-step <step>` to retry. Use `--force` to skip contract checks. |
+| **Rework (test guard)** | `test_diff` or `test_count_baseline` detects test deletion/regression. Step re-executes automatically. | The rework loop retries the step up to `max_attempts`. If test count drops, the implementer must restore tests. |
 | **Adapter crash** | LLM CLI process exits unexpectedly. Step is marked failed. | `--from-step <step>` to retry with a fresh adapter invocation. |
 | **Missing artifact** | A required input artifact from a prior step is missing. | Re-run the upstream step that produces the artifact, then resume. |
 | **Timeout** | Step exceeds its configured timeout. | Increase timeout in manifest or simplify the prompt, then resume. |

docs/guides/web-dashboard.md

@@ -46,6 +46,10 @@ The dashboard is available at `http://127.0.0.1:8080` by default.
 
 Browser-driven onboarding chats with the same `internal/onboarding.Service` the CLI uses. Hitting `GET /onboard` allocates a session and redirects to `/onboard/{sessionID}`; the page subscribes to `/onboard/{sessionID}/stream` (SSE) and surfaces conversation events as chat bubbles. When the agent asks a question (`PromptString` / `PromptChoice`), a form is rendered and `POST /onboard/{sessionID}/answer` (form-encoded `answer` + `prompt_id`) feeds the answer back into the blocked Service goroutine. Reload survives via `Last-Event-ID` ring-buffer replay; sessions are in-memory and tied to the `wave webui` process lifetime.
 
+### Proposals (`/proposals`)
+
+Evolution proposal review and approval. Lists proposals generated by `pipeline-evolve` with status (proposed/approved/rejected/superseded), trigger reason, and eval signal summary. Each proposal shows a diff between current and proposed pipeline YAML. Approve or reject via buttons — approving atomically activates the new pipeline version. A rollback button on approved proposals reverts to the prior version.
+
 ## Authentication
 
 When binding to localhost (default), no authentication is required. When binding to a non-localhost address, a token is required:
@@ -77,6 +81,11 @@ Clients authenticate via the `Authorization: Bearer <token>` header or the `?tok
 | POST | `/api/runs/{id}/resume` | Resume from a step |
 | GET | `/api/personas` | List personas |
 | GET | `/api/pipelines` | List pipelines |
+| GET | `/proposals` | List evolution proposals |
+| GET | `/proposals/{name}` | Proposals for a specific pipeline |
+| POST | `/proposals/{name}/{id}/approve` | Approve a proposal |
+| POST | `/proposals/{name}/{id}/reject` | Reject a proposal |
+| POST | `/proposals/{name}/{id}/rollback` | Rollback to prior pipeline version |
 
 ## Configuration
 

docs/reference/cli.md

@@ -28,6 +28,7 @@ Wave CLI commands for pipeline orchestration.
 | `wave retro` | View and manage run retrospectives |
 | `wave rewind` | Rewind a run to an earlier checkpoint |
 | `wave skills` | Discover, validate, install, and diagnose SKILL.md files |
+| `wave proposals` | Manage evolution proposals (list, show, approve, reject, rollback) |
 | `wave suggest` | Suggest impactful pipeline runs |
 | `wave serve` | Start the web dashboard server |
 | `wave migrate` | Database migrations |
@@ -1318,6 +1319,32 @@ All commands support:
 
 ---
 
+## proposals
+
+Manage evolution proposals generated by `pipeline-evolve`.
+
+```bash
+wave proposals list [--status proposed|approved|rejected|superseded] [--format text|json]
+wave proposals show <id> [--format text|json]
+wave proposals approve <id> [--reason "..."]
+wave proposals reject <id> [--reason "..."]
+```
+
+Proposals are created when the evolution loop detects pipeline improvement opportunities (drift signals, retry-rate patterns, eval-score thresholds). Approving a proposal creates a new `pipeline_version` row and activates it — the next `wave run` picks up the evolved YAML.
+
+| Subcommand | Description |
+|-----------|-------------|
+| `list` | List proposals, default filter: `--status proposed` |
+| `show <id>` | Display proposal details, reason, and eval signal summary |
+| `approve <id>` | Activate the proposed pipeline version |
+| `reject <id>` | Mark proposal as rejected |
+
+### Web UI
+
+The `/proposals` page in the web dashboard provides the same approve/reject workflow with diff preview. Proposal rollback (revert to prior version) is available via the web UI rollback button.
+
+---
+
 ## Exit Codes
 
 | Code | Meaning |

docs/scope/2026-04-30-webhooks-worksource-overlap.md

@@ -0,0 +1,15 @@
+# Webhooks + WorkSource overlap analysis
+
+Audited overlap between future webhooks (#638) and current worksource/dispatch surface (Phase 2). Conclusion: additive, no refactor needed.
+
+## Outbound webhooks (lifecycle listeners)
+
+Integration point: `internal/pipeline/executor_observers.go:112-116` via existing `HookRunner` / `FireWebhooks()`. Webhooks fire on lifecycle events (run-start, step-complete, run-finish) as additional observers alongside existing emitter, state-store, and contract hooks. No worksource changes required.
+
+## Inbound webhook triggers (future phase)
+
+Payload normalization → `WorkItemRef` → `MatchBindings()` → `launchPipelineExecution`. Plug-in point: `internal/webui/handlers_work_dispatch.go:83-91`. New endpoint (`POST /api/webhooks/{forge}`) would parse forge-specific payloads, extract issue/PR identifiers, and feed into the existing dispatch flow. No worksource schema changes needed — `WorkItemRef` already models the required fields.
+
+## No action required
+
+This document is informational. Link from Epic #1565 follow-ups and future #638 epic body.