forked from farhoodlabs/paperclip
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>
This commit is contained in:
Devin Foley
@@ -0,0 +1,28 @@
|
||||
CREATE TABLE "issue_plan_decompositions" (
|
||||
"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
|
||||
"company_id" uuid NOT NULL,
|
||||
"source_issue_id" uuid NOT NULL,
|
||||
"accepted_plan_revision_id" uuid NOT NULL,
|
||||
"accepted_interaction_id" uuid,
|
||||
"status" text DEFAULT 'in_flight' NOT NULL,
|
||||
"request_fingerprint" text NOT NULL,
|
||||
"requested_child_count" integer DEFAULT 0 NOT NULL,
|
||||
"requested_children" jsonb DEFAULT '[]'::jsonb NOT NULL,
|
||||
"child_issue_ids" jsonb DEFAULT '[]'::jsonb NOT NULL,
|
||||
"owner_agent_id" uuid,
|
||||
"owner_user_id" text,
|
||||
"owner_run_id" uuid,
|
||||
"completed_at" timestamp with time zone,
|
||||
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
|
||||
"updated_at" timestamp with time zone DEFAULT now() NOT NULL
|
||||
);
|
||||
--> statement-breakpoint
|
||||
ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
|
||||
ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_source_issue_id_issues_id_fk" FOREIGN KEY ("source_issue_id") REFERENCES "public"."issues"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
|
||||
ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_accepted_plan_revision_id_document_revisions_id_fk" FOREIGN KEY ("accepted_plan_revision_id") REFERENCES "public"."document_revisions"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
|
||||
ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_accepted_interaction_id_issue_thread_interactions_id_fk" FOREIGN KEY ("accepted_interaction_id") REFERENCES "public"."issue_thread_interactions"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
|
||||
ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_owner_agent_id_agents_id_fk" FOREIGN KEY ("owner_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
|
||||
ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_owner_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("owner_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
|
||||
CREATE INDEX "issue_plan_decompositions_company_source_status_idx" ON "issue_plan_decompositions" USING btree ("company_id","source_issue_id","status");--> statement-breakpoint
|
||||
CREATE INDEX "issue_plan_decompositions_active_owner_idx" ON "issue_plan_decompositions" USING btree ("company_id","owner_agent_id") WHERE "issue_plan_decompositions"."status" = 'in_flight';--> statement-breakpoint
|
||||
CREATE UNIQUE INDEX "issue_plan_decompositions_source_revision_uq" ON "issue_plan_decompositions" USING btree ("company_id","source_issue_id","accepted_plan_revision_id");
|
||||
File diff suppressed because it is too large
Load Diff
@@ -645,6 +645,13 @@
|
||||
"when": 1778810394522,
|
||||
"tag": "0091_old_swarm",
|
||||
"breakpoints": true
|
||||
},
|
||||
{
|
||||
"idx": 92,
|
||||
"version": "7",
|
||||
"when": 1779999768200,
|
||||
"tag": "0092_mighty_puma",
|
||||
"breakpoints": true
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -32,6 +32,7 @@ export { workspaceRuntimeServices } from "./workspace_runtime_services.js";
|
||||
export { projectGoals } from "./project_goals.js";
|
||||
export { goals } from "./goals.js";
|
||||
export { issues } from "./issues.js";
|
||||
export { issuePlanDecompositions } from "./issue_plan_decompositions.js";
|
||||
export { issueRecoveryActions } from "./issue_recovery_actions.js";
|
||||
export { issueReferenceMentions } from "./issue_reference_mentions.js";
|
||||
export { issueRelations } from "./issue_relations.js";
|
||||
|
||||
@@ -0,0 +1,48 @@
|
||||
import { sql } from "drizzle-orm";
|
||||
import { pgTable, uuid, text, integer, timestamp, jsonb, index, uniqueIndex } from "drizzle-orm/pg-core";
|
||||
import { agents } from "./agents.js";
|
||||
import { companies } from "./companies.js";
|
||||
import { documentRevisions } from "./document_revisions.js";
|
||||
import { heartbeatRuns } from "./heartbeat_runs.js";
|
||||
import { issueThreadInteractions } from "./issue_thread_interactions.js";
|
||||
import { issues } from "./issues.js";
|
||||
|
||||
export const issuePlanDecompositions = pgTable(
|
||||
"issue_plan_decompositions",
|
||||
{
|
||||
id: uuid("id").primaryKey().defaultRandom(),
|
||||
companyId: uuid("company_id").notNull().references(() => companies.id),
|
||||
sourceIssueId: uuid("source_issue_id").notNull().references(() => issues.id, { onDelete: "cascade" }),
|
||||
acceptedPlanRevisionId: uuid("accepted_plan_revision_id")
|
||||
.notNull()
|
||||
.references(() => documentRevisions.id, { onDelete: "cascade" }),
|
||||
acceptedInteractionId: uuid("accepted_interaction_id")
|
||||
.references(() => issueThreadInteractions.id, { onDelete: "set null" }),
|
||||
status: text("status").notNull().default("in_flight"),
|
||||
requestFingerprint: text("request_fingerprint").notNull(),
|
||||
requestedChildCount: integer("requested_child_count").notNull().default(0),
|
||||
requestedChildren: jsonb("requested_children").$type<Record<string, unknown>[]>().notNull().default(sql`'[]'::jsonb`),
|
||||
childIssueIds: jsonb("child_issue_ids").$type<string[]>().notNull().default(sql`'[]'::jsonb`),
|
||||
ownerAgentId: uuid("owner_agent_id").references(() => agents.id, { onDelete: "set null" }),
|
||||
ownerUserId: text("owner_user_id"),
|
||||
ownerRunId: uuid("owner_run_id").references(() => heartbeatRuns.id, { onDelete: "set null" }),
|
||||
completedAt: timestamp("completed_at", { withTimezone: true }),
|
||||
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
|
||||
updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
|
||||
},
|
||||
(table) => ({
|
||||
companySourceStatusIdx: index("issue_plan_decompositions_company_source_status_idx").on(
|
||||
table.companyId,
|
||||
table.sourceIssueId,
|
||||
table.status,
|
||||
),
|
||||
activeOwnerIdx: index("issue_plan_decompositions_active_owner_idx")
|
||||
.on(table.companyId, table.ownerAgentId)
|
||||
.where(sql`${table.status} = 'in_flight'`),
|
||||
sourceRevisionUq: uniqueIndex("issue_plan_decompositions_source_revision_uq").on(
|
||||
table.companyId,
|
||||
table.sourceIssueId,
|
||||
table.acceptedPlanRevisionId,
|
||||
),
|
||||
}),
|
||||
);
|
||||
@@ -473,6 +473,12 @@ export type {
|
||||
RequestConfirmationTarget,
|
||||
RequestConfirmationPayload,
|
||||
RequestConfirmationResult,
|
||||
AcceptedPlanDecompositionStatus,
|
||||
AcceptedPlanDecompositionChild,
|
||||
AcceptedPlanDecomposition,
|
||||
AcceptedPlanDecompositionResult,
|
||||
AcceptedPlanDecompositionChildIssue,
|
||||
AcceptedPlanDecompositionSummary,
|
||||
IssueThreadInteractionBase,
|
||||
SuggestTasksInteraction,
|
||||
AskUserQuestionsInteraction,
|
||||
@@ -868,6 +874,7 @@ export {
|
||||
createIssueSchema,
|
||||
createIssueInputSchema,
|
||||
createChildIssueSchema,
|
||||
createAcceptedPlanDecompositionSchema,
|
||||
resolveCreateIssueStatusDefault,
|
||||
createIssueLabelSchema,
|
||||
issueBlockedInboxAttentionSchema,
|
||||
@@ -936,6 +943,7 @@ export {
|
||||
releaseIssueTreeHoldSchema,
|
||||
type CreateIssue,
|
||||
type CreateChildIssue,
|
||||
type CreateAcceptedPlanDecomposition,
|
||||
type CreateIssueLabel,
|
||||
type UpdateIssue,
|
||||
type ResolveIssueRecoveryAction,
|
||||
|
||||
@@ -238,6 +238,12 @@ export type {
|
||||
RequestConfirmationTarget,
|
||||
RequestConfirmationPayload,
|
||||
RequestConfirmationResult,
|
||||
AcceptedPlanDecompositionStatus,
|
||||
AcceptedPlanDecompositionChild,
|
||||
AcceptedPlanDecomposition,
|
||||
AcceptedPlanDecompositionResult,
|
||||
AcceptedPlanDecompositionChildIssue,
|
||||
AcceptedPlanDecompositionSummary,
|
||||
IssueThreadInteractionBase,
|
||||
SuggestTasksInteraction,
|
||||
AskUserQuestionsInteraction,
|
||||
|
||||
@@ -29,6 +29,7 @@ export interface InstanceGeneralSettings {
|
||||
export interface InstanceExperimentalSettings {
|
||||
enableEnvironments: boolean;
|
||||
enableIsolatedWorkspaces: boolean;
|
||||
enableIssuePlanDecompositions: boolean;
|
||||
enableCloudSync: boolean;
|
||||
autoRestartDevServerWhenIdle: boolean;
|
||||
enableIssueGraphLivenessAutoRecovery: boolean;
|
||||
|
||||
@@ -129,6 +129,71 @@ export interface LegacyPlanDocument {
|
||||
source: "issue_description";
|
||||
}
|
||||
|
||||
export type AcceptedPlanDecompositionStatus = "in_flight" | "completed";
|
||||
|
||||
export interface AcceptedPlanDecompositionChild {
|
||||
projectId?: string | null;
|
||||
projectWorkspaceId?: string | null;
|
||||
goalId?: string | null;
|
||||
blockedByIssueIds?: string[];
|
||||
title: string;
|
||||
description?: string | null;
|
||||
status: IssueStatus;
|
||||
workMode: IssueWorkMode;
|
||||
priority: IssuePriority;
|
||||
assigneeAgentId?: string | null;
|
||||
assigneeUserId?: string | null;
|
||||
requestDepth?: number;
|
||||
billingCode?: string | null;
|
||||
assigneeAdapterOverrides?: IssueAssigneeAdapterOverrides | null;
|
||||
executionPolicy?: IssueExecutionPolicy | null;
|
||||
executionWorkspaceId?: string | null;
|
||||
executionWorkspacePreference?: string | null;
|
||||
executionWorkspaceSettings?: IssueExecutionWorkspaceSettings | null;
|
||||
labelIds?: string[];
|
||||
acceptanceCriteria?: string[];
|
||||
blockParentUntilDone?: boolean;
|
||||
}
|
||||
|
||||
export interface AcceptedPlanDecomposition {
|
||||
id: string;
|
||||
companyId: string;
|
||||
sourceIssueId: string;
|
||||
acceptedPlanRevisionId: string;
|
||||
acceptedInteractionId: string | null;
|
||||
status: AcceptedPlanDecompositionStatus;
|
||||
requestFingerprint: string;
|
||||
requestedChildCount: number;
|
||||
childIssueIds: string[];
|
||||
ownerAgentId: string | null;
|
||||
ownerUserId: string | null;
|
||||
ownerRunId: string | null;
|
||||
completedAt: Date | string | null;
|
||||
createdAt: Date | string;
|
||||
updatedAt: Date | string;
|
||||
}
|
||||
|
||||
export interface AcceptedPlanDecompositionResult {
|
||||
decomposition: AcceptedPlanDecomposition;
|
||||
childIssueIds: string[];
|
||||
newlyCreatedChildIssueIds: string[];
|
||||
}
|
||||
|
||||
export interface AcceptedPlanDecompositionChildIssue {
|
||||
id: string;
|
||||
identifier: string | null;
|
||||
title: string;
|
||||
status: IssueStatus;
|
||||
priority: IssuePriority;
|
||||
assigneeAgentId: string | null;
|
||||
assigneeUserId: string | null;
|
||||
}
|
||||
|
||||
export interface AcceptedPlanDecompositionSummary extends AcceptedPlanDecomposition {
|
||||
acceptedPlanRevisionNumber: number | null;
|
||||
childIssues: AcceptedPlanDecompositionChildIssue[];
|
||||
}
|
||||
|
||||
export interface IssueRelationIssueSummary {
|
||||
id: string;
|
||||
identifier: string | null;
|
||||
|
||||
@@ -186,6 +186,7 @@ export {
|
||||
createIssueSchema,
|
||||
createIssueInputSchema,
|
||||
createChildIssueSchema,
|
||||
createAcceptedPlanDecompositionSchema,
|
||||
resolveCreateIssueStatusDefault,
|
||||
createIssueLabelSchema,
|
||||
issueBlockedInboxAttentionSchema,
|
||||
@@ -237,6 +238,7 @@ export {
|
||||
restoreIssueDocumentRevisionSchema,
|
||||
type CreateIssue,
|
||||
type CreateChildIssue,
|
||||
type CreateAcceptedPlanDecomposition,
|
||||
type CreateIssueLabel,
|
||||
type UpdateIssue,
|
||||
type IssueExecutionWorkspaceSettings,
|
||||
|
||||
@@ -38,6 +38,7 @@ export const patchInstanceGeneralSettingsSchema = instanceGeneralSettingsSchema.
|
||||
export const instanceExperimentalSettingsSchema = z.object({
|
||||
enableEnvironments: z.boolean().default(false),
|
||||
enableIsolatedWorkspaces: z.boolean().default(false),
|
||||
enableIssuePlanDecompositions: z.boolean().default(false),
|
||||
enableCloudSync: z.boolean().default(false),
|
||||
autoRestartDevServerWhenIdle: z.boolean().default(false),
|
||||
enableIssueGraphLivenessAutoRecovery: z.boolean().default(false),
|
||||
|
||||
@@ -412,6 +412,13 @@ export const createChildIssueSchema = withCreateIssueStatusDefault(createIssueBa
|
||||
|
||||
export type CreateChildIssue = z.infer<typeof createChildIssueSchema>;
|
||||
|
||||
export const createAcceptedPlanDecompositionSchema = z.object({
|
||||
acceptedPlanRevisionId: z.string().uuid(),
|
||||
children: z.array(createChildIssueSchema).min(1).max(25),
|
||||
});
|
||||
|
||||
export type CreateAcceptedPlanDecomposition = z.infer<typeof createAcceptedPlanDecompositionSchema>;
|
||||
|
||||
export const createIssueLabelSchema = z.object({
|
||||
name: z.string().trim().min(1).max(48),
|
||||
color: z.string().regex(/^#(?:[0-9a-fA-F]{6})$/, "Color must be a 6-digit hex value"),
|
||||
|
||||
Reference in New Issue
Block a user