Add accepted-plan decomposition exact-once guards and UI state (#6831)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies, so
planning approvals and child-issue fan-out are part of the core
control-plane loop.
> - Accepted plans are supposed to be a safe bridge from planning into
execution, especially when agents wake from review decisions and reuse
isolated workspaces.
> - The duplicate-subtask incident showed that an accepted plan revision
could be interpreted more than once across overlapping runs, which broke
the single-source-of-truth model for issue decomposition.
> - Fixing that required tightening the backend contract first:
accepted-plan decomposition needs an exact-once fingerprint, durable
claim state, and retry-safe child creation.
> - Once that backend behavior existed, the board still needed
visibility into what happened, so the issue detail view needed a
dedicated decomposition section instead of forcing operators to
reconstruct child creation from raw activity.
> - This pull request adds the exact-once decomposition primitive,
hardens wake routing and regressions around the incident, and surfaces
decomposition state in the UI so future incidents are both prevented and
easier to inspect.

## What Changed

- Added accepted-plan decomposition semantics to
`doc/execution-semantics.md`, including the exact-once fingerprint,
durable claim/result expectations, and retry/resume behavior.
- Added persistent accepted-plan decomposition claims in the backend,
including schema, shared types/validators, service logic, and issue
routes for creating and listing decomposition state.
- Hardened heartbeat routing so an accepted-plan continuation stays
scoped to the relevant planning issue instead of opportunistically
re-decomposing another accepted issue on the same assignee.
- Added regression coverage for the original failure modes: concurrent
same-parent retries, cross-issue accepted-plan isolation, and partial
child recreation under the same fingerprint.
- Added the `Plan decomposition` issue-detail section plus supporting
API/query-key/activity formatting updates so operators can see revision
status, owner, child counts, and the linked child issues directly in the
UI.
- Included the small follow-up UI fix so the decomposition section still
renders when the issue work mode is no longer `planning`.

## Verification

- `pnpm --filter @paperclipai/server typecheck`
- `pnpm --filter @paperclipai/ui typecheck`
- `pnpm --filter @paperclipai/db typecheck`
- `pnpm exec vitest run server/src/__tests__/issues-service.test.ts`
- `pnpm exec vitest run server/src/__tests__/issues-service.test.ts -t
"lists persisted decompositions with child issue summaries"`
- `pnpm exec vitest run server/src/__tests__/issues-service.test.ts -t
"accepted plan decomposition"
server/src/__tests__/heartbeat-accepted-plan-workspace-refresh.test.ts
server/src/__tests__/heartbeat-context-summary.test.ts`
- Manual UI path: create a planning issue without an isolated execution
workspace, add a `plan` document, accept the `request_confirmation`, let
Paperclip create child issues, then reopen the parent issue detail page
and confirm the `Plan decomposition` section shows the accepted
revision, status, idempotent-claim badge, and child links.
- Separate follow-up bug noted during manual UI validation: accepting a
plan on an issue whose run never records `workspace_finalize` is tracked
in `PAPA-445` and is not part of this PR’s fix scope.

## Risks

- This adds a new migration and a large Drizzle snapshot update;
reviewers should confirm the schema shape and generated metadata match
the intended decomposition table.
- The exact-once claim changes sit on the accepted-plan fan-out path, so
regressions there could block legitimate child creation or mis-handle
retries if the claim state machine is wrong.
- The new UI only appears when decomposition records exist; reviewers
should use the manual verification path above rather than expecting
existing issues on a stale local instance to show the section
automatically.
- `PAPA-445` remains an open follow-up for the `workspace_finalize`
accept gate when a planning handoff never records finalize; that bug can
interfere with reproducing the UI flow on isolated workspaces but does
not change the correctness of the exact-once decomposition feature
itself.

> Checked `ROADMAP.md`: this PR is a bug fix / control-plane hardening
change for accepted-plan decomposition, not a new uncoordinated roadmap
feature.

## Model Used

- OpenAI Codex via Paperclip `codex_local` (GPT-5-based coding agent;
exact backend model ID/context window not exposed in the run context),
with repository tool use, shell execution, and code-editing
capabilities.

<img width="806" height="1069" alt="Screenshot 2026-05-27 at 11 05
48 PM"
src="https://github.com/user-attachments/assets/5b00b670-96cd-4470-b0a3-581743bcae28"
/>


## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

ui/storybook/stories/issue-plan-decompositions.stories.tsx

@@ -0,0 +1,129 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useQueryClient } from "@tanstack/react-query";
+import type { AcceptedPlanDecompositionSummary } from "@paperclipai/shared";
+import { IssuePlanDecompositionsSection } from "@/components/IssuePlanDecompositionsSection";
+import { queryKeys } from "@/lib/queryKeys";
+import { storybookAgentMap } from "../fixtures/paperclipData";
+
+const issueId = "issue-plan-decomposition-story";
+const issueIdentifier = "PAP-6831";
+
+function buildDecomposition(
+  overrides: Partial<AcceptedPlanDecompositionSummary>,
+): AcceptedPlanDecompositionSummary {
+  return {
+    id: "decomposition-story-1",
+    companyId: "company-storybook",
+    sourceIssueId: issueId,
+    acceptedPlanRevisionId: "revision-story-1",
+    acceptedInteractionId: "interaction-story-1",
+    status: "completed",
+    requestFingerprint: "fingerprint-story-1",
+    requestedChildCount: 2,
+    childIssueIds: ["issue-child-1", "issue-child-2"],
+    ownerAgentId: "agent-codex",
+    ownerUserId: null,
+    ownerRunId: "run-story-1",
+    completedAt: "2026-05-28T06:22:00.000Z",
+    createdAt: "2026-05-28T06:18:00.000Z",
+    updatedAt: "2026-05-28T06:22:00.000Z",
+    acceptedPlanRevisionNumber: 7,
+    childIssues: [
+      {
+        id: "issue-child-1",
+        identifier: "PAP-6840",
+        title: "Harden accepted-plan wake routing",
+        status: "done",
+        priority: "medium",
+        assigneeAgentId: "agent-codex",
+        assigneeUserId: null,
+      },
+      {
+        id: "issue-child-2",
+        identifier: "PAP-6841",
+        title: "Add decomposition regression coverage",
+        status: "in_progress",
+        priority: "medium",
+        assigneeAgentId: "agent-qa",
+        assigneeUserId: null,
+      },
+    ],
+    ...overrides,
+  };
+}
+
+function HydratedSection({
+  decompositions,
+}: {
+  decompositions: AcceptedPlanDecompositionSummary[];
+}) {
+  const queryClient = useQueryClient();
+  const [ready] = useState(() => {
+    queryClient.setQueryData(queryKeys.issues.acceptedPlanDecompositions(issueId), decompositions);
+    return true;
+  });
+
+  if (!ready) return null;
+
+  return (
+    <div className="paperclip-story">
+      <main className="paperclip-story__inner">
+        <div className="mx-auto max-w-3xl rounded-2xl border border-border bg-background/95 p-6 shadow-sm">
+          <IssuePlanDecompositionsSection
+            issueId={issueId}
+            issueIdentifier={issueIdentifier}
+            agentMap={storybookAgentMap}
+          />
+        </div>
+      </main>
+    </div>
+  );
+}
+
+const meta = {
+  title: "Issue Detail/Plan Decompositions",
+  component: HydratedSection,
+  args: {
+    decompositions: [],
+  },
+  parameters: {
+    layout: "fullscreen",
+  },
+} satisfies Meta<typeof HydratedSection>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const InFlight: Story = {
+  args: {
+    decompositions: [
+      buildDecomposition({
+        status: "in_flight",
+        completedAt: null,
+        updatedAt: "2026-05-28T06:20:00.000Z",
+        childIssueIds: ["issue-child-1"],
+        childIssues: [
+          {
+            id: "issue-child-1",
+            identifier: "PAP-6840",
+            title: "Harden accepted-plan wake routing",
+            status: "done",
+            priority: "medium",
+            assigneeAgentId: "agent-codex",
+            assigneeUserId: null,
+          },
+        ],
+      }),
+    ],
+  },
+};
+
+export const Completed: Story = {
+  args: {
+    decompositions: [
+      buildDecomposition({}),
+    ],
+  },
+};