@backburner/cli 0.1.0

package/dist/src/tasks/derivation/handlers/comment-response.js

@@ -0,0 +1,169 @@
+import { classifyManagementPullRequest } from "../../../github/pr-classification.js";
+import { workflowRegistry } from "../../../workflows/registry.js";
+import { isRetryLinkCommand } from "../../retry.js";
+import { buildCommentReason, buildTaskId, isAgentAuthoredComment } from "../builders.js";
+export const commentResponseHandler = {
+    name: "comment_response",
+    derive(context, env) {
+        return deriveCommentTasks(context, env);
+    }
+};
+export function deriveManagementPullRequestCommentTasks(context, env, _sink) {
+    return deriveCommentTasks(context, env).filter((task) => task.kind !== "respond_pr_comment");
+}
+function deriveCommentTasks(context, env) {
+    const attention = context.attention;
+    if (!attention?.commentIds?.length) {
+        return [];
+    }
+    const tasks = [];
+    for (const commentId of [...attention.commentIds].sort((left, right) => left.localeCompare(right))) {
+        const comment = env.currentCommentsById.get(commentId);
+        if (!comment || isAgentAuthoredComment(comment)) {
+            continue;
+        }
+        if (attention.reasons.includes("retry_requested") && isRetryLinkCommand(comment.body)) {
+            continue;
+        }
+        const previousComment = env.previousComments.get(comment.id);
+        const isNewOrEdited = !previousComment ||
+            previousComment.updatedAt !== comment.updatedAt ||
+            previousComment.body !== comment.body;
+        if (!isNewOrEdited) {
+            continue;
+        }
+        if (comment.parentType === "issue") {
+            const issue = context.issue;
+            if (!issue || issue.number !== comment.parentNumber) {
+                continue;
+            }
+            if (!env.previousIssues.has(issue.id) && context.attention?.reasons.includes("new_issue")) {
+                continue;
+            }
+            tasks.push(createCommentTask("respond_issue_comment", comment, issue, {
+                localRepoPath: context.repoSyncRecord?.localPath
+            }, {
+                reason: buildCommentReason(comment, previousComment),
+                summary: `Respond to issue comment on #${issue.number}: ${issue.title}`,
+                contextBuilder: env.input.contextBuilder,
+                now: env.input.now
+            }, undefined, context.workstream.id, context.workstream.phase));
+            continue;
+        }
+        const prTask = derivePullRequestCommentTask(comment, previousComment, context, env);
+        if (prTask) {
+            tasks.push(prTask);
+        }
+    }
+    return tasks;
+}
+function derivePullRequestCommentTask(comment, previousComment, context, env) {
+    let parentPullRequest = resolveCommentPullRequest(comment, context);
+    let isPacketPR = false;
+    let worktreeContext = {
+        localRepoPath: context.activeWorktree?.path ?? context.repoSyncRecord?.localPath,
+        branchName: context.activeWorktree?.branchName,
+        planDocumentPath: context.activeWorktree?.planDocumentPath,
+        productSpecDocumentPath: context.activeWorktree?.productSpecDocumentPath,
+        logDocumentPath: context.activeWorktree?.logDocumentPath,
+        packetId: context.activeWorktree?.packet?.packetId
+    };
+    if (!parentPullRequest) {
+        const packetProjection = env.packetProjectionByRepoAndPrNumber.get(`${comment.repoId}:${comment.parentNumber}`);
+        if (packetProjection &&
+            packetProjection.parentWorkstream.id === context.workstream.id &&
+            packetProjection.pullRequest.number === comment.parentNumber) {
+            parentPullRequest = packetProjection.pullRequest;
+            isPacketPR = true;
+            worktreeContext = {
+                localRepoPath: packetProjection.packetWorktree?.path ?? context.repoSyncRecord?.localPath,
+                branchName: packetProjection.packetWorktree?.branchName,
+                planDocumentPath: packetProjection.packetWorktree?.planDocumentPath,
+                productSpecDocumentPath: packetProjection.packetWorktree?.productSpecDocumentPath,
+                logDocumentPath: packetProjection.packetWorktree?.logDocumentPath,
+                packetId: packetProjection.packetWorktree?.packet?.packetId ?? packetProjection.packet.id
+            };
+        }
+    }
+    if (!parentPullRequest) {
+        return undefined;
+    }
+    const isManagementPR = classifyManagementPullRequest({
+        repoId: parentPullRequest.repoId,
+        repoSlug: parentPullRequest.repoSlug,
+        pullRequestNumber: parentPullRequest.number,
+        headBranch: parentPullRequest.headBranch,
+        managementPrs: env.input.previousState.managementPrs,
+        ...(env.input.managementRepo ? { managementRepo: env.input.managementRepo } : {})
+    }).kind === "management";
+    if (isManagementPR) {
+        return undefined;
+    }
+    if (!isPacketPR &&
+        !env.previousPullRequests.has(parentPullRequest.id) &&
+        parentPullRequest.number === comment.parentNumber) {
+        return undefined;
+    }
+    return createCommentTask("respond_pr_comment", comment, parentPullRequest, worktreeContext, {
+        reason: buildCommentReason(comment, previousComment),
+        summary: `Respond to PR comment on #${parentPullRequest.number}: ${parentPullRequest.title}`,
+        contextBuilder: env.input.contextBuilder,
+        now: env.input.now
+    }, comment.pullRequestReviewLocation, context.workstream.id, context.workstream.phase);
+}
+function resolveCommentPullRequest(comment, context) {
+    if (context.activePullRequest && context.activePullRequest.number === comment.parentNumber) {
+        return context.activePullRequest;
+    }
+    return undefined;
+}
+function createCommentTask(kind, comment, parent, worktreeContext, input, pullRequestReviewLocation, workstreamId, workflowPhase) {
+    const executionPolicy = workflowRegistry.resolveTaskExecutionPolicy(kind);
+    return {
+        id: buildTaskId(kind, comment.id),
+        kind,
+        status: "pending",
+        executionPermission: executionPolicy.executionPermission,
+        handoffPolicy: executionPolicy.handoffPolicy,
+        repoId: comment.repoId,
+        repoName: comment.repoName,
+        repoSlug: comment.repoSlug,
+        sourceKind: "comment",
+        sourceId: comment.id,
+        sourceUrl: comment.url,
+        sourceReactionTargetId: comment.reactionTargetId,
+        parentSourceKind: comment.parentType === "issue" ? "issue" : "pull_request",
+        parentSourceId: parent.id,
+        relevant: true,
+        reason: input.reason,
+        summary: input.summary,
+        ...(workstreamId ? { workstreamId } : {}),
+        ...(workflowPhase ? { workflowPhase } : {}),
+        context: input.contextBuilder.build({
+            taskKind: kind,
+            ...(workflowPhase ? { workflowPhase } : {}),
+            repoIdentifier: comment.repoSlug,
+            sourceKind: "comment",
+            sourceUrl: comment.url,
+            labels: parent.labels,
+            parentUrl: parent.url,
+            ...(parent.kind === "issue"
+                ? {
+                    issueTitle: parent.title,
+                    issueBody: parent.body
+                }
+                : { headSha: parent.headSha }),
+            commentUrl: comment.url,
+            commentText: comment.body,
+            ...(worktreeContext.localRepoPath ? { localRepoPath: worktreeContext.localRepoPath } : {}),
+            ...(worktreeContext.branchName ? { branchName: worktreeContext.branchName } : {}),
+            ...(worktreeContext.planDocumentPath ? { planDocumentPath: worktreeContext.planDocumentPath } : {}),
+            ...(worktreeContext.productSpecDocumentPath ? { productSpecDocumentPath: worktreeContext.productSpecDocumentPath } : {}),
+            ...(worktreeContext.logDocumentPath ? { logDocumentPath: worktreeContext.logDocumentPath } : {}),
+            ...(worktreeContext.packetId ? { packetId: worktreeContext.packetId } : {}),
+            ...(pullRequestReviewLocation ? { pullRequestReviewLocation } : {})
+        }),
+        createdAt: input.now,
+        updatedAt: input.now
+    };
+}

package/dist/src/tasks/derivation/handlers/implement-plan.js

@@ -0,0 +1,103 @@
+import { buildTaskRecord, createPullRequestTask } from "../builders.js";
+export const implementPlanHandler = {
+    name: "implement_plan",
+    derive(context, env) {
+        const task = deriveImplementTask(context, env);
+        return task ? [task] : [];
+    }
+};
+export function derivePacketImplementTask(context, env) {
+    const { workstream, issue, activePullRequest, activeWorktree, packetPullRequest } = context;
+    if (workstream.status !== "open" ||
+        workstream.phase === "abandoned" ||
+        workstream.phase === "resolved") {
+        return undefined;
+    }
+    if (packetPullRequest && packetPullRequest.state !== "open") {
+        return undefined;
+    }
+    if (!activeWorktree?.packet || activeWorktree.status !== "implementation_ready") {
+        return undefined;
+    }
+    const parentSource = issue ?? activePullRequest;
+    const source = packetPullRequest ?? parentSource;
+    if (!source) {
+        return undefined;
+    }
+    return createWorktreeImplementTask(source, activeWorktree, {
+        contextBuilder: env.input.contextBuilder,
+        now: env.input.now
+    }, parentSource, workstream.id);
+}
+function deriveImplementTask(context, env) {
+    const { workstream, attention, activePullRequest, activeWorktree, repoConfig, repoSyncRecord } = context;
+    if (!attention || !activePullRequest || !repoConfig) {
+        return undefined;
+    }
+    if (activeWorktree?.status === "implementation_done" || workstream.phase === "implementation_done") {
+        return undefined;
+    }
+    if (activeWorktree &&
+        activeWorktree.status !== "implementation_ready" &&
+        activeWorktree.status !== "awaiting_plan_approval" &&
+        activeWorktree.status !== "implementing") {
+        return undefined;
+    }
+    if (workstream.phase === "abandoned" || workstream.phase === "resolved") {
+        return undefined;
+    }
+    if (activePullRequest.state !== "open") {
+        return undefined;
+    }
+    if (attention.reasons.includes("pr_review_requested") ||
+        (!attention.reasons.includes("plan_approved") &&
+            workstream.phase !== "implementation_ready" &&
+            workstream.phase !== "implementing" &&
+            workstream.phase !== "implementation_feedback")) {
+        return undefined;
+    }
+    return createPullRequestTask("implement_plan", activePullRequest, repoSyncRecord, {
+        reason: `Pull request carries the "${repoConfig.labels.agentPlanApproved}" label and is ready for implementation.`,
+        summary: `Implement approved plan for PR #${activePullRequest.number}: ${activePullRequest.title}`,
+        contextBuilder: env.input.contextBuilder,
+        now: env.input.now
+    }, activeWorktree, workstream.id);
+}
+function createWorktreeImplementTask(source, worktree, input, parentSource, workstreamId) {
+    const reason = worktree.packet
+        ? `Implementation packet "${worktree.packet.packetId}" is approved in wave ${worktree.packet.waveIndex} and ready for implementation.`
+        : `Implementation ready for ${source.kind === "issue" ? "issue" : "PR"} #${source.number}: ${source.title}`;
+    const summary = worktree.packet
+        ? `Implement approved packet "${worktree.packet.packetId}" in wave ${worktree.packet.waveIndex}`
+        : `Implement approved plan for ${source.kind === "issue" ? "issue" : "PR"} #${source.number}: ${source.title}`;
+    return buildTaskRecord(`task:implement_plan:worktree:${worktree.id}`, "implement_plan", source, undefined, {
+        reason,
+        summary,
+        contextBuilder: input.contextBuilder,
+        now: input.now
+    }, input.contextBuilder.build({
+        taskKind: "implement_plan",
+        repoIdentifier: source.repoSlug,
+        sourceKind: worktree.prUrl ? "pull_request" : source.kind,
+        sourceUrl: worktree.prUrl || source.url,
+        ...(worktree.prUrl ? { parentUrl: parentSource?.url ?? source.url } : {}),
+        labels: source.labels,
+        localRepoPath: worktree.path,
+        branchName: worktree.branchName,
+        ...(worktree.packet?.packetId ? { packetId: worktree.packet.packetId } : {}),
+        planDocumentPath: worktree.planDocumentPath,
+        ...(worktree.productSpecDocumentPath ? { productSpecDocumentPath: worktree.productSpecDocumentPath } : {}),
+        logDocumentPath: worktree.logDocumentPath,
+        ...(parentSource && parentSource.kind === "issue"
+            ? {
+                issueTitle: parentSource.title,
+                issueBody: parentSource.body
+            }
+            : source.kind === "issue"
+                ? {
+                    issueTitle: source.title,
+                    issueBody: source.body
+                }
+                : {})
+    }), workstreamId);
+}

package/dist/src/tasks/derivation/handlers/index.js

@@ -0,0 +1,54 @@
+import { commentResponseHandler } from "./comment-response.js";
+import { implementPlanHandler } from "./implement-plan.js";
+import { packetPullRequestControlHandler } from "./packet-pr-control.js";
+import { packetWorktreeHandler } from "./packet-worktree.js";
+import { preparePullRequestForMergeHandler } from "./prepare-for-merge.js";
+import { productDiscoveryHandler } from "./product-discovery.js";
+import { retryFailedTaskHandler } from "./retry-failed-task.js";
+import { reviewPullRequestHandler } from "./review-pr.js";
+import { syncParentBranchHandler, syncParentBranchPreflightHandler } from "./sync-parent-branch.js";
+import { hasOpenWaveAssessmentParentPullRequest, isWaveAssessmentCheckpointAllowed, waveAssessmentHandler } from "./wave-assessment.js";
+import { writePlanHandler } from "./write-plan.js";
+import { writeProductSpecHandler } from "./write-product-spec.js";
+export { deriveManagementPullRequestCommentTasks } from "./comment-response.js";
+export { isActiveParentWorkstream } from "./shared.js";
+export { planBreakdownHandler } from "./plan-breakdown.js";
+export { waveAssessmentHandler } from "./wave-assessment.js";
+const gatedSyncParentBranchPreflightHandler = {
+    name: syncParentBranchPreflightHandler.name,
+    derive(context, env, sink) {
+        if (hasOpenWaveAssessmentParentPullRequest(context, env) &&
+            !isWaveAssessmentCheckpointAllowed(context, env)) {
+            return [];
+        }
+        return syncParentBranchPreflightHandler.derive(context, env, sink);
+    }
+};
+const gatedSyncParentBranchHandler = {
+    name: syncParentBranchHandler.name,
+    derive(context, env, sink) {
+        if (!isWaveAssessmentCheckpointAllowed(context, env)) {
+            return [];
+        }
+        return syncParentBranchHandler.derive(context, env, sink);
+    }
+};
+export const parentWorkstreamHandlers = [
+    waveAssessmentHandler,
+    gatedSyncParentBranchPreflightHandler,
+    gatedSyncParentBranchHandler,
+    reviewPullRequestHandler,
+    preparePullRequestForMergeHandler,
+    packetPullRequestControlHandler,
+    writeProductSpecHandler,
+    writePlanHandler
+];
+export const activeParentWorkstreamHandlers = [
+    packetWorktreeHandler
+];
+export const finalWorkstreamHandlers = [
+    implementPlanHandler,
+    productDiscoveryHandler,
+    retryFailedTaskHandler,
+    commentResponseHandler
+];

package/dist/src/tasks/derivation/handlers/packet-pr-control.js

@@ -0,0 +1,92 @@
+import { classifyManagementPullRequest } from "../../../github/pr-classification.js";
+import { buildTaskId, createPullRequestTask } from "../builders.js";
+import { createPrepareForMergeTask } from "./prepare-for-merge.js";
+import { isActiveParentWorkstream } from "./shared.js";
+export const packetPullRequestControlHandler = {
+    name: "packet_pr_control",
+    derive(context, env, sink) {
+        return derivePacketPullRequestTasks(context, env, sink);
+    }
+};
+function derivePacketPullRequestTasks(context, env, sink) {
+    if (!isActiveParentWorkstream(context.workstream)) {
+        return [];
+    }
+    const tasks = [];
+    const projectionsForWorkstream = env.packetPullRequestProjections.filter((projection) => projection.parentWorkstream.id === context.workstream.id);
+    for (const projection of projectionsForWorkstream) {
+        const isManagementPR = classifyManagementPullRequest({
+            repoId: projection.pullRequest.repoId,
+            repoSlug: projection.pullRequest.repoSlug,
+            pullRequestNumber: projection.pullRequest.number,
+            headBranch: projection.pullRequest.headBranch,
+            managementPrs: env.input.previousState.managementPrs,
+            ...(env.input.managementRepo ? { managementRepo: env.input.managementRepo } : {})
+        }).kind === "management";
+        if (isManagementPR) {
+            continue;
+        }
+        const repoConfig = env.repoConfigs.get(projection.pullRequest.repoId);
+        if (!repoConfig || projection.pullRequest.state !== "open") {
+            continue;
+        }
+        if (projection.pullRequest.labels.includes(repoConfig.labels.agentReview)) {
+            const packetReviewTask = derivePacketPullRequestReviewTask(context, projection, repoConfig, env, sink);
+            if (packetReviewTask) {
+                tasks.push(packetReviewTask);
+            }
+        }
+        if (projection.pullRequest.labels.includes(repoConfig.labels.prepareForMerge)) {
+            const packetPrepareForMergeTask = createPrepareForMergeTask({
+                pullRequest: projection.pullRequest,
+                repoSyncRecord: env.repoSyncRecords.get(projection.pullRequest.repoId),
+                repoConfig,
+                contextBuilder: env.input.contextBuilder,
+                now: env.input.now,
+                workstreamId: context.workstream.id,
+                worktree: projection.packetWorktree,
+                packetProjection: projection
+            });
+            tasks.push(packetPrepareForMergeTask);
+        }
+    }
+    return tasks;
+}
+function derivePacketPullRequestReviewTask(context, projection, repoConfig, env, sink) {
+    const handledHeadSha = findHandledReviewHeadShaForPullRequest({
+        pullRequest: projection.pullRequest,
+        previousPullRequests: env.input.previousState.prs,
+        currentPullRequests: env.currentPullRequests,
+        tasks: env.input.previousState.tasks
+    });
+    if (handledHeadSha && handledHeadSha === projection.pullRequest.headSha) {
+        const taskId = buildTaskId("review_pr", projection.pullRequest.id);
+        sink.preserveExisting(taskId);
+        return undefined;
+    }
+    return createPullRequestTask("review_pr", projection.pullRequest, env.repoSyncRecords.get(projection.pullRequest.repoId), {
+        reason: `Packet pull request has the "${repoConfig.labels.agentReview}" label and code changed (head: ${projection.pullRequest.headSha || "unknown"}).`,
+        summary: `Review packet PR #${projection.pullRequest.number}: ${projection.pullRequest.title}`,
+        contextBuilder: env.input.contextBuilder,
+        now: env.input.now
+    }, projection.packetWorktree, context.workstream.id);
+}
+function findHandledReviewHeadShaForPullRequest(input) {
+    const latestCompletedTask = input.tasks
+        .filter((task) => task.kind === "review_pr" &&
+        task.status === "completed" &&
+        task.sourceId === input.pullRequest.id)
+        .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))[0];
+    if (!latestCompletedTask) {
+        return undefined;
+    }
+    const previousPr = input.previousPullRequests.find((pr) => pr.id === input.pullRequest.id);
+    if (previousPr) {
+        return previousPr.headSha;
+    }
+    const currentPr = input.currentPullRequests.find((pr) => pr.id === input.pullRequest.id);
+    if (currentPr) {
+        return currentPr.headSha;
+    }
+    return undefined;
+}

package/dist/src/tasks/derivation/handlers/packet-worktree.js

@@ -0,0 +1,29 @@
+import { derivePacketImplementTask } from "./implement-plan.js";
+import { resolvePacketPullRequest } from "./shared.js";
+import { deriveWritePlanTask } from "./write-plan.js";
+export const packetWorktreeHandler = {
+    name: "packet_worktree_tasks",
+    derive(context, env) {
+        return derivePacketWorktreeTasks(context, env);
+    }
+};
+function derivePacketWorktreeTasks(context, env) {
+    const tasks = [];
+    for (const packetWorktree of env.packetWorktreesByWorkstreamId.get(context.workstream.id) ?? []) {
+        const packetPullRequest = resolvePacketPullRequest(packetWorktree, env.currentPrsByRepoAndNumber);
+        const packetContext = {
+            ...context,
+            activeWorktree: packetWorktree,
+            packetPullRequest
+        };
+        const writePlanTask = deriveWritePlanTask(packetContext, env);
+        if (writePlanTask) {
+            tasks.push(writePlanTask);
+        }
+        const implementTask = derivePacketImplementTask(packetContext, env);
+        if (implementTask) {
+            tasks.push(implementTask);
+        }
+    }
+    return tasks;
+}

package/dist/src/tasks/derivation/handlers/plan-breakdown.js

@@ -0,0 +1,45 @@
+import { hasGeneratedPlanBreakdown } from "../../../workstreams/packet-plan.js";
+import { buildTaskId, buildTaskRecord } from "../builders.js";
+export const planBreakdownHandler = {
+    name: "plan_breakdown",
+    derive(context, env) {
+        const task = derivePlanBreakdownTask(context, env);
+        return task ? [task] : [];
+    },
+    shouldBlockRemainingHandlers(task) {
+        return task.status !== "completed" && task.status !== "failed";
+    }
+};
+function derivePlanBreakdownTask(context, env) {
+    const { workstream, attention, issue, activePullRequest, repoConfig, repoSyncRecord } = context;
+    if (hasGeneratedPlanBreakdown(workstream)) {
+        return undefined;
+    }
+    if (!attention?.reasons.includes("plan_breakdown_requested") || !repoConfig) {
+        return undefined;
+    }
+    const source = (issue?.labels.includes(repoConfig.labels.planBreakdownNeeded) ? issue : undefined)
+        ?? (activePullRequest?.labels.includes(repoConfig.labels.planBreakdownNeeded) ? activePullRequest : undefined);
+    if (!source) {
+        return undefined;
+    }
+    return buildTaskRecord(buildTaskId("plan_breakdown", source.id), "plan_breakdown", source, repoSyncRecord, {
+        reason: `The "${repoConfig.labels.planBreakdownNeeded}" label is present, requesting a technical breakdown before implementation.`,
+        summary: `Break down implementation for ${source.kind.replace("_", " ")} #${source.number}: ${source.title}`,
+        contextBuilder: env.input.contextBuilder,
+        now: env.input.now
+    }, env.input.contextBuilder.build({
+        taskKind: "plan_breakdown",
+        repoIdentifier: source.repoSlug,
+        sourceKind: source.kind,
+        sourceUrl: source.url,
+        labels: source.labels,
+        ...(source.kind === "issue"
+            ? {
+                issueTitle: source.title,
+                issueBody: source.body
+            }
+            : {}),
+        ...(repoSyncRecord?.localPath ? { localRepoPath: repoSyncRecord.localPath } : {})
+    }), workstream.id);
+}

package/dist/src/tasks/derivation/handlers/prepare-for-merge.js

@@ -0,0 +1,91 @@
+import { buildTaskId, buildTaskRecord } from "../builders.js";
+export const preparePullRequestForMergeHandler = {
+    name: "prepare_pr_for_merge",
+    derive(context, env) {
+        const task = derivePrepareForMergeTask(context, env);
+        return task ? [task] : [];
+    }
+};
+function derivePrepareForMergeTask(context, env) {
+    const { workstream, attention, activePullRequest, activeWorktree, repoConfig, repoSyncRecord } = context;
+    if (!attention ||
+        !activePullRequest ||
+        !repoConfig ||
+        activePullRequest.state !== "open" ||
+        !attention.reasons.includes("prepare_for_merge_requested") ||
+        !activePullRequest.labels.includes(repoConfig.labels.prepareForMerge)) {
+        return undefined;
+    }
+    const worktree = activeWorktree?.branchName === activePullRequest.headBranch ? activeWorktree : undefined;
+    return createPrepareForMergeTask({
+        pullRequest: activePullRequest,
+        repoSyncRecord,
+        repoConfig,
+        contextBuilder: env.input.contextBuilder,
+        now: env.input.now,
+        workstreamId: workstream.id,
+        worktree
+    });
+}
+export function createPrepareForMergeTask(input) {
+    const { pullRequest, repoSyncRecord, repoConfig, contextBuilder, now, workstreamId, worktree, packetProjection } = input;
+    const preflight = {
+        prNumber: pullRequest.number,
+        headBranch: pullRequest.headBranch,
+        headSha: pullRequest.headSha,
+        baseBranch: pullRequest.baseBranch,
+        prTitle: pullRequest.title,
+        // Capture durable worktree paths at derivation time for audit/log use after clone cleanup
+        persistentWorktreePath: worktree?.path,
+        persistentLogDocumentPath: worktree?.logDocumentPath,
+        persistentPlanDocumentPath: worktree?.planDocumentPath
+    };
+    const waveIndex = packetProjection?.packetWorktree?.packet?.waveIndex ??
+        findWaveIndexForPacket(packetProjection?.packet.id, packetProjection?.parentWorkstream.packetPlan);
+    const reason = packetProjection
+        ? `Packet pull request #${pullRequest.number} (packet: ${packetProjection.packet.id}, wave: ${waveIndex ?? "unknown"}) has the "${repoConfig.labels.prepareForMerge}" label, requesting merge preparation into "${pullRequest.baseBranch}".`
+        : `Pull request has the "${repoConfig.labels.prepareForMerge}" label, requesting merge preparation into "${pullRequest.baseBranch}".`;
+    const summary = packetProjection
+        ? `Prepare packet PR #${pullRequest.number} for merge into ${pullRequest.baseBranch} (Workstream: ${workstreamId})`
+        : `Prepare PR #${pullRequest.number} for merge into ${pullRequest.baseBranch}: ${pullRequest.title}`;
+    return buildTaskRecord(buildTaskId("prepare_pr_for_merge", pullRequest.id), "prepare_pr_for_merge", pullRequest, repoSyncRecord, {
+        reason,
+        summary,
+        contextBuilder,
+        now
+    }, contextBuilder.build({
+        taskKind: "prepare_pr_for_merge",
+        repoIdentifier: pullRequest.repoSlug,
+        sourceKind: "pull_request",
+        sourceUrl: pullRequest.url,
+        labels: pullRequest.labels,
+        prepareForMerge: preflight,
+        ...(worktree?.path
+            ? {
+                localRepoPath: worktree.path,
+                branchName: worktree.branchName,
+                planDocumentPath: worktree.planDocumentPath,
+                logDocumentPath: worktree.logDocumentPath
+            }
+            : repoSyncRecord?.localPath
+                ? { localRepoPath: repoSyncRecord.localPath }
+                : {}),
+        ...(worktree?.packet?.packetId
+            ? { packetId: worktree.packet.packetId }
+            : packetProjection?.packet.id
+                ? { packetId: packetProjection.packet.id }
+                : {})
+    }), workstreamId);
+}
+function findWaveIndexForPacket(packetId, packetPlan) {
+    if (!packetId || !packetPlan) {
+        return undefined;
+    }
+    for (let i = 0; i < packetPlan.waves.length; i++) {
+        const wave = packetPlan.waves[i];
+        if (wave && wave.includes(packetId)) {
+            return i;
+        }
+    }
+    return undefined;
+}

package/dist/src/tasks/derivation/handlers/product-discovery.js

@@ -0,0 +1,36 @@
+import { createIssueTask } from "../builders.js";
+export const productDiscoveryHandler = {
+    name: "product_discovery",
+    derive(context, env) {
+        const task = deriveProductDiscoveryTask(context, env);
+        return task ? [task] : [];
+    }
+};
+function deriveProductDiscoveryTask(context, env) {
+    const { workstream, attention, issue, repoConfig, repoSyncRecord } = context;
+    if (!issue || workstream.origin.type !== "issue") {
+        return undefined;
+    }
+    if (workstream.phase !== "product_discovery") {
+        return undefined;
+    }
+    const hasExistingProductDiscoveryTask = env.existingTasks.some((task) => task.kind === "product_discovery" && task.workstreamId === workstream.id);
+    const previousWorkstream = env.input.previousState.workstreams.find((record) => record.id === workstream.id);
+    const issueCommentsUnavailable = repoSyncRecord?.githubScan?.failures.some((failure) => failure.step === "issue_comments" && failure.scope === `issue#${issue.number}`) ?? false;
+    const isNewIssueProductDiscovery = Boolean(attention?.reasons.includes("new_issue") && !env.previousIssues.has(issue.id));
+    const isMigratedProductDiscovery = Boolean(!hasExistingProductDiscoveryTask &&
+        !issueCommentsUnavailable &&
+        (previousWorkstream?.phase === "issue_triage" || previousWorkstream?.phase === "issue_waiting"));
+    if (!isNewIssueProductDiscovery && !isMigratedProductDiscovery) {
+        return undefined;
+    }
+    if (repoConfig && issue.labels.includes(repoConfig.labels.agentProductApproved)) {
+        return undefined;
+    }
+    return createIssueTask("product_discovery", issue, repoSyncRecord, {
+        reason: "Issue is newly seen and needs Product Discovery before implementation approval.",
+        summary: `Product Discovery for issue #${issue.number}: ${issue.title}`,
+        contextBuilder: env.input.contextBuilder,
+        now: env.input.now
+    }, workstream.id);
+}