docs(support): sync Deep Planning QA verification docs — plan acceptance flow, diff schema, support case (VOY-1326)

Author: Paperclip-Paperclip

docs/api/plans.md

@@ -19,7 +19,7 @@ Plan documents are structured, revisioned issue artifacts that represent an impl
 | **Revision** | Each update creates or supersedes a revision. Plan revisions can be compared with diff endpoints. |
 | **Review Gate** | An approval checkpoint on a plan revision. Gates are created per-revision and must be approved before the plan can be considered fully accepted. |
 | **Plan Status** | Overall plan status: `draft` → `in_review` → `approved` → `superseded`. A plan auto-transitions to `approved` when all its gates for the current revision are approved. |
-| **Accepted Plan Decomposition** | When a plan is approved, the agent can create child issues from it via the accepted plan decomposition workflow. |
+| **Accepted Plan Decomposition** | When a plan is approved, agents can request board acceptance via a `request_confirmation` interaction. Once a board user accepts, the agent can create child issues from the approved plan via the accepted plan decomposition workflow. Agents cannot accept — human board interaction is required. |
 
 ## Create/Update Plan Document
 
@@ -133,6 +133,45 @@ GET /issues/{issueId}/documents/plan/revisions/{revisionId}/diff?againstRevision
 
 Returns a structured diff between two plan revisions.
 
+**Response**: Returns a `PlanRevisionDiff` object:
+
+```json
+{
+  "revision": {
+    "id": "uuid-of-target-revision",
+    "revisionNumber": 3
+  },
+  "previousRevision": {
+    "id": "uuid-of-compared-revision",
+    "revisionNumber": 2
+  },
+  "bodyDiff": [
+    {
+      "type": "unchanged",
+      "value": "Step 1: Set up Redis client",
+      "oldLineNumber": 1,
+      "newLineNumber": 1
+    },
+    {
+      "type": "added",
+      "value": "Step 2: Create cache service",
+      "newLineNumber": 2
+    },
+    {
+      "type": "removed",
+      "value": "Step 2: Evaluate Redis options",
+      "oldLineNumber": 2
+    }
+  ]
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `revision` | `{ id, revisionNumber }` | The target revision the diff was computed for |
+| `previousRevision` | `{ id, revisionNumber } | null` | The revision compared against. `null` when this is the first revision. |
+| `bodyDiff` | `PlanBodyDiffLine[]` | Line-level diff of the plan body. Each line has `type` (`added`, `removed`, or `unchanged`), `value` (the line text), and optional `oldLineNumber`/`newLineNumber` for position tracking. |
+
 ## Create Plan Review Gate
 
 ```text
@@ -262,6 +301,19 @@ Creates child issues from an accepted (approved) plan. The `acceptedPlanRevision
 
 **Response**: `201 Created` — returns the created child issues.
 
+**Requirement — accepted plan confirmation**: Decomposition is only possible after a human (board user) has **accepted a plan confirmation interaction** for that exact plan revision. The flow is:
+
+1. An agent creates a `request_confirmation` interaction on the issue with a target of `{ "type": "issue_document", "key": "plan", "issueId": "...", "revisionId": "..." }` — the `revisionId` must be the latest plan revision. The interaction is the explicit waiting path; the issue is moved to `in_review`.
+2. A **board user** accepts the confirmation via the board UI (`POST /issues/{id}/interactions/{interactionId}/accept`). **Agents cannot accept plan confirmations** — `assertBoard` requires a human user. (Task watchdogs may only accept when the plan is eligible under their contract; otherwise the board decides.)
+3. Once accepted, agents can call this decomposition endpoint with the accepted `acceptedPlanRevisionId`.
+
+If the plan revision is superseded by a newer revision before acceptance, the pending interaction expires with `outcome: "stale_target"` — create a fresh confirmation against the new revision. If a board/user comment lands while the confirmation is pending, it is superseded (`superseded_by_comment`) and must be re-created.
+
+**Errors**:
+- `422 Unprocessable Entity` — `"acceptedPlanRevisionId must have an accepted plan confirmation"` — no accepted `request_confirmation` interaction targets this revision. Have a board user accept the plan confirmation first.
+- `422 Unprocessable Entity` — `"acceptedPlanRevisionId must belong to the source issue's plan document"` — the revision is not from this issue's plan document.
+- `409 Conflict` — `"Accepted-plan decomposition already exists for this revision with a different child set"` — decomposition is idempotent per revision; a retry with a different child set is rejected.
+
 ## Plan Lifecycle
 
 ```text
@@ -273,13 +325,16 @@ draft ──> in_review ──> approved ──> superseded
                      │
                 plan status → approved
                      │
+                board accepts plan confirmation
+                     │
                 decomposition allowed
 ```
 
 - Plans start as `draft`
 - Review gates keep the plan in `in_review` until all are approved
 - Once all gates for the current revision approve, plan auto-transitions to `approved`
-- Approved plans can be decomposed into child issues
+- `approved` alone is not enough to decompose — a board user must accept the plan confirmation (`request_confirmation` targeting the approved revision) first. Agents cannot accept; this requires human board interaction.
+- Once accepted, approved plans can be decomposed into child issues
 - Newer revisions supersede older ones (gates on previous revisions are auto-superseded)
 
 ## Agent Events

docs/releases.md

@@ -21,7 +21,7 @@ Paperclip ships continuously. This page documents each release to the main branc
 
 - **Plan Review Gates** — Approval gates on plan revisions with per-milestone acceptance criteria. When all gates for the current revision approve, the plan auto-transitions to `approved`.
 
-- **Approved Plan Decomposition** — Approved plans can be decomposed into child issues, creating a direct link from the approved plan to executable work items.
+- **Approved Plan Decomposition** — Approved plans can be decomposed into child issues after a board user accepts the plan confirmation, creating a direct link from the approved plan to executable work items. Human acceptance is required — agents cannot accept plan confirmations.
 
 - **Agent Memory (pgvector)** — A durable, queryable agent memory system. Agents capture text (30-day TTL), upsert curated records, and search via hybrid semantic + full-text retrieval. Memory is scoped per-agent with shared company-wide records.
 

docs/support/assessments/support-case-v0.4.0-deep-planning.md

@@ -16,7 +16,7 @@ Deep Planning introduces a structured plan document system that replaces ad-hoc
 
 3. **Review Gates** — Agents can create approval gates on plan revisions. Gates are linked to milestones and acceptance criteria. When all gates for the current revision are approved, the plan status auto-transitions to `approved`.
 
-4. **Plan Decomposition** — Once a plan's gates are all approved, the agent can decompose the plan into child issues via the accepted plan decomposition workflow.
+4. **Plan Decomposition** — Once a plan's gates are all approved, a `request_confirmation` interaction is created targeting the plan revision. A **board user** must accept this confirmation (agents cannot accept). Once accepted, the agent can decompose the plan into child issues via the accepted plan decomposition workflow.
 
 5. **Agent Wake Reasons** — Agents are woken when plans are updated (`issue_plan_updated`) and when gates are resolved (`issue_plan_gate_resolved`), enabling reactive workflows.
 
@@ -38,7 +38,7 @@ The plan UI also mounts inside the Issue Detail page when an issue has a plan do
 
 1. **"My plan disappeared / I can't find it"** — Plans live on the issue's documents with key `plan`. Check the issue detail page's plan section or use `GET /issues/{id}/documents/plan`.
 
-2. **"The plan won't let me add child issues"** — Child issues via plan decomposition require the plan to be in `approved` status. All review gates for the plan's current revision must be approved. Check gate status with `GET /issues/{id}/plan/gates`.
+2. **"The plan won't let me add child issues"** — Child issues via plan decomposition require the plan to be in `approved` status. All review gates for the plan's current revision must be approved. Check gate status with `GET /issues/{id}/plan/gates`. Even after approval, a **board user must accept the plan confirmation interaction** (`request_confirmation` targeting the approved revision) — agents cannot accept this. Check for a pending `request_confirmation` on the issue and have a board user accept it.
 
 3. **"I created gates but nothing happened"** — Gates don't auto-resolve. An agent or board must explicitly approve each gate via `PATCH /issues/{id}/plan/gates/{gateId}`. Auto-approval only happens when all gates are resolved to `approved`.
 
@@ -48,6 +48,8 @@ The plan UI also mounts inside the Issue Detail page when an issue has a plan do
 
 6. **"Old gates are gone"** — When a new plan revision is created, pending gates from previous revisions are auto-superseded. This is by design — each revision gets fresh gates.
 
+7. **"The decomposition endpoint says 'acceptedPlanRevisionId must have an accepted plan confirmation'"** — A board user must accept a `request_confirmation` interaction on the issue first (targeting the plan revision). Agents cannot accept plan confirmations — only board users can. See the FAQ entry "How do I turn a plan into actual work?" below for the full flow.
+
 ## FAQ
 
 **Q: How do I create a plan?**
@@ -60,7 +62,14 @@ A: Create gates on `POST /issues/{issueId}/plan/gates`. Each gate targets a mile
 A: Existing pending gates are auto-superseded. You need to create new gates for the updated revision.
 
 **Q: How do I turn a plan into actual work?**
-A: Once the plan is `approved`, use `POST /issues/{issueId}/accepted-plan-decompositions` to create child issues. This replaces the previous decomposition workflow.
+A: The full flow:
+   1. Create a plan document via `POST /issues/{issueId}/documents/plan`
+   2. Create review gates via `POST /issues/{issueId}/plan/gates`
+   3. Have gates approved via `PATCH /issues/{issueId}/plan/gates/{gateId}` until all are approved — the plan auto-transitions to `approved`
+   4. The agent creates a `request_confirmation` interaction on the issue (targeting the approved plan revision) — this is the explicit waiting path, and the issue moves to `in_review`
+   5. A **board user** accepts the confirmation via the board UI — **agents cannot accept plan confirmations**
+   6. Once accepted, use `POST /issues/{issueId}/accepted-plan-decompositions` to create child issues
+   This replaces the previous ad-hoc decomposition workflow.
 
 **Q: Can I edit a milestone after creating it?**
 A: Milestones are part of `planMetadata`. You update them by creating a new plan revision with updated milestones. Each revision has its own snapshot of milestones.
@@ -87,6 +96,8 @@ A: No. A rejected gate means that gate's acceptance criteria were not met. The p
 3. All gates for the current revision must be `approved`
 4. The `acceptedPlanRevisionId` must reference an approved revision
 5. If gates exist but aren't approved, resolve them first
+6. **Check for an accepted plan confirmation**: Even if the plan is `approved`, a board user must accept a `request_confirmation` interaction targeting the plan revision first. Agents cannot accept — the board must. Look for a pending `request_confirmation` on the issue with kind `request_confirmation` and target `{ type: "issue_document", key: "plan" }`. If none exists, create one; if it's pending, have a board user accept it via the board UI.
+7. If the endpoint returns `422: "acceptedPlanRevisionId must have an accepted plan confirmation"`, this confirms the acceptance step is missing
 
 ### Gates not appearing after plan update
 
@@ -110,14 +121,16 @@ A: No. A rejected gate means that gate's acceptance criteria were not met. The p
 
 ## Error States
 
-| Error | User sees | Root cause | Recovery |
-|---|---|---|---|
-| 409 Conflict on plan update | "Stale baseRevisionId" | `baseRevisionId` doesn't match latest revision | Fetch current plan doc to get latest revision ID |
-| 404 on plan GET | "Plan document not found" | No plan exists on this issue | Create one with POST |
-| Gate not resolving | Unexpected error | Gate already superseded or doesn't exist | List gates to verify state |
-| Decomposition fails | 400 error | Plan not approved or revision mismatch | Check plan status and gates |
-| Gate creation fails | Missing issue | Issue ID not found | Verify issue exists |
-| 403 on agent actions | Forbidden | Agent trying to access another agent's scope | Use correct agent authentication |
+|| Error | User sees | Root cause | Recovery |
+|---|---|---|---|---|
+|| 409 Conflict on plan update | "Stale baseRevisionId" | `baseRevisionId` doesn't match latest revision | Fetch current plan doc to get latest revision ID |
+|| 404 on plan GET | "Plan document not found" | No plan exists on this issue | Create one with POST |
+|| Gate not resolving | Unexpected error | Gate already superseded or doesn't exist | List gates to verify state |
+|| Decomposition fails | 400 error | Plan not approved or revision mismatch | Check plan status and gates |
+|| Decomposition fails | 422: "acceptedPlanRevisionId must have an accepted plan confirmation" | No accepted `request_confirmation` interaction targets this revision | Have a board user accept the plan confirmation first via the board UI |
+|| Decomposition fails | 422: "acceptedPlanRevisionId must belong to the source issue's plan document" | Revision is from a different issue's plan | Use the correct revision ID from the target issue's plan document |
+|| Gate creation fails | Missing issue | Issue ID not found | Verify issue exists |
+|| 403 on agent actions | Forbidden | Agent trying to access another agent's scope | Use correct agent authentication |
 
 ## Related Documentation
 
@@ -135,4 +148,5 @@ A: No. A rejected gate means that gate's acceptance criteria were not met. The p
 | Decomposition creates issues outside the plan's scope | High | CTO | Security/scope violation |
 | Plan revision diff returns empty or wrong data | Medium | Staff Engineer | Diff computation issue |
 | Agent not woken on plan update or gate resolve | Medium | Staff Engineer | Wake reason may not be delivered |
-| Milestone acceptance criteria lost on revision | Medium | Founding Engineer | Milestone snapshot fidelity issue |
+| Milestone acceptance criteria lost on revision | Medium | Founding Engineer | Milestone snapshot fidelity issue |
+| Decomposition fails with 422: "acceptedPlanRevisionId must have an accepted plan confirmation" | Low | First line support (guide board user) | No accepted plan confirmation exists for this revision. This is by design — agents cannot accept; a board user must accept the `request_confirmation` interaction. Guide the board user to the board UI to accept the pending confirmation or create one if missing. |

docs/support/heartbeat-log.md

@@ -988,3 +988,46 @@ Documentation updates **required** for RC-3. The Phase 5 Plan Board UI surface w
 - **VOY-1265 QA findings** → any UI behavior deltas worth a support note
 - **PostHog cron deployment to VPS-1** → SOP goes from final to operational; may generate first PostHog error issues for triage
 - **COO request for documentation health report** — available on demand
+
+## 2026-08-17 — Heartbeat: Deep Planning QA verification (VOY-1212) — docs synced
+
+### What was done
+
+1. **Diff assessment of VOY-1326 task** — QA verification of Deep Planning Workstream A (VOY-1212) is complete. Verified the 9 backend API endpoints shipping in v0.4.0-alpha. Analyzed the codebase for documentation gaps.
+
+2. **Gap identified: Plan acceptance flow undocumented** — The decomposition endpoint (`POST /issues/:id/accepted-plan-decompositions`) requires an accepted `request_confirmation` interaction targeting the plan revision. Agents cannot accept this — `assertBoard` requires a human user. This flow was entirely absent from customer-facing documentation.
+
+3. **`docs/api/plans.md` updated**:
+   - **Accepted Plan Decomposition** — Added full acceptance flow: agent creates `request_confirmation` → board user accepts → decomposition allowed. Documented the three error responses (422 for missing confirmation, 422 for wrong revision, 409 for idempotency conflict). Updated Key Concepts, Plan Lifecycle, and the decomposition section.
+   - **Diff Plan Revisions** — Added explicit response schema (`{ revision, previousRevision, bodyDiff }`) with JSON example, field descriptions, and line-level diff type documentation.
+
+4. **`docs/support/assessments/support-case-v0.4.0-deep-planning.md` updated**:
+   - Added confusion point #7 for the "accepted plan confirmation" error
+   - Updated FAQ "How do I turn a plan into actual work?" with the full 6-step flow
+   - Updated troubleshooting for decomposition with acceptance flow checks
+   - Updated Error States and Escalation Path with the new 422 error
+   - Updated Feature Overview to reflect human acceptance requirement
+
+5. **`docs/support/releases/v0.4.0-alpha-deep-planning.md` updated**:
+   - Added acceptance flow to Support Notes
+   - Updated "Approved Plan Decomposition" highlights to note human acceptance requirement
+   - Added decomposition 422 to Support Escalation Path
+
+6. **`docs/releases.md` updated** — "Approved Plan Decomposition" highlight now notes human acceptance requirement.
+
+### Current state
+
+| Metric | Status |
+|---|---|
+| Open support issues (VOY-1326) | 1 — actively working |
+| Pending KB articles | 0 |
+| Pending feature assessments | 5 (planned backlog) |
+| Release notes currency | Up to date through v0.4.0-alpha-rc.4 |
+| Docs synced with live code | ✅ Deep Planning QA verification (VOY-1212) — all 9 endpoints, schemas, acceptance flow documented |
+| Product dev server | UP (port 3100 healthy) |
+
+### Next triggers to watch for
+
+- **v0.4.0 release to main** → final release notes refresh for v0.4.0 (stable)
+- **PostHog error monitoring (VOY-999) reaching production** → finalize SOP from draft
+- **COO request for documentation health report** — available on demand